ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOFireWireAVCLibUnitInterface

Declared In:

Overview

Initial interface discovered for all AV/C unit drivers.

Discussion

The IOFireWireAVCLibUnitInterface is the initial interface discovered by most drivers. It supplies the methods that control the operation of the AV/C unit as a whole. Finally, the unit can supply a reference to the IOFireWireUnit. This can be useful if a driver wishes to access the standard FireWire APIs.

In Mac OS X v10.4 and later, the IOFireWireAVCLibUnitInterface contains functions to create and send asynchronous AV/C commands and receive responses.

Functions

addCallbackDispatcherToRunLoop: Adds a dispatcher for kernel callbacks to the specified run loop.
AVCAsynchronousCommandCancel: Cancels a submitted command.
AVCAsynchronousCommandReinit: Reinitializes an existing IOFireWireAVCLibAsynchronousCommand object, preserving the existing command.
AVCAsynchronousCommandReinitWithCommandBytes: Reinitializes an existing IOFireWireAVCLibAsynchronousCommand object, replacing the existing command with a new one.
AVCAsynchronousCommandRelease: Releases an IOFireWireAVCLibAsynchronousCommand object.
AVCAsynchronousCommandSubmit: Issues the asynchronous command on the bus.
AVCCommand: Sends an AV/C command to the device and returns the response.
AVCCommandInGeneration: Sends an AV/C command to the device and returns the response.
breakLocalP2PInputConnection: Decrements the point-to-point connection count of a unit input plug.
breakLocalP2POutputConnection: Decrements the point-to-point connection count of a unit output plug.
breakP2PInputConnection: Decrements the point-to-point connection count of a unit input plug.
breakP2POutputConnection: Decrements the point-to-point connection count of a unit output plug.
close: Closes an exclusive access to the device.
createAVCAsynchronousCommand: Creates an IOFireWireAVCLibAsynchronousCommand object to use with the asynchronous AV/C command functions.
getAncestorInterface: Creates a plug-in object for an ancestor (in the I/O Registry) of the AV/C unit and returns an interface to it.
getAsyncConnectionPlugCounts: Gets the number of plugs in the producer.
getProtocolInterface: Creates a plug-in object for a protocol driver for the FireWire bus the AV/C unit is connected to and returns an interface to it.
getSessionRef: Opens a connection to a device that is not already open.
makeLocalP2POutputConnection: Increments the point-to-point connection count of a unit output plug.
makeP2PInputConnection: Increments the point-to-point connection count of a unit input plug.
makeP2POutputConnection: Increments the point-to-point connection count of a unit output plug.
open: Exclusively opens a connection to the in-kernel device.
openWithSessionRef: Opens a connection to a device that is not already open.
removeCallbackDispatcherFromRunLoop: Removes a dispatcher for kernel callbacks to the specified run loop.
setMessageCallback: Sets callback for user space message routine.
updateAVCCommandTimeout: Updates an AVCCommand's timeout back to 10 seconds.

addCallbackDispatcherToRunLoop

Adds a dispatcher for kernel callbacks to the specified run loop.

IOReturn ( *addCallbackDispatcherToRunLoop)(
    void *self,
    CFRunLoopRef cfRunLoopRef );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
cfRunLoopRef: Reference to a run loop.

Return Value

Returns kIOReturnSuccess on success.

Discussion

The user space portions of the AV/C API communicate with the in-kernel services by messaging the kernel. Similarly, the kernel messages the user space services in response. These responses need to be picked up by a piece of code. This call adds that code to the specified run loop. Most drivers will call this method on the run loop that was created when your task was created. To avoid deadlock you must avoid sleeping (or spin waiting) the run loop to wait for AV/C response. If you do this the dispatcher will never get to run and you will wait forever.

AVCAsynchronousCommandCancel

Cancels a submitted command.

IOReturn ( *AVCAsynchronousCommandCancel)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
pCommandObject: Pointer to an IOFireWireAVCLibAsynchronousCommand object passed back in createAVCAsynchronousCommand.

AVCAsynchronousCommandReinit

Reinitializes an existing IOFireWireAVCLibAsynchronousCommand object, preserving the existing command.

IOReturn ( *AVCAsynchronousCommandReinit)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
pCommandObject: Pointer to an IOFireWireAVCLibAsynchronousCommand object passed back in createAVCAsynchronousCommand.

AVCAsynchronousCommandReinitWithCommandBytes

Reinitializes an existing IOFireWireAVCLibAsynchronousCommand object, replacing the existing command with a new one.

IOReturn ( *AVCAsynchronousCommandReinitWithCommandBytes)(
    void *self, 
    IOFireWireAVCLibAsynchronousCommand *pCommandObject, 
    const UInt8 * command, 
    UInt32 cmdLen);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
pCommandObject: Pointer to an IOFireWireAVCLibAsynchronousCommand object passed back in createAVCAsynchronousCommand.
command: Pointer to the command buffer.
cmdLen: Length of the command buffer.

AVCAsynchronousCommandRelease

Releases an IOFireWireAVCLibAsynchronousCommand object.

IOReturn ( *AVCAsynchronousCommandRelease)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
pCommandObject: Pointer to an IOFireWireAVCLibAsynchronousCommand object passed back in createAVCAsynchronousCommand.

AVCAsynchronousCommandSubmit

Issues the asynchronous command on the bus.

IOReturn ( *AVCAsynchronousCommandSubmit)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
pCommandObject: Pointer to an IOFireWireAVCLibAsynchronousCommand object passed back in createAVCAsynchronousCommand.

AVCCommand

Sends an AV/C command to the device and returns the response.

IOReturn ( *AVCCommand)(
    void *self, 
    const UInt8 * command,
    UInt32 cmdLen,
    UInt8 * response,
    UInt32 *responseLen);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
command: Pointer to command to send.
cmdLen: Length (in bytes) of command.
response: Pointer to place to store the response sent by the device.
responseLen: Pointer to place to store the length of the response. On entry, this parameter contains the size of the response buffer in bytes; on exit, it contains the number of valid bytes in the response buffer.

Discussion

This function will block until the device returns a response or the kernel driver times out.

AVCCommandInGeneration

Sends an AV/C command to the device and returns the response.

IOReturn ( *AVCCommandInGeneration)(
    void *self,
    UInt32 busGeneration, 
    const UInt8 * command,
    UInt32 cmdLen,
    UInt8 * response,
    UInt32 *responseLen);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
busGeneration: FireWire bus generation that the command is valid in.
command: Pointer to command to send.
cmdLen: Length (in bytes) of command.
response: Pointer to place to store the response sent by the device.
responseLen: Pointer to place to store the length of the response. On entry, this parameter contains the size of the response buffer in bytes; on exit, it contains the number of valid bytes in the response buffer.

Discussion

Sends an AV/C command to the device and returns the response. The command must complete in the specified bus generation. This function will block until the device returns a response or the kernel driver times out.

Availability: Interface version 1 or greater.

breakLocalP2PInputConnection

Decrements the point-to-point connection count of a unit input plug.

IOReturn ( *breakP2PInputConnection)(
    void *self,
    UInt32 inputPlug);

Availability: Interface version 3 or greater.

breakLocalP2POutputConnection

Decrements the point-to-point connection count of a unit output plug.

IOReturn ( *breakP2POutputConnection)(
    void *self,
    UInt32 outputPlug);

Availability: Interface version 3 or greater.

breakP2PInputConnection

Decrements the point-to-point connection count of a unit input plug.

IOReturn ( *breakP2PInputConnection)(
    void *self,
    UInt32 inputPlug);

Availability: Interface version 3 or greater.

breakP2POutputConnection

Decrements the point-to-point connection count of a unit output plug.

IOReturn ( *breakP2POutputConnection)(
    void *self,
    UInt32 outputPlug);

Availability: Interface version 3 or greater.

close

Closes an exclusive access to the device.

void ( *close)(
    void *self );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.

Discussion

Closes an exclusive access to the device. When a device is closed it may be unloaded by the kernel. If it is unloaded and then later reappears it will be represented by a different object. You won't be able to use this user client on the new object. The new object will have to be looked up in the I/O Registry and a new user client will have to be opened on it.

createAVCAsynchronousCommand

Creates an IOFireWireAVCLibAsynchronousCommand object to use with the asynchronous AV/C command functions.

IOReturn ( *createAVCAsynchronousCommand)(
    void *self, 
    const UInt8 * command, 
    UInt32 cmdLen, 
    IOFireWireAVCLibAsynchronousCommandCallback completionCallback, 
    void *pRefCon, 
    IOFireWireAVCLibAsynchronousCommand **ppCommandObject);

Parameters

self: Pointer to an IOFireWireAVCLibUnitInterface.
command: Pointer to the command buffer.
cmdLen: The length of the command buffer.
completionCallback: The address of the completion routine.
pRefCon: Pointer to arbitrary data to be returned as the first argument of the callback routine.
ppCommandObject: Pointer to pointer to an IOFireWireAVCLibAsynchronousCommand object to be passed in other asynchronous AV/C command functions.

getAncestorInterface

Creates a plug-in object for an ancestor (in the I/O Registry) of the AV/C unit and returns an interface to it.

void * ( *getAncestorInterface)(
    void *self,
    char *object_class,
    REFIID pluginType,
    REFIID iid);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
object_class: Class name of ancestor of the device to get an interface for.
pluginType: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of plug-in service to be returned for the ancestor.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created plug-in object.

Return Value

Returns a COM-style interface pointer. Returns 0 upon failure.

Availability: Interface version 1 or greater.

getAsyncConnectionPlugCounts

Gets the number of plugs in the producer.

IOReturn ( *getAsyncConnectionPlugCounts) (
    void *self,
    UInt8 *inputPlugCount,
    UInt8 *outputPlugCount );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
inputPlugCount: Pointer to the number of input plugs.
outputPlugCount: Pointer to the number of output plugs.

getProtocolInterface

Creates a plug-in object for a protocol driver for the FireWire bus the AV/C unit is connected to and returns an interface to it.

void * ( *getProtocolInterface)(
    void *self,
    REFIID pluginType,
    REFIID iid);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
pluginType: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of plug-in service to be returned for the created protocol object.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created protocol device object.

Return Value

Returns a COM-style interface pointer. Returns 0 upon failure.

Availability: Interface version 1 or greater.

getSessionRef

Opens a connection to a device that is not already open.

IOFireWireSessionRef ( *getSessionRef)(
    void *self);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.

Return Value

Returns an IOFireWireSessionRef on success.

Discussion

Sometimes it is desirable to open multiple user clients on a device. In the case of FireWire sometimes we wish to have both the FireWire User Client and the AV/C User Client open at the same time. The technique to arbitrate this is as follows:

Open normally the device furthest from the root in the I/O Registry.
Get its sessionRef with the getSessionRef call.
Open the device further up the chain by calling this method and passing the sessionRef returned from the call in step 2.

makeLocalP2POutputConnection

Increments the point-to-point connection count of a unit output plug.

IOReturn ( *makeP2POutputConnection)(
    void *self,
    UInt32 outputPlug,
    UInt32 chan,
    IOFWSpeed speed);

Availability: Interface version 3 or greater.

makeP2PInputConnection

Increments the point-to-point connection count of a unit input plug.

IOReturn ( *makeP2PInputConnection)(
    void *self,
    UInt32 inputPlug,
    UInt32 chan);

Availability: Interface version 3 or greater.

makeP2POutputConnection

Increments the point-to-point connection count of a unit output plug.

IOReturn ( *makeP2POutputConnection)(
    void *self,
    UInt32 outputPlug,
    UInt32 chan,
    IOFWSpeed speed);

Availability: Interface version 3 or greater.

open

Exclusively opens a connection to the in-kernel device.

IOReturn ( *open)(
    void *self );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.

Return Value

Returns kIOReturnSuccess on success.

Discussion

Exclusively opens a connection to the in-kernel device. As long as the in-kernel device object is open, no other drivers will be able to open a connection to the device. When open, the device on the bus may disappear, but the in-kernel object representing it will stay instantiated and can begin communicating with the device again if it ever reappears.

openWithSessionRef

Opens a connection to a device that is not already open.

IOReturn ( *openWithSessionRef)(
    void *self,
    IOFireWireSessionRef sessionRef );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
sessionRef: SessionRef returned from getSessionRef call.

Return Value

Returns kIOReturnSuccess on success.

Discussion

Open normally the device furthest from the root in the I/O Registry.
Get its sessionRef with the getSessionRef call.
Open the device further up the chain by calling this method and passing the sessionRef returned from the call in step 2.

removeCallbackDispatcherFromRunLoop

Removes a dispatcher for kernel callbacks to the specified run loop.

void ( *removeCallbackDispatcherFromRunLoop)(
    void *self );

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.

Discussion

Undoes the work of addCallbackDispatcherToRunLoop.

setMessageCallback

Sets callback for user space message routine.

void ( *setMessageCallback)(
    void *self,
    void *refCon,
    IOFWAVCMessageCallback callback);

Parameters

self: Pointer to IOFireWireAVCLibUnitInterface.
refCon: RefCon to be returned as first argument of completion routine.
callback: Address of completion routine.

Discussion

In FireWire and AV/C, bus status messages are delivered via IOKit's message routine. This routine is emulated in user space for AV/C and FireWire messages via this callback. You should register here for bus reset and reconnect messages.

updateAVCCommandTimeout

Updates an AVCCommand's timeout back to 10 seconds.

IOReturn ( *updateAVCCommandTimeout)(
    void *self);

Discussion

AVCCommands will time out after 10 seconds unless this function is called (from another thread) to update the command's timeout back to 10 seconds.

Availability: Interface version 2 or greater.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2009-02-23