Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access I/O Kit Framework Reference

IOFireWireCommandInterface

Declared In:

IOFireWireLib.h

Overview

IOFireWireLib command object.

Discussion

Represents an object that is configured and submitted to issue synchronous and asynchronous bus commands. This is a superclass containing all command object functionality not specific to any kind of bus transaction.

Note that data may not always be transferred to or from the data buffer for command objects at the time the command is submitted. In some cases the transfer may happen as soon as SetBuffer() (below, v2 interfaces and newer) is called. You can use the SetFlags() call (below, v2 interfaces and newer) to control this behavior.

Functions

Cancel: Cancel command execution
GetAckCode: Gets the most recently received ack code for this transaction.
GetBuffer: Set the command refCon value and callback handler, and submit the command to FireWire for execution.
GetRefCon: Gets the refcon associated with this command
GetResponseCode: Gets the most recently received response code for this transaction.
GetStatus: Return command completion status.
GetTargetAddress: Get command target address.
GetTransferredBytes: Return number of bytes transferred by this command object when it last completed execution.
IsExecuting: Is this command object currently executing?
SetBuffer: Set the buffer where read data should be stored.
SetCallback: Set the completion handler to be called once the command completes asynchronous execution .
SetFlags: Set flags governing this command's execution.
SetGeneration: Set FireWire bus generation for which the command object shall be valid. If the failOnReset attribute has been set, the command will only be considered for execution during the bus generation specified by this function.
SetMaxPacket: Set the maximum size in bytes of packets transferred by this command.
SetMaxPacketSpeed: Gets the most recently received ack code for this transaction.
SetMaxRetryCount: Sets the maximum number of retries for this command.
SetRefCon: Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function.
SetTarget: Set command target address
SetTimeoutDuration: Sets the duration of the timeout for this command.
Submit
SubmitWithRefconAndCallback: Set the command refCon value and callback handler, and submit the command to FireWire for execution.

Cancel

Cancel command execution

IOReturn ( *Cancel)(
    IOFireWireLibCommandRef self,
    IOReturn reason);

Parameters

self: The command object interface of interest

Return Value

An IOReturn result code

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

GetAckCode

Gets the most recently received ack code for this transaction.

UInt32 ( *GetAckCode)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

The FireWire ack code.

GetBuffer

Set the command refCon value and callback handler, and submit the command to FireWire for execution.

void ( *GetBuffer)(
    IOFireWireLibCommandRef self,
    UInt32 *outSize,
    void **outBuf);

Parameters

self: The command object interface of interest

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

GetRefCon

Gets the refcon associated with this command

void * ( *GetRefCon)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

void

GetResponseCode

Gets the most recently received response code for this transaction.

UInt32 ( *GetResponseCode)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

The FireWire response code.

GetStatus

Return command completion status.

IOReturn ( *GetStatus)(
    IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

An IOReturn error code indicating the completion error (if any) returned the last time this command object was executed

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

GetTargetAddress

Get command target address.

void ( *GetTargetAddress)(
    IOFireWireLibCommandRef self,
    FWAddress *outAddr);

Parameters

self: The command object interface of interest
outAddr: A pointer to an FWAddress to contain the function result.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	NO

GetTransferredBytes

Return number of bytes transferred by this command object when it last completed execution.

UInt32 ( *GetTransferredBytes)(
    IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

A UInt32 containing the bytes transferred value

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

IsExecuting

Is this command object currently executing?

const Boolean (*IsExecuting)(IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

Returns true if the command object is executing.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetBuffer

Set the buffer where read data should be stored.

void ( *SetBuffer)(
    IOFireWireLibCommandRef self,
    UInt32 size,
    void *buf);

Parameters

self: The command object interface of interest
size: Size in bytes of the receive buffer.
buf: A pointer to the receive buffer.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetCallback

Set the completion handler to be called once the command completes asynchronous execution .

void ( *SetCallback)(
    IOFireWireLibCommandRef self,
    IOFireWireLibCommandCallback inCallback);

Parameters

self: The command object interface of interest
inCallback: A callback handler. Passing nil forces the command object to execute synchronously.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetFlags

Set flags governing this command's execution.

void ( *SetFlags)(
    IOFireWireLibCommandRef self,
    UInt32 inFlags);

Parameters

self

The command object interface of interest

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this command object. The following values may be used:

kFWCommandNoFlags -- all flags off
kFWCommandInterfaceForceNoCopy -- data sent by this command should always be received/sent directly from the buffer set with SetBuffer(). Whatever data is in the buffer when the command is submitted will be used.
kFWCommandInterfaceForceCopyAlways -- data will always be copied out of the command object data buffer when SetBuffer() is called, up to a maximum allowed size (kFWUserCommandSubmitWithCopyMaxBufferBytes). This can result in faster data transfer. Changes made to the data buffer contents after calling SetBuffer() will be ignored; SetBuffer() should be called whenever the data buffer contents change.
kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object to execute synchronously. The calling context will block until the command object has completed execution or an error occurs. Using synchronous execution can avoid kernel transitions associated with asynchronous completion and often remove the need for a state machine.
kFWCommandInterfaceForceBlockRequest -- Setting this flag causes read and write transactions to use block request packets even if the payload is 4 bytes. If this flag is not set 4 byte transactions will occur using quadlet transactions.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetGeneration

Set FireWire bus generation for which the command object shall be valid. If the failOnReset attribute has been set, the command will only be considered for execution during the bus generation specified by this function.

void ( *SetGeneration)(
    IOFireWireLibCommandRef self,
    UInt32 generation);

Parameters

self: The command object interface of interest
generation: A bus generation. The current bus generation can be obtained from IOFireWireDeviceInterface::GetBusGeneration().

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetMaxPacket

Set the maximum size in bytes of packets transferred by this command.

IOReturn ( *SetMaxPacket)(
    IOFireWireLibCommandRef self,
    IOByteCount maxPacketSize);

Parameters

self: The command object interface of interest
maxPacketSize: Size in bytes of largest packet that should be transferred by this command.

Return Value

An IOReturn result code indicating whether or not the command was successfully submitted

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetMaxPacketSpeed

Gets the most recently received ack code for this transaction.

void ( *SetMaxPacketSpeed)(
    IOFireWireLibCommandRef self,
    IOFWSpeed speed );

Parameters

self: A reference to the command
speed: the desired maximum packet speed

Return Value

void

SetMaxRetryCount

Sets the maximum number of retries for this command.

void ( *SetMaxRetryCount)(
    IOFireWireLibCommandRef self,
    UInt32 count );

Parameters

self: A reference to the command
count: The number of retires

Return Value

void

SetRefCon

Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function.

void ( *SetRefCon)(
    IOFireWireLibCommandRef self,
    void *refCon);

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetTarget

Set command target address

void ( *SetTarget)(
    IOFireWireLibCommandRef self,
    const FWAddress* addr);

Parameters

self: The command object interface of interest
addr: A pointer to an FWAddress.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	NO

SetTimeoutDuration

Sets the duration of the timeout for this command.

void ( *SetTimeoutDuration)(
    IOFireWireLibCommandRef self,
    UInt32 duration );

Parameters

self: A reference to the command
duration: A timeout value in microseconds

Return Value

void

Submit

IOReturn ( *Submit)(
    IOFireWireLibCommandRef self);

Discussion

Description forthcoming

SubmitWithRefconAndCallback

Set the command refCon value and callback handler, and submit the command to FireWire for execution.

IOReturn ( *SubmitWithRefconAndCallback)(
    IOFireWireLibCommandRef self,
    void *refCon,
    IOFireWireLibCommandCallback inCallback);

Parameters

self: The command object interface of interest

Return Value

An IOReturn result code indicating whether or not the command was successfully submitted

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

Member Data

revision
version

revision

UInt32 revision;

Discussion

Interface revision

version

UInt32 version;

Discussion

Interface version

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2009-10-15