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

IOFireWireLibVectorCommandInterface

Declared In:

Overview

IOFireWireLib command object for grouping commands execution.

Discussion

Read and Write commands can be attached in order to the vector command. When the vector command is submitted all the commands are sent to the kernel for execution. When all the commands in a vector command are complete the vector command's completion is called. The advantage over submitting and completeing each command simultaneously is that only one kernel transition will be used for submission and one for completion, regardless of the number of commands in the vector.

Functions

AddCommand: Adds a command to the vector command.
EnsureCapacity: Sets the number of commands this vector can hold.
GetCommandAtIndex: Returns the command at a given index.
GetCommandCount: Returns the number of commands currently in this vector.
GetFlags: Get the flags currently set for this command.
GetIndexOfCommand: Returns the index of the specified command.
GetRefCon: Get the reference constant for this command.
InsertCommandAtIndex: Inserts a command at a given index. Commands at and after this index will be moved to their next sequential index.
IsExecuting: Checks if the vector command is currently executing.
RemoveAllCommands: Removes all commands from the vector.
RemoveCommand: Removes a command to the vector command.
RemoveCommandAtIndex: Removes the command at a give index. Commands at and afte this index will be moved to their previous sequential index.
SetCallback: Set the callback routine for this command.
SetFlags: Set flags governing this command's execution.
SetRefCon(IOFireWireLibVectorCommandRef, UInt32): Set flags governing this command's execution.
SetRefCon(IOFireWireLibVectorCommandRef, void *): Set the reference constant for this command.
Submit(IOFireWireLibVectorCommandRef): Submit this command object to FireWire for execution.
Submit(IOFireWireLibVectorCommandRef, void *, IOFireWireLibCommandCallback): Submit this command object to FireWire for execution.
SubmitWithRefconAndCallback: Submit this command object to FireWire for execution.

AddCommand

Adds a command to the vector command.

void ( *AddCommand)(
    IOFireWireLibVectorCommandRef self,
    IOFireWireLibCommandRef command);

Parameters

self: A reference to the vector command object
command: A reference to the command to add

Return Value

An IOReturn result code

EnsureCapacity

Sets the number of commands this vector can hold.

IOReturn ( *EnsureCapacity)(
    IOFireWireLibVectorCommandRef self,
    UInt32 capacity);

Parameters

self: A reference to the vector command object
capacity: The number of commands this vector command should expect to hold

Return Value

An IOReturn result code

Discussion

The vector can grow dynamically, but for performance reasons developers may want the storage preallocated for a certain number of commmands

GetCommandAtIndex

Returns the command at a given index.

IOFireWireLibCommandRef ( *GetCommandAtIndex)(
    IOFireWireLibVectorCommandRef self,
    UInt32 index);

Parameters

self: A reference to the vector command object
index: The index to return a command from

Return Value

The IOFireWireLibCommandRef at the specified index on return

Discussion

Returns kIOReturnBadArgument if the index is out of bounds.

GetCommandCount

Returns the number of commands currently in this vector.

UInt32 ( *GetCommandCount)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

Return Value

UInt32 The number of commands in this vector

GetFlags

Get the flags currently set for this command.

UInt32 ( *GetFlags)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

Return Value

The flags set in SetFlags

GetIndexOfCommand

Returns the index of the specified command.

UInt32 ( *GetIndexOfCommand)(
    IOFireWireLibVectorCommandRef self,
    IOFireWireLibCommandRef command);

Parameters

self: A reference to the vector command object
command: The command in question

Return Value

The index of the specified command

Discussion

Returns kIOReturnNotFound if the command does not exist in this vector.

GetRefCon

Get the reference constant for this command.

void * ( *GetRefCon)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

Return Value

The reference contant set in SetRefCon

InsertCommandAtIndex

Inserts a command at a given index. Commands at and after this index will be moved to their next sequential index.

void ( *InsertCommandAtIndex)(
    IOFireWireLibVectorCommandRef self,
    IOFireWireLibCommandRef command,
    UInt32 index);

Parameters

self: A reference to the vector command object
command: A reference to the command to be inserted
index: The index to insert the command at.

IsExecuting

Checks if the vector command is currently executing.

Boolean ( *IsExecuting)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

Return Value

True if the command is executing, false otherwise

RemoveAllCommands

Removes all commands from the vector.

void ( *RemoveAllCommands)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

RemoveCommand

Removes a command to the vector command.

void ( *RemoveCommand)(
    IOFireWireLibVectorCommandRef self,
    IOFireWireLibCommandRef command);

Parameters

self: A reference to the vector command object
command: A reference to the command to be removed

Return Value

An IOReturn result code

RemoveCommandAtIndex

Removes the command at a give index. Commands at and afte this index will be moved to their previous sequential index.

void ( *RemoveCommandAtIndex)(
    IOFireWireLibVectorCommandRef self,
    UInt32 index);

Parameters

self: A reference to the vector command object
command: The command in question
outIndex: Will be set to the index of the specified command.

Discussion

Returns kIOReturnBadArgument if the index is out of bounds.

SetCallback

Set the callback routine for this command.

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

Parameters

self: A reference to the vector command object
inCallback: A callback function to be called upon command completion.

Return Value

void

SetFlags

Set flags governing this command's execution.

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

Parameters

self

A reference to the vector command object

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
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.
kFWVectorCommandInterfaceOrdered - Normally all commands in a vector are executed simultaneously. Setting this flag will dispatch a command only after the prior command has completed.

Return Value

void

SetRefCon(IOFireWireLibVectorCommandRef, UInt32)

Set flags governing this command's execution.

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

Parameters

self

A reference to the vector command object

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
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.
kFWVectorCommandInterfaceOrdered - Normally all commands in a vector are executed simultaneously. Setting this flag will dispatch a command only after the prior command has completed.

Return Value

void

SetRefCon(IOFireWireLibVectorCommandRef, void *)

Set the reference constant for this command.

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

Parameters

self: A reference to the vector command object
refCon: A reference constant for 3rd party use.

Return Value

void

Submit(IOFireWireLibVectorCommandRef)

Submit this command object to FireWire for execution.

IOReturn ( *Submit)(
    IOFireWireLibVectorCommandRef self);

Parameters

self: A reference to the vector command object

Return Value

An IOReturn result code

Submit(IOFireWireLibVectorCommandRef, void *, IOFireWireLibCommandCallback)

Submit this command object to FireWire for execution.

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

Parameters

self: A reference to the vector command object
refCon: A reference constant for 3rd party use. This is the same refcon set with SetRefCon and retreived with GetRefCon.
inCallback: A callback function to be called upon command completion.

Return Value

An IOReturn result code

Discussion

A convienence method to set the callback and refcon and then submit.

SubmitWithRefconAndCallback

Submit this command object to FireWire for execution.

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

Parameters

self: A reference to the vector command object
refCon: A reference constant for 3rd party use. This is the same refcon set with SetRefCon and retreived with GetRefCon.
inCallback: A callback function to be called upon command completion.

Return Value

An IOReturn result code

Discussion

A convienence method to set the callback and refcon and then submit.

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