Added/adjusted documentation for doxygen.

Henning Meier-Geinitz <henning@meier-geinitz.de>
DEVEL_2_0_BRANCH-1
Henning Geinitz 2002-04-11 19:46:31 +00:00
rodzic 6fa90ef05c
commit cd71f39763
2 zmienionych plików z 329 dodań i 89 usunięć

Wyświetl plik

@ -37,8 +37,13 @@
If you write modifications of your own for SANE, it is your choice
whether to permit this exception to apply to your modifications.
If you do not wish that, delete this exception notice.
*/
This file implements an interface for the Mustek PP chipset A4S2 */
/** @file sanei_pa4s2.h
* This file implements an interface for the Mustek PP chipset A4S2
*
* @sa sanei_usb.h, sanei_ab306.h, sanei_lm983x.h, sanei_scsi.h, sanei_pio.h
*/
#ifndef sanei_pa4s2_h
#define sanei_pa4s2_h
@ -46,46 +51,119 @@
#include <sys/types.h>
#include <sane/sane.h>
/* options to controll interface operations */
/** @name Options to control interface operations */
/* @{ */
#define SANEI_PA4S2_OPT_DEFAULT 0 /* normal mode */
#define SANEI_PA4S2_OPT_TRY_MODE_UNI 1 /* enable UNI protocoll */
#define SANEI_PA4S2_OPT_ALT_LOCK 2 /* use alternative lock cmd */
/* @} */
/*
opens *dev as pa4s2 device, possible values for *dev are "0x378",
"0x278" and "0x3BC"
/** Open pa4s2 device
*
* Opens *dev as pa4s2 device.
*
* @param dev IO port address ("0x378", "0x278", or "0x3BC")
* @param fd file descriptor
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if no scanner was found or the port number was wrong
* - SANE_STATUS_DEVICE_BUSY - if the device is already in use
* - SANE_STATUS_IO_ERROR - if the port couldn't be accessed
*
*/
extern SANE_Status sanei_pa4s2_open (const char *dev, int *fd);
/* closes the device */
/** Close pa4s2 device
*
* @param fd file descriptor
*/
extern void sanei_pa4s2_close (int fd);
/*
sets/gets interface options. Options will be taken over, when set is
SANE_TRUE. These options should be set before the firt device is opened
/** Set/get options
*
* Sets/gets interface options. Options will be taken over, when set is
* SANE_TRUE. These options should be set before the first device is opened
*
* @param options pointer to options
* @param set set (SANE_TRUE) or get (SANE_FALSE) options
*
* @return
* - SANE_STATUS_GOOD - on success
*/
extern SANE_Status sanei_pa4s2_options (u_int * options, int set);
/*
enables/disables the device. possible values for enable are SANE_TRUE
and SANE_FALSE. When the device is disabled, the printer can accessed,
when it's enabled data can be read/written
/** Enables/disable device
*
* When the device is disabled, the printer can be accessed, when it's enabled
* data can be read/written.
*
* @param fd file descriptor
* @param enable enable (SANE_TRUE) or disable (SANE_FALSE) device
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if fd is invalid or device not in use
*/
extern SANE_Status sanei_pa4s2_enable (int fd, int enable);
/*
the function to read a register is split up in three parts, so a register
can be read more than once
/** Select a register
*
* The function to read a register is split up in three parts, so a register
* can be read more than once.
*
* @param fd file descriptor
* @param reg register
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if fd is invalid or device not in use
*
* @sa sanei_pa4s2_readbyte(), sanei_pa4s2_readend()
*/
/* selects a register */
extern SANE_Status sanei_pa4s2_readbegin (int fd, u_char reg);
/* reads a register */
/** Read a register
*
* The function to read a register is split up in three parts, so a register
* can be read more than once.
*
* @param fd file descriptor
* @param val pointer to value
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if fd is invalid or device not in use
*
* @sa sanei_pa4s2_readbegin(), sanei_pa4s2_readend()
*/
extern SANE_Status sanei_pa4s2_readbyte (int fd, u_char * val);
/* terminates reading sequence */
/** Terminate reading sequence
*
* The function to read a register is split up in three parts, so a register
* can be read more than once.
*
* @param fd file descriptor
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if fd is invalid or device not in use
* @sa sanei_pa4s2_readbegin(), sanei_pa4s2_readbyte()
*/
extern SANE_Status sanei_pa4s2_readend (int fd);
/* reads a register */
/** Write a register
*
* @param fd file descriptor
* @param reg register
* @param val value to be written
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_INVAL - if fd is invalid or device not in use
*/
extern SANE_Status sanei_pa4s2_writebyte (int fd, u_char reg, u_char val);

Wyświetl plik

@ -16,7 +16,13 @@
along with sane; see the file COPYING. If not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Generic interface to SCSI drivers. */
*/
/** @file sanei_scsi.h
* Generic interface to SCSI drivers.
* @sa sanei_usb.h, sanei_ab306.h,sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h,
* and man sane-scsi(5) for user-oriented documentation
*/
#ifndef sanei_scsi_h
#define sanei_scsi_h
@ -25,123 +31,279 @@
#include <sane/sane.h>
/** Sense handler
*
* The sense handler can be implemented in backends. It's for deciding
* which sense codes should be considered an error and which shouldn't.
*
* @param fd file descriptor
* @param sense_buffer pointer to buffer containing sense codes
* @param arg pointer to data buffer
*
* @return
* - SANE_STATUS_GOOD - on success (sense isn't regarded as error)
* - any other status if sense code is regarded as error
*/
typedef SANE_Status (*SANEI_SCSI_Sense_Handler) (int fd,
u_char *sense_buffer,
void *arg);
/** Maximum size of a SCSI request
*/
extern int sanei_scsi_max_request_size;
/* Find each SCSI devices that matches the pattern specified by the
arguments. String arguments can be "omitted" by passing NULL,
integer arguments can be "omitted" by passing -1. Callback ATTACH
gets invoked once for each device. The DEV argument passed to this
callback is the real devicename.
Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would
attach all HP devices on SCSI bus 3. */
/** Find SCSI devices.
*
* Find each SCSI device that matches the pattern specified by the
* arguments. String arguments can be "omitted" by passing NULL,
* integer arguments can be "omitted" by passing -1.
*
* Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would
* attach all HP devices on SCSI bus 3.
*
* @param vendor
* @param model
* @param type
* @param bus
* @param channel
* @param id
* @param lun
* @param attach callback invoked once for each device
* @param dev real devicename (passed to attach callback)
*
*/
extern void sanei_scsi_find_devices (const char *vendor, const char *model,
const char *type,
int bus, int channel, int id, int lun,
SANE_Status (*attach) (const char *dev));
/** Open a SCSI device
*
* Opens a SCSI device by its device filename and returns a file descriptor.
* If it's necessary to adjust the SCSI buffer size, use
* sanei_scsi_open_extended().
*
* @param devicename name of the devicefile, e.g. "/dev/sg0"
* @param fd file descriptor
* @param sense_handler called whenever the SCSI driver returns a sense buffer
* @param sense_arg pointer to data for the sense handler
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to
* permissions
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured
*
* @sa sanei_scsi_open_extended(), HAVE_SANEI_SCSI_OPEN_EXTENDED
*/
extern SANE_Status sanei_scsi_open (const char * device_name, int * fd,
SANEI_SCSI_Sense_Handler sense_handler,
void *sense_arg);
/* The extended open call allows a backend to ask for a specific
buffer size. sanei_scsi_open tries to allocate a buffer of the
size given by *buffersize upon entry to this function. If
sanei_scsi_open_extended returns successfully, *buffersize
contains the available buffer size. This value may be both
smaller or larger than the value requested by the backend;
it can even be zero. The backend must decide, if it got enough
buffer memory to work.
Note that the value of *buffersize may differ for different
files.
*/
/** Open a SCSI device and set the buffer size
*
* The extended open call allows a backend to ask for a specific buffer
* size. sanei_scsi_open_extended() tries to allocate a buffer of the size
* given by *buffersize upon entry to this function. If
* sanei_scsi_open_extended returns successfully, *buffersize contains the
* available buffer size. This value may be both smaller or larger than the
* value requested by the backend; it can even be zero. The backend must
* decide, if it got enough buffer memory to work.
*
* Note that the value of *buffersize may differ for different files.
*
* @param devicename name of the devicefile, e.g. "/dev/sg0"
* @param fd file descriptor
* @param sense_handler called whenever the SCSI driver returns a sense buffer
* @param sense_arg pointer to data for the sense handler
* @param buffersize size of the SCAI request buffer (in bytes)
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to
* permissions
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured
*
* @sa sanei_scsi_open(), HAVE_SANEI_SCSI_OPEN_EXTENDED
*/
extern SANE_Status sanei_scsi_open_extended (
const char * device_name, int * fd,
SANEI_SCSI_Sense_Handler sense_handler,
void *sense_arg, int *buffersize);
/* Let backends decide, which open call to use:
if HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended
may be used.
May also be used to decide, if sanei_scsi_req_flush_all or
sanei_scsi_req_flush_all_extended should be used.
/** Do we have sanei_scsi_open_extended()?
*
* Let backends decide, which open call to use: if
* HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended may be
* used. May also be used to decide, if sanei_scsi_req_flush_all or
* sanei_scsi_req_flush_all_extended() should be used.
*
* @sa sanei_scsi_open(), sanei_scsi_open_extended()
*/
#define HAVE_SANEI_SCSI_OPEN_EXTENDED
/* One or more scsi commands can be enqueued by calling req_enter().
SRC is the pointer to the SCSI command and associated write data
and SRC_SIZE is the length of the command and data. DST is a
pointer to a buffer in which data is returned (if any). It may be
NULL if no data is returned by the command. On input *DST_SIZE is
the size of the buffer pointed to by DST, on exit, *DST_SIZE is set
to the number of bytes returned in the buffer (which is less than
or equal to the buffer size). DST_SIZE may be NULL if no data is
expected. IDP is a pointer to a void* that uniquely identifies
the entered request.
NOTE: Some systems may not support multiple outstanding commands.
On such systems, enter() may block. In other words, it is not
proper to assume that enter() is a non-blocking routine.
src points to a buffer which contains the SCSI command followed
by data to be written to the device (if any)
/** Enqueue SCSI command
*
* One or more scsi commands can be enqueued by calling sanei_scsi_req_enter().
*
* NOTE: Some systems may not support multiple outstanding commands. On such
* systems, sanei_scsi_req_enter() may block. In other words, it is not proper
* to assume that enter() is a non-blocking routine.
*
* @param fd file descriptor
* @param src pointer to the SCSI command and associated write data (if any)
* @param src_size length of the command and data
* @param dst pointer to a buffer in which data is returned; NULL if no data is
* returned
* @param dst_size on input, the size of the buffer pointed to by dst, on exit,
* set to the number of bytes returned in the buffer (which is less than or equal
* to the buffer size; may be NULL if no data is expected
* @param idp pointer to a void* that uniquely identifies the entered request
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if a locking or an unknown error occured
* @sa sanei_scsi_req_enter2()
*
*/
extern SANE_Status sanei_scsi_req_enter (int fd,
const void * src, size_t src_size,
void * dst, size_t * dst_size,
void **idp);
/* Same as above, but with separate buffers for the SCSI command and
for the data to be sent to the device.
With sanei_scsi_req_enter, the length of te SCSI command block must be
guessed. While that works in most cases, Canon scanners for example
use the vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon
scanners want to get 6 byte command blocks for these commands,
but sanei_scsi_req_enter and sanei_scsi_cmd send 12 bytes.
cmd: pointer to SCSI command
cmd_size: size of the command
src: pointer to the buffer with data to be sent rto the scanner
src_size: size of that buffer
dst, dst_size, idp: see above
If dst_size and *dst_size are non-zero, a "read command" (ie,
data transfer from the device to the host) is assumed.
*/
/** Enqueue SCSI command and separated data
*
* Same as sanei_scsi_req_enter(), but with separate buffers for the SCSI
* command and for the data to be sent to the device.
*
* With sanei_scsi_req_enter(), the length of te SCSI command block must be
* guessed. While that works in most cases, Canon scanners for example use the
* vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon scanners want to
* get 6 byte command blocks for these commands, but sanei_scsi_req_enter() and
* sanei_scsi_cmd() send 12 bytes.
*
* If dst_size and *dst_size are non-zero, a "read command" (ie, data transfer
* from the device to the host) is assumed.
*
* @param fd file descriptor
* @param cmd pointer to SCSI command
* @param cmd_size size of the command
* @param src pointer to the buffer with data to be sent to the scanner
* @param src_size size of src buffer
* @param dst pointer to a buffer in which data is returned; NULL if no data is
* returned
* @param dst_size on input, the size of the buffer pointed to by dst, on exit,
* set to the number of bytes returned in the buffer (which is less than or equal
* to the buffer size; may be NULL if no data is expected
* @param idp pointer to a void* that uniquely identifies the entered request
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if a locking or an unknown error occured
* @sa sanei_scsi_req_enter()
*/
extern SANE_Status sanei_scsi_req_enter2 (int fd,
const void * cmd, size_t cmd_size,
const void * src, size_t src_size,
void * dst, size_t * dst_size,
void **idp);
/* Wait for the completion of the SCSI command with id ID. */
/** Wait for SCSI command
*
* Wait for the completion of the SCSI command with id ID.
*
* @param id id used in sanei_scsi_req_enter()
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_DEVICE_BUSY - if the device is busy (try again later)
* - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
*/
extern SANE_Status sanei_scsi_req_wait (void *id);
/* This is a convenience function that is equivalent to a pair of
enter()/wait() calls. */
/** Send SCSI command
*
* This is a convenience function that is equivalent to a pair of
* sanei_scsi_req_enter()/sanei_scsi_req_wait() calls.
*
* @param fd file descriptor
* @param src pointer to the SCSI command and associated write data (if any)
* @param src_size length of the command and data
* @param dst pointer to a buffer in which data is returned; NULL if no data is
* returned
* @param dst_size on input, the size of the buffer pointed to by dst, on exit,
* set to the number of bytes returned in the buffer (which is less than or equal
* to the buffer size; may be NULL if no data is expected
*
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if a locking or an unknown error occured
*
* @sa sanei_scsi_cmd2(), sanei_scsi_req_enter(), sanei_scsi_req_wait()
*/
extern SANE_Status sanei_scsi_cmd (int fd,
const void * src, size_t src_size,
void * dst, size_t * dst_size);
/** Send SCSI command and separated data
*
* This is a convenience function that is equivalent to a pair of
* sanei_scsi_req_enter2()/sanei_scsi_req_wait() calls.
*
* @param fd file descriptor
* @param cmd pointer to SCSI command
* @param cmd_size size of the command
* @param src pointer to the buffer with data to be sent to the scanner
* @param src_size size of src buffer
* @param dst pointer to a buffer in which data is returned; NULL if no data is
* returned
* @param dst_size on input, the size of the buffer pointed to by dst, on exit,
* set to the number of bytes returned in the buffer (which is less than or equal
* to the buffer size; may be NULL if no data is expected
* @return
* - SANE_STATUS_GOOD - on success
* - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
* - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
* - SANE_STATUS_INVAL - if a locking or an unknown error occured
*
* @sa sanei_scsi_cmd(), sanei_scsi_req_enter(), sanei_scsi_req_wait()
*/
extern SANE_Status sanei_scsi_cmd2 (int fd,
const void * cmd, size_t cmd_size,
const void * src, size_t src_size,
void * dst, size_t * dst_size);
/* Flush all pending SCSI commands. This function work only,
if zero or one SCSI file handles are open.
/** Flush queue
*
* Flush all pending SCSI commands. This function work only, if zero or one
* SCSI file handles are open.
*
* @sa sanei_scsi_req_flush_all_extended()
*/
extern void sanei_scsi_req_flush_all (void);
/* Flush all SCSI commands pending for one handle */
/** Flush queue for handle
*
* Flush all SCSI commands pending for one handle
*
* @param fd file descriptor
*
* @sa sanei_scsi_req_flush_all()
*/
extern void sanei_scsi_req_flush_all_extended (int fd);
/** Close a SCSI device
*
* @param fd file descriptor
*
*/
extern void sanei_scsi_close (int fd);
#endif /* sanei_scsi_h */