raw1394.h

libraw1394-1.1.0.tar.gz 1394的一个库文件

#define raw1394_get_rcode(errcode) ((errcode) & 0xf)
#define raw1394_get_internal(errcode) (errcode)

/**
 * raw1394_get_errcode - return error code of async transaction
 * @handle: libraw1394 handle
 *
 * Some macros are available to extract information from the error code,
 * raw1394_errcode_to_errno() can be used to convert it to an errno number of
 * roughly the same meaning.
 *
 * Returns: the error code of the last raw1394_read(), raw1394_write(),
 * raw1394_lock() or raw1394_iso_write().  The error code is either an internal
 * error (i.e. not a bus error) or a combination of acknowledge code and
 * response code, as appropriate.
 *
 **/
raw1394_errcode_t raw1394_get_errcode(raw1394handle_t handle);

/**
 * raw1394_errcode_to_errno - convert libraw1394 errcode to errno
 * @errcode: the error code to convert
 *
 * The error code as retrieved by raw1394_get_errcode() is converted into a
 * roughly equivalent errno number and returned.  %0xdead is returned for an
 * illegal errcode.
 *
 * It is intended to be used to decide what to do (retry, give up, report error)
 * for those programs that aren't interested in details, since these get lost in
 * the conversion.  However the returned errnos are equivalent in source code
 * meaning only, the associated text of e.g. perror() is not necessarily
 * meaningful.
 *
 * Returns: %EAGAIN (retrying might succeed, also generation number
 * mismatch), %EREMOTEIO (other node had internal problems), %EPERM (operation
 * not allowed on this address, e.g. write on read-only location), %EINVAL
 * (invalid argument) and %EFAULT (invalid pointer).
 **/
int raw1394_errcode_to_errno(raw1394_errcode_t errcode);

/**
 * raw1394_new_handle - create new handle
 *
 * Creates and returns a new handle which can (after being set up) control one
 * port.  It is not allowed to use the same handle in multiple threads or forked
 * processes.  It is allowed to create and use multiple handles, however.  Use
 * one handle per thread which needs it in the multithreaded case.
 *
 * Returns: the created handle or %NULL when initialization fails. In the latter
 * case errno either contains some OS specific error code or %0 if the error is
 * that libraw1394 and raw1394 don't support each other's protocol versions.
 **/
raw1394handle_t raw1394_new_handle(void);

/**
 * raw1394_destroy_handle - deallocate handle
 * @handle: handle to deallocate
 *
 * Closes connection with raw1394 on this handle and deallocates everything
 * associated with it.  It is safe to pass %NULL as handle, nothing is done in
 * this case.
 **/
void raw1394_destroy_handle(raw1394handle_t handle);

/**
 * raw1394_new_handle_on_port - create a new handle and bind it to a port
 * @port: port to connect to (same as argument to raw1394_set_port())
 *
 * Same as raw1394_new_handle(), but also binds the handle to the
 * specified 1394 port. Equivalent to raw1394_new_handle() followed by
 * raw1394_get_port_info() and raw1394_set_port(). Useful for
 * command-line programs that already know what port they want. If
 * raw1394_set_port() returns ESTALE, retries automatically.
 *
 * Returns: the new handle on success or NULL on failure
 **/
raw1394handle_t raw1394_new_handle_on_port(int port);

/**
 * raw1394_busreset_notify - Switch off/on busreset-notification for handle
 * @handle: libraw1394 handle
 * @off_on_switch: RAW1394_NOTIFY_OFF or RAW1394_NOTIFY_ON
 *
 * Returns: 0 on success or -1 on failure (sets errno)
 **/
int raw1394_busreset_notify (raw1394handle_t handle, int off_on_switch);

/**
 * raw1394_get_fd - get the communication file descriptor
 * @handle: libraw1394 handle
 *
 * This can be used for select()/poll() calls if you wait on other fds or can be
 * integrated into another event loop (e.g. from a GUI application framework).
 * It can also be used to set/remove the O_NONBLOCK flag using fcntl() to modify
 * the blocking behaviour in raw1394_loop_iterate().  It must not be used for
 * anything else.
 *
 * Returns: the fd used for communication with the raw1394 kernel module.
 **/
int raw1394_get_fd(raw1394handle_t handle);

/**
 * raw1394_set_userdata - associate user data with a handle
 * @handle: libraw1394 handle
 * @data: user data (pointer)
 *
 * Allows to associate one void pointer with a handle.  libraw1394 does not care
 * about the data, it just stores it in the handle allowing it to be retrieved
 * at any time with raw1394_get_userdata().  This can be useful when multiple
 * handles are used, so that callbacks can identify the handle.
 **/
void raw1394_set_userdata(raw1394handle_t handle, void *data);

/**
 * raw1394_get_userdata - retrieve user data from handle
 * @handle: libraw1394 handle
 *
 * Returns: the user data pointer associated with the handle using
 * raw1394_set_userdata().
 **/
void *raw1394_get_userdata(raw1394handle_t handle);

/**
 * raw1394_get_local_id - get node ID of the current port
 * @handle: libraw1394 handle
 *
 * Returns: the node ID of the local node connected to which the handle is
 * connected.  This value can change with every bus reset.
 **/
nodeid_t raw1394_get_local_id(raw1394handle_t handle);

/**
 * raw1394_get_irm_id - get node ID of isochronous resource manager
 * @handle: libraw1394 handle
 *
 * Returns: the node ID of the isochronous resource manager of the bus the handle
 * is connected to.  This value may change with every bus reset.
 **/
nodeid_t raw1394_get_irm_id(raw1394handle_t handle);

/**
 * raw1394_get_nodecount - get number of nodes on the bus
 * @handle: libraw1394 handle
 *
 * Since the root node always has
 * the highest node ID, this number can be used to determine that ID (it's
 * LOCAL_BUS|(count-1)).
 *
 * Returns: the number of nodes on the bus to which the handle is connected.
 * This value can change with every bus reset.
 **/
int raw1394_get_nodecount(raw1394handle_t handle);

struct raw1394_portinfo {
        int nodes;
        char name[32];
};

/**
 * raw1394_get_port_info - get information about available ports
 * @handle: libraw1394 handle
 * @pinf: pointer to an array of struct raw1394_portinfo
 * @maxports: number of elements in @pinf
 *
 * Before you can set which port to use, you have to use this function to find
 * out which ports exist.
 *
 * If your program is interactive, you should present the user with this list to
 * let them decide which port to use if there is more than one.  A
 * non-interactive program (and probably interactive ones, too) should provide a
 * command line option to choose the port. If @maxports is %0, @pinf can be
 * %NULL, too.
 *
 * Returns: the number of ports and writes information about them into @pinf, but
 * not into more than @maxports elements.
 **/
int raw1394_get_port_info(raw1394handle_t handle, struct raw1394_portinfo *pinf,
                          int maxports);

/**
 * raw1394_set_port - choose port for handle
 * @handle: libraw1394 handle
 * @port: port to connect to (corresponds to index of struct raw1394_portinfo)
 *
 * This function connects the handle to the port given (as queried with
 * raw1394_get_port_info()).  If successful, raw1394_get_port_info() and
 * raw1394_set_port() are not allowed to be called afterwards on this handle.
 * To make up for this, all the other functions (those handling asynchronous and
 * isochronous transmissions) can now be called.
 *
 * Returns: %0 for success or -1 for failure with errno set appropriately.  A
 * possible failure mode is with errno = %ESTALE, in this case the configuration
 * has changed since the call to raw1394_get_port_info() and it has to be called
 * again to update your view of the available ports.
 **/
int raw1394_set_port(raw1394handle_t handle, int port);

/**
 * raw1394_reset_bus - initiate bus reset
 * @handle: libraw1394 handle
 *
 * This function initiates a bus reset on the connected port.  Usually this is
 * not necessary and should be avoided, this function is here for low level bus
 * control and debugging.
 *
 * Returns: %0 for success or -1 for failure with errno set appropriately
 **/
int raw1394_reset_bus(raw1394handle_t handle);

/**
 * raw1394_reset_bus_new - Reset the connected bus (with certain type). 
 * @handle: libraw1394 handle
 * @type: RAW1394_SHORT_RESET or RAW1394_LONG_RESET
 *
 * Returns: %0 for success or -1 for failure 
 **/
int raw1394_reset_bus_new(raw1394handle_t handle, int type);

/**
 * raw1394_loop_iterate - get and process one event message
 * @handle: libraw1394 handle
 *
 * Get one new message through handle and process it with the registered message
 * handler. Note that some other library functions may call this function 
 * multiple times to wait for their completion, some handler return values may 
 * get lost if you use these.
 *
 * Returns: %-1 for an error or the return value of
 * the handler which got executed. The default handlers always return zero.
 **/
int raw1394_loop_iterate(raw1394handle_t handle);

typedef int (*bus_reset_handler_t)(raw1394handle_t, unsigned int generation);

/**
 * raw1394_set_bus_reset_handler - set bus reset handler
 * @handle: libraw1394 handle
 * @new_h: pointer to new handler
 *
 * Sets the handler to be called on every bus reset to @new_h.
 * The default handler just calls raw1394_update_generation().
 *
 * Returns: the old handler
 **/
bus_reset_handler_t raw1394_set_bus_reset_handler(raw1394handle_t handle,
                                                  bus_reset_handler_t new_h);

/**
 * raw1394_get_generation - get generation number of handle
 * @handle: libraw1394 handle
 *
 * The generation number is incremented on every bus reset, and every transaction
 * started by raw1394 is tagged with the stored generation number.  If these
 * don't match, the transaction will abort with an error.
 * The generation number of the handle is not automatically updated,
 * raw1394_update_generation() has to be used for this.
 *
 * Returns: the generation number associated with the handle 
 **/
unsigned int raw1394_get_generation(raw1394handle_t handle);

/**
 * raw1394_update_generation - set generation number of handle
 * @handle: libraw1394 handle
 * @generation: new generation number
 *
 * This function sets the generation number of the handle to @gen.  All requests
 * that apply to a single node ID are tagged with this number and abort with an
 * error if that is different from the generation number kept in the kernel.
 * This avoids acting on the wrong node which may have changed its ID in a bus
 * reset.
 *
 * You should call this within your bus reset handler with an incremented value.
 **/
void raw1394_update_generation(raw1394handle_t handle, unsigned int generation);

typedef int (*tag_handler_t)(raw1394handle_t, unsigned long tag,
                             raw1394_errcode_t err);

/**
 * raw1394_set_tag_handler - set request completion handler
 * @handle: libraw1394 handle
 * @new_h: pointer to new handler
 *
 * Sets the handler to be called whenever a request completes to @new_h.
 * The default handler interprets the tag as a pointer
 * to a &struct raw1394_reqhandle and calls the callback in there.
 *
 * Care must be taken when replacing the tag handler and calling the synchronous
 * versions of the transaction functions (i.e. raw1394_read(), raw1394_write(),
 * raw1394_lock(), raw1394_iso_write()) since these do pass pointers to &struct
 * raw1394_reqhandle as the tag and expect the callback to be invoked.
 *
 * Returns: the old handler
 **/
tag_handler_t raw1394_set_tag_handler(raw1394handle_t handle,
                                      tag_handler_t new_h);

typedef int (*arm_tag_handler_t)(raw1394handle_t handle, unsigned long arm_tag,
                             byte_t request_type, unsigned int requested_length,
                             void *data); 

/**
 * raw1394_set_arm_tag_handler - set the async request handler
 * @handle: libraw1394 handle
 * @new_h: pointer to new handler