0% found this document useful (0 votes)

2K views1,392 pages

Apple Manual

As title

Uploaded by

Tommaso Scigliuzzo

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

2K views1,392 pages

Apple Manual

As title

Uploaded by

IOFireWireLibPHYPacketListenerInterface 212
Overview 212 Tasks 212 Instance Methods 213 Instance Variables 216

IOFireWireLibVectorCommandInterface 217
Overview 217 Tasks 217 Instance Methods 218 Instance Variables 227

IOFireWireLocalIsochPortInterface 228
Overview 228 Tasks 228 Instance Methods 229 Instance Variables 237

IOFireWireLocalUnitDirectoryInterface 238
Overview 238 Tasks 238 Instance Methods 239 Instance Variables 241

IOFireWireNubInterface 242
Overview 242

IOFireWireNuDCLPoolInterface 244
Overview 244 Tasks 244 Instance Methods 247 Instance Variables 266

Contents

IOUSBDeviceInterface 456
Overview 456 Tasks 456 Instance Methods 458

IOUSBDeviceInterface182 471
Overview 471 Tasks 471 Instance Methods 472

IOUSBDeviceInterface187 477
Overview 477 Tasks 477 Instance Methods 477

IOUSBDeviceInterface197 479
Overview 479 Tasks 479 Instance Methods 479

IOUSBDeviceInterface245 482
Overview 482

IOUSBDeviceInterface300 483
Overview 483 Tasks 483 Instance Methods 483

IOUSBDeviceInterface320 485
Overview 485 Tasks 485 Instance Methods 486

IOUSBDeviceInterface500 489
Overview 489 Tasks 489 Instance Methods 489

IOUSBInterfaceInterface 491
Overview 491

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Tasks 491 Instance Methods 493

IOUSBInterfaceInterface182 514
Overview 514 Tasks 514 Instance Methods 515

IOUSBInterfaceInterface183 522
Overview 522 Tasks 522 Instance Methods 522

IOUSBInterfaceInterface190 524
Overview 524 Tasks 524 Instance Methods 525

IOUSBInterfaceInterface192 529
Overview 529 Tasks 529 Instance Methods 530

IOUSBInterfaceInterface197 537
Overview 537 Tasks 537 Instance Methods 537

MMCDeviceInterface 540
Overview 540 Tasks 540 Instance Methods 541 Instance Variables 560

SCSITaskDeviceInterface 561
Overview 561 Tasks 561 Instance Methods 562 Instance Variables 565

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Constants 635

IOFireWireAVCLib.h Reference 636

Overview 636 Callbacks 636

IOFireWireFamilyCommon.h User-Space Reference 640

Overview 640 Constants 640

IOFireWireLib.h Reference 643

Overview 643 Functions 644 Callbacks 644 Data Types 651 Constants 652

IOFireWireSBP2Lib.h Reference 654

Overview 654 Callbacks 654 Data Types 658 Constants 660

IOFireWireStorageCharacteristics.h User-Space Reference 663

Overview 663 Constants 663

IOFramebufferShared.h User-Space Reference 665

Overview 665 Data Types 665 Constants 671

IOGraphicsLib.h Reference 674

Overview 674 Functions 675 Constants 696

IOGraphicsTypes.h User-Space Reference 698

Overview 698 Data Types 698

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

IOHIDBase.h Reference 714

Overview 714 Callbacks 714 Data Types 718 Constants 719

IOHIDDevice.h User-Space Reference 721

Overview 721 Functions 721

IOHIDDevicePlugIn.h Reference 745

Overview 745 Constants 746

IOHIDElement.h Reference 751

Overview 751 Functions 751

IOHIDKeys.h User-Space Reference 774

Overview 774 Data Types 774 Constants 775

IOHIDLibObsolete.h Reference 813

Overview 813 Callbacks 813 Constants 816

IOHIDManager.h Reference 819

Overview 819 Functions 819 Data Types 832

IOHIDQueue.h Reference 834

Overview 834 Functions 835 Data Types 844

IOHIDTransaction.h Reference 845

Overview 845

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Functions 845 Data Types 855

IOHIDValue.h Reference 856

Overview 856 Functions 856

IOI2CInterface.h User-Space Reference 864

Overview 864 Functions 864 Data Types 868

IOKitLib.h Reference 872

Overview Functions Callbacks Constants 872 873 927 930

IOKitServer.h User-Space Reference 932

Overview 932 Constants 932

IOMedia.h User-Space Reference 936

Overview 936 Constants 936

IOMessage.h User-Space Reference 941

Overview 941 Functions 941 Constants 942

IONetworkController.h User-Space Reference 945

Overview 945 Constants 945

IONetworkData.h User-Space Reference 952

Overview 952 Constants 952

IONetworkInterface.h User-Space Reference 955

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Overview 955 Constants 955

IONetworkLib.h Reference 959

Overview 959 Functions 959 Constants 965

IONetworkMedium.h User-Space Reference 966

Overview 966 Data Types 966 Constants 966

IONetworkStats.h User-Space Reference 968

Overview 968 Data Types 968 Constants 969

IOPM.h User-Space Reference 970

Overview 970 Data Types 970 Constants 971

IOPMKeys.h Reference 979

Overview 979 Constants 979

IOPMLib.h Reference 981

Overview 981 Functions by Task 981 Functions 984 Data Types 1009 Constants 1010

IOPSKeys.h Reference 1021

Overview 1021 Constants 1021

IOPartitionScheme.h User-Space Reference 1036

Overview 1036

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Constants 1036

IOPowerSources.h Reference 1038

Overview 1038 Functions by Task 1038 Functions 1039 Data Types 1045 Constants 1046

IOStorage.h User-Space Reference 1047

Overview 1047 Constants 1047

IOStorageCardCharacteristics.h User-Space Reference 1049

Overview 1049 Constants 1049

IOStorageDeviceCharacteristics.h User-Space Reference 1059

Overview 1059 Constants 1059

IOStorageProtocolCharacteristics.h User-Space Reference 1075

Overview 1075 Constants 1075

IOStreamLib.h Reference 1116

Overview 1116 Functions by Task 1116 Functions 1119 Callbacks 1129 Data Types 1129

IOStreamShared.h User-Space Reference 1131

Overview 1131 Data Types 1131 Constants 1133

IOTypes.h User-Space Reference 1136

Overview 1136 Constants 1136

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

IOUPSPlugIn.h Reference 1138

Overview 1138 Callbacks 1139 Constants 1140

IOUSBLib.h Reference 1142

Overview 1142 Functions 1142 Constants 1146

IOVideoDeviceLib.h User-Space Reference 1175

Overview 1175 Functions 1175 Callbacks 1180 Data Types 1181 Constants 1182

IOVideoDeviceShared.h User-Space Reference 1184

Overview 1184 Constants 1184

IOVideoDeviceUserClient.h User-Space Reference 1186

Overview 1186 Constants 1186

IOVideoTypes.h User-Space Reference 1188

Overview 1188 Data Types 1188 Constants 1190

KextManager.h Reference 1199

Overview 1199 Functions 1199

SCSICmds_INQUIRY_Definitions.h User-Space Reference 1205

Overview 1205 Data Types 1205 Constants 1211

SCSICmds_MODE_Definitions.h User-Space Reference 1238

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Overview 1238 Data Types 1238 Constants 1244

SCSICmds_READ_CAPACITY_Definitions.h User-Space Reference 1256

Overview 1256 Data Types 1256 Constants 1257

SCSICmds_REPORT_LUNS_Definitions.h User-Space Reference 1260

Overview 1260 Data Types 1260 Constants 1262

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference 1264

Overview 1264 Data Types 1264 Constants 1265

SCSICommandDefinitions.h User-Space Reference 1272

Overview 1272 Data Types 1272 Constants 1289

SCSITask.h User-Space Reference 1297

Overview 1297 Callbacks 1297 Data Types 1298 Constants 1308

SCSITaskLib.h Reference 1311

Overview 1311 Callbacks 1311 Constants 1312

USB.h User-Space Reference 1318

Overview 1318 Functions by Task 1318 Functions 1319 Callbacks 1320

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Contents

Data Types 1323 Constants 1350

USBSpec.h User-Space Reference 1378

Overview 1378 Constants 1378

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

Framework Header file directories Companion guide Declared in

/System/Library/Frameworks/IOKit.framework /System/Library/Frameworks/IOKit.framework/Headers I/O Kit Fundamentals ATASMARTLib.h Controls.h IOAudioDefines.h IOAudioTypes.h IOBDBlockStorageDevice.h IOBDMedia.h IOBlockStorageDevice.h IOBlockStorageDriver.h IOCDBlockStorageDevice.h IOCDMedia.h IODVDBlockStorageDevice.h IODVDMedia.h IODataQueue.h IODataQueueClient.h IODataQueueShared.h IOEthernetController.h IOEthernetInterface.h IOEthernetStats.h IOFilterScheme.h IOFireWireAVCLib.h IOFireWireFamilyCommon.h IOFireWireLib.h IOFireWireSBP2Lib.h IOFireWireSBP2Login.h IOFireWireStorageCharacteristics.h IOFramebufferShared.h IOGraphicsLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOHIDBase.h IOHIDDevice.h IOHIDDevicePlugIn.h IOHIDElement.h IOHIDKeys.h IOHIDLibObsolete.h IOHIDManager.h IOHIDQueue.h IOHIDTransaction.h IOHIDValue.h IOI2CInterface.h IOKitLib.h IOKitServer.h IOLib.h IOMedia.h IOMessage.h IONetworkController.h IONetworkData.h IONetworkInterface.h IONetworkLib.h IONetworkMedium.h IONetworkStats.h IOPM.h IOPMKeys.h IOPMLib.h IOPSKeys.h IOPartitionScheme.h IOPowerSources.h IOSharedDataQueue.h IOStorage.h IOStorageCardCharacteristics.h IOStorageDeviceCharacteristics.h IOStorageProtocolCharacteristics.h IOStreamLib.h IOStreamShared.h IOTypes.h IOUPSPlugIn.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOUSBLib.h IOVideoDeviceLib.h IOVideoDeviceShared.h IOVideoDeviceUserClient.h IOVideoTypes.h KextManager.h SCSICmds_INQUIRY_Definitions.h SCSICmds_MODE_Definitions.h SCSICmds_READ_CAPACITY_Definitions.h SCSICmds_REPORT_LUNS_Definitions.h SCSICmds_REQUEST_SENSE_Defs.h SCSICommandDefinitions.h SCSITask.h SCSITaskLib.h USB.h USBSpec.h

The I/O Kit framework implements non-kernel access to I/O Kit objects (drivers and nubs) through the device-interface mechanism.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

COMInterfaces

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface

Declared in

ATASMARTLib.h (page 580)

Overview
Self-Monitoring, Analysis, and Reporting Technology Interface. See section 6.14 and section 8.54 of T13:1410D ATA/ATAPI-6 for details on Self-Monitoring, Analysis, and Reporting Technology feature set.

Tasks
Miscellaneous
GetATAIdentifyData

(page 25) Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command. (page 26) (page 26) toggle SMART Autosave.

SMARTEnableDisableAutosave

SMARTEnableDisableOperations

toggle SMART Operations.

SMARTExecuteOffLineImmediate

(page 26) immediately initiate collection of SMART data. (page 27) Retrieves 512 byte device SMART data structure. (page 27) Retrieves 512 byte device SMART data thresholds structure. (page 27) Reads the 512-byte log at the specified logOffset in the log.

SMARTReadData

SMARTReadDataThresholds

SMARTReadLogAtAddress

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface Instance Methods

SMARTReadLogDirectory

(page 28) Reads the 512-byte log directory. (page 28) see if device has detected a threshold exceeded condition. (page 29) Test the integrity of the device SMART data structure. (page 29) Writes to the 512-byte log at the specified logOffset in the log.

SMARTReturnStatus

SMARTValidateReadData

SMARTWriteLogAtAddress

Instance Methods
GetATAIdentifyData
Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command.
IOReturn ( *GetATAIdentifyData ) ( void *interface, void *buffer, UInt32 inSize, UInt32 *outSize );

Parameters
interface

A valid IOATASMARTInterface**.
buffer

A valid buffer.
inSize

The number of bytes to place in the buffer.

outSize

The number of bytes placed in the buffer. Can be NULL if the information is not required by the caller. Return Value An IOReturn result code. If inSize is greater than 512 or less than 1, kIOReturnBadArgument is returned. Discussion Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command. See section 8.15 of ATA/ATAPI-6. The data placed in buffer is guaranteed to be in native endian form on return. (i.e. it will be byte swapped on big endian platforms, so the caller need not do anything)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface Instance Methods

SMARTEnableDisableAutosave
toggle SMART Autosave.
IOReturn ( *SMARTEnableDisableAutosave ) ( void *interface, Boolean enable );

Parameters
enable

Passing true will ENABLE SMART Autosave, false will DISABLE SMART Autosave. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client. Discussion See section 8.54.2 of ATA/ATAPI-6.

SMARTEnableDisableOperations
toggle SMART Operations.
IOReturn ( *SMARTEnableDisableOperations ) ( void *interface, Boolean enable );

Parameters
enable

Passing true will ENABLE SMART operations, false will DISABLE SMART operations. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client. Discussion See section 8.54.1 and 8.54.3 of ATA/ATAPI-6.

SMARTExecuteOffLineImmediate
immediately initiate collection of SMART data.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface Instance Methods

IOReturn ( SMARTExecuteOffLineImmediate ) ( void interface, Boolean extendedTest );

Parameters
extendedTest

passing true will collect "off-line" extended test, false short test. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client. Discussion See section 8.54.4 of ATA/ATAPI-6.

SMARTReadData
Retrieves 512 byte device SMART data structure.
IOReturn ( *SMARTReadData ) ( void *interface, ATASMARTData *data );

Discussion See section 8.54.5 of ATA/ATAPI-6. Will return an appropiate error if command can not be completed.

SMARTReadDataThresholds
Retrieves 512 byte device SMART data thresholds structure.
IOReturn ( *SMARTReadDataThresholds ) ( void *interface, ATASMARTDataThresholds *dataThresholds );

Discussion Retrieves 512 byte device SMART data thresholds structure. This command is not defined as part of ATA/ATAPI-6, but is implemented by a large variety of manufacturers. Will return an appropiate error if command can not be completed.

SMARTReadLogAtAddress
Reads the 512-byte log at the specified logOffset in the log.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface Instance Methods

IOReturn ( *SMARTReadLogAtAddress ) ( void *interface, UInt32 logOffset, void *buffer, UInt32 size );

Discussion Reads the 512-byte log at the specified logOffset in the log. See section 8.54.6.4 of ATA/ATAPI-6.

SMARTReadLogDirectory
Reads the 512-byte log directory.
IOReturn ( *SMARTReadLogDirectory ) ( void *interface, ATASMARTLogDirectory *logData );

Discussion The log directory is a directory of all possible SMART logs available from the drive.

SMARTReturnStatus
see if device has detected a threshold exceeded condition.
IOReturn ( *SMARTReturnStatus ) ( void *interface, Boolean *exceededCondition );

Parameters
exceededCondition

if exceededCondition is non-zero the device threshold exceeded condition. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client. Discussion The caller will poll this function and if exceededCondition is non-zero and we returned kIOReturnSuccess the device threshold exceeded condition. This would prompt the caller to call ATASMARTReadData to get more information. See section 8.54.7 of ATA/ATAPI-6.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOATASMARTInterface Instance Methods

SMARTValidateReadData
Test the integrity of the device SMART data structure.
IOReturn ( *SMARTValidateReadData ) ( void *interface, const ATASMARTData *data );

Discussion The data structure checksum is the two's complement of the sum of the first 511 bytes in the data structure. The sum of all 512 bytes will be zero when the checksum is correct. See section 8.54.5.8.7 of ATA/ATAPI-6. Will return an error if checksum fails.

SMARTWriteLogAtAddress
Writes to the 512-byte log at the specified logOffset in the log.
IOReturn ( *SMARTWriteLogAtAddress ) ( void *interface, UInt32 logOffset, const void *buffer, UInt32 size );

Discussion Writes to the 512-byte log at the specified logOffset in the log. See section 8.54.8.4 of ATA/ATAPI-6.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Description forthcoming

Tasks
Miscellaneous
Cancel

(page 32) Cancel command execution (page 32) Gets the most recently received ack code for this transaction. (page 33) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 33) Gets the refcon associated with this command (page 34) Gets the most recently received response code for this transaction. (page 34) Return command completion status. (page 35) Get command target address. (page 35) Return number of bytes transferred by this command object when it last completed execution. (page 36) Is this command object currently executing?

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

GetTargetAddress

GetTransferredBytes

IsExecuting

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Tasks

SetBuffer

(page 37) Set the buffer where read data should be stored. (page 37) Set the completion handler to be called once the command completes asynchronous execution . (page 38) Set the new channel to transmit the AsyncStream command. (page 38) Set flags governing this command's execution. (page 40) 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. (page 40) Set the maximum size in bytes of packets transferred by this command. (page 41) Gets the most recently received ack code for this transaction. (page 41) Sets the maximum number of retries for this command. (page 42) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 42) Set the sync bits for the AsynStream packets. (page 43) Set the tag bits for the AsynStream packets. (page 43) Set command target address (page 44) Sets the duration of the timeout for this command. (page 44)

SetCallback

SetChannel

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

SetSyncBits

IOFireWireAsyncStreamCommandInterface Instance Methods

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID NO YES YES YES YES YES YES YES

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES 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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES NO NO NO YES NO YES NO

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

inCallback

A callback handler. Passing nil forces the command object to execute synchronously. Discussion Availability: (for interfaces obtained with ID)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

SetChannel
Set the new channel to transmit the AsyncStream command.
void ( *SetChannel)( IOFireWireLibAsyncStreamCommandRef self, UInt32 channel );

Parameters
self

The command object interface of interest

channel

The channel for AsyncStream command transmit. Discussion Available in v1 and newer.

SetFlags
Set flags governing this command's execution.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES 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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES NO NO NO YES NO YES NO

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

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)

SetSyncBits
Set the sync bits for the AsynStream packets.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

void ( *SetSyncBits)( IOFireWireLibAsyncStreamCommandRef self, UInt16 sync );

Parameters
self

The command object interface of interest

sync

The value for sync bits in the AsyncStream packet Discussion Available in v1 and newer.

SetTagBits
Set the tag bits for the AsynStream packets.
void ( *SetTagBits)( IOFireWireLibAsyncStreamCommandRef self, UInt16 tag );

Parameters
self

The command object interface of interest

tag

The value for tag bits in the AsyncStream packet Discussion Available in v1 and newer.

SetTarget
Set command target address
void ( *SetTarget)( IOFireWireLibCommandRef self, const FWAddress *addr);

Parameters
self

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Methods

addr

A pointer to an FWAddress. Discussion Availability: (for interfaces obtained with ID)

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Variables

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

Instance Variables
revision
UInt32 revision;

Interface revision.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAsyncStreamCommandInterface Instance Variables

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibConsumerInterface

Declared in

IOFireWireAVCLib.h (page 636)

Overview
Interface for an asynchronous connection consumer. Used to receive data from an asynchronous connection producer.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface

Declared in

IOFireWireAVCLib.h (page 636)

Overview
Initial interface discovered for all AVC protocol drivers. The IOFireWireAVCLibProtocolInterface is used to set up local plug control registers and to receive AVC requests.

Tasks
Miscellaneous
addCallbackDispatcherToRunLoop

(page 50) Adds a dispatcher for kernel callbacks to the specified run loop. (page 50) Installs a virtual AVC subunit. (page 51) Allocates an input plug. (page 52) Allocates an output plug. (page 52) Establishes an internal AVC plug connection between subunit/unit plugs. (page 53) Breaks an internal AVC plug connection between subunit/unit plugs. (page 54) Deallocates an input plug. (page 55) Deallocates an output plug.

addSubunit

allocateInputPlug

allocateOutputPlug

connectTargetPlugs

disconnectTargetPlugs

freeInputPlug

freeOutputPlug

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Tasks

getSubunitPlugSignalFormat

(page 55) Gets the signal format of the specifed plug. (page 55) Gets the connection details for a specific plug. (page 56) Installs a command handler for handling specific incoming AVC commands. (page 57) Publishes an AVC unit directory in the config ROM. (page 57) Returns the current value of the input master plug. (page 58) Returns the current value of an input plug. (page 58) Returns the current value of the output master plug. (page 58) Returns the current value of an output plug. (page 59) Removes a dispatcher for kernel callbacks to the specified run loop. (page 59) Sends an AVC response packet. (page 59) This function has been deprecated. Use installAVCCommandHandler instead. (page 60) Sets callback for user space message routine. (page 60) Sets the signal format of the specifed plug. (page 61) Updates the value of the master input plug (simulating a lock transaction). (page 61) Updates the value of an input plug (simulating a lock transaction). (page 62) Updates the value of the master output plug (simulating a lock transaction). (page 62) Updates the value of an output plug (simulating a lock transaction).

getTargetPlugConnection

installAVCCommandHandler

publishAVCUnitDirectory

readInputMasterPlug

readInputPlug

readOutputMasterPlug

readOutputPlug

removeCallbackDispatcherFromRunLoop

sendAVCResponse

setAVCRequestCallback

setMessageCallback

setSubunitPlugSignalFormat

updateInputMasterPlug

updateInputPlug

updateOutputMasterPlug

updateOutputPlug

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

Instance Methods
addCallbackDispatcherToRunLoop
Adds a dispatcher for kernel callbacks to the specified run loop.
IOReturn ( *addCallbackDispatcherToRunLoop)( void *self, CFRunLoopRef cfRunLoopRef );

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
cfRunLoopRef

Reference to a run loop. Return Value Returns kIOReturnSuccess on success. Discussion The user space portions of the AVC 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 AVC response. If you do this the dispatcher will never get to run and you will wait forever.

addSubunit
Installs a virtual AVC subunit.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *addSubunit)( void *self, UInt32 subunitType, UInt32 numSourcePlugs, UInt32 numDestPlugs, void *refCon, IOFWAVCSubunitPlugHandlerCallback callback, UInt32 *pSubunitTypeAndID);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
subunitType

The type of subunit to create.

numSourcePlugs

The number of source plugs for this subunit.

numDestPlugs

The number of destination plugs for this subunit.

refCon

Arbitrary value passed back as first argument of callback.

callback

A pointer to the callback to receive plug management messages.

pSubunitTypeAndID

A pointer to a byte to hold the returned subunit address for the new subunit.

allocateInputPlug
Allocates an input plug.
IOReturn ( *allocateInputPlug)( void *self, void *refcon, IOFWAVCPCRCallback func, UInt32 *plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
refcon

Arbitrary value passed back as first argument of callback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

func

Callback function when a successful lock transaction to the plug has been performed.
plug

Set to the plug number if a plug is successfully allocated.

allocateOutputPlug
Allocates an output plug.
IOReturn ( *allocateOutputPlug)( void *self, void *refcon, IOFWAVCPCRCallback func, UInt32 *plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
refcon

Arbitrary value passed back as first argument of callback.

func

Callback function when a successful lock transaction to the plug has been performed.
plug

Set to the plug number if a plug is successfully allocated.

connectTargetPlugs
Establishes an internal AVC plug connection between subunit/unit plugs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *connectTargetPlugs)( void *self, UInt32 sourceSubunitTypeAndID, IOFWAVCPlugTypes sourcePlugType, UInt32 *pSourcePlugNum, UInt32 destSubunitTypeAndID, IOFWAVCPlugTypes destPlugType, UInt32 *pDestPlugNum, bool lockConnection, bool permConnection);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
sourceSubunitTypeAndID

The subunit type and ID for the source plug

sourcePlugType

The source plug type.

pSourcePlugNum

A pointer to the source plug num. Will return the actual source plug num here.
destSubunitTypeAndID

The subunit type and ID for the destination plug.

destPlugType

The dest plug type.

pDestPlugNum

A pointer to the dest plug num. Will return the actual dest plug num here.
lockConnection

A flag to specify if this connection should be locked.

permConnection

A flag to specify if this connection is permanent.

disconnectTargetPlugs
Breaks an internal AVC plug connection between subunit/unit plugs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *disconnectTargetPlugs)( void *self, UInt32 sourceSubunitTypeAndID, IOFWAVCPlugTypes sourcePlugType, UInt32 sourcePlugNum, UInt32 destSubunitTypeAndID, IOFWAVCPlugTypes destPlugType, UInt32 destPlugNum);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
sourceSubunitTypeAndID

The subunit type and ID for the source plug.

sourcePlugType

The source plug type.

sourcePlugNum

The source plug num.

destSubunitTypeAndID

The subunit type and ID for the destination plug.

destPlugType

The dest plug type.

destPlugNum

The dest plug num.

freeInputPlug
Deallocates an input plug.
void ( *freeInputPlug)( void *self, UInt32 plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateInputPlug.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

freeOutputPlug
Deallocates an output plug.
void ( *freeOutputPlug)( void *self, UInt32 plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateOutputPlug.

getSubunitPlugSignalFormat
Gets the signal format of the specifed plug.
IOReturn ( *getSubunitPlugSignalFormat)( void *self, UInt32 subunitTypeAndID, IOFWAVCPlugTypes plugType, UInt32 plugNum, UInt32 *pSignalFormat);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID

The subunit type and ID of the plug.

plugType

The plug type.

plugNum

The plug number.

pSignalFormat

A pointer to the location to return the signal format value.

getTargetPlugConnection
Gets the connection details for a specific plug.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *getTargetPlugConnection)( void *self, UInt32 subunitTypeAndID, IOFWAVCPlugTypes plugType, UInt32 plugNum, UInt32 *pConnectedSubunitTypeAndID, IOFWAVCPlugTypes *pConnectedPlugType, UInt32 *pConnectedPlugNum, bool *pLockConnection, bool *pPermConnection);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID

The subunit type and ID of the plug.

plugType

The plug type.

plugNum

The plug number.

pConnectedSubunitTypeAndID

The subunit type and ID of the connected plug.

pConnectedPlugType

The type of the connected plug.

pConnectedPlugNum

The number of the connected plug.

pLockConnection

A pointer for returning the lock status of the connection.

pPermConnection

A pointer for returning the perm status of the connection.

installAVCCommandHandler
Installs a command handler for handling specific incoming AVC commands.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *installAVCCommandHandler)( void *self, UInt32 subUnitTypeAndID, UInt32 opCode, void *refCon, IOFWAVCCommandHandlerCallback callback);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
subUnitTypeAndID

The subunit type and ID for this command handler.

opCode

The opcode for this command handler.

refCon

Arbitrary value passed back as first argument of callback.

callback

A pointer to the callback function

publishAVCUnitDirectory
Publishes an AVC unit directory in the config ROM.
IOReturn ( *publishAVCUnitDirectory)( void *self);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.

readInputMasterPlug
Returns the current value of the input master plug.
UInt32 ( *readInputMasterPlug)( void *self);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

readInputPlug
Returns the current value of an input plug.
UInt32 ( *readInputPlug)( void *self, UInt32 plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateInputPlug.

readOutputMasterPlug
Returns the current value of the output master plug.
UInt32 ( *readOutputMasterPlug)( void *self);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.

readOutputPlug
Returns the current value of an output plug.
UInt32 ( *readOutputPlug)( void *self, UInt32 plug);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateOutputPlug.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

removeCallbackDispatcherFromRunLoop
Removes a dispatcher for kernel callbacks to the specified run loop.
void ( *removeCallbackDispatcherFromRunLoop)( void *self );

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface. Discussion Undoes the work of addCallbackDispatcherToRunLoop.

sendAVCResponse
Sends an AVC response packet.
IOReturn ( *sendAVCResponse)( void *self, UInt32 generation, UInt16 nodeID, const char *response, UInt32 responseLen);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
generation

The Firewire bus generation that this response should be sent in.
nodeID

The node ID of the device we are sending this response to.

response

A pointer to the response bytes.

responseLen

The number of response bytes.

setAVCRequestCallback
This function has been deprecated. Use installAVCCommandHandler instead.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *setAVCRequestCallback)( void *self, UInt32 subUnitType, UInt32 subUnitID, void *refCon, IOFWAVCRequestCallback callback);

setMessageCallback
Sets callback for user space message routine.
void ( *setMessageCallback)( void *self, void *refCon, IOFWAVCMessageCallback callback);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
refCon

RefCon to be returned as first argument of completion routine.

callback

Address of completion routine. Discussion In FireWire and AVC, bus status messages are delivered via IOKit's message routine. This routine is emulated in user space for AVC and FireWire messages via this callback. You should register here for bus reset and reconnect messages.

setSubunitPlugSignalFormat
Sets the signal format of the specifed plug.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *setSubunitPlugSignalFormat)( void *self, UInt32 subunitTypeAndID, IOFWAVCPlugTypes plugType, UInt32 plugNum, UInt32 signalFormat);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID

The subunit type and ID of the plug.

plugType

The plug type.

plugNum

The plug number.

signalFormat

The 32-bit signal format value.

updateInputMasterPlug
Updates the value of the master input plug (simulating a lock transaction).
IOReturn ( *updateInputMasterPlug)( void *self, UInt32 oldVal, UInt32 newVal);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
oldVal

Value returned by readInputMasterPlug.

newVal

New value to store in plug if its current value is oldVal.

updateInputPlug
Updates the value of an input plug (simulating a lock transaction).

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *updateInputPlug)( void *self, UInt32 plug, UInt32 oldVal, UInt32 newVal);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateInputPlug.

oldVal

Value returned by readInputPlug.

newVal

New value to store in plug if its current value is oldVal.

updateOutputMasterPlug
Updates the value of the master output plug (simulating a lock transaction).
IOReturn ( *updateOutputMasterPlug)( void *self, UInt32 oldVal, UInt32 newVal);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
oldVal

Value returned by readOutputMasterPlug.

newVal

New value to store in plug if its current value is oldVal.

updateOutputPlug
Updates the value of an output plug (simulating a lock transaction).

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibProtocolInterface Instance Methods

IOReturn ( *updateOutputPlug)( void *self, UInt32 plug, UInt32 oldVal, UInt32 newVal);

Parameters
self

Pointer to IOFireWireAVCLibProtocolInterface.
plug

Value returned by allocateOutputPlug.

oldVal

Value returned by readOutputPlug.

newVal

New value to store in plug if its current value is oldVal.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface

Declared in

IOFireWireAVCLib.h (page 636)

Overview
Initial interface discovered for all AVC Unit drivers. The IOFireWireAVCLibUnitInterface is the initial interface discovered by most drivers. It supplies the methods that control the operation of the AVC 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.

Tasks
Miscellaneous
addCallbackDispatcherToRunLoop

(page 66) Adds a dispatcher for kernel callbacks to the specified runloop. (page 67) (page 67) (page 67)

AVCAsynchronousCommandCancel

AVCAsynchronousCommandReinit

AVCAsynchronousCommandReinitWithCommandBytes

AVCAsynchronousCommandRelease

(page 67)

AVCAsynchronousCommandSubmit

(page 67)

AVCCommand

(page 67) Sends an AVC command to the device and returns the response.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Tasks

AVCCommandInGeneration

(page 68) Sends an AVC command to the device and returns the response. (page 69) Decrements the point-to-point connection count of a unit input plug. (page 69) Decrements the point-to-point connection count of a unit output plug. (page 69) Closes an exclusive access to the device. (page 70)

breakP2PInputConnection

breakP2POutputConnection

createAVCAsynchronousCommand

getAncestorInterface

(page 70) Creates a plug-in object for an ancestor (in the I/O Registry) of the AVC unit and returns an interface to it. (page 71) Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit is connected to and returns an interface to it. (page 71) Get the session reference. (page 72) Increments the point-to-point connection count of a unit input plug. (page 72) Increments the point-to-point connection count of a unit output plug.

getProtocolInterface

getSessionRef

makeP2PInputConnection

makeP2POutputConnection

open

(page 72) Exclusively opens a connection to the in-kernel device. (page 73) Opens a connection to a device that is not already open. (page 74) Removes a dispatcher for kernel callbacks to the specified run loop. (page 74) Sets callback for user space message routine. (page 75) Updates an AVCCommand's timeout back to 10 seconds.

openWithSessionRef

removeCallbackDispatcherFromRunLoop

setMessageCallback

updateAVCCommandTimeout

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

Instance Methods
addCallbackDispatcherToRunLoop
Adds a dispatcher for kernel callbacks to the specified runloop.
IOReturn ( *addCallbackDispatcherToRunLoop)( void *self, CFRunLoopRef cfRunLoopRef );

Parameters
self

Pointer to IOFireWireAVCLibUnitInterface.
cfRunLoopRef

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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

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

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

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

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

AVCCommand
Sends an AVC command to the device and returns the response.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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. Discussion This function will block until the device returns a response or the kernel driver times out.

AVCCommandInGeneration
Sends an AVC 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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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. Discussion Sends an AVC command to the device and returns the response. The command must complete in the specified bus generation. This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?). This function will block until the device returns a response or the kernel driver times out.

breakP2PInputConnection
Decrements the point-to-point connection count of a unit input plug.
IOReturn ( *breakP2PInputConnection)( void *self, UInt32 inputPlug);

Discussion This function is only available if the interface version is > 3.

breakP2POutputConnection
Decrements the point-to-point connection count of a unit output plug.
IOReturn ( *breakP2POutputConnection)( void *self, UInt32 outputPlug);

Discussion This function is only available if the interface version is > 3.

close
Closes an exclusive access to the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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
IOReturn ( *createAVCAsynchronousCommand)( void *self, const UInt8 *command, UInt32 cmdLen, IOFireWireAVCLibAsynchronousCommandCallback completionCallback, void *pRefCon, IOFireWireAVCLibAsynchronousCommand **ppCommandObject);

getAncestorInterface
Creates a plug-in object for an ancestor (in the I/O Registry) of the AVC 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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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. Discussion This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?).

getProtocolInterface
Creates a plug-in object for a protocol driver for the FireWire bus the AVC 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. Discussion This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?).

getSessionRef
Get the session reference.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

IOFireWireSessionRef ( getSessionRef)( void self);

Parameters
self

Pointer to IOFireWireAVCLibUnitInterface. Return Value Returns a sessionRef on success. Discussion Gets the sessionRef to be used with openWithSessionRef.

makeP2PInputConnection
Increments the point-to-point connection count of a unit input plug.
IOReturn ( *makeP2PInputConnection)( void *self, UInt32 inputPlug, UInt32 chan);

Discussion This function is only available if the interface version is > 3.

makeP2POutputConnection
Increments the point-to-point connection count of a unit output plug.
IOReturn ( *makeP2POutputConnection)( void *self, UInt32 outputPlug, UInt32 chan, IOFWSpeed speed);

Discussion This function is only available if the interface version is > 3.

open
Exclusively opens a connection to the in-kernel device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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
sessionRef

SessionRef returned from getSessionRef call.

self

Pointer to IOFireWireAVCLibUnitInterface. Return Value Returns kIOReturnSuccess 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 AVC User Client open at the same time. The technique to arbitrate this is as follows: First open normally the device furthest from the root in the I/O Registry. Second, get its sessionRef with the getSessionRef call.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

Third, 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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireAVCLibUnitInterface Instance Methods

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. This function is only available if the interface version is > 2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib command object. 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.

Tasks
Miscellaneous
Cancel

(page 78) Cancel command execution (page 78) Gets the most recently received ack code for this transaction. (page 79) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 79) Gets the refcon associated with this command (page 80) Gets the most recently received response code for this transaction. (page 80) Return command completion status.

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Tasks

GetTargetAddress

(page 81) Get command target address. (page 81) Return number of bytes transferred by this command object when it last completed execution. (page 82) Is this command object currently executing? (page 83) Set the buffer where read data should be stored. (page 83) Set the completion handler to be called once the command completes asynchronous execution . (page 84) Set flags governing this command's execution. (page 85) 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. (page 86) Set the maximum size in bytes of packets transferred by this command. (page 87) Gets the most recently received ack code for this transaction. (page 87) Sets the maximum number of retries for this command. (page 88) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 88) Set command target address (page 89) Sets the duration of the timeout for this command. (page 89)

GetTransferredBytes

IsExecuting

SetBuffer

SetCallback

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

IOFireWireCommandInterface Instance Methods

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.

IOFireWireCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Methods

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

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

generation

SetMaxPacket
Set the maximum size in bytes of packets transferred by this command.
IOReturn ( *SetMaxPacket)( IOFireWireLibCommandRef self, IOByteCount maxPacketSize);

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Methods

count

The number of retires Return Value void

Discussion Availability: (for interfaces obtained with ID)

SetTarget
Set command target address
void ( *SetTarget)( IOFireWireLibCommandRef self, const FWAddress *addr);

Parameters
self

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Methods

addr

A pointer to an FWAddress. Discussion Availability: (for interfaces obtained with ID)

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Variables

Parameters
self

Instance Variables
revision
UInt32 revision;

Interface revision

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCommandInterface Instance Variables

version
UInt32 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Description forthcoming

Tasks
Miscellaneous
Cancel

(page 93) Cancel command execution (page 94) Was the last lock operation successful? (page 94) Return command completion status. (page 95) Get command target address. (page 96) Return number of bytes transferred by this command object when it last completed execution. (page 96) Is this command object currently executing? (page 97) Get the 32-bit value returned on the last compare swap operation. (page 98) Get the 64-bit value returned on the last compare swap operation. (page 98) Set the completion handler to be called once the command completes asynchronous execution .

DidLock

GetStatus

GetTargetAddress

GetTransferredBytes

IsExecuting

Locked

Locked64

SetCallback

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

SetFlags

(page 99) Set flags governing this command's execution. (page 99) 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. (page 100) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 100) Set command target address (page 101) Set values for 32-bit compare swap operation. Calling this function will make the command object perform 32-bit compare swap transactions on the bus. To perform 64-bit compare swap operations, use the SetValues64() call, below. (page 102) Set values for 64-bit compare swap operation. Calling this function will make the command object perform 64-bit compare swap transactions on the bus. To perform 32-bit compare swap operations, use the SetValues() call, above. (page 102)

SetGeneration

SetRefCon

SetTarget

SetValues

SetValues64

Submit

SubmitWithRefconAndCallback

(page 102) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

Return Value An IOReturn result code Discussion Availability: (for interfaces obtained with ID)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

DidLock
Was the last lock operation successful?
Boolean ( *DidLock)( IOFireWireLibCompareSwapCommandRef self);

Parameters
self

The command object interface of interest Return Value Returns true if the last lock operation performed by this command object was successful, false otherwise. Discussion Available in v2 and newer.

GetStatus
Return command completion status.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

IOReturn ( *GetStatus)( IOFireWireLibCommandRef self);

Parameters
self

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)
kIOFireWireAsyncStreamCommandInterfaceID NO

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES

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)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

IsExecuting
Is this command object currently executing?

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

Locked
Get the 32-bit value returned on the last compare swap operation.
IOReturn ( *Locked)( IOFireWireLibCompareSwapCommandRef self, UInt32 *oldValue);

Parameters
self

The command object interface of interest

oldValue

A pointer to contain the value returned by the target of this command on the last compare swap operation Return Value Returns kIOReturnBadArgument if the last compare swap operation performed was 64-bit. Discussion Available in v2 and newer.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

Locked64
Get the 64-bit value returned on the last compare swap operation.
IOReturn ( *Locked64)( IOFireWireLibCompareSwapCommandRef self, UInt64 *oldValue);

Parameters
self

The command object interface of interest

oldValue

A pointer to contain the value returned by the target of this command on the last compare swap operation Return Value Returns kIOReturnBadArgument if the last compare swap performed was 32-bit. Discussion Available in v2 and newer.

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES

SetFlags
Set flags governing this command's execution.
void ( *SetFlags)( IOFireWireLibCompareSwapCommandRef 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. Discussion Available in v2 and newer. Same as SetFlags() above.

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)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

IOFireWireCompareSwapCommandInterface Instance Methods

kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES YES

Discussion Availability: (for interfaces obtained with ID)

SetTarget
Set command target address

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

100

IOFireWireCompareSwapCommandInterface Instance Methods

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)

SetValues
Set values for 32-bit compare swap operation. Calling this function will make the command object perform 32-bit compare swap transactions on the bus. To perform 64-bit compare swap operations, use the SetValues64() call, below.
void ( *SetValues)( IOFireWireLibCompareSwapCommandRef self, UInt32 cmpVal, UInt32 newVal);

Parameters
self

The command object interface of interest

cmpVal

The value expected at the address targeted by this command object

newVal

The value to be written at the address targeted by this command object

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

101

IOFireWireCompareSwapCommandInterface Instance Methods

Discussion Available in v2 and newer.

SetValues64
Set values for 64-bit compare swap operation. Calling this function will make the command object perform 64-bit compare swap transactions on the bus. To perform 32-bit compare swap operations, use the SetValues() call, above.
void ( *SetValues64)( IOFireWireLibCompareSwapCommandRef self, UInt64 cmpVal, UInt64 newVal);

Parameters
self

The command object interface of interest

cmpVal

The value expected at the address targeted by this command object

newVal

The value to be written at the address targeted by this command object Discussion Available in v2 and newer.

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

102

IOFireWireCompareSwapCommandInterface Instance Variables

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

Parameters
self

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

103

IOFireWireCompareSwapCommandInterface_v3

Declared in

IOFireWireLib.h (page 643)

Overview
Description forthcoming

Tasks
Miscellaneous
Cancel

(page 106) Cancel command execution (page 107) Was the last lock operation successful? (page 107) Gets the most recently received ack code for this transaction. (page 107) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 108) Gets the refcon associated with this command (page 108) Gets the most recently received response code for this transaction. (page 109) Return command completion status. (page 109) Get command target address. (page 110) Return number of bytes transferred by this command object when it last completed execution.

DidLock

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

GetTargetAddress

GetTransferredBytes

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

104

IOFireWireCompareSwapCommandInterface_v3 Tasks

IsExecuting

(page 111) Is this command object currently executing? (page 111) Get the 32-bit value returned on the last compare swap operation. (page 112) Get the 64-bit value returned on the last compare swap operation. (page 112) Set the buffer where read data should be stored. (page 113) Set the completion handler to be called once the command completes asynchronous execution . (page 114) Set flags governing this command's execution. (page 115) 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. (page 116) Set the maximum size in bytes of packets transferred by this command. (page 116) Gets the most recently received ack code for this transaction. (page 117) Sets the maximum number of retries for this command. (page 117) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 118) Set command target address (page 118) Sets the duration of the timeout for this command. (page 119) Set values for 32-bit compare swap operation. Calling this function will make the command object perform 32-bit compare swap transactions on the bus. To perform 64-bit compare swap operations, use the SetValues64() call, below.

Locked

Locked64

SetBuffer

SetCallback

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

SetTarget

SetTimeoutDuration

SetValues

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

105

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

SetValues64

(page 119) Set values for 64-bit compare swap operation. Calling this function will make the command object perform 64-bit compare swap transactions on the bus. To perform 32-bit compare swap operations, use the SetValues() call, above. (page 120)

Submit

SubmitWithRefconAndCallback

Discussion Availability: (for interfaces obtained with ID)

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

108

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

GetStatus
Return command completion status.
IOReturn ( *GetStatus)( IOFireWireLibCommandRef self);

Parameters
self

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

109

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

Return Value Returns kIOReturnBadArgument if the last compare swap operation performed was 64-bit. Discussion Available in v2 and newer.

Locked64
Get the 64-bit value returned on the last compare swap operation.
IOReturn ( *Locked64)( IOFireWireLibCompareSwapCommandV3Ref self, UInt64 *oldValue);

Parameters
self

The command object interface of interest

oldValue

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

112

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

buf

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

113

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES 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:

Discussion Availability: (for interfaces obtained with ID)

kIOFireWireAsyncStreamCommandInterfaceID YES

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

114

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

Parameters
self

A reference to the command

count

The number of retires Return Value void

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

117

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES 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)

SetTimeoutDuration
Sets the duration of the timeout for this command.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

118

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

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

Parameters
self

A reference to the command

duration

A timeout value in microseconds Return Value void

Parameters
self

The command object interface of interest

cmpVal

The value expected at the address targeted by this command object

newVal

The value to be written at the address targeted by this command object Discussion Available in v2 and newer.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

119

IOFireWireCompareSwapCommandInterface_v3 Instance Methods

void ( *SetValues64)( IOFireWireLibCompareSwapCommandV3Ref self, UInt64 cmpVal, UInt64 newVal);

Parameters
self

The command object interface of interest

cmpVal

The value expected at the address targeted by this command object

newVal

The value to be written at the address targeted by this command object Discussion Available in v2 and newer.

Submit
IOReturn ( *Submit)( IOFireWireLibCommandRef self);

Discussion Description forthcoming

Parameters
self

The command object interface of interest Return Value An IOReturn result code indicating whether or not the command was successfully submitted

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

120

IOFireWireCompareSwapCommandInterface_v3 Instance Variables

Discussion Availability: (for interfaces obtained with ID)

Instance Variables
revision
UInt32 revision;

Interface version.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

121

IOFireWireConfigDirectoryInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib device config ROM browsing interface Represents an interface to the config ROM of a remote device. You can use the methods of this interface to browser the ROM and obtain key values. You can also create additional IOFireWireConfigDirectoryInterface's to represent subdirectories within the ROM.

Tasks
Miscellaneous
GetIndexEntry

(page 124)

GetIndexKey

(page 124) (page 124)

GetIndexOffset_FWAddress

GetIndexOffset_UInt32

(page 124)

GetIndexType

(page 125) (page 125)

GetIndexValue_ConfigDirectory

GetIndexValue_Data

(page 125)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

122

IOFireWireConfigDirectoryInterface Tasks

GetIndexValue_String

(page 125) (page 126) (page 126)

GetIndexValue_UInt32

GetKeyOffset_FWAddress

GetKeySubdirectories

(page 126)

GetKeyType

(page 126) (page 127)

GetKeyValue_ConfigDirectory

GetKeyValue_Data

(page 127) (page 127)

GetKeyValue_UInt32

GetNumEntries

(page 127) (page 128)

GetSubdirectories

GetType

(page 128)

Update

(page 128) Causes the ROM data to be updated through the specified byte offset. This function should not be called in normal usage.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

123

IOFireWireConfigDirectoryInterface Instance Methods

Instance Methods
GetIndexEntry
IOReturn ( *GetIndexEntry) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32 *outValue);

Discussion Description forthcoming

GetIndexKey
IOReturn ( *GetIndexKey) ( IOFireWireLibConfigDirectoryRef self, int inIndex, int *key);

Discussion Description forthcoming

GetIndexOffset_FWAddress
IOReturn ( *GetIndexOffset_FWAddress) ( IOFireWireLibConfigDirectoryRef self, int inIndex, FWAddress *outValue);

Discussion Description forthcoming

GetIndexOffset_UInt32
IOReturn ( *GetIndexOffset_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32 *outValue);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

124

IOFireWireConfigDirectoryInterface Instance Methods

GetIndexType
IOReturn ( *GetIndexType) ( IOFireWireLibConfigDirectoryRef self, int inIndex, IOConfigKeyType *type);

Discussion Description forthcoming

GetIndexValue_ConfigDirectory
IOReturn ( *GetIndexValue_ConfigDirectory) ( IOFireWireLibConfigDirectoryRef self, int inIndex, IOFireWireLibConfigDirectoryRef *outValue, REFIID iid);

Discussion Description forthcoming

GetIndexValue_Data
IOReturn ( *GetIndexValue_Data) ( IOFireWireLibConfigDirectoryRef self, int inIndex, CFDataRef *value);

Discussion Description forthcoming

GetIndexValue_String
IOReturn ( *GetIndexValue_String) ( IOFireWireLibConfigDirectoryRef self, int inIndex, CFStringRef *outValue);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

125

IOFireWireConfigDirectoryInterface Instance Methods

GetIndexValue_UInt32
IOReturn ( *GetIndexValue_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inIndex, UInt32 *value);

Discussion Description forthcoming

GetKeyOffset_FWAddress
IOReturn ( *GetKeyOffset_FWAddress) ( IOFireWireLibConfigDirectoryRef self, int inKey, FWAddress *outValue, CFStringRef *text);

Discussion Description forthcoming

GetKeySubdirectories
IOReturn ( *GetKeySubdirectories) ( IOFireWireLibConfigDirectoryRef self, int inKey, io_iterator_t *outIterator);

Discussion Description forthcoming

GetKeyType
IOReturn ( *GetKeyType) ( IOFireWireLibConfigDirectoryRef self, int inKey, IOConfigKeyType *outType);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

126

IOFireWireConfigDirectoryInterface Instance Methods

GetKeyValue_ConfigDirectory
IOReturn ( *GetKeyValue_ConfigDirectory) ( IOFireWireLibConfigDirectoryRef self, int inKey, IOFireWireLibConfigDirectoryRef *outValue, REFIID iid, CFStringRef *outText);

Discussion Description forthcoming

GetKeyValue_Data
IOReturn ( *GetKeyValue_Data) ( IOFireWireLibConfigDirectoryRef self, int inKey, CFDataRef *outValue, CFStringRef *outText);

Discussion Description forthcoming

GetKeyValue_UInt32
IOReturn ( *GetKeyValue_UInt32) ( IOFireWireLibConfigDirectoryRef self, int inKey, UInt32 *outValue, CFStringRef *outText);

Discussion Description forthcoming

GetNumEntries
IOReturn ( *GetNumEntries) ( IOFireWireLibConfigDirectoryRef self, int *outNumEntries);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

127

IOFireWireConfigDirectoryInterface Instance Methods

GetSubdirectories
IOReturn ( *GetSubdirectories) ( IOFireWireLibConfigDirectoryRef self, io_iterator_t *outIterator);

Discussion Description forthcoming

GetType
IOReturn ( *GetType) ( IOFireWireLibConfigDirectoryRef self, int *outType);

Discussion Description forthcoming

Update
Causes the ROM data to be updated through the specified byte offset. This function should not be called in normal usage.
IOReturn ( *Update) ( IOFireWireLibConfigDirectoryRef self, UInt32 inOffset);

Parameters
self

The config directory interface of interest

inOffset

Offset in bytes indicating length of ROM to be updated. Return Value An IOReturn result code

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

128

IOFireWireConfigDirectoryInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

129

IOFireWireDCLCommandPoolInterface

Declared in

IOFireWireLibIsoch.h

Overview
Description forthcoming.

Tasks
Miscellaneous
Allocate

(page 132) (page 132)

AllocateCallProcDCL

AllocateJumpDCL

(page 132) (page 132) (page 133) (page 133) (page 133) (page 134)

AllocateLabelDCL

AllocatePtrTimeStampDCL

AllocateReceiveBufferDCL

AllocateReceivePacketDCL

AllocateReceivePacketStartDCL

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

130

IOFireWireDCLCommandPoolInterface Tasks

AllocateSendBufferDCL

(page 134) (page 134) (page 135) (page 135)

AllocateSendPacketDCL

AllocateSendPacketStartDCL

AllocateSendPacketWithHeaderStartDCL

AllocateSetTagSyncBitsDCL

(page 135) (page 136) (page 136)

AllocateTransferBufferDCL

AllocateTransferPacketDCL

AllocateUpdateDCLListDCL

(page 136)

AllocateWithOpcode

(page 137)

Free

(page 137) (page 137)

GetBytesRemaining

GetSize

(page 137) (page 138)

SetSize

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

131

IOFireWireDCLCommandPoolInterface Instance Methods

Instance Methods
Allocate
DCLCommand* ( *Allocate) ( IOFireWireLibDCLCommandPoolRef self, IOByteCount inSize );

Discussion Description forthcoming

AllocateCallProcDCL
DCLCommand* ( *AllocateCallProcDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, DCLCallCommandProc *inProc, DCLCallProcDataType inProcData);

Discussion Description forthcoming

AllocateJumpDCL
DCLCommand* ( *AllocateJumpDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, DCLLabel *pInJumpDCLLabel);

Discussion Description forthcoming

AllocateLabelDCL
DCLCommand* ( *AllocateLabelDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

132

IOFireWireDCLCommandPoolInterface Instance Methods

AllocatePtrTimeStampDCL
DCLCommand* ( *AllocatePtrTimeStampDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, UInt32 *inTimeStampPtr);

Discussion Description forthcoming

AllocateReceiveBufferDCL
DCLCommand* ( *AllocateReceiveBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset);

Discussion Description forthcoming

AllocateReceivePacketDCL
DCLCommand* ( *AllocateReceivePacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

133

IOFireWireDCLCommandPoolInterface Instance Methods

AllocateReceivePacketStartDCL
DCLCommand* ( *AllocateReceivePacketStartDCL)( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

AllocateSendBufferDCL
DCLCommand* ( *AllocateSendBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset);

Discussion Description forthcoming

AllocateSendPacketDCL
DCLCommand* ( *AllocateSendPacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

134

IOFireWireDCLCommandPoolInterface Instance Methods

AllocateSendPacketStartDCL
DCLCommand* ( *AllocateSendPacketStartDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

AllocateSendPacketWithHeaderStartDCL
DCLCommand* ( *AllocateSendPacketWithHeaderStartDCL)( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

AllocateSetTagSyncBitsDCL
DCLCommand* ( *AllocateSetTagSyncBitsDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, UInt16 inTagBits, UInt16 inSyncBits);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

135

IOFireWireDCLCommandPoolInterface Instance Methods

AllocateTransferBufferDCL
DCLCommand* ( *AllocateTransferBufferDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, UInt32 inOpcode, void *inBuffer, IOByteCount inSize, IOByteCount inPacketSize, UInt32 inBufferOffset);

Discussion Description forthcoming

AllocateTransferPacketDCL
DCLCommand* ( *AllocateTransferPacketDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, UInt32 inOpcode, void *inBuffer, IOByteCount inSize);

Discussion Description forthcoming

AllocateUpdateDCLListDCL
DCLCommand* ( *AllocateUpdateDCLListDCL) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, DCLCommand **inDCLCommandList, UInt32 inNumCommands);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

136

IOFireWireDCLCommandPoolInterface Instance Methods

AllocateWithOpcode
IOReturn ( *AllocateWithOpcode) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL, DCLCommand **outDCL, UInt32 opcode, ... );

Discussion Description forthcoming

Free
void ( *Free) ( IOFireWireLibDCLCommandPoolRef self, DCLCommand *inDCL );

Discussion Description forthcoming

GetBytesRemaining
IOByteCount ( *GetBytesRemaining) ( IOFireWireLibDCLCommandPoolRef self );

Discussion Description forthcoming

GetSize
IOByteCount ( *GetSize) ( IOFireWireLibDCLCommandPoolRef self );

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

137

IOFireWireDCLCommandPoolInterface Instance Variables

SetSize
Boolean ( *SetSize) ( IOFireWireLibDCLCommandPoolRef self, IOByteCount inSize );

Discussion Description forthcoming

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

138

IOFireWireDeviceInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib. You can use IOFireWireDeviceInterface to:

IOFireWireReadCommandInterface IOFireWireReadQuadletCommandInterface IOFireWireWriteCommandInterface IOFireWireWriteQuadletCommandInterface IOFireWireCompareSwapCommandInterface IOFireWirePseudoAddressSpaceInterface -- pseudo address space services IOFireWirePhysicalAddressSpaceInterface -- physical address space services IOFireWireLocalUnitDirectoryInterface -- manage local unit directories in the mac IOFireWireConfigDirectoryInterface -- access and browse remote device config directories IOFireWireIsochChannelInterface -- create/manage talker and listener isoch channels IOFireWireLocalIsochPortInterface -- create local isoch ports IOFireWireRemoteIsochPortInterface -- create remote isoch ports IOFireWireDCLCommandPoolInterface -- create a DCL command pool allocator. perform synchronous read, write and lock operations perform other miscellanous bus operations, such as reset the FireWire bus. create FireWire command objects and interfaces used to perform synchronous/asynchronous read, write and lock operations. These include: create interfaces which provide a other extended services. These include:

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

139

IOFireWireDeviceInterface Tasks

create interfaces which provide isochronous services (see IOFireWireLibIsoch.h). These include:

Tasks
Miscellaneous
AddCallbackDispatcherToRunLoop

(page 145) Installs the proper run loop event source to allow callbacks to function. This method must be called before callback notifications for this interface or any interfaces created using this interface can function. (page 145) Add a run loop event source to allow IOFireWireLib callbacks to function. (page 146) This function adds an event source for the isochronous callback dispatcher to the specified CFRunLoop. Isochronous related callbacks will not function before this function is called. This functions is similar to AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop.

AddCallbackDispatcherToRunLoopForMode

AddIsochCallbackDispatcherToRunLoop(IOFireWireLibDeviceRef, CFRunLoopRef)

AddIsochCallbackDispatcherToRunLoop(IOFireWireLibDeviceRef, CFRunLoopRef, CFStringRef) (page

147) Add a run loop event source to allow IOFireWireLib isoch callbacks to function.
AddIsochCallbackDispatcherToRunLoopForMode

(page 147) Add a run loop event source to allow IOFireWireLib isoch callbacks to function. (page 148) Attempt to allocate some isochronous bandwidth from the IRM (page 149) Attempt to allocate an isochronous channel from the IRM (page 149) Cause a bus reset (page 150) This function must be called from callback routines once they have completed processing a callback. This function only applies to callbacks which take an IOFireWireLibDeviceRef (i.e. bus reset), parameter. (page 150)

AllocateIRMBandwidthInGeneration

AllocateIRMChannelInGeneration

BusReset

ClientCommandIsComplete

ClipMaxRec2K

(page 150) Release exclusive access to the device

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

140

IOFireWireDeviceInterface Tasks

CompareSwap

(page 151) Perform synchronous lock operation (page 152) Perform synchronous lock operation (page 153) Create a command object for sending Async Stream packets (page 154) Creates a async stream listener object and returns an interface to it. (page 155) Create a quadlet compare/swap command object. (page 156) Create a quadlet compare/swap command object and initialize it with 64-bit values. (page 157) This function can be used to create a config directory object and a corresponding interface from an opaque IOObject reference. Some configuration directory interface methods may return an io_object_t instead of an IOFireWireLibConfigDirectoryRef. Use this function to obtain an IOFireWireLibConfigDirectoryRef from an io_object_t. (page 157) Creates a command pool object and returns an interface to it. The command pool can be used to build DCL programs. (page 158) Creates a pseudo address space in initial units space. (page 160) Attempt to create an IRM allocation that persists accross bus-resets. (page 160) Creates an isochronous channel object and returns an interface to it. An isochronous channel object is an abstract entity used to represent a FireWire isochronous channel. (page 161) Creates a local isochronous port object and returns an interface to it. A local isochronous port object is an abstract entity used to represent a talking or listening endpoint in the local machine. (page 163) Create a local isoch port

CompareSwap64

CreateAsyncStreamCommand

CreateAsyncStreamListener

CreateCompareSwapCommand

CreateCompareSwapCommand64

CreateConfigDirectoryWithIOObject

CreateDCLCommandPool

CreateInitialUnitsPseudoAddressSpace

CreateIRMAllocation

CreateIsochChannel

CreateLocalIsochPort

CreateLocalIsochPortWithOptions

CreateLocalUnitDirectory

(page 164) Creates a local unit directory object and returns an interface to it. An instance of a unit directory object corresponds to an instance of a unit directory in the local machine's configuration ROM.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

141

IOFireWireDeviceInterface Tasks

CreateNuDCLPool

(page 164)

CreatePHYCommand

(page 164) Create a command object for sending a PHY packet (page 165) Create a listener object for receiving PHY packets (page 166) Creates a physical address space object and returns an interface to it. This will create a physical address space on the local machine. (page 167) Creates a pseudo address space object and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine. (page 168) Create a block read command object. (page 169) Create a quadlet read command object. (page 171) Creates a remote isochronous port object and returns an interface to it. A remote isochronous port object is an abstract entity used to represent a remote talker or listener device on an isochronous channel. (page 171) Create a vector command object. (page 172) Create a block write command object. (page 173) Create a quadlet write command object. (page 174)

CreatePHYPacketListener

CreatePhysicalAddressSpace

CreatePseudoAddressSpace

CreateReadCommand

CreateReadQuadletCommand

CreateRemoteIsochPort

CreateVectorCommand

CreateWriteCommand

CreateWriteQuadletCommand

FireBugMsg

FireLog

(page 174) Logs string to in-kernel debug buffer (page 174) Get bus and cycle time. (page 175) Get bus generation number.

GetBusCycleTime

GetBusGeneration

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

142

IOFireWireDeviceInterface Tasks

GetConfigDirectory

(page 176) Creates a config directory object and returns an interface to it. The created config directory object represents the config directory in the remote device or unit to which the creating device interface is attached. (page 176) Get bus cycle time. (page 176) Get bus cycle time and cpu uptime. (page 177)

GetCycleTime

GetCycleTimeAndUpTime

GetDebugProperty

GetDevice

(page 177) Get the IOKit service to which this interface is connected. (page 178) (Obsolete) Get bus generation and remote device node ID. (page 178)

GetGenerationAndNodeID

GetIRMNodeID

GetIsochAsyncPort

(page 178) Returns the notification port used for async and isoch callbacks (page 179) (Obsolete) Get local node ID. (page 179) Get node ID of local machine. (page 180) Get user reference value set on this interface (page 180) Get node ID of device to which this interface is attached. (page 181) Get time since last bus reset. (page 182)

GetLocalNodeID

GetLocalNodeIDWithGeneration

GetRefCon

GetRemoteNodeID

GetResetTime

GetSessionRef

GetSpeedBetweenNodes

(page 182) Get the maximum transfer speed between nodes 'srcNodeID' and 'destNodeID'. (page 183) Get maximum transfer speed to device to which this interface is attached.

GetSpeedToNode

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

143

IOFireWireDeviceInterface Tasks

InterfaceIsInited

(page 183) Determine whether interface has been properly inited. (page 183) Determine whether callback notifications for this interface are currently active

NotificationIsOn

Open

(page 184) Open the connected device for exclusive access. When you have the device open using this method, all accesses by other clients of this device will be denied until Close() is called. (page 184) An open function which allows this interface to have access to the device when already opened. The service which has already opened the device must be able to provide an IOFireWireSessionRef. (page 185) Walk a DCL program linked list and print its contents

OpenWithSessionRef

PrintDCLProgram

Read

(page 185) Perform synchronous block read (page 186) Perform synchronous quadlet read (page 187) Attempt to release some isochronous bandwidth from the IRM (page 187) Attempt to release an isochronous channel from the IRM (page 188) Reverses the effects of AddCallbackDispatcherToRunLoop(). This method removes the run loop event source that was added to the specified run loop preventing any future callbacks from being called (page 188) Removes an IOFireWireLib-added run loop event source. (page 189) Seize control of device/unit (page 189) Sets the callback that should be called after a bus reset has occurred and reconfiguration of the bus has been completed. This function will only be called once per bus reset. (page 190) Sets the callback that should be called when a bus reset occurs. Note that this callback can be called multiple times before the bus reset done handler is called. (f.ex., multiple bus resets might occur before bus reconfiguration has completed.)

ReadQuadlet

ReleaseIRMBandwidthInGeneration

ReleaseIRMChannelInGeneration

RemoveCallbackDispatcherFromRunLoop

RemoveIsochCallbackDispatcherFromRunLoop

Seize

SetBusResetDoneHandler

SetBusResetHandler

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

144

IOFireWireDeviceInterface Instance Methods

SetRefCon

(page 190) Set user reference value on this interface (page 191) Deactivates and callbacks specified for this device interface. Reverses the effects of TurnOnNotification() (page 191) Activates any callbacks specified for this device interface. Only works after AddCallbackDispatcherToRunLoop has been called. See also AddIsochCallbackDispatcherToRunLoop(). (page 191) Perform synchronous block write (page 192) Perform synchronous quadlet write

TurnOffNotification

TurnOnNotification

Write

WriteQuadlet

Instance Methods
AddCallbackDispatcherToRunLoop
Installs the proper run loop event source to allow callbacks to function. This method must be called before callback notifications for this interface or any interfaces created using this interface can function.
const IOReturn ( *AddCallbackDispatcherToRunLoop)( IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop);

Parameters
self

The device interface to use.

inRunLoop

The run loop on which to install the event source

AddCallbackDispatcherToRunLoopForMode
Add a run loop event source to allow IOFireWireLib callbacks to function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

145

IOFireWireDeviceInterface Instance Methods

IOReturn ( *AddCallbackDispatcherToRunLoopForMode)( IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode );

Parameters
self

The device interface to use.

inRunLoop

The run loop on which to install the event source

inRunLoopMode

The run loop mode(s) for which to install the event source Return Value An IOReturn error code. Discussion Installs the proper run loop event source to allow callbacks to function. This method must be called before callback notifications for this interface or any interfaces created using this interface can function. With this function, you can additionally specify for which run loop modes this source should be added. Availability: IOFireWireDeviceInterface_v3, and newer

AddIsochCallbackDispatcherToRunLoop(IOFireWireLibDeviceRef, CFRunLoopRef )
This function adds an event source for the isochronous callback dispatcher to the specified CFRunLoop. Isochronous related callbacks will not function before this function is called. This functions is similar to AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop.
IOReturn ( *AddIsochCallbackDispatcherToRunLoop)( IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop);

Parameters
self

The device interface to use.

inRunLoop

A CFRunLoopRef for the run loop to which the event loop source should be added

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

146

IOFireWireDeviceInterface Instance Methods

Return Value An IOReturn error code.

AddIsochCallbackDispatcherToRunLoop(IOFireWireLibDeviceRef, FRunLoopRef, FStringRef ) C C

Add a run loop event source to allow IOFireWireLib isoch callbacks to function.
IOReturn ( *AddIsochCallbackDispatcherToRunLoopForMode)( IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode );

Parameters
self

The device interface to use.

inRunLoop

A CFRunLoopRef for the run loop to which the event loop source should be added
inRunLoopMode

The run loop mode(s) for which to install the event source Return Value An IOReturn error code. Discussion This function adds an event source for the isochronous callback dispatcher to the specified CFRunLoop. Isochronous related callbacks will not be called unless this function has been called. This function is similar to AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop. Availability: IOFireWireDeviceInterface_v3, and newer

AddIsochCallbackDispatcherToRunLoopForMode
Add a run loop event source to allow IOFireWireLib isoch callbacks to function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

147

IOFireWireDeviceInterface Instance Methods

IOReturn ( *AddIsochCallbackDispatcherToRunLoopForMode)( IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop, CFStringRef inRunLoopMode );

Parameters
self

The device interface to use.

inRunLoop

A CFRunLoopRef for the run loop to which the event loop source should be added
inRunLoopMode

AllocateIRMBandwidthInGeneration
Attempt to allocate some isochronous bandwidth from the IRM
IOReturn ( *AllocateIRMBandwidthInGeneration)( IOFireWireLibDeviceRef self, UInt32 bandwidthUnits, UInt32 generation);

Parameters
bandwidthUnits

The number of bandwidth units to allocate

generation

The bus generation that this allocation attempt is to take place in.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

148

IOFireWireDeviceInterface Instance Methods

Return Value Returns kIOReturnSuccess if bandwidth allocation was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed) Discussion Attempts to allocates some isochronous bandwidth from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

AllocateIRMChannelInGeneration
Attempt to allocate an isochronous channel from the IRM
IOReturn ( *AllocateIRMChannelInGeneration)( IOFireWireLibDeviceRef self, UInt8 isochChannel, UInt32 generation);

Parameters
isochChannel

The isochronous channel to allocate

generation

The bus generation that this allocation attempt is to take place in. Return Value Returns kIOReturnSuccess if channel allocation was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed) Discussion Attempts to allocates an isochronous channel from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

BusReset
Cause a bus reset

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

149

IOFireWireDeviceInterface Instance Methods

IOReturn ( *BusReset)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use.

ClientCommandIsComplete
This function must be called from callback routines once they have completed processing a callback. This function only applies to callbacks which take an IOFireWireLibDeviceRef (i.e. bus reset), parameter.
void ( *ClientCommandIsComplete)( IOFireWireLibDeviceRef self, FWClientCommandID commandID, IOReturn status);

Parameters
commandID

The command ID passed to the callback function when it was called

status

An IOReturn value indicating the completion status of the callback function

ClipMaxRec2K
IOReturn ( *ClipMaxRec2K)( IOFireWireLibDeviceRef self, Boolean clipMaxRec );

Discussion Description forthcoming

Close
Release exclusive access to the device

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

150

IOFireWireDeviceInterface Instance Methods

void ( *Close)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use

CompareSwap
Perform synchronous lock operation
IOReturn ( *CompareSwap)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 cmpVal, UInt32 newVal, Boolean failOnReset, UInt32 generation);

Parameters
self

The device interface to use.

device

The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr

Command target address

cmpVal

The check/compare value

newVal

Value to set
failOnReset

Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

151

IOFireWireDeviceInterface Instance Methods

Return Value An IOReturn error code

CompareSwap64
Perform synchronous lock operation
IOReturn ( *CompareSwap64)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 *expectedVal, UInt32 *newVal, UInt32 *oldVal, IOByteCount size, Boolean failOnReset, UInt32 generation);

Parameters
self

The device interface to use.

device

Command target address

expectedVal

Pointer to quadlets expected at target.

newVal

Pointer to quadlets to atomically set at target if compare is successful.

oldVal

Pointer to quadlets to hold value found at target address after transaction if completed.
size

Size in bytes of compare swap transaction to perform. Value values are 4 and 8.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

152

IOFireWireDeviceInterface Instance Methods

failOnReset

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Return Value An IOReturn error code

CreateAsyncStreamCommand
Create a command object for sending Async Stream packets
IOFireWireLibCommandRef ( *CreateAsyncStreamCommand)( IOFireWireLibDeviceRef self, UInt32 channel, UInt32 sync, UInt32 tag, void *buf, UInt32 size, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

channel

The channel number to use.

buf

A pointer to the buffer containing the data to be written

size

Number of bytes to write

callback

Command completion callback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

153

IOFireWireDeviceInterface Instance Methods

failOnReset

A user specified reference value. This will be passed to all callback functions.
iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy packet listener object. Return Value An IOReturn error code

CreateAsyncStreamListener
Creates a async stream listener object and returns an interface to it.
IOFWAsyncStreamListenerInterfaceRef ( *CreateAsyncStreamListener)( IOFireWireLibDeviceRef self, UInt32 channel, IOFWAsyncStreamListenerHandler callback, void *inRefCon, UInt32 inQueueBufferSize, REFIID iid);

Parameters
self

The device interface to use.

channel

The channel to allocate.

inRefCon

A user specified reference value. This will be passed to all callback functions.
inQueueBufferSize

The size of the queue which receives packets from the bus before they are handed to the client. A larger queue can help eliminate dropped packets when receiving large bursts of data. When a packet is received which can not fit into the queue, the packet dropped callback will be called.
iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created ayns stream listener object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

154

IOFireWireDeviceInterface Instance Methods

Return Value An IOFWAsyncStreamListenerInterfaceRef. Returns 0 upon failure

CreateCompareSwapCommand
Create a quadlet compare/swap command object.
IOFireWireLibCommandRef ( *CreateCompareSwapCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 cmpVal, UInt32 newVal, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

device

Command target address

cmpVal

32-bit value expected at target address

newVal

32-bit value to be set at target address

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.
failOnReset

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

155

IOFireWireDeviceInterface Instance Methods

generation

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing. Return Value An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateCompareSwapCommand64
Create a quadlet compare/swap command object and initialize it with 64-bit values.
IOFireWireLibCommandRef ( *CreateCompareSwapCommand64)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt64 cmpVal, UInt64 newVal, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

device

Command target address

cmpVal

64-bit value expected at target address

newVal

64-bit value to be set at target address

callback

Command completion callback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

156

IOFireWireDeviceInterface Instance Methods

failOnReset

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Return Value An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateConfigDirectoryWithIOObject
This function can be used to create a config directory object and a corresponding interface from an opaque IOObject reference. Some configuration directory interface methods may return an io_object_t instead of an IOFireWireLibConfigDirectoryRef. Use this function to obtain an IOFireWireLibConfigDirectoryRef from an io_object_t.
IOFireWireLibConfigDirectoryRef ( *CreateConfigDirectoryWithIOObject)( IOFireWireLibDeviceRef self, io_object_t inObject, REFIID iid);

Parameters
self

The device interface to use.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created config directory object. Return Value An IOFireWireLibConfigDirectoryRef. Returns 0 upon failure

CreateDCLCommandPool
Creates a command pool object and returns an interface to it. The command pool can be used to build DCL programs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

157

IOFireWireDeviceInterface Instance Methods

IOFireWireLibDCLCommandPoolRef ( *CreateDCLCommandPool)( IOFireWireLibDeviceRef self, IOByteCount size, REFIID iid );

Parameters
self

The device interface to use.

size

Starting size of command pool

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object. Return Value An IOFireWireLibDCLCommandPoolRef. Returns 0 upon failure

CreateInitialUnitsPseudoAddressSpace
Creates a pseudo address space in initial units space.
IOFireWireLibPseudoAddressSpaceRef ( *CreateInitialUnitsPseudoAddressSpace)( IOFireWireLibDeviceRef self, UInt32 inAddressLo, UInt32 inSize, void *inRefCon, UInt32 inQueueBufferSize, void *inBackingStore, UInt32 inFlags, REFIID iid);

Parameters
self

The device interface to use.

inAddressLo

The lower 32 bits of the base address of the address space to be created. The address is always in initial units space.
inSize

The size in bytes of this address space.

inRefCon

A user specified reference value. This will be passed to all callback functions.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

158

IOFireWireDeviceInterface Instance Methods

inQueueBufferSize

The size of the queue which receives packets from the bus before they are handed to the client and/or put in the backing store. A larger queue can help eliminate dropped packets when receiving large bursts of data. When a packet is received which can not fit into the queue, the packet dropped callback will be called.
inBackingStore

An optional block of allocated memory representing the contents of the address space. This memory block must be of size inSize.
inFlags

A UInt32 with bits set corresponding to the flags that should be set for this address space.

kFWAddressSpaceNoFlags -- All flags off kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space. kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space. kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents of the backing store. The user process will not be notified of writes. kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically using the contents of the backing store. The user process will not be notified of reads. kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly to the backing store at the same time the user process is notified of a write. Clients will only be notified of a write if kFWAddressSpaceAutoWriteReply is not set. kFWAddressSpaceShareIfExists -- Allows creation of this address space even if another client already has an address space at the requested address. All clients will be notified of writes to covered addresses. kFWAddressSpaceExclusive -- Ensures that the allocation of this address space will fail if any portion of this address range is already allocated. If the allocation is successful this flag ensures that any future allocations overlapping this range will fail even if allocted with kFWAddressSpaceShareIfExists.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created pseudo address space object. Return Value An IOFireWireLibPseudoAddressSpaceRef. Returns 0 upon failure

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

159

IOFireWireDeviceInterface Instance Methods

Discussion Creates a pseudo address space object in initial units space and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine. Availablilty: IOFireWireDeviceInterface_v3, and newer

CreateIRMAllocation
Attempt to create an IRM allocation that persists accross bus-resets.
IOFireWireLibIRMAllocationRef ( *CreateIRMAllocation)( IOFireWireLibDeviceRef self, Boolean releaseIRMResourcesOnFree, IOFireWireLibIRMAllocationLostNotificationProc callback, void *pLostNotificationProcRefCon, REFIID iid);

Parameters
releaseIRMResourcesOnFree

Specify whether or not the IRM resources shall be released when the IOFireWireLibIRMAllocation is destroyed. Can be overrided later.
callback

The handler to notify clients of failure to reclaim IRM resources after bus-reset.
pLostNotificationProcRefCon

The refCon passed with the callback. Return Value Returns a pointer to the newly created IRM allocation object, if successful, NULL otherwise. Discussion Create an IOFireWireIRMAllocation object, which can be used to allocate IRM resources, and will reallocate automatically after bus-resets (if possible). Availability: IOFireWireDeviceInterface_v9 and newer

CreateIsochChannel
Creates an isochronous channel object and returns an interface to it. An isochronous channel object is an abstract entity used to represent a FireWire isochronous channel.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

160

IOFireWireDeviceInterface Instance Methods

IOFireWireLibIsochChannelRef ( *CreateIsochChannel)( IOFireWireLibDeviceRef self, Boolean doIrm, UInt32 packetSize, IOFWSpeed prefSpeed, REFIID iid );

Parameters
self

The device interface to use.

doIrm

Controls whether the channel automatically performs IRM operations. Pass true if the channel should allocate its channel and bandwidth with the IRM. Pass false to ignore the IRM.
packetSize

Size of payload in bytes of packets being sent or received with this channel, excluding headers. This is automatically translated into a bandwidth allocation appropriate for the speed passed in prefSpeed.
prefSpeed

The preferred bus speed of this channel.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object. Return Value An IOFireWireLibIsochChannelRef. Returns 0 upon failure

CreateLocalIsochPort
Creates a local isochronous port object and returns an interface to it. A local isochronous port object is an abstract entity used to represent a talking or listening endpoint in the local machine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

161

IOFireWireDeviceInterface Instance Methods

IOFireWireLibLocalIsochPortRef ( *CreateLocalIsochPort)( IOFireWireLibDeviceRef self, Boolean inTalking, DCLCommand *inDCLProgram, UInt32 inStartEvent, UInt32 inStartState, UInt32 inStartMask, IOVirtualRange inDCLProgramRanges[], // optional optimization parameters UInt32 inDCLProgramRangeCount, IOVirtualRange inBufferRanges[], UInt32 inBufferRangeCount, REFIID iid);

Parameters
self

The device interface to use.

inTalking

Pass true if this port represents an isochronous talker. Pass false if this port represents an isochronous listener.
inDCLProgram

A pointer to the first DCL command struct of the DCL program to be compiled and used to send or receive data on this port.
inStartEvent

Start event: 0 or kFWDCLCycleEvent or kFWDCLSyBitsEvent

inStartState

Start state bits. For kFWDCLCycleEvent specifies the cycle to start the DMA on. For kFWDCLSyBitsEvent specifies the packet sync field value for the first packet to receive.
inStartMask

Start mask bits. For kFWDCLCycleEvent specifies a mask for the start cycle: the DMA will start when currentCycle & inStartMask == inStartEvent & inStartMask. For kFWDCLSyBitsEvent specifies a mask for the sync field: the DMA will start when packet sync == inStartEvent & inStartMask.
inDCLProgramRanges

This is an optional optimization parameter which can be used to decrease the time the local port object spends determining which set of virtual ranges the passed DCL program occupies. Pass a pointer to an array of IOVirtualRange structs or nil to ignore this parameter.
inDCLProgramRangeCount

The number of virtual ranges passed to inDCLProgramRanges. Pass 0 for none.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

162

IOFireWireDeviceInterface Instance Methods

inBufferRanges

This is an optional optimization parameter which can be used to decrease the time the local port object spends determining which set of virtual ranges the data buffers referenced by the passed DCL program occupy. Pass a pointer to an array of IOVirtualRange structs or nil to ignore this parameter.
inBufferRangeCount

The number of virtual ranges passed to inBufferRanges. Pass 0 for none.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object. Return Value An IOFireWireLibLocalIsochPortRef. Returns 0 upon failure

CreateLocalIsochPortWithOptions
Create a local isoch port
IOFireWireLibLocalIsochPortRef ( *CreateLocalIsochPortWithOptions)( IOFireWireLibDeviceRef self, Boolean inTalking, DCLCommand *dclProgram, UInt32 startEvent, UInt32 startState, UInt32 startMask, IOVirtualRange dclProgramRanges[], // optional optimization parameters UInt32 dclProgramRangeCount, IOVirtualRange bufferRanges[], UInt32 bufferRangeCount, IOFWIsochPortOptions options, REFIID iid);

Parameters
options

Currently supported options are 'kFWIsochPortUseSeparateKernelThread'. If this option is used, a separate kernel thread will be created to handle interrupt processing for this port only. Pass 'kFWIsochPortDefaultOptions' for no options. Return Value Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

163

IOFireWireDeviceInterface Instance Methods

Discussion Same as CreateLocalIsochPort(), above, but allows additional options to be passed. Availability: IOFireWireDeviceInterface_v8 and newer

CreateLocalUnitDirectory
Creates a local unit directory object and returns an interface to it. An instance of a unit directory object corresponds to an instance of a unit directory in the local machine's configuration ROM.
IOFireWireLibLocalUnitDirectoryRef ( *CreateLocalUnitDirectory)( IOFireWireLibDeviceRef self, REFIID iid);

Parameters
self

The device interface to use.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created unit directory object. Return Value An IOFireWireLibLocalUnitDirectoryRef. Returns 0 upon failure

CreateNuDCLPool
IOFireWireLibNuDCLPoolRef ( *CreateNuDCLPool)( IOFireWireLibDeviceRef self, UInt32 capacity, REFIID iid );

Discussion Description forthcoming

CreatePHYCommand
Create a command object for sending a PHY packet

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

164

IOFireWireDeviceInterface Instance Methods

IOFireWireLibCommandRef ( *CreatePHYCommand)( IOFireWireLibDeviceRef self, UInt32 data1, UInt32 data2, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid );

Parameters
self

The device interface to use.

data1

phy packet quadlet 1

data2

phy packet quadlet 1

callback

completion callback
failOnReset

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.
iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy command object. Return Value An IOReturn error code

CreatePHYPacketListener
Create a listener object for receiving PHY packets

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

165

IOFireWireDeviceInterface Instance Methods

IOFireWireLibPHYPacketListenerRef ( *CreatePHYPacketListener)( IOFireWireLibDeviceRef self, UInt32 queueCount, REFIID iid );

Parameters
self

The device interface to use.

queueCount

The maximum queue size to use to buffer phy packets between kernel and user space
iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy packet listener object. Return Value An IOReturn error code

CreatePhysicalAddressSpace
Creates a physical address space object and returns an interface to it. This will create a physical address space on the local machine.
IOFireWireLibPhysicalAddressSpaceRef ( *CreatePhysicalAddressSpace)( IOFireWireLibDeviceRef self, UInt32 inSize, void *inBackingStore, UInt32 inFlags, REFIID iid);

Parameters
self

The device interface to use.

inSize

The size in bytes of this address space.

inBackingStore

An block of allocated memory representing the contents of the address space.

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this address space. For future use -- always pass 0.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

166

IOFireWireDeviceInterface Instance Methods

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created physical address space object. Return Value An IOFireWireLibPhysicalAddressSpaceRef. Returns 0 upon failure

CreatePseudoAddressSpace
Creates a pseudo address space object and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine.
IOFireWireLibPseudoAddressSpaceRef ( *CreatePseudoAddressSpace)( IOFireWireLibDeviceRef self, UInt32 inSize, void *inRefCon, UInt32 inQueueBufferSize, void *inBackingStore, UInt32 inFlags, REFIID iid);

Parameters
self

The device interface to use.

inSize

The size in bytes of this address space.

inRefCon

A user specified reference value. This will be passed to all callback functions.
inQueueBufferSize

An optional block of allocated memory representing the contents of the address space. This memory block must be of size inSize.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

167

IOFireWireDeviceInterface Instance Methods

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this address space.

iid

CreateReadCommand
Create a block read command object.
IOFireWireLibCommandRef ( *CreateReadCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, void *buf, UInt32 size, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

168

IOFireWireDeviceInterface Instance Methods

device

Command target address

buf

A pointer to a buffer where the results will be stored

size

Number of bytes to read

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.
failOnReset

CreateReadQuadletCommand
Create a quadlet read command object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

169

IOFireWireDeviceInterface Instance Methods

IOFireWireLibCommandRef ( *CreateReadQuadletCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 quads[], UInt32 numQuads, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

device

Command target address

quads

An array of quadlets where results should be stored

numQuads

Number of quadlets to read

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.
failOnReset

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

170

IOFireWireDeviceInterface Instance Methods

CreateRemoteIsochPort
Creates a remote isochronous port object and returns an interface to it. A remote isochronous port object is an abstract entity used to represent a remote talker or listener device on an isochronous channel.
IOFireWireLibRemoteIsochPortRef ( *CreateRemoteIsochPort)( IOFireWireLibDeviceRef self, Boolean inTalking, REFIID iid);

Parameters
self

The device interface to use.

inTalking

Pass true if this port represents an isochronous talker. Pass false if this port represents an isochronous listener.
iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created remote isochronous port object. Return Value An IOFireWireLibRemoteIsochPortRef. Returns 0 upon failure

CreateVectorCommand
Create a vector command object.
IOFireWireLibVectorCommandRef ( *CreateVectorCommand)( IOFireWireLibDeviceRef self, IOFireWireLibCommandCallback callback, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.
inRefCon

Reference constant for 3rd party use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

171

IOFireWireDeviceInterface Instance Methods

Return Value An IOFireWireLibVectorCommandRef interface

CreateWriteCommand
Create a block write command object.
IOFireWireLibCommandRef ( *CreateWriteCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, void *buf, UInt32 size, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

device

Command target address

buf

A pointer to the buffer containing the data to be written

size

Number of bytes to write

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.
failOnReset

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

172

IOFireWireDeviceInterface Instance Methods

generation

CreateWriteQuadletCommand
Create a quadlet write command object.
IOFireWireLibCommandRef ( *CreateWriteQuadletCommand)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 quads[], UInt32 numQuads, IOFireWireLibCommandCallback callback, Boolean failOnReset, UInt32 generation, void *inRefCon, REFIID iid);

Parameters
self

The device interface to use.

device

Command target address

quads

An array of quadlets containing quadlets to be written

numQuads

Number of quadlets to write

callback

Command completion callback. Setting the callback value to nil defaults to synchronous execution.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

173

IOFireWireDeviceInterface Instance Methods

failOnReset

FireBugMsg
IOReturn ( *FireBugMsg)( IOFireWireLibDeviceRef self, const char *msg);

Discussion Description forthcoming

FireLog
Logs string to in-kernel debug buffer
IOReturn ( *FireLog)( IOFireWireLibDeviceRef self, const char *format, ... );

Parameters
self

The device interface to use.

GetBusCycleTime
Get bus and cycle time.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

174

IOFireWireDeviceInterface Instance Methods

IOReturn ( GetBusCycleTime)( IOFireWireLibDeviceRef self, UInt32 outBusTime, UInt32 *outCycleTime);

Parameters
self

The device interface to use.

outBusTime

A pointer to a UInt32 to hold the bus time

outCycleTime

A pointer to a UInt32 to hold the cycle time Return Value An IOReturn error code.

GetBusGeneration
Get bus generation number.
IOReturn ( *GetBusGeneration)( IOFireWireLibDeviceRef self, UInt32 *outGeneration );

Parameters
self

The device interface to use.

outGeneration

A pointer to a UInt32 to hold the bus generation number Return Value Returns kIOReturnSuccess if a valid bus generation has been returned in 'outGeneration'. Discussion The bus generation number stays constant between bus resets and can be used in combination with a FireWire node ID to uniquely identify nodes on the bus. Pass the generation number to functions that take or return FireWire node IDs. Availability: IOFireWireDeviceInterface_v4 and newer

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

175

IOFireWireDeviceInterface Instance Methods

GetConfigDirectory
Creates a config directory object and returns an interface to it. The created config directory object represents the config directory in the remote device or unit to which the creating device interface is attached.
IOFireWireLibConfigDirectoryRef ( *GetConfigDirectory)( IOFireWireLibDeviceRef self, REFIID iid);

Parameters
self

The device interface to use.

iid

GetCycleTime
Get bus cycle time.
IOReturn ( *GetCycleTime)( IOFireWireLibDeviceRef self, UInt32 *outCycleTime);

Parameters
self

The device interface to use.

outCycleTime

A pointer to a UInt32 to hold the result Return Value An IOReturn error code.

GetCycleTimeAndUpTime
Get bus cycle time and cpu uptime.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

176

IOFireWireDeviceInterface Instance Methods

IOReturn ( GetCycleTimeAndUpTime)( IOFireWireLibDeviceRef self, UInt32 outCycleTime, UInt64 *outUpTime);

Parameters
self

The device interface to use.

outCycleTime

A pointer to a UInt32 to hold the result

outUpTime

A pointer to a UInt64 to hold the result Return Value An IOReturn error code.

GetDebugProperty
CFTypeRef ( *GetDebugProperty)( IOFireWireLibDeviceRef self, void *interface, CFStringRef inPropertyName, CFTypeID *outPropertyType);

Discussion Do not use this function.

GetDevice
Get the IOKit service to which this interface is connected.
io_object_t ( *GetDevice)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use. Return Value Returns an io_object_t corresponding to the device the interface is using

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

177

IOFireWireDeviceInterface Instance Methods

GetGenerationAndNodeID
(Obsolete) Get bus generation and remote device node ID.
IOReturn ( *GetGenerationAndNodeID)( IOFireWireLibDeviceRef self, UInt32 *outGeneration, UInt16 *outNodeID);

Parameters
self

The device interface to use.

outGeneration

A pointer to a UInt32 to hold the generation result

outNodeID

A pointer to a UInt16 to hold the remote device node ID Return Value An IOReturn error code. Discussion Obsolete -- Please use GetBusGeneration() and/or GetRemoteNodeID() in interface v4.

GetIRMNodeID
IOReturn ( *GetIRMNodeID)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16 *outIRMNodeID );

Discussion Description forthcoming

GetIsochAsyncPort
Returns the notification port used for async and isoch callbacks

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

178

IOFireWireDeviceInterface Instance Methods

mach_port_t ( *GetIsochAsyncPort)( IOFireWireLibDeviceRef self );

Parameters
self

The device interface to use. Return Value Returns the mach_port used for notifications Discussion If necessary GetIsochAsyncPort will allocate the port. Availability: IOFireWireDeviceInterface_v9 and newer

GetLocalNodeID
(Obsolete) Get local node ID.
IOReturn ( *GetLocalNodeID)( IOFireWireLibDeviceRef self, UInt16 *outLocalNodeID);

Parameters
self

The device interface to use.

outLocalNodeID

A pointer to a UInt16 to hold the local device node ID Return Value An IOReturn error code. Discussion Obsolete -- Please use GetBusGeneration() and GetLocalNodeIDWithGeneration() in interface v4.

GetLocalNodeIDWithGeneration
Get node ID of local machine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

179

IOFireWireDeviceInterface Instance Methods

IOReturn ( GetLocalNodeIDWithGeneration)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16 outLocalNodeID );

Parameters
self

The device interface to use.

checkGeneration

A bus generation number obtained from GetBusGeneration()

outLocalNodeID

A pointer to a UInt16 to hold the node ID of the local machine. Return Value Returns kIOReturnSuccess if a valid nodeID has been returned in 'outLocalNodeID'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number. Discussion Use this function instead of GetLocalNodeID(). Availability: IOFireWireDeviceInterface_v4 and newer

GetRefCon
Get user reference value set on this interface
void* ( *GetRefCon)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use. Return Value Returns the user's reference value set on this interface.

GetRemoteNodeID
Get node ID of device to which this interface is attached.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

180

IOFireWireDeviceInterface Instance Methods

IOReturn ( GetRemoteNodeID)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16 outRemoteNodeID );

Parameters
self

The device interface to use.

checkGeneration

A bus generation number obtained from GetBusGeneration()

outRemoteNodeID

A pointer to a UInt16 to hold the node ID of the remote device. Return Value Returns kIOReturnSuccess if a valid nodeID has been returned in 'outRemoteNodeID'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number. Discussion Availability: IOFireWireDeviceInterface_v4 and newer

GetResetTime
Get time since last bus reset.
IOReturn ( *GetResetTime)( IOFireWireLibDeviceRef self, AbsoluteTime *outResetTime);

Parameters
self

The device interface to use.

outResetTime

A pointer to an AbsolutTime to hold the result. Return Value An IOReturn error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

181

IOFireWireDeviceInterface Instance Methods

GetSessionRef
IOFireWireSessionRef ( *GetSessionRef)( IOFireWireLibDeviceRef self );

Discussion Description forthcoming

GetSpeedBetweenNodes
Get the maximum transfer speed between nodes 'srcNodeID' and 'destNodeID'.
IOReturn ( *GetSpeedBetweenNodes)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, UInt16 srcNodeID, UInt16 destNodeID, IOFWSpeed *outSpeed);

Parameters
self

The device interface to use.

checkGeneration

A bus generation number obtained from GetBusGeneration()

srcNodeID

A FireWire node ID.

destNodeID

A FireWire node ID.

outSpeed

A pointer to an IOFWSpeed to hold the maximum transfer speed between node 'srcNodeID' and 'destNodeID'. Return Value Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number. Discussion Availability: IOFireWireDeviceInterface_v4 and newer

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

182

IOFireWireDeviceInterface Instance Methods

GetSpeedToNode
Get maximum transfer speed to device to which this interface is attached.
IOReturn ( *GetSpeedToNode)( IOFireWireLibDeviceRef self, UInt32 checkGeneration, IOFWSpeed *outSpeed);

Parameters
self

The device interface to use.

checkGeneration

A bus generation number obtained from GetBusGeneration()

outSpeed

A pointer to an IOFWSpeed to hold the maximum speed to the remote device. Return Value Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number. Discussion Availability: IOFireWireDeviceInterface_v4 and newer

InterfaceIsInited
Determine whether interface has been properly inited.
Boolean ( *InterfaceIsInited)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use. Return Value Returns true if interface is inited and false if is it not.

NotificationIsOn
Determine whether callback notifications for this interface are currently active

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

183

IOFireWireDeviceInterface Instance Methods

const Boolean ( *NotificationIsOn)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use Return Value A Boolean value where true indicates notifications are active

Open
Open the connected device for exclusive access. When you have the device open using this method, all accesses by other clients of this device will be denied until Close() is called.
IOReturn ( *Open)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use. Return Value An IOReturn error code

OpenWithSessionRef
An open function which allows this interface to have access to the device when already opened. The service which has already opened the device must be able to provide an IOFireWireSessionRef.
IOReturn ( *OpenWithSessionRef)( IOFireWireLibDeviceRef self, IOFireWireSessionRef sessionRef);

Parameters
self

The device interface to use

sessionRef

The sessionRef returned from the client who has the device open Return Value An IOReturn error code

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

184

IOFireWireDeviceInterface Instance Methods

PrintDCLProgram
Walk a DCL program linked list and print its contents
void ( *PrintDCLProgram)( IOFireWireLibDeviceRef self, const DCLCommand *inProgram, UInt32 inLength);

Parameters
self

The device interface to use.

inProgram

A pointer to the first DCL of the program to print

inLength

Number of DCLs expected in the program. PrintDCLProgram() will report an error if this number does not match the number of DCLs found in the program.

Read
Perform synchronous block read
IOReturn ( *Read)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, void *buf, UInt32 *size, Boolean failOnReset, UInt32 generation);

Parameters
self

The device interface to use.

device

The service (representing an attached FireWire device) to read. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr

Command target address

buf

A pointer to a buffer where the results will be stored

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

185

IOFireWireDeviceInterface Instance Methods

size

Number of bytes to read

failOnReset

Pass true if the command should only be executed during the FireWire bus generation specified in generation. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation

ReadQuadlet
Perform synchronous quadlet read
IOReturn ( *ReadQuadlet)( IOFireWireLibDeviceRef self, io_object_t device, const FWAddress *addr, UInt32 *val, Boolean failOnReset, UInt32 generation);

Parameters
self

The device interface to use.

device

Command target address

val

A pointer to where to data should be stored

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

186

IOFireWireDeviceInterface Instance Methods

failOnReset

ReleaseIRMBandwidthInGeneration
Attempt to release some isochronous bandwidth from the IRM
IOReturn ( *ReleaseIRMBandwidthInGeneration)( IOFireWireLibDeviceRef self, UInt32 bandwidthUnits, UInt32 generation);

Parameters
bandwidthUnits

The number of bandwidth units to release

generation

The bus generation that this release attempt is to take place in. Return Value Returns kIOReturnSuccess if bandwidth release was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed) Discussion Attempts to release some isochronous bandwidth from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

ReleaseIRMChannelInGeneration
Attempt to release an isochronous channel from the IRM

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

187

IOFireWireDeviceInterface Instance Methods

IOReturn ( *ReleaseIRMChannelInGeneration)( IOFireWireLibDeviceRef self, UInt8 isochChannel, UInt32 generation);

Parameters
isochChannel

The isochronous channel to release

generation

The bus generation that this release attempt is to take place in. Return Value Returns kIOReturnSuccess if channel relase was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed) Discussion Attempts to release an isochronous channel from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

RemoveCallbackDispatcherFromRunLoop
Reverses the effects of AddCallbackDispatcherToRunLoop(). This method removes the run loop event source that was added to the specified run loop preventing any future callbacks from being called
const void ( *RemoveCallbackDispatcherFromRunLoop)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use.

RemoveIsochCallbackDispatcherFromRunLoop
Removes an IOFireWireLib-added run loop event source.
void ( *RemoveIsochCallbackDispatcherFromRunLoop)( IOFireWireLibDeviceRef self);

Parameters
self

The device interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

188

IOFireWireDeviceInterface Instance Methods

Discussion Reverses the effects of AddIsochCallbackDispatcherToRunLoop(). This method removes the run loop event source that was added to the specified run loop preventing any future callbacks from being called. Availability: IOFireWireDeviceInterface_v3, and newer

Seize
Seize control of device/unit
IOReturn ( *Seize)( IOFireWireLibDeviceRef self, IOOptionBits inFlags, ... );

Parameters
self

The device interface to use.

inFlags

Reserved for future use. Set to NULL. Description forthcoming? Discussion Allows a user space client to seize control of an in-kernel service even if that service has been Opened() by another client or in-kernel driver. This function should be used with care. Admin rights are required to use this function. Calling this method makes it appear to all other drivers that the device has been unplugged. Open() should be called after this method has been invoked. When access is complete, Close() and then IOServiceRequestProbe() should be called to restore normal operation. Calling IOServiceRequestProbe() makes it appear that the device has been "re-plugged."

SetBusResetDoneHandler
Sets the callback that should be called after a bus reset has occurred and reconfiguration of the bus has been completed. This function will only be called once per bus reset.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

189

IOFireWireDeviceInterface Instance Methods

const IOFireWireBusResetDoneHandler ( *SetBusResetDoneHandler)( IOFireWireLibDeviceRef self, IOFireWireBusResetDoneHandler handler);

Parameters
self

The device interface to use.

handler

Function pointer to the handler to install Return Value Returns on IOFireWireBusResetDoneHandler function pointer to the previously installed bus reset handler. Returns 0 if none was set.

SetBusResetHandler
Sets the callback that should be called when a bus reset occurs. Note that this callback can be called multiple times before the bus reset done handler is called. (f.ex., multiple bus resets might occur before bus reconfiguration has completed.)
const IOFireWireBusResetHandler ( *SetBusResetHandler)( IOFireWireLibDeviceRef self, IOFireWireBusResetHandler handler);

Parameters
self

The device interface to use.

handler

Function pointer to the handler to install Return Value Returns an IOFireWireBusResetHandler function pointer to the previously installed bus reset handler. Returns 0 if none was set.

SetRefCon
Set user reference value on this interface

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

190

IOFireWireDeviceInterface Instance Methods

void ( SetRefCon)( IOFireWireLibDeviceRef self, const void refCon);

Parameters
self

The device interface to use.

refCon

The reference value to set.

TurnOffNotification
Deactivates and callbacks specified for this device interface. Reverses the effects of TurnOnNotification()
void ( *TurnOffNotification)( IOFireWireLibDeviceRef self);

val

The value to write

failOnReset

Instance Variables
revision
UInt32 revision; // version/revision

Interface revision

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

193

IOFireWireDeviceInterface Instance Variables

version
UInt32 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

194

IOFireWireIsochChannelInterface

Declared in

IOFireWireLibIsoch.h

Overview
FireWire user client isochronous channel object. IOFireWireIsochChannelInterface is an abstract representataion of a FireWire bus isochronous channel. This interface coordinates starting and stopping traffic on a FireWire bus isochronous channel and can optionally communicate with the IRM to automatically allocate bandwidth and channel numbers. When using automatic IRM allocation, the channel interface reallocates its bandwidth and channel reservation after each bus reset. Isochronous port interfaces representing FireWire isochronous talkers and listeners must be added to the channel using SetTalker() and AddListener()

Tasks
Miscellaneous
AddListener

(page 196) Modify the transfer size of a transfer packet DCL (send or receive) (page 197) Prepare all hardware to begin sending or receiving isochronous data. (page 197)

AllocateChannel

ClientCommandIsComplete

GetRefCon

(page 197) Set reference value associated with this channel. (page 198)

NotificationIsOn

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

195

IOFireWireIsochChannelInterface Instance Methods

ReleaseChannel

(page 198) Release all hardware after stopping the isochronous channel. (page 198) Set the channel force stop handler. (page 199) Set reference value associated with this channel. (page 199) Set the talker port for this channel. (page 200) Start the channel.

SetChannelForceStopHandler

SetRefCon

SetTalker

Start

Stop

(page 200) Stop the channel. (page 201)

TurnOffNotification

TurnOnNotification

(page 201)

Instance Methods
AddListener
Modify the transfer size of a transfer packet DCL (send or receive)
IOReturn ( *AddListener) ( IOFireWireLibIsochChannelRef self, IOFireWireLibIsochPortRef listener );

Parameters
self

The isoch channel interface to use.

listener

The listener to add. Return Value Returns an IOReturn error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

196

IOFireWireIsochChannelInterface Instance Methods

Discussion Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The transfer size can be set to any size less than or equal to the size set when the DCL program was compiled (including 0). Availability: IOFireWireLocalIsochPortInterface_v3 and newer.

AllocateChannel
Prepare all hardware to begin sending or receiving isochronous data.
IOReturn ( *AllocateChannel) ( IOFireWireLibIsochChannelRef self );

Parameters
self

The isoch channel interface to use. Return Value Returns an IOReturn error code. Discussion Calling this function will result in all listener and talker ports on this isochronous channel having their AllocatePort method called.

ClientCommandIsComplete
void ( *ClientCommandIsComplete) ( IOFireWireLibIsochChannelRef self, FWClientCommandID commandID, IOReturn status);

Discussion Description forthcoming

GetRefCon
Set reference value associated with this channel.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

197

IOFireWireIsochChannelInterface Instance Methods

void* ( *GetRefCon) ( IOFireWireLibIsochChannelRef self);

Parameters
self

The isoch channel interface to use. Discussion Retrieve the reference value with SetRefCon()

NotificationIsOn
Boolean ( *NotificationIsOn) ( IOFireWireLibIsochChannelRef self);

Discussion Description forthcoming

ReleaseChannel
Release all hardware after stopping the isochronous channel.
IOReturn ( *ReleaseChannel) ( IOFireWireLibIsochChannelRef self );

Parameters
self

SetChannelForceStopHandler
Set the channel force stop handler.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

198

IOFireWireIsochChannelInterface Instance Methods

IOFireWireIsochChannelForceStopHandler ( *SetChannelForceStopHandler) ( IOFireWireLibIsochChannelRef self, IOFireWireIsochChannelForceStopHandler stopProc);

Parameters
self

The isoch channel interface to use.

stopProc

The handler to set. Return Value Returns the previously set handler or NULL is no handler was set. Discussion The specified callback is called when the channel is stopped and cannot be restarted automatically.

SetRefCon
Set reference value associated with this channel.
void ( *SetRefCon) ( IOFireWireLibIsochChannelRef self, void *stopProcRefCon);

Parameters
self

The isoch channel interface to use.

stopProcRefCon

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

200

IOFireWireIsochChannelInterface Instance Variables

Return Value Returns an IOReturn error code. Discussion Calling this function will result in all listener and talker ports on this isochronous channel having their Stop method called.

TurnOffNotification
void ( *TurnOffNotification) ( IOFireWireLibIsochChannelRef self);

Discussion Description forthcoming

TurnOnNotification
Boolean ( *TurnOnNotification) ( IOFireWireLibIsochChannelRef self);

Discussion Description forthcoming

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

201

IOFireWireIsochPortInterface

Declared in

IOFireWireLibIsoch.h

Overview
FireWire user client isochronous port interface Isochronous ports represent talkers or listeners on a FireWire isochronous channel. This is a base class containing all isochronous port functionality not specific to any type of port. Ports are added to channel interfaces (IOFireWireIsochChannelInterface) which coordinate the start and stop of isochronous traffic on a FireWire bus isochronous channel.

Tasks
Miscellaneous
AllocatePort

(page 203) The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified. (page 203) Get reference value associated with this port. (page 204) The method is called to determine which FireWire isochronous channels and speed this port supports. (page 204) The method is called to release the hardware after the channel has been stopped. (page 205) Set reference value associated with this port. (page 205) The method is called when the port is to begin talking or listening.

GetRefCon

GetSupported

ReleasePort

SetRefCon

Start

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

202

IOFireWireIsochPortInterface Instance Methods

Stop

(page 206) The method is called when the port is to stop talking or listening.

Instance Methods
AllocatePort
The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified.
IOReturn ( *AllocatePort) ( IOFireWireLibIsochPortRef self, IOFWSpeed speed, UInt32 chan );

Parameters
self

The isoch port interface to use.

speed

Channel speed
chan

Channel number (-63) Return Value Return kIOReturnSuccess on success, other return any other IOReturn error code. Discussion This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

GetRefCon
Get reference value associated with this port.
void* ( *GetRefCon) ( IOFireWireLibIsochPortRef self);

Parameters
self

The isoch port interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

203

IOFireWireIsochPortInterface Instance Methods

Return Value The port refcon value. Discussion Set the reference value with SetRefCon()

GetSupported
The method is called to determine which FireWire isochronous channels and speed this port supports.
IOReturn ( *GetSupported) ( IOFireWireLibIsochPortRef self, IOFWSpeed *maxSpeed, UInt64 *chanSupported );

Parameters
self

The isoch port interface to use.

maxSpeed

A pointer to an IOFWSpeed which should be filled with the maximum speed this port can talk or listen.
chanSupported

A pointer to a UInt64 which should be filled with a bitmask representing the FireWire bus isochonous channels on which the port can talk or listen. Set '1' for supported, '' for unsupported. Return Value Return kIOReturnSuccess on success, other return any other IOReturn error code. Discussion This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

ReleasePort
The method is called to release the hardware after the channel has been stopped.
IOReturn ( *ReleasePort) ( IOFireWireLibIsochPortRef self );

Parameters
self

The isoch port interface to use.

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

206

IOFireWireLibIRMAllocationInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Description forthcoming

Tasks
Miscellaneous
allocateIsochResources

(page 208) Use this interface to allocate isochronous resources (page 208) Poll to see if IRM resources are still allocated (page 209) Deallocate previously allocated resources (page 209) Get the current refcon (page 209) Is notification on? (page 210) Set a new refcon (page 210) Set a new value for releaseIRMResourcesOnFree (page 210) Force notification off. (page 211) Try to turn on notifications

areIsochResourcesAllocated

deallocateIsochResources

GetRefCon

NotificationIsOn

SetRefCon

setReleaseIRMResourcesOnFree

TurnOffNotification

TurnOnNotification

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

207

IOFireWireLibIRMAllocationInterface Instance Methods

Instance Methods
allocateIsochResources
Use this interface to allocate isochronous resources
IOReturn ( *allocateIsochResources)( IOFireWireLibIRMAllocationRef self, UInt8 isochChannel, UInt32 bandwidthUnits);

The IRMAllocation interface to use. Return Value Returns the current refcon value

NotificationIsOn
Is notification on?
Boolean ( *NotificationIsOn)( IOFireWireLibIRMAllocationRef self);

TurnOffNotification
Force notification off.
void ( *TurnOffNotification)( IOFireWireLibIRMAllocationRef self);

Parameters
self

The IRMAllocation interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

210

IOFireWireLibIRMAllocationInterface Instance Methods

TurnOnNotification
Try to turn on notifications
Boolean ( *TurnOnNotification)( IOFireWireLibIRMAllocationRef self);

Parameters
self

The IRMAllocation interface to use. Return Value Returns true upon success

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

211

IOFireWireLibPHYPacketListenerInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Represents and provides management functions for a phy packet listener object.

Tasks
Miscellaneous
ClientCommandIsComplete

(page 213) Notify the PHY packet listener object that a packet notification handler has completed. (page 213) get the flags of listener. (page 214) Returns the user refCon value for thisinterface. (page 214) Is notification on? (page 214) set flags for the listener. (page 215) Set the callback that should be called to handle incoming phy packets (page 215) Sets the user refCon value for this interface. (page 215) Set the callback that should be called when incoming phy packets are dropped by the listener space. (page 216) Turn packet notification off.

GetFlags

GetRefCon

NotificationIsOn

SetFlags

SetListenerCallback

SetRefCon

SetSkippedPacketCallback

TurnOffNotification

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

212

IOFireWireLibPHYPacketListenerInterface Instance Methods

TurnOnNotification

(page 216) Try to turn on packet notifications for this listener.

Instance Methods
ClientCommandIsComplete
Notify the PHY packet listener object that a packet notification handler has completed.
void ( *ClientCommandIsComplete)( IOFireWireLibPHYPacketListenerRef self, FWClientCommandID commandID );

Parameters
self

The PHY packet listener object.

commandID

The ID of the packet notification being completed. This is the same ID that was passed when a packet notification handler is called. Discussion Packet notifications are received one at a time, in order. This function must be called after a packet handler has completed its work.

GetFlags
get the flags of listener.
UInt32 ( *GetFlags)( IOFireWireLibPHYPacketListenerRef self );

Parameters
self

The PHY packet listener object. Return Value flags No current flags are defined.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

213

IOFireWireLibPHYPacketListenerInterface Instance Methods

GetRefCon
Returns the user refCon value for thisinterface.
void* ( *GetRefCon)( IOFireWireLibPHYPacketListenerRef self );

Parameters
self

The PHY packet listener object. Return Value returns the refcon

NotificationIsOn
Is notification on?
Boolean ( *NotificationIsOn)( IOFireWireLibPHYPacketListenerRef self );

Parameters
self

The PHY packet listener object. Return Value Returns true if packet notifications for this listener are active

SetFlags
set flags for the listener.
void ( *SetFlags)( IOFireWireLibPHYPacketListenerRef self, UInt32 flags );

refcon

the refcon

SetSkippedPacketCallback
Set the callback that should be called when incoming phy packets are dropped by the listener space.
void ( *SetSkippedPacketCallback)( IOFireWireLibPHYPacketListenerRef self, IOFireWireLibPHYPacketSkippedCallback inCallback );

Parameters
self

The PHY packet listener object.

inCallback

The callback to set.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

215

IOFireWireLibPHYPacketListenerInterface Instance Variables

TurnOffNotification
Turn packet notification off.
void ( *TurnOffNotification)( IOFireWireLibPHYPacketListenerRef self );

Parameters
self

The PHY packet listener object.

TurnOnNotification
Try to turn on packet notifications for this listener.
IOReturn ( *TurnOnNotification)( IOFireWireLibPHYPacketListenerRef self );

Parameters
self

The PHY packet listener object. Return Value Returns kIOReturnSuccess if successful

Instance Variables
revision
UInt16 revision;

Interface revision.

version
UInt16 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

216

IOFireWireLibVectorCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib command object for grouping commands execution. 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.

Tasks
Miscellaneous
AddCommand

(page 218) Adds a command to the vector command. (page 219) Sets the number of commands this vector can hold. (page 219) Returns the command at a given index. (page 220) Returns the number of commands currently in this vector. (page 220) Get the flags currently set for this command. (page 221) Returns the index of the specified command.

EnsureCapacity

GetCommandAtIndex

GetCommandCount

GetFlags

GetIndexOfCommand

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

217

IOFireWireLibVectorCommandInterface Instance Methods

GetRefCon

(page 221) Get the reference constant for this command. (page 221) Inserts a command at a given index. Commands at and after this index will be moved to their next sequential index. (page 222) Checks if the vector command is currently executing. (page 222) Removes all commands from the vector. (page 223) Removes a command to the vector command. (page 223) Removes the command at a give index. Commands at and afte this index will be moved to their previous sequential index. (page 223) Set the callback routine for this command. (page 224) Set flags governing this command's execution. (page 225) Set the reference constant for this command. (page 225) Submit this command object to FireWire for execution. (page 225) Submit this command object to FireWire for execution.

InsertCommandAtIndex

IsExecuting

RemoveAllCommands

RemoveCommand

RemoveCommandAtIndex

SetCallback

SetFlags

SetRefCon

Submit(IOFireWireLibVectorCommandRef)

Submit(IOFireWireLibVectorCommandRef, void *, IOFireWireLibCommandCallback)

SubmitWithRefconAndCallback

(page 226) Submit this command object to FireWire for execution.

Instance Methods
AddCommand
Adds a command to the vector command.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

218

IOFireWireLibVectorCommandInterface Instance Methods

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

219

IOFireWireLibVectorCommandInterface Instance Methods

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

220

IOFireWireLibVectorCommandInterface Instance Methods

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

221

IOFireWireLibVectorCommandInterface Instance Methods

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

222

IOFireWireLibVectorCommandInterface Instance Methods

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

index

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

223

IOFireWireLibVectorCommandInterface Instance Methods

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

224

IOFireWireLibVectorCommandInterface Instance Methods

SetRefCon
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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

225

IOFireWireLibVectorCommandInterface Instance Methods

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.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

226

IOFireWireLibVectorCommandInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

227

IOFireWireLocalIsochPortInterface

Declared in

IOFireWireLibIsoch.h

Overview
FireWire user client local isochronous port object. Represents a FireWire isochronous talker or listener within the local machine. Isochronous transfer is controlled by an associated DCL (Data Stream Control Language) program, which is similar to a hardware DMA program but is hardware agnostic. DCL programs can be written using the IOFireWireDCLCommandPoolInterface object. This interface contains all methods of IOFireWireIsochPortInterface and IOFireWireLocalIsochPortInterface. This interface will contain all v2 methods of IOFireWireLocalIsochPortInterface when instantiated as v2 or newer. Transfer buffers for the local isoch port must all come from a single allocation made with vm_allocate() or mmap(..., MAP_ANON ). Calling vm_deallocate() on the buffers before deallocating a local isoch port object may result in a deadlock. Note: Calling Release() on the local isoch port may not immediately release the isoch port; so it may not be safe to call vm_deallocate() on your transfer buffers. To guarantee the port has been release, run the isochronous runloop until the port is finalized (it has processed any pending callbacks). The finalize callback will be called when the port is finalized. Set the finalize callback using SetFinalizeCallback().

Tasks
Miscellaneous
AllocatePort

(page 229) The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified. (page 230) Get reference value associated with this port.

GetRefCon

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

228

IOFireWireLocalIsochPortInterface Instance Methods

GetSupported

(page 230) The method is called to determine which FireWire isochronous channels and speed this port supports. (page 231) Change the jump target label of a jump DCL. (page 232) Modify the transfer size of a transfer packet DCL (send or receive) (page 232) NOT IMPLEMENTED. Modify the transfer size of a transfer packet DCL (send or receive) (page 233) Modify the transfer size of a transfer packet DCL (send or receive) (page 234) Display the contents of a DCL program. (page 234) The method is called to release the hardware after the channel has been stopped. (page 235) Set the finalize callback for a local isoch port (page 235) Set reference value associated with this port. (page 236) The method is called when the port is to begin talking or listening.

ModifyJumpDCL

ModifyTransferPacketDCL

ModifyTransferPacketDCLBuffer

ModifyTransferPacketDCLSize

PrintDCLProgram

ReleasePort

SetFinalizeCallback

SetRefCon

Start

Stop

(page 236) The method is called when the port is to stop talking or listening.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

229

IOFireWireLocalIsochPortInterface Instance Methods

IOReturn ( *AllocatePort) ( IOFireWireLibIsochPortRef self, IOFWSpeed speed, UInt32 chan );

Parameters
self

The isoch port interface to use.

speed

Channel speed
chan

GetRefCon
Get reference value associated with this port.
void* ( *GetRefCon) ( IOFireWireLibIsochPortRef self);

Parameters
self

The isoch port interface to use. Return Value The port refcon value. Discussion Set the reference value with SetRefCon()

GetSupported
The method is called to determine which FireWire isochronous channels and speed this port supports.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

230

IOFireWireLocalIsochPortInterface Instance Methods

IOReturn ( GetSupported) ( IOFireWireLibIsochPortRef self, IOFWSpeed maxSpeed, UInt64 *chanSupported );

Parameters
self

The isoch port interface to use.

maxSpeed

A pointer to an IOFWSpeed which should be filled with the maximum speed this port can talk or listen.
chanSupported

ModifyJumpDCL
Change the jump target label of a jump DCL.
IOReturn ( *ModifyJumpDCL)( IOFireWireLibLocalIsochPortRef self, DCLJump *inJump, DCLLabel *inLabel);

Parameters
self

The local isoch port interface to use.

inJump

The jump DCL to modify.

inLabel

The label to jump to. Return Value kIOReturnSuccess on success. Will return an error if 'inJump' does not point to a valid jump DCL or 'inLabel' does not point to a valid label DCL.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

231

IOFireWireLocalIsochPortInterface Instance Methods

Discussion Use this function to change the flow of a DCL program. Works whether the DCL program is currently running or not.

ModifyTransferPacketDCL
Modify the transfer size of a transfer packet DCL (send or receive)
IOReturn ( *ModifyTransferPacketDCL)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket *inDCL, void *buffer, IOByteCount size );

Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

buffer

The new buffer to or from data will be transferred.

size

The new size of data to be transferred. Return Value Returns kIOReturnSuccess on success. Will return an error if 'size' is too large or 'inDCL' does not point to a valid transfer packet DCL, or the range specified by [buffer, buffer+size] is not in the range of memory locked down for this program. Discussion Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The transfer size can be set to any size less than or equal to the size set when the DCL program was compiled (including 0). Availability: IOFireWireLocalIsochPortInterface_v3 and newer.

ModifyTransferPacketDCLBuffer
NOT IMPLEMENTED. Modify the transfer size of a transfer packet DCL (send or receive)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

232

IOFireWireLocalIsochPortInterface Instance Methods

IOReturn ( ModifyTransferPacketDCLBuffer)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket inDCL, void *buffer );

Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

buffer

The new buffer to or from data will be transferred. Return Value Returns kIOReturnSuccess on success. Will return an error if the range specified by [buffer, buffer+size] is not in the range of memory locked down for this program. Discussion NOT IMPLEMENTED. Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The buffer can be set to be any location within the range of buffers specified when the DCL program was compiled (including 0). Availability: IOFireWireLocalIsochPortInterface_v3 and newer.

ModifyTransferPacketDCLSize
Modify the transfer size of a transfer packet DCL (send or receive)
IOReturn ( *ModifyTransferPacketDCLSize)( IOFireWireLibLocalIsochPortRef self, DCLTransferPacket *inDCL, IOByteCount size );

Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

size

The new size of data to be transferred.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

233

IOFireWireLocalIsochPortInterface Instance Methods

Return Value Returns kIOReturnSuccess on success. Will return an error if 'size' is too large for this program. Discussion Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The transfer size can be set to any size less than or equal to the size set when the DCL program was compiled (including 0). Availability: IOFireWireLocalIsochPortInterface_v2 and newer.

PrintDCLProgram
Display the contents of a DCL program.
void ( *PrintDCLProgram)( IOFireWireLibLocalIsochPortRef self, const DCLCommand *inProgram, UInt32 inLength);

Parameters
self

The local isoch port interface to use.

inProgram

A pointer to the first DCL of the program to display.

inLength

The length (in DCLs) of the program.

ReleasePort
The method is called to release the hardware after the channel has been stopped.
IOReturn ( *ReleasePort) ( IOFireWireLibIsochPortRef self );

Parameters
self

The isoch port interface to use. Return Value Return kIOReturnSuccess on success, other return any other IOReturn error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

234

IOFireWireLocalIsochPortInterface Instance Methods

Discussion This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

SetFinalizeCallback
Set the finalize callback for a local isoch port
IOReturn ( *SetFinalizeCallback)( IOFireWireLibLocalIsochPortRef self, IOFireWireLibIsochPortFinalizeCallback finalizeCallback );

Parameters
self

The local isoch port interface to use.

finalizeCallback

The finalize callback. Return Value Returns true if this isoch port has no more pending callbacks and does not need any more runloop time. Discussion When Stop() is called on a LocalIsochPortInterface, there may or may not be isoch callbacks still pending for this isoch port. The port must be allowed to handle any pending callbacks, so the isoch runloop should not be stopped until a port has handled all pending callbacks. The finalize callback is called after the final callback has been made on the isoch runloop. After this callback is sent, it is safe to stop the isoch runloop. You should not access the isoch port after the finalize callback has been made; it may be released immediately after this callback is sent. Availability: IOFireWireLocalIsochPortInterface_v4 and newer.

SetRefCon
Set reference value associated with this port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

235

IOFireWireLocalIsochPortInterface Instance Methods

void ( SetRefCon) ( IOFireWireLibIsochPortRef self, void inRefCon);

Parameters
self

The isoch port interface to use.

inRefCon

The new reference value. Discussion Retrieve the reference value with GetRefCon()

Start
The method is called when the port is to begin talking or listening.
IOReturn ( *Start) ( IOFireWireLibIsochPortRef self );

Parameters
self

Stop
The method is called when the port is to stop talking or listening.
IOReturn ( *Stop) ( IOFireWireLibIsochPortRef self );

Parameters
self

The isoch port interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

236

IOFireWireLocalIsochPortInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision

version
UInt32 version;

Interface revision

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

237

IOFireWireLocalUnitDirectoryInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Allows creation and management of unit directories in the config ROM of the local machine. After the unit directory has been built, Publish() should be called to cause it to appear in the config ROM. Unpublish() has the reverse effect as Publish(). This interface can be created using IOFireWireDeviceInterface::CreateLocalUnitDirectory.

Tasks
Miscellaneous
AddEntry_FWAddress

(page 239) Append an offset leaf (page 239) Append a data leaf (page 240) Append an immediate leaf (page 240) Causes a constructed or updated unit directory to appear in the local machine's config ROM. Note that this call will cause a bus reset, after which the unit directory will be visible to devices on the bus. (page 241) Has the opposite effect from Publish(). This call removes a unit directory from the local machine's config ROM. Note that this call will cause a bus reset, after which the unit directory will no longer appear to devices on the bus.

AddEntry_Ptr

AddEntry_UInt32

Publish

Unpublish

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

238

IOFireWireLocalUnitDirectoryInterface Instance Methods

Instance Methods
AddEntry_FWAddress
Append an offset leaf
IOReturn ( *AddEntry_FWAddress)( IOFireWireLibLocalUnitDirectoryRef self, int key, const FWAddress *value, CFStringRef inDesc);

Parameters
self

The local unit directory interface to use.

key

The config ROM key for the data to be added.

value

A pointer to a FireWire address.

inDesc

Reserved; set to NULL. Discussion Appends an offset leaf to a unit directory. The address passed in value should be an address in initial unit space of the local config ROM.

AddEntry_Ptr
Append a data leaf
IOReturn ( *AddEntry_Ptr)( IOFireWireLibLocalUnitDirectoryRef self, int key, void *inBuffer, size_t inLen, CFStringRef inDesc);

Parameters
self

The local unit directory interface to use.

key

The config ROM key for the data to be added.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

239

IOFireWireLocalUnitDirectoryInterface Instance Methods

inBuffer

A pointer to the data to be placed in the added leaf.

inLen

Length of the data being added.

inDesc

Reserved; set to NULL. Discussion Appends a leaf data node to a unit directory

AddEntry_UInt32
Append an immediate leaf
IOReturn ( *AddEntry_UInt32)( IOFireWireLibLocalUnitDirectoryRef self, int key, UInt32 value, CFStringRef inDesc);

Parameters
self

The local unit directory interface to use.

key

The config ROM key for the data to be added.

value

The value to be added.

inDesc

Reserved; set to NULL. Discussion Appends an immediate leaf to a unit directory. Note that only the lower 3 bytes of the passed in value can appear in the unit directory.

Publish
Causes a constructed or updated unit directory to appear in the local machine's config ROM. Note that this call will cause a bus reset, after which the unit directory will be visible to devices on the bus.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

240

IOFireWireLocalUnitDirectoryInterface Instance Variables

IOReturn ( *Publish)( IOFireWireLibLocalUnitDirectoryRef self);

Parameters
self

The local unit directory interface to use.

Unpublish
Has the opposite effect from Publish(). This call removes a unit directory from the local machine's config ROM. Note that this call will cause a bus reset, after which the unit directory will no longer appear to devices on the bus.
IOReturn ( *Unpublish)( IOFireWireLibLocalUnitDirectoryRef self);

Parameters
self

The local unit directory interface to use.

Instance Variables
revision
UInt32 revision;

Interface revision

version
UInt32 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

241

IOFireWireNubInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib. You can use IOFireWireDeviceInterface to:

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

242

IOFireWireNubInterface Overview

create interfaces which provide isochronous services (see IOFireWireLibIsoch.h). These include:

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

243

IOFireWireNuDCLPoolInterface

Declared in

IOFireWireLibIsoch.h

Overview
Use this interface to build NuDCL-based DCL programs.

Tasks
Miscellaneous
AllocateReceivePacket

(page 247) Allocate a ReceivePacket NuDCL and append it to the program (page 248) Allocate a ReceivePacket NuDCL and append it to the program (page 248) Allocate a SendPacket NuDCL and append it to the program. (page 249) Allocate a SendPacket NuDCL and append it to the program. (page 250) Allocate a SkipCycle NuDCL and append it to the program. (page 250) Add a memory range to the scatter gather list of a NuDCL (page 251)

AllocateReceivePacket_v

AllocateSendPacket

AllocateSendPacket_v

AllocateSkipCycle

AppendDCLRanges

AppendDCLUpdateList

CopyDCLUpdateList

(page 251)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

244

IOFireWireNuDCLPoolInterface Tasks

CountDCLRanges

(page 251) Returns number of buffers for a NuDCL (page 252) Get the next pointer for a NuDCL (page 252) Get the branch pointer for a NuDCL (page 252) Get callback for a NuDCL (page 253)

FindDCLNextDCL

GetDCLBranch

GetDCLCallback

GetDCLFlags

GetDCLRanges

(page 253) Get the scatter-gather list for a NuDCL (page 254)

GetDCLRefcon

GetDCLs

(page 254) Returns the pool's DCL program as a CFArray of NuDCLRef's. (page 254) Returns number of bytes to be transferred by a NuDCL (page 255) (page 255)

GetDCLSize

GetDCLSkipBranch

GetDCLSkipCallback

GetDCLSkipRefcon

(page 255)

GetDCLSpan

(page 255) Returns a virtual range spanning lowest referenced buffer address to highest (page 256) Get the status pointer for a NuDCL. (page 256)

GetDCLStatusPtr

GetDCLSyncBits

GetDCLTagBits

(page 256)

GetDCLTimeStampPtr

(page 256) Get the time stamp pointer for a NuDCL.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

245

IOFireWireNuDCLPoolInterface Tasks

GetDCLUserHeaderPtr

(page 257)

GetProgram

(page 257) Finds the first DCL in the pool not preceeded by any other DCL. (page 258)

GetUserHeaderMaskPtr

PrintDCL

(page 258) (page 258) (page 258)

PrintProgram

RemoveDCLUpdateList

SetCurrentTagAndSync

(page 258) Set current tag and sync bits (page 259) Set the branch pointer for a NuDCL (page 259) Set the callback for a NuDCL (page 260)

SetDCLBranch

SetDCLCallback

SetDCLFlags

SetDCLRanges

(page 260) Set the scatter gather list for a NuDCL (page 261) (page 262) (page 262)

SetDCLRefcon

SetDCLSkipBranch

SetDCLSkipCallback

SetDCLSkipRefcon

(page 262)

SetDCLStatusPtr

(page 262) Set the status pointer for a NuDCL (page 264)

SetDCLSyncBits

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

246

IOFireWireNuDCLPoolInterface Instance Methods

SetDCLTagBits

(page 264)

SetDCLTimeStampPtr

(page 264) Set the time stamp pointer for a NuDCL (page 265)

SetDCLUpdateList

SetDCLUserHeaderPtr

(page 265) Set a user specified header for a send NuDCL (page 266)

SetDCLWaitControl

Instance Methods
AllocateReceivePacket
Allocate a ReceivePacket NuDCL and append it to the program
NuDCLReceivePacketRef ( *AllocateReceivePacket)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt8 headerBytes, UInt32 numBuffers, IOVirtualRange *buffers );

Parameters
self

The NuDCL pool to use.

headerBytes

Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8.
saveBag

The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure.
numBuffers

The number of virtual ranges in 'buffers'.

buffers

An array of virtual memory ranges containing the packet contents. The array is copied into the DCL.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

247

IOFireWireNuDCLPoolInterface Instance Methods

Return Value Returns an NuDCLReceivePacketRef on success or 0 on failure. Discussion The ReceivePacket DCL receives an isochronous packet from the bus. One DCL runs per bus cycle. If receiving isochronous headers, an update must be run before the isochronous header is valid. Receive DCLs can be modified using other functions of IOFireWireLibNuDCLPool.

AllocateReceivePacket_v
Allocate a ReceivePacket NuDCL and append it to the program
NuDCLReceivePacketRef ( *AllocateReceivePacket_v)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt8 headerBytes, IOVirtualRange *firstRange, ... );

Parameters
self

The NuDCL pool to use.

saveBag

Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8.
firstRange

The first buffer to be transmitted. Follow with additional ranges; terminate with NULL. Return Value Returns an NuDCLReceivePacketRef on success or 0 on failure. Discussion Same as AllocateReceivePacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's

AllocateSendPacket
Allocate a SendPacket NuDCL and append it to the program.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

248

IOFireWireNuDCLPoolInterface Instance Methods

NuDCLSendPacketRef ( *AllocateSendPacket)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, UInt32 numBuffers, IOVirtualRange *buffers );

Parameters
self

The NuDCL pool to use.

saveBag

The number of virtual ranges in 'buffers'.

buffers

An array of virtual memory ranges containing the packet contents. The array is copied into the DCL. Return Value Returns an NuDCLSendPacketRef on success or 0 on failure. Discussion The SendPacket DCL sends an isochronous packet on the bus. One DCL runs per bus cycle. The isochronous header is automatically generated, but can be overriden. An update must be run to regenerate the isochronous header. The sync and tag fields of allocated DCLs default to 0, unless If SetCurrentTagAndSync has been called. Send DCLs can be modified using other functions of IOFireWireLibNuDCLPool.

AllocateSendPacket_v
Allocate a SendPacket NuDCL and append it to the program.
NuDCLSendPacketRef ( *AllocateSendPacket_v)( IOFireWireLibNuDCLPoolRef self, CFMutableSetRef saveBag, IOVirtualRange *firstRange, ... );

Parameters
self

The NuDCL pool to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

249

IOFireWireNuDCLPoolInterface Instance Methods

saveBag

The first buffer to be transmitted. Follow with additional ranges; terminate with NULL. Return Value Returns an NuDCLSendPacketRef on success or 0 on failure. Discussion Same as AllocateSendPacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's

AllocateSkipCycle
Allocate a SkipCycle NuDCL and append it to the program.
NuDCLSkipCycleRef ( *AllocateSkipCycle)( IOFireWireLibNuDCLPoolRef self );

Parameters
self

The NuDCL pool to use. Return Value Returns an NuDCLSkipCycleRef on success or 0 on failure. Discussion The SkipCycle DCL causes the DCL program to "sends" an empty cycle.

AppendDCLRanges
Add a memory range to the scatter gather list of a NuDCL
IOReturn ( *AppendDCLRanges) ( NuDCLRef dcl, UInt32 numRanges, IOVirtualRange *range );

Parameters
dcl

The DCL to modify

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

250

IOFireWireNuDCLPoolInterface Instance Methods

range

A IOVirtualRange to add to this DCL buffer list. Do not pass NULL. Return Value Returns an IOReturn error code. Discussion This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify() Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef

AppendDCLUpdateList
IOReturn ( *AppendDCLUpdateList)( NuDCLRef dcl, NuDCLRef updateDCL );

Discussion Description forthcoming

CopyDCLUpdateList
CFSetRef ( *CopyDCLUpdateList)( NuDCLRef dcl );

Discussion Description forthcoming

CountDCLRanges
Returns number of buffers for a NuDCL
UInt32 ( *CountDCLRanges) ( NuDCLRef dcl );

Parameters
dcl

The DCL to query Return Value Returns number of ranges in DCLs scatter-gather list

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

251

IOFireWireNuDCLPoolInterface Instance Methods

Discussion Applies: NuDCLSendPacketRef, NuDCLReceivePacket

FindDCLNextDCL
Get the next pointer for a NuDCL
NuDCLRef ( *FindDCLNextDCL)( IOFireWireLibNuDCLPoolRef self, NuDCLRef dcl );

Parameters
dcl

The dcl whose next pointer will be returned Return Value Returns the DCL immediately following this DCL in program order (ignoring branches) or 0 for none. Discussion Applies: Any NuDCLRef

GetDCLBranch
Get the branch pointer for a NuDCL
NuDCLRef ( *GetDCLBranch)( NuDCLRef dcl );

GetDCLRefcon
void* ( *GetDCLRefcon)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLs
Returns the pool's DCL program as a CFArray of NuDCLRef's.
CFArrayRef ( *GetDCLs)( IOFireWireLibNuDCLPoolRef self );

Parameters
self

The NuDCL pool to use. Return Value A CFArrayRef.

GetDCLSize
Returns number of bytes to be transferred by a NuDCL
IOByteCount ( *GetDCLSize) ( NuDCLRef dcl );

Parameters
dcl

The DCL to query Return Value Returns an IOByteCount. Discussion Applies: NuDCLSendPacketRef, NuDCLReceivePacket

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

254

IOFireWireNuDCLPoolInterface Instance Methods

GetDCLSkipBranch
NuDCLRef ( *GetDCLSkipBranch)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLSkipCallback
NuDCLCallback ( *GetDCLSkipCallback)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLSkipRefcon
void * ( *GetDCLSkipRefcon)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLSpan
Returns a virtual range spanning lowest referenced buffer address to highest
IOReturn ( *GetDCLSpan) ( NuDCLRef dcl, IOVirtualRange *spanRange );

Parameters
dcl

The DCL to query Return Value Returns an IOVirtualRange. Discussion Applies: NuDCLSendPacketRef, NuDCLReceivePacket

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

255

IOFireWireNuDCLPoolInterface Instance Methods

GetDCLStatusPtr
Get the status pointer for a NuDCL.
UInt32* ( *GetDCLStatusPtr)( NuDCLRef dcl );

Parameters
dcl

The DCL whose status pointer will be returned. Return Value Returns a UInt32 status pointer. Discussion Applies: Any NuDCLRef.

GetDCLSyncBits
UInt8 ( *GetDCLSyncBits)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLTagBits
UInt8 ( *GetDCLTagBits)( NuDCLRef dcl );

Discussion Description forthcoming

GetDCLTimeStampPtr
Get the time stamp pointer for a NuDCL.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

256

IOFireWireNuDCLPoolInterface Instance Methods

UInt32* ( *GetDCLTimeStampPtr)( NuDCLRef dcl );

Parameters
dcl

The DCL whose timestamp pointer will be returned. Return Value Returns a UInt32 time stamp pointer. Discussion Applies: Any NuDCLRef.

GetDCLUserHeaderPtr
UInt32 * ( *GetDCLUserHeaderPtr)( NuDCLRef dcl );

Discussion Description forthcoming

GetProgram
Finds the first DCL in the pool not preceeded by any other DCL.
DCLCommand* ( *GetProgram)( IOFireWireLibNuDCLPoolRef self );

Parameters
self

The NuDCL pool to use. Return Value A DCLCommand pointer. Discussion Returns a backwards-compatible DCL program pointer. This can be passed to IOFireWireLibDeviceRef::CreateLocalIsochPort.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

257

IOFireWireNuDCLPoolInterface Instance Methods

GetUserHeaderMaskPtr
UInt32 * ( *GetUserHeaderMaskPtr)( NuDCLRef dcl );

Discussion Description forthcoming

PrintDCL
void ( *PrintDCL)( NuDCLRef dcl );

Discussion Description forthcoming

PrintProgram
void ( *PrintProgram)( IOFireWireLibNuDCLPoolRef self );

Discussion Description forthcoming

RemoveDCLUpdateList
IOReturn ( *RemoveDCLUpdateList)( NuDCLRef dcl );

Discussion Description forthcoming

SetCurrentTagAndSync
Set current tag and sync bits

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

258

IOFireWireNuDCLPoolInterface Instance Methods

void ( *SetCurrentTagAndSync)( IOFireWireLibNuDCLPoolRef self, UInt8 tag, UInt8 sync );

Parameters
self

The NuDCL pool to use.

tag

Tag field value for subsequently allocated send DCLs

sync

Sync field value for subsequently allocated send DCLs Discussion Sets the DCL pool's current tag and sync bits. All send DCLs allocated after calling this function will transmit the specified tag and sync values. These fields can also be set on each DCL using SetDCLTagBits() and SetDCLSyncBits().

SetDCLBranch
Set the branch pointer for a NuDCL
IOReturn ( *SetDCLBranch)( NuDCLRef dcl, NuDCLRef branchDCL );

Return Value Returns an IOReturn error code. Discussion Program execution will jump to the DCL pointed to by 'branchDCL', after the DCL is executed. If set to 0, execution will stop after this DCL. This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify() Applies: Any NuDCLRef.

SetDCLCallback
Set the callback for a NuDCL

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

259

IOFireWireNuDCLPoolInterface Instance Methods

IOReturn ( *SetDCLCallback) ( NuDCLRef dcl, NuDCLCallback callback );

Parameters
dcl

The DCL to modify

callback

The callback function. Return Value Returns an IOReturn error code. Discussion A callback can be called each time a NuDCL is run. Use SetDCLCallback() to set the callback for a NuDCL. If the update option is also set, the callback will be called after the update has run. This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify() Applies: Any NuDCLRef

SetDCLFlags
void ( *SetDCLFlags)( NuDCLRef dcl, UInt32 flags );

Discussion Description forthcoming

SetDCLRanges
Set the scatter gather list for a NuDCL

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

260

IOFireWireNuDCLPoolInterface Instance Methods

IOReturn ( SetDCLRanges) ( NuDCLRef dcl, UInt32 numRanges, IOVirtualRange ranges );

Parameters
dcl

The DCL to modify

numRanges

number of ranges in 'ranges'.

ranges

An array of virtual ranges Return Value Returns an IOReturn error code. Discussion Set the list of data buffers for a DCL. Setting too many ranges may result in a memory region with too many discontinous physical segments for the hardware to send or receive in a single packet. This will result in an error when the program is compiled. This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify() Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef

SetDCLRefcon
void ( *SetDCLRefcon)( NuDCLRef dcl, void *refcon );

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

261

IOFireWireNuDCLPoolInterface Instance Methods

SetDCLSkipBranch
IOReturn ( *SetDCLSkipBranch)( NuDCLRef dcl, NuDCLRef skipCycleDCL );

Discussion Description forthcoming

SetDCLSkipCallback
IOReturn ( *SetDCLSkipCallback)( NuDCLRef dcl, NuDCLCallback callback );

Discussion Description forthcoming

SetDCLSkipRefcon
IOReturn ( *SetDCLSkipRefcon)( NuDCLRef dcl, void *refcon );

Discussion Description forthcoming

SetDCLStatusPtr
Set the status pointer for a NuDCL
IOReturn ( *SetDCLStatusPtr)( NuDCLRef dcl, UInt32 *statusPtr );

Parameters
dcl

The DCL for which status pointer will be set

statusPtr

A pointer to a quadlet which will hold the status after 'dcl' is updated.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

262

IOFireWireNuDCLPoolInterface Instance Methods

Return Value Returns an IOReturn error code. Discussion Setting a the status pointer for a NuDCL causes the packet transmit/receive hardware status to be recorded when the DCL executes. This DCL must be updated after it has executed for the status to be valid. This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify() Status values are as follows: (from the OHCI spec, section 3.1.1)
5'h1D 5'h11 5'h0E 5'h0B 5'h0A ack_data_error (receive) ack_complete (receive/transmit) evt_unknown (receive/transmit) evt_tcode_err (transmit) evt_timeout (transmit) A data field CRC or data_length error. No event occurred. (Success) An error condition has occurred that cannot be represented by any other event codes defined herein. A bad tCode is associated with this packet. The packet was flushed. Indicates that the asynchronous transmit response packet expired and was not transmitted, or that an IT DMA context experienced a skip processing overflow (See section9.3.4). An error occurred while the Host Controller was attempting to write to host memory either in the data stage of descriptor processing (AR, IR), or when processing a single 16-bit host memory write (IT). An error occurred while the Host Controller was attempting to read from host memory in the data stage of descriptor processing. An unrecoverable error occurred while the Host Controller was reading a descriptor block. A receive FIFO overflowed during the reception of an isochronous packet. The received data length was greater than the buffer's data_length.

5'h08

evt_data_write (receive/transmit)

5'h07

evt_data_read (transmit)

5'h06 5'h05 5'h02 5'h00

evt_descriptor_read (receive/transmit) evt_overrun (receive) evt_long_packet (receive) No event status.

Applies: Any NuDCLRef.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

263

IOFireWireNuDCLPoolInterface Instance Methods

SetDCLSyncBits
IOReturn ( *SetDCLSyncBits)( NuDCLRef dcl, UInt8 syncBits );

Discussion Description forthcoming

SetDCLTagBits
IOReturn ( *SetDCLTagBits)( NuDCLRef dcl, UInt8 tagBits );

Discussion Description forthcoming

SetDCLTimeStampPtr
Set the time stamp pointer for a NuDCL
IOReturn ( *SetDCLTimeStampPtr)( NuDCLRef dcl, UInt32 *timeStampPtr );

Parameters
dcl

The DCL for which time stamp pointer will be set

timeStampPtr

A pointer to a quadlet which will hold the timestamp after 'dcl' is updated. Return Value Returns an IOReturn error code. Discussion Setting a the time stamp pointer for a NuDCL causes a time stamp to be recorded when a DCL executes. This DCL must be updated after it has executed for the timestamp to be valid. This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

264

IOFireWireNuDCLPoolInterface Instance Methods

Applies: Any NuDCLRef.

SetDCLUpdateList
IOReturn ( *SetDCLUpdateList)( NuDCLRef dcl, CFSetRef dclList );

Discussion Description forthcoming

SetDCLUserHeaderPtr
Set a user specified header for a send NuDCL
IOReturn ( *SetDCLUserHeaderPtr)( NuDCLRef dcl, UInt32 *headerPtr, UInt32 *mask );

Parameters
dcl

The DCL to modify

headerPtr

A pointer to a two-quadlet header. See section 9.6 of the the OHCI specification.
mask

A pointer to a two-quadlet mask. The quadlets in headerPtr are masked with 'mask' and the masked-out bits are replaced by the FireWire system software. Return Value Returns an IOReturn error code. Discussion Allows the client to create a custom header for a transmitted isochronous packet. The header is masked with 'mask', and the FireWire system software fills in the masked out bits. This change will apply immediately to a non-running DCL program. An update must be run on the DCL for changes to take effect in a running program. Applies: NuDCLSendPacketRef

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

265

IOFireWireNuDCLPoolInterface Instance Variables

SetDCLWaitControl
IOReturn ( *SetDCLWaitControl)( NuDCLRef dcl, Boolean wait );

Discussion Description forthcoming

Instance Variables
revision
UInt32 revision;

Interface version

version
UInt32 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

266

IOFireWirePHYCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Description forthcoming

Tasks
Miscellaneous
Cancel

(page 269) Cancel command execution (page 269) Gets the most recently received ack code for this transaction. (page 270) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 270) Gets the refcon associated with this command (page 271) Gets the most recently received response code for this transaction. (page 271) Return command completion status. (page 272) Get command target address. (page 272) Return number of bytes transferred by this command object when it last completed execution. (page 273) Is this command object currently executing?

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

GetTargetAddress

GetTransferredBytes

IsExecuting

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

267

IOFireWirePHYCommandInterface Tasks

SetBuffer

(page 274) Set the buffer where read data should be stored. (page 274) Set the completion handler to be called once the command completes asynchronous execution . (page 275) Set the 2 quadlets of data to be sent in a PHY packet. (page 276) Set flags governing this command's execution. (page 277) 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. (page 278) Set the maximum size in bytes of packets transferred by this command. (page 278) Gets the most recently received ack code for this transaction. (page 279) Sets the maximum number of retries for this command. (page 279) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 280) Set command target address (page 280) Sets the duration of the timeout for this command. (page 281)

SetCallback

SetDataQuads

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

SetTarget

SetTimeoutDuration

Submit

SubmitWithRefconAndCallback

(page 281) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

268

IOFireWirePHYCommandInterface Instance Methods

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

GetAckCode
Gets the most recently received ack code for this transaction.
UInt32 ( *GetAckCode)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

269

IOFireWirePHYCommandInterface Instance Methods

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

GetRefCon
Gets the refcon associated with this command
void * ( *GetRefCon)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

270

IOFireWirePHYCommandInterface Instance Methods

Return Value void

GetResponseCode
Gets the most recently received response code for this transaction.
UInt32 ( *GetResponseCode)( IOFireWireLibCommandRef self );

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

272

IOFireWirePHYCommandInterface Instance Methods

Return Value A UInt32 containing the bytes transferred value Discussion Availability: (for interfaces obtained with ID)
kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID YES YES YES YES YES YES YES YES

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

273

IOFireWirePHYCommandInterface Instance Methods

kIOFireWireReadCommandInterfaceID

YES

SetBuffer
Set the buffer where read data should be stored.
void ( *SetBuffer)( IOFireWireLibCommandRef self, UInt32 size, void *buf);

The command object interface of interest

data1

The value of the first quad of the phy packet

data2

The value of the second quad of the phy packet

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

275

IOFireWirePHYCommandInterface Instance Methods

Discussion Available in v1 and newer.

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:

Discussion Availability: (for interfaces obtained with ID)

kIOFireWireAsyncStreamCommandInterfaceID YES

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

276

IOFireWirePHYCommandInterface Instance Methods

Parameters
self

A reference to the command

count

The number of retires Return Value void

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

279

IOFireWirePHYCommandInterface Instance Methods

kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES 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)

SetTimeoutDuration
Sets the duration of the timeout for this command.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

280

IOFireWirePHYCommandInterface Instance Methods

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

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

281

IOFireWirePHYCommandInterface Instance Variables

kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

282

IOFireWirePhysicalAddressSpaceInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib physical address space object. ( interface name: IOFireWirePhysicalAddressSpaceInterface ) Represents and provides management functions for a physical address space (hardware-backed) in the local machine. Physical address space objects can be created using IOFireWireDeviceInterface.

Tasks
Miscellaneous
GetBuffer

(page 284) Get a pointer to the backing store for this address space (page 284) Get the size in bytes of this address space. (page 284) Get the FireWire address of this address space (page 285) Returns the physical address of the beginning of this address space (page 285) Returns the physical segment containing the address at a specified offset from the beginning of this address space (page 285) Returns the list of physical memory ranges this address space occupies on the local machine.

GetBufferSize

GetFWAddress

GetPhysicalAddress

GetPhysicalSegment

GetPhysicalSegments

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

283

IOFireWirePhysicalAddressSpaceInterface Instance Methods

Instance Methods
GetBuffer
Get a pointer to the backing store for this address space
void* ( *GetBuffer)( IOFireWireLibPhysicalAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value A pointer to the backing store of this address space.

GetBufferSize
Get the size in bytes of this address space.
const UInt32 ( *GetBufferSize)( IOFireWireLibPhysicalAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value Size of the pseudo address space in bytes.

GetFWAddress
Get the FireWire address of this address space
void ( *GetFWAddress)( IOFireWireLibPhysicalAddressSpaceRef self, FWAddress *outAddr);

Parameters
self

The address space interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

284

IOFireWirePhysicalAddressSpaceInterface Instance Methods

GetPhysicalAddress
Returns the physical address of the beginning of this address space
IOPhysicalAddress ( *GetPhysicalAddress)( IOFireWireLibPhysicalAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value The physical address of the start of this address space

GetPhysicalSegment
Returns the physical segment containing the address at a specified offset from the beginning of this address space
IOPhysicalAddress ( *GetPhysicalSegment)( IOFireWireLibPhysicalAddressSpaceRef self, IOByteCount offset, IOByteCount *length);

Parameters
self

The address space interface to use.

offset

Offset from beginning of address space

length

Pointer to a value which upon completion will contain the length of the segment returned by the function. Return Value The address of the physical segment containing the address at the specified offset of the address space

GetPhysicalSegments
Returns the list of physical memory ranges this address space occupies on the local machine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

285

IOFireWirePhysicalAddressSpaceInterface Instance Variables

void ( *GetPhysicalSegments)( IOFireWireLibPhysicalAddressSpaceRef self, UInt32 *ioSegmentCount, IOByteCount outSegments[], IOPhysicalAddress outAddresses[]);

Parameters
self

The address space interface to use.

ioSegmentCount

Pass in a pointer to the number of list entries in outSegments and outAddress. Upon completion, this will contain the actual number of segments returned in outSegments and outAddress
outSegments

A pointer to an array to hold the function results. Upon completion, this will contain the lengths of the physical segments this address space occupies on the local machine
outAddresses

A pointer to an array to hold the function results. Upon completion, this will contain the addresses of the physical segments this address space occupies on the local machine. If NULL, ioSegmentCount will contain the number of physical segments in the address space.

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

286

IOFireWirePseudoAddressSpaceInterface

Declared in

IOFireWireLib.h (page 643)

Overview
Represents and provides management functions for a pseudo address space (software-backed) in the local machine. Pseudo address space objects can be created using IOFireWireDeviceInterface.

Tasks
Miscellaneous
ClientCommandIsComplete

(page 288) Notify the address space that a packet notification handler has completed. (page 288) Get a pointer to the backing store for this address space (page 289) Get the size in bytes of this address space. (page 289) Get the FireWire address of this address space (page 289) Returns the user refCon value for this address space. (page 290) Is notification on? (page 290) Set the callback that should be called to handle read accesses to the corresponding address space

GetBuffer

GetBufferSize

GetFWAddress

GetRefCon

NotificationIsOn

SetReadHandler

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

287

IOFireWirePseudoAddressSpaceInterface Instance Methods

SetSkippedPacketHandler

(page 291) Set the callback that should be called when incoming packets are dropped by the address space. (page 291) Set the callback that should be called to handle write accesses to the corresponding address space (page 291) Force packet notification off. (page 292) Try to turn on packet notifications for this address space.

SetWriteHandler

TurnOffNotification

TurnOnNotification

Instance Methods
ClientCommandIsComplete
Notify the address space that a packet notification handler has completed.
void ( *ClientCommandIsComplete)( IOFireWireLibPseudoAddressSpaceRef self, FWClientCommandID commandID, IOReturn status);

Parameters
self

The address space interface to use.

commandID

The ID of the packet notification being completed. This is the same ID that was passed when a packet notification handler is called.
status

The completion status of the packet handler Discussion Packet notifications are received one at a time, in order. This function must be called after a packet handler has completed its work.

GetBuffer
Get a pointer to the backing store for this address space

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

288

IOFireWirePseudoAddressSpaceInterface Instance Methods

void* ( *GetBuffer)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value A pointer to the backing store of this pseudo address space. Returns nil if none.

GetBufferSize
Get the size in bytes of this address space.
const UInt32 ( *GetBufferSize)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value Size of the pseudo address space in bytes. Returns 0 for none.

GetFWAddress
Get the FireWire address of this address space
void ( *GetFWAddress)( IOFireWireLibPseudoAddressSpaceRef self, FWAddress *outAddr);

Parameters
self

The pseudo address interface to use.

GetRefCon
Returns the user refCon value for this address space.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

289

IOFireWirePseudoAddressSpaceInterface Instance Methods

void* ( *GetRefCon)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value Size of the pseudo address space in bytes. Returns 0 for none.

NotificationIsOn
Is notification on?
Boolean ( *NotificationIsOn)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value Returns true if packet notifications for this address space are active

SetReadHandler
Set the callback that should be called to handle read accesses to the corresponding address space
const IOFireWirePseudoAddressSpaceReadHandler ( *SetReadHandler)( IOFireWireLibPseudoAddressSpaceRef self, IOFireWirePseudoAddressSpaceReadHandler inReader);

inWriter

The callback to set. Return Value Returns the callback that was previously set or nil for none.

TurnOffNotification
Force packet notification off.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

291

IOFireWirePseudoAddressSpaceInterface Instance Variables

void ( *TurnOffNotification)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The pseudo address interface to use.

TurnOnNotification
Try to turn on packet notifications for this address space.
Boolean ( *TurnOnNotification)( IOFireWireLibPseudoAddressSpaceRef self);

Parameters
self

The address space interface to use. Return Value Returns true upon success

Instance Variables
revision
UInt32 revision;

Interface revision

version
UInt32 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

292

IOFireWireReadCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib block read command object. Represents an object that is configured and submitted to issue synchronous and asynchronous block read commands. This interface contains all methods of IOFireWireCommandInterface. This interface will contain all v2 methods of IOFireWireCommandInterface when instantiated as v2 or newer.

Tasks
Miscellaneous
Cancel

(page 295) Cancel command execution (page 295) Gets the most recently received ack code for this transaction. (page 296) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 296) Gets the refcon associated with this command (page 297) Gets the most recently received response code for this transaction. (page 297) Return command completion status.

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

293

IOFireWireReadCommandInterface Tasks

GetTargetAddress

(page 298) Get command target address. (page 298) Return number of bytes transferred by this command object when it last completed execution. (page 299) Is this command object currently executing? (page 300) Set the buffer where read data should be stored. (page 300) Set the completion handler to be called once the command completes asynchronous execution . (page 301) Set flags governing this command's execution. (page 302) 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. (page 303) Set the maximum size in bytes of packets transferred by this command. (page 304) Gets the most recently received ack code for this transaction. (page 304) Sets the maximum number of retries for this command. (page 305) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 305) Set command target address (page 306) Sets the duration of the timeout for this command. (page 307)

GetTransferredBytes

IsExecuting

SetBuffer

SetCallback

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

SetTarget

SetTimeoutDuration

Submit

SubmitWithRefconAndCallback

(page 307) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

294

IOFireWireReadCommandInterface Instance Methods

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

GetAckCode
Gets the most recently received ack code for this transaction.
UInt32 ( *GetAckCode)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

295

IOFireWireReadCommandInterface Instance Methods

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

GetRefCon
Gets the refcon associated with this command
void * ( *GetRefCon)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

296

IOFireWireReadCommandInterface Instance Methods

Return Value void

GetResponseCode
Gets the most recently received response code for this transaction.
UInt32 ( *GetResponseCode)( IOFireWireLibCommandRef self );

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

298

IOFireWireReadCommandInterface Instance Methods

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

299

IOFireWireReadCommandInterface Instance Methods

kIOFireWireReadCommandInterfaceID

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

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

300

IOFireWireReadCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

inCallback

SetFlags
Set flags governing this command's execution.
void ( *SetFlags)( IOFireWireLibCommandRef self, UInt32 inFlags);

Parameters
self

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

301

IOFireWireReadCommandInterface Instance Methods

inFlags

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

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

302

IOFireWireReadCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

generation

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

303

IOFireWireReadCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

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

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

307

IOFireWireReadCommandInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

308

IOFireWireReadQuadletCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireReadQuadletCommandInterface -- IOFireWireLib quadlet read command object. Obsolete; do not use. Use IOFireWireReadCommandInterface v2 or newer and its function SetMaxPacket()

Tasks
Miscellaneous
Cancel

(page 310) Cancel command execution (page 311) Return command completion status. (page 311) Get command target address. (page 312) Return number of bytes transferred by this command object when it last completed execution. (page 313) Is this command object currently executing? (page 313) Set the completion handler to be called once the command completes asynchronous execution . (page 314) 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.

GetStatus

GetTargetAddress

GetTransferredBytes

IsExecuting

SetCallback

SetGeneration

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

309

IOFireWireReadQuadletCommandInterface Instance Methods

SetQuads

(page 315) Set destination for read data (page 315) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 316) Set command target address (page 317)

SetRefCon

SetTarget

Submit

SubmitWithRefconAndCallback

(page 317) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

310

IOFireWireReadQuadletCommandInterface Instance Methods

kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES

GetStatus
Return command completion status.
IOReturn ( *GetStatus)( IOFireWireLibCommandRef self);

Parameters
self

GetTargetAddress
Get command target address.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

311

IOFireWireReadQuadletCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

outAddr

GetTransferredBytes
Return number of bytes transferred by this command object when it last completed execution.
UInt32 ( *GetTransferredBytes)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

312

IOFireWireReadQuadletCommandInterface Instance Methods

kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

313

IOFireWireReadQuadletCommandInterface Instance Methods

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

315

IOFireWireReadQuadletCommandInterface Instance Methods

kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES 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)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

316

IOFireWireReadQuadletCommandInterface Instance Methods

Submit
IOReturn ( *Submit)( IOFireWireLibCommandRef self);

Discussion Description forthcoming

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

317

IOFireWireReadQuadletCommandInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

318

IOFireWireRemoteIsochPortInterface

Declared in

IOFireWireLibIsoch.h

Overview
Description forthcoming

Tasks
Miscellaneous
AllocatePort

(page 320) The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified. (page 321) Get reference value associated with this port. (page 321) The method is called to determine which FireWire isochronous channels and speed this port supports. (page 322) The method is called to release the hardware after the channel has been stopped. (page 322) (page 322)

GetRefCon

GetSupported

ReleasePort

SetAllocatePortHandler

SetGetSupportedHandler

SetRefCon

(page 322) Set reference value associated with this port. (page 323)

SetReleasePortHandler

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

319

IOFireWireRemoteIsochPortInterface Instance Methods

SetStartHandler

(page 323)

SetStopHandler

(page 323)

Start

(page 324) The method is called when the port is to begin talking or listening.

Stop

(page 324) The method is called when the port is to stop talking or listening.

Discussion Description forthcoming

SetGetSupportedHandler
IOFireWireLibIsochPortGetSupportedCallback ( *SetGetSupportedHandler) ( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortGetSupportedCallback inHandler);

Discussion Description forthcoming

SetRefCon
Set reference value associated with this port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

322

IOFireWireRemoteIsochPortInterface Instance Methods

void ( SetRefCon) ( IOFireWireLibIsochPortRef self, void inRefCon);

Parameters
self

The isoch port interface to use.

inRefCon

The new reference value. Discussion Retrieve the reference value with GetRefCon()

SetReleasePortHandler
IOFireWireLibIsochPortCallback ( *SetReleasePortHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler);

Discussion Description forthcoming

SetStartHandler
IOFireWireLibIsochPortCallback ( *SetStartHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler);

Discussion Description forthcoming

SetStopHandler
IOFireWireLibIsochPortCallback ( *SetStopHandler)( IOFireWireLibRemoteIsochPortRef self, IOFireWireLibIsochPortCallback inHandler);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

323

IOFireWireRemoteIsochPortInterface Instance Methods

Start
The method is called when the port is to begin talking or listening.
IOReturn ( *Start) ( IOFireWireLibIsochPortRef self );

Parameters
self

Stop
The method is called when the port is to stop talking or listening.
IOReturn ( *Stop) ( IOFireWireLibIsochPortRef self );

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

324

IOFireWireRemoteIsochPortInterface Instance Variables

Instance Variables
revision
UInt32 revision;

Interface revision.

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

325

IOFireWireSBP2LibLoginInterface

Declared in

IOFireWireSBP2Lib.h (page 654)

Overview
Supplies the login maintenance and Normal Command ORB execution portions of the API. Supplies APIs for login maintenance and command execution. Drivers can use this object to create IOFireWireSBP2LibORBInterface objects and execute them. Solicited and unsolicited status callback routines can be registered and the SBP2 services will notify the driver when the appropriate status arrives. This class also handles login maintenance. Supplies APIs for logging in and logging out and attempts to reconnect to the LUN after bus resets. The base FireWire services deliver bus reset notification via the IOKit message routine. The SBP2 services build on this behavior and deliver reconnectFailed and reconnectComplete through the message routine as well.

Tasks
Miscellaneous
createORB

(page 328) Creates a new IOFireWireSBP2ORB for this login. (page 328) Enables unsolicited status. (page 329) Returns the current login ID. (page 329) Returns the maximum command block size. (page 329) Returns the refCon set with setRefCon.

enableUnsolicitedStatus

getLoginID

getMaxCommandBlockSize

getRefCon

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

326

IOFireWireSBP2LibLoginInterface Tasks

ringDoorbell

(page 330) Rings the doorbell on the LUN. (page 330) Sets the value to be written to the BUSY_TIMEOUT register. (page 331) Sets the callback to be called when a fetch agent reset completes. (page 332) Sets the callback to be called when the fetch agent write completes. (page 332) Sets the callback to be called when a login attempt is complete. (page 333) Sets login configuration flags. (page 333) Sets the callback to be called when a logout attempt is complete. (page 334) Sets the maximum data transfer length for a normal command ORB. (page 334) Sets the login password. (page 335) Sets the desired reconnect duration. (page 336) Sets the login refCon. (page 336) Sets the callback to be called on normal command status. (page 337) Sets the callback to be called on normal command status. (page 337) Resets the LUN's fetch agent. (page 338) Attempts to login to the LUN. (page 338) Attempts to logout of the LUN. (page 338) Submits the given orb

setBusyTimeoutRegisterValue

setFetchAgentResetCallback

setFetchAgentWriteCallback

setLoginCallback

setLoginFlags

setLogoutCallback

setMaxPayloadSize

setPassword

setReconnectTime

setRefCon

setStatusNotify

setUnsolicitedStatusNotify

submitFetchAgentReset

submitLogin

submitLogout

submitORB

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

327

IOFireWireSBP2LibLoginInterface Instance Methods

Instance Methods
createORB
Creates a new IOFireWireSBP2ORB for this login.
IUnknownVTbl** ( *createORB)( void *self, REFIID iid );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

331

IOFireWireSBP2LibLoginInterface Instance Methods

setFetchAgentWriteCallback
Sets the callback to be called when the fetch agent write completes.
void ( *setFetchAgentWriteCallback)( void *self, void *refCon, IOFWSBP2FetchAgentWriteCallback callback );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

refCon

refCon passed to callback.

callback

address of callback method of type FWSBP2FetchAgentWriteCallback. Discussion When an immediate orb is executed with submitORB, it's address is written to a specific address on the device. This address is called the fetch agent. The device the reads that orb from the Mac's memory and executes it. With this call you can register to be called back when this write to the fetch agent completes. The SBP2 services guarantee that the fetch agent write will be complete before status is reported for an ORB, so for most drivers this notification is not required.

setLoginCallback
Sets the callback to be called when a login attempt is complete.
void ( *setLoginCallback)( void *self, void *refCon, IOFWSBP2LoginCallback callback );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

refCon

refCon passed to callback.

callback

address of callback method of type FWSBP2LoginCallback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

332

IOFireWireSBP2LibLoginInterface Instance Methods

Discussion The supplied callback is called when a login attempt has completed. "status" in the callback's params should be checked to determine the success or failure of the login attempt. The "refCon" field in the params will return the refcon set with setRefCon. If "statusBlock" is non-null then login status was written and it has been supplied here. If the login attempt was successful then the login response will be supplied in the "loginResponse" buffer. Note: all buffers supplied to callbacks are only valid for the duration of the callback. Also, you are not to modify the contents of any supplied buffer.

setLoginFlags
Sets login configuration flags.
void ( *setLoginFlags)( void *self, UInt32 flags );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

flags

the login configuration flags. Discussion Configures the login behavior according to the provided flags. Currently two flags are defined for this API. kFWSBP2ExclusiveLogin sets the exclusive login bit in the login ORB. kFWSBP2DontSynchronizeMgmtAgent allows simultaneous logins or reconnects to LUNs with a common management agent (ie LUNs in the same unit directory).

setLogoutCallback
Sets the callback to be called when a logout attempt is complete.
void ( *setLogoutCallback)( void *self, void *refCon, IOFWSBP2LogoutCallback callback );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

333

IOFireWireSBP2LibLoginInterface Instance Methods

refCon

refCon passed to callback.

callback

address of callback method of type FWSBP2LogoutCallback. Discussion The supplied callback is called when a logout attempt has completed. "status" in the callback's params should be checked to determine the success or failure of the logout attempt. The "refCon" field in the params will return the refcon set with setRefCon. If "statusBlock" is non-null then logout status was written and it has been supplied here. Note: all buffers supplied to callbacks are only valid for the duration of the callback. Also, you are not to modify the contents of any supplied buffer.

setMaxPayloadSize
Sets the maximum data transfer length for a normal command ORB.
void ( *setMaxPayloadSize)( void *self, UInt32 size );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

size

The desired maximum payload size in bytes. Discussion Sets the maximum data transfer length for a normal command ORB. This value is the maximum for all ORBs sent to this LUN. This can be trimmed further on an ORB by ORB basis, by a similar call in the IOFireWireSBP2ORB itself.

setPassword
Sets the login password.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

334

IOFireWireSBP2LibLoginInterface Instance Methods

IOReturn ( setPassword)( void self, void *buffer, UInt32 length );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

buffer

a pointer to the password buffer.

length

the length in bytes of the password buffer. Return Value Returns kIOReturnSuccess on success. Discussion Sets the login password using a buffer and a length. An alternate version exists that accepts an IOMemoryDescriptor. If the password length is 8 or less the password is copied directly into the login orb. If the length is greater than 8 the buffer is referenced by address in the login ORB. In this case the buffer is not copied and should remain allocated for the duration of the login attempt.

setReconnectTime
Sets the desired reconnect duration.
void ( *setReconnectTime)( void *self, UInt32 time );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object. Return Value Returns kIOReturnSuccess if the reset started successfully. Discussion The fetch agent state machine on the device can be reset by a write to a specific register. This reset can be intiated by a call to this method. Notification of the completion of this write can be had by registering a callback with the setFetchAgentResetCallback method.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

337

IOFireWireSBP2LibLoginInterface Instance Methods

submitLogin
Attempts to login to the LUN.
IOReturn ( *submitLogin)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object. Return Value Returns kIOReturnSuccess login has successlly begun. Discussion This call begins the login process. The login object should be configured prior to this call. If kIOReturnSuccess is returned from this call then the loginCompletion routine will be called when the login completes (successfully or unsuccesfully).

submitLogout
Attempts to logout of the LUN.
IOReturn ( *submitLogout)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object. Return Value Returns kIOReturnSuccess if logout has successfully begun. Discussion This call begins the logout process. If kIOReturnSuccess is returned from this call then the logoutCompletion routine will be called when the logout completes (successfully or unsuccesfully).

submitORB
Submits the given orb

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

338

IOFireWireSBP2LibLoginInterface Instance Methods

IOReturn ( submitORB)( void self, IOFireWireSBP2LibORBInterface **orb );

Parameters
self

Pointer to IOFireWireSBP2LibLoginInterface object.

orb

The orb to be executed. Return Value Returns kIOReturnSuccess if the ORB has been started successfully. Discussion Starts execution of the given ORB. If the ORB is an immediate ORB it's addresss is written to the fetch agent. If it is a non immediate orb its address is appended to the last orb of the currently processing chain. The doorbell is not rung automatically it must be run manually with the ringDoorbell command described below.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

339

IOFireWireSBP2LibLUNInterface

Declared in

IOFireWireSBP2Lib.h (page 654)

getRefCon
Returns the refCon set with setRefCon.
void * ( *getRefCon)( void *self);

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface. Return Value Returns the previously stored user defined value. Discussion Returns the user defined value previously stored in the ORB with setRefCon.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

343

IOFireWireSBP2LibLUNInterface Instance Methods

getSessionRef
Returns the session reference to an already open device.
IOFireWireSessionRef ( *getSessionRef)( void *self);

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface. Return Value Returns a sessionRef 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 SBP2 User Client open at the same time. The technique to arbitrate this is as follows: First open normally the device furthest from the root in the IORegistry. Second, get its sessionRef with a call to this method. Third open the device further up the chain by calling openWithSessionRef and passing the sessionRef returned from this call.

open
Exclusively opens a connection to the in-kernel device.
IOReturn ( *open)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface. Return Value Returns kIOReturnSuccess on success.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

344

IOFireWireSBP2LibLUNInterface Instance Methods

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 already open.
IOReturn ( *openWithSessionRef)( void *self, IOFireWireSessionRef sessionRef );

Parameters
sessionRef

SessionRef returned from getSessionRef call.

self

Pointer to IOFireWireSBP2LibLUNInterface. Return Value Returns kIOReturnSuccess 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 SBP2 User Client open at the same time. The technique to arbitrate this is as follows : First open normally the device furthest from the root in the IORegistry. Second, get its sessionRef with the getSessionRef call. Third 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 from the specified runloop.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

345

IOFireWireSBP2LibLUNInterface Instance Methods

void ( removeCallbackDispatcherFromRunLoop)( void self );

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface. Discussion Undoes the work of addCallbackDispatcherToRunLoop.

setMessageCallback
Set callback for user space message routine.
void ( *setMessageCallback)( void *self, void *refCon, IOFWSBP2MessageCallback callback);

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface.
refCon

RefCon to be returned as first argument of completion routine

callback

Address of completion routine. Discussion In FireWire & SBP2 bus status messages are delivered via IOKit's message routine. This routine is emulated in user space for SBP2 & FireWire messages via this callback. You should register here for bus reset, and reconnect messages.

setRefCon
Sets the ORB refCon.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

346

IOFireWireSBP2LibLUNInterface Instance Methods

void ( setRefCon)( void self, void *refCon );

Parameters
self

Pointer to IOFireWireSBP2LibLUNInterface.
refCon

a user defined value. Discussion Sets a user defined value on the ORB that can be retrieved later with the method getRefCon.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

347

IOFireWireSBP2LibMgmtORBInterface

Declared in

IOFireWireSBP2Lib.h (page 654)

Overview
Supplies non login related management ORBs. Management ORBs can be executed independent of a login, if necessary. Management ORBs are created using the IOFireWireSBP2LibLUNInterface.

Tasks
Miscellaneous
getRefCon

(page 349) Returns the current function of the management ORB. (page 349) Sets the function of the management ORB. (page 350) Sets the command to be managed by the management ORB. (page 350) Sets the command to be managed by the management ORB. (page 351) Sets the ORB completion routine. (page 351) Sets the login refCon. (page 352) Sets the response buffer for the management ORB. (page 352) Submits this ORB for execution.

setCommandFunction

setManageeLogin

setManageeORB

setORBCompleteCallback

setRefCon

setResponseBuffer

submitORB

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

348

IOFireWireSBP2LibMgmtORBInterface Instance Methods

Instance Methods
getRefCon
Returns the current function of the management ORB.
void * ( *getRefCon)( void *self);

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface. Return Value Returns the function of the management ORB. Discussion Returns the function of the management ORB. This is the same value that was set with setCommandFunction.

setCommandFunction
Sets the function of the management ORB.
IOReturn ( *setCommandFunction)( void *self, UInt32 function );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
function

a value indicating the desired management function. Return Value Returns kIOReturnSuccess if function was a legal function. Discussion Sets the the function of the management ORB. Legal values are kFWSBP2QueryLogins, kFWSBP2AbortTask, kFWSBP2AbortTaskSet, kFWSBP2LogicalUnitReset, and kFWSBP2TargetReset.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

349

IOFireWireSBP2LibMgmtORBInterface Instance Methods

setManageeLogin
Sets the command to be managed by the management ORB.
IOReturn ( *setManageeLogin)( void *self, void *command );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
command

a reference to an IOFireWireSBP2Login or an IOFireWireSBP2ORB. Return Value Returns kIOReturnSuccess on a success. Discussion All management functions except kFWSBP2QueryLogins require a reference to an ORB of some sort. kFWSBP2AbortTaskSet, kFWSBP2LogicalUnitReset, and kFWSBP2TargetReset require a reference to the login ORB. This method allows you to set the login ORB to be managed.

setManageeORB
Sets the command to be managed by the management ORB.
IOReturn ( *setManageeORB)( void *self, void *command );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
command

a reference to an IOFireWireSBP2Login or an IOFireWireSBP2ORB. Return Value Returns kIOReturnSuccess on a success.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

350

IOFireWireSBP2LibMgmtORBInterface Instance Methods

Discussion All management functions except kFWSBP2QueryLogins require a reference to an ORB of some sort. kFWSBP2AbortTask requires a reference to the ORB to be aborted. This method allows you to set the Normal Command ORB to be managed.

setORBCompleteCallback
Sets the ORB completion routine.
void ( *setORBCompleteCallback)( void *self, void *refCon, IOFWSBP2ORBCompleteCallback callback );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
refCon

refCon passed as first argument to completion routine Discussion Sets the completion routine to be called when the ORB finishes execution. The refCon set with setRefCon will also be passed as the third argument to the completion handler.

setRefCon
Sets the login refCon.
void ( *setRefCon)( void *self, void *refCon );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
refCon

a user defined value. Discussion Sets a user defined value on the login that can be retrieved later with the method getRefCon.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

351

IOFireWireSBP2LibMgmtORBInterface Instance Methods

setResponseBuffer
Sets the response buffer for the management ORB.
IOReturn ( *setResponseBuffer)( void *self, void *buf, UInt32 len );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface.
buf

backing store for buffer

len

length of buffer. Return Value Returns kIOReturnSuccess on a success. Discussion Sets the response buffer for the management ORB. kFWSBP2QueryLogins returns a response to its query and needs to write it somewhere. This routine allows you to specify the location.

submitORB
Submits this ORB for execution.
IOReturn ( *submitORB)( void *self );

Parameters
self

Pointer to a IOFireWireSBP2LibMgmtORBInterface. Discussion Submits this ORB for execution

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

352

IOFireWireSBP2LibORBInterface

Declared in

IOFireWireSBP2Lib.h (page 654)

Overview
Represents an SBP2 normal command ORB. Supplies the APIs for configuring normal command ORBs. This includes setting the command block and writing the page tables for I/O. The ORBs are executed using the submitORB method in IOFireWireSBP2LibLoginInterface.

Tasks
Miscellaneous
getRefCon

(page 354) Returns the refCon set with setRefCon. (page 354) Creates a page table with the LSI workaround from a list of ranges. (page 355) Synchronize the buffers for input.

LSIWorkaroundSetCommandBuffersAsRanges

LSIWorkaroundSyncBuffersForInput

LSIWorkaroundSyncBuffersForOutput

(page 356) Synchronize the buffers for output. (page 356) Releases SBP2's reference to the command buffers. (page 357) Sets the command block portion of the ORB. (page 357) Creates a page table from a list of ranges. (page 358) Sets configuration flags for the ORB.

releaseCommandBuffers

setCommandBlock

setCommandBuffersAsRanges

setCommandFlags

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

353

IOFireWireSBP2LibORBInterface Instance Methods

setCommandGeneration

(page 359) Sets the command generation. (page 360) Sets the timeout of the ORB. (page 360) Sets max payload size for the ORB. (page 361) Sets the ORB refCon.

setCommandTimeout

setMaxORBPayloadSize

setRefCon

Instance Methods
getRefCon
Returns the refCon set with setRefCon.
void * ( *getRefCon)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface. Return Value Returns the previously stored user defined value. Discussion Returns the user defined value previously stored in the ORB with setRefCon.

LSIWorkaroundSetCommandBuffersAsRanges
Creates a page table with the LSI workaround from a list of ranges.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

354

IOFireWireSBP2LibORBInterface Instance Methods

IOReturn ( *LSIWorkaroundSetCommandBuffersAsRanges)( void *self, FWSBP2VirtualRange *ranges, UInt32 withCount, UInt32 withDirection, UInt32 offset, UInt32 length );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
ranges

An array of ranges representing the data to be transfered.

withCount

The number of ranges in the ranges array.

withDirection

An IODirection indicating the direction of data transfer.

offset

Offset in bytes into data to begin writing table at.

length

Number of bytes of data to map from offset. Return Value Returns KIOReturnSuccess if the page table was written successfully. Discussion Creates an LSI workaround page table with the given parameters. Any addresses mapped by this method routine must remain valid until setCommandBuffers is called again or releaseCommandBuffers is called. The SBP2 services do not release references to the command buffers just because the command has completed.

LSIWorkaroundSyncBuffersForInput
Synchronize the buffers for input.
IOReturn ( *LSIWorkaroundSyncBuffersForInput)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

355

IOFireWireSBP2LibORBInterface Instance Methods

Return Value Returns kIOReturnSuccess if sync was successful. Discussion Since double buffering may be invovled in the workaround. The driver needs to indicate when these buffers should be syncronized with the original descriptor. For data that will be input LSIWorkaroundSyncBuffersForInput should be called after receiving completion status for the ORB.

LSIWorkaroundSyncBuffersForOutput
Synchronize the buffers for output.
IOReturn ( *LSIWorkaroundSyncBuffersForOutput)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface. Return Value Returns kIOReturnSuccess if sync was successful. Discussion Since double buffering may be invovled in the workaround. The driver needs to indicate when these buffers should be syncronized with the original descriptor. For data that will be output LSIWorkaroundSyncBuffersForOutput should be called before submiting the ORB.

releaseCommandBuffers
Releases SBP2's reference to the command buffers.
IOReturn ( *releaseCommandBuffers)( void *self );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface. Return Value Returns KIOReturnSuccess if the page table was cleared successfully.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

356

IOFireWireSBP2LibORBInterface Instance Methods

Discussion When you create a page table with one of the variants of setCommandBuffers. SBP2 holds on to a reference to the buffers until this method is called. This means that if a command completed and you released the buffers without calling this method you could leave FW in an inconsistent state.

setCommandBlock
Sets the command block portion of the ORB.
IOReturn ( *setCommandBlock)( void *self, void *buffer, UInt32 length );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
buffer

Pointer to buffer to copy command block from.

length

Number of bytes of data to copy. Return Value Returns KIOReturnSuccess if the command block was updated successfully. Discussion Copys the data provided in the buffer to the command block portion of the ORB.

setCommandBuffersAsRanges
Creates a page table from a list of ranges.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

357

IOFireWireSBP2LibORBInterface Instance Methods

IOReturn ( *setCommandBuffersAsRanges)( void *self, FWSBP2VirtualRange *ranges, UInt32 withCount, UInt32 withDirection, UInt32 offset, UInt32 length );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
ranges

An array of ranges representing the data to be transfered.

withCount

The number of ranges in the ranges array.

withDirection

An IODirection indicating the direction of data transfer.

offset

Offset in bytes into data to begin writing table at.

length

Number of bytes of data to map from offset. Return Value Returns KIOReturnSuccess if the page table was written successfully. Discussion Creates a page table with the given parameters. Any addresses mapped by this method must remain valid until setCommandBuffers is called again or releaseCommandBuffers is called. The SBP2 services do not release references to the command buffers just because the command has completed.

setCommandFlags
Sets configuration flags for the ORB.
void ( *setCommandFlags)( void *self, UInt32 flags );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

358

IOFireWireSBP2LibORBInterface Instance Methods

flags

The flags to be set. Discussion Sets the configuration flags for the ORB. These can be any of the following: kFWSBP2CommandCompleteNotify - Set the notify bit as specified in SBP2 standard. Set to receive completion/timeout notification on this ORB. You almost always want to set this. kFWSBP2CommandTransferDataFromTarget - Transfer direction as specified in SBP2 standard. Set if data is to be written by the device into the host's memory. kFWSBP2CommandImmediate - Immediate Append. ORB address will be written to fetch agent and not chained. It is only legal to have one immediate ORB in progress at a time. kFWSBP2CommandNormalORB - ORB format 0 - Format specified by SBP2 standard. Set this for most ORBs. kFWSBP2CommandReservedORB - ORB format 1 - Format reserved by SBP2 standard for future standardization. kFWSBP2CommandVendorORB - ORB format 2 - Format specified by SBP2 standard for vendor dependent ORBs. kFWSBP2CommandDummyORB - ORB format 3 - Format specified by SBP2 standard for dummy ORBs. kFWSBP2CommandCheckGeneration - If set upon submitORB, the ORB will only be appended if generation set with setCommandGeneration() matches the current generation. Pretty much all SBP2 drivers need sophisticated logic to track login state, so this is generally not used. kFWSBP2CommandFixedSize - Do not allocate more memory for page table if needed. If there is not enough space in the currently allocated page table, the setCommandBuffers call will fail. This is important to set if your device is the backing store, as we don't want to cause memory allocations on the paging path. kFWSBP2CommandVirtualORBs - Normally ORBs are backed by physical address spaces. Setting this flag makes this ORB backed by a pseudo address space. This can make ORBs easier to see in a bus trace. Virtual ORBs will have an address in the form of ffcX.XXXX.0000.0000. Pseudo address space backed ORBs are slower, so you won't want to set for deployment builds.

setCommandGeneration
Sets the command generation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

359

IOFireWireSBP2LibORBInterface Instance Methods

void ( setCommandGeneration)( void self, UInt32 generation );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
generation

The bus generation for command execution. Discussion This sets the bus generation this ORB should be appended in. It is only meaningful when combined with the kFWSBP2CommandCheckGeneration flags above.

setCommandTimeout
Sets the timeout of the ORB.
void ( *setCommandTimeout)( void *self, UInt32 timeout );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
timeout

The timeout duration in milliseconds. Discussion This sets the timeout for the ORB in milliseconds. Note that ORBs without timeouts can be "lost." You will obviously not recieve timeout notification for timeouts of zero. But perhaps less obviously you will not recieve orb reset notification, which is really a sort of accelerated timeout notification for bus reset situations.

setMaxORBPayloadSize
Sets max payload size for the ORB.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

360

IOFireWireSBP2LibORBInterface Instance Methods

void ( setMaxORBPayloadSize)( void self, UInt32 size );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
size

The maximum payload size in bytes. Discussion This sets the maximum payload size for this ORB only. This size is clipped by the global max payload size set in the login object.

setRefCon
Sets the ORB refCon.
void ( *setRefCon)( void *self, void *refCon );

Parameters
self

Pointer to IOFireWireSBP2LibORBInterface.
refCon

a user defined value. Discussion Sets a user defined value on the ORB that can be retrieved later with the method getRefCon.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

361

IOFireWireUnitInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib. You can use IOFireWireDeviceInterface to:

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

362

IOFireWireUnitInterface Overview

create interfaces which provide isochronous services (see IOFireWireLibIsoch.h). These include:

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

363

IOFireWireWriteCommandInterface

Declared in

IOFireWireLib.h (page 643)

Tasks
Miscellaneous
Cancel

(page 366) Cancel command execution (page 366) Gets the most recently received ack code for this transaction. (page 367) Set the command refCon value and callback handler, and submit the command to FireWire for execution. (page 367) Gets the refcon associated with this command (page 368) Gets the most recently received response code for this transaction. (page 368) Return command completion status.

GetAckCode

GetBuffer

GetRefCon

GetResponseCode

GetStatus

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

364

IOFireWireWriteCommandInterface Tasks

GetTargetAddress

(page 369) Get command target address. (page 369) Return number of bytes transferred by this command object when it last completed execution. (page 370) Is this command object currently executing? (page 371) Set the buffer where read data should be stored. (page 371) Set the completion handler to be called once the command completes asynchronous execution . (page 372) Set flags governing this command's execution. (page 373) 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. (page 374) Set the maximum size in bytes of packets transferred by this command. (page 375) Gets the most recently received ack code for this transaction. (page 375) Sets the maximum number of retries for this command. (page 376) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 376) Set command target address (page 377) Sets the duration of the timeout for this command. (page 377)

GetTransferredBytes

IsExecuting

SetBuffer

SetCallback

SetFlags

SetGeneration

SetMaxPacket

SetMaxPacketSpeed

SetMaxRetryCount

SetRefCon

SetTarget

SetTimeoutDuration

Submit

SubmitWithRefconAndCallback

(page 378) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

365

IOFireWireWriteCommandInterface Instance Methods

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

GetAckCode
Gets the most recently received ack code for this transaction.
UInt32 ( *GetAckCode)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

366

IOFireWireWriteCommandInterface Instance Methods

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

GetRefCon
Gets the refcon associated with this command
void * ( *GetRefCon)( IOFireWireLibCommandRef self );

Parameters
self

A reference to the command Return Value void

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

367

IOFireWireWriteCommandInterface Instance Methods

GetResponseCode
Gets the most recently received response code for this transaction.
UInt32 ( *GetResponseCode)( IOFireWireLibCommandRef self );

369

IOFireWireWriteCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

370

IOFireWireWriteCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

373

IOFireWireWriteCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

generation

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

374

IOFireWireWriteCommandInterface Instance Methods

Discussion Availability: (for interfaces obtained with ID)

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

375

IOFireWireWriteCommandInterface Instance Methods

count

The number of retires Return Value void

Discussion Availability: (for interfaces obtained with ID)

SetTarget
Set command target address
void ( *SetTarget)( IOFireWireLibCommandRef self, const FWAddress *addr);

Parameters
self

The command object interface of interest

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

376

IOFireWireWriteCommandInterface Instance Methods

addr

A pointer to an FWAddress. Discussion Availability: (for interfaces obtained with ID)

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

377

IOFireWireWriteCommandInterface Instance Variables

Parameters
self

Instance Variables
revision
UInt32 revision;

Interface revision.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

378

IOFireWireWriteCommandInterface Instance Variables

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

379

IOFireWireWriteQuadletCommandInterface

Declared in

IOFireWireLib.h (page 643)

Overview
IOFireWireLib quadlet read command object. Obsolete; do not use. Use IOFireWireWriteCommandInterface v2 or newer and its function SetMaxPacket()

Tasks
Miscellaneous
Cancel

(page 381) Cancel command execution (page 382) Return command completion status. (page 382) Get command target address. (page 383) Return number of bytes transferred by this command object when it last completed execution. (page 384) Is this command object currently executing? (page 384) Set the completion handler to be called once the command completes asynchronous execution . (page 385) 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.

GetStatus

GetTargetAddress

GetTransferredBytes

IsExecuting

SetCallback

SetGeneration

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

380

IOFireWireWriteQuadletCommandInterface Instance Methods

SetQuads

(page 386)

SetRefCon

(page 386) Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function. (page 387) Set command target address (page 387)

SetTarget

Submit

SubmitWithRefconAndCallback

(page 388) Set the command refCon value and callback handler, and submit the command to FireWire for execution.

Instance Methods
Cancel
Cancel command execution
IOReturn ( *Cancel)( IOFireWireLibCommandRef self, IOReturn reason);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

381

IOFireWireWriteQuadletCommandInterface Instance Methods

kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES

GetStatus
Return command completion status.
IOReturn ( *GetStatus)( IOFireWireLibCommandRef self);

Parameters
self

GetTargetAddress
Get command target address.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

382

IOFireWireWriteQuadletCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

outAddr

GetTransferredBytes
Return number of bytes transferred by this command object when it last completed execution.
UInt32 ( *GetTransferredBytes)( IOFireWireLibCommandRef self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

383

IOFireWireWriteQuadletCommandInterface Instance Methods

kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES

IsExecuting
Is this command object currently executing?
const Boolean ( *IsExecuting)( IOFireWireLibCommandRef self);

Parameters
self

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

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

384

IOFireWireWriteQuadletCommandInterface Instance Methods

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

Parameters
self

The command object interface of interest

inCallback

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)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

385

IOFireWireWriteQuadletCommandInterface Instance Methods

kIOFireWireAsyncStreamCommandInterfaceID kIOFireWireCompareSwapCommandInterfaceID kIOFireWireWriteQuadletCommandInterfaceID kIOFireWireReadQuadletCommandInterfaceID kIOFireWireWriteCommandInterfaceID_v2 kIOFireWireWriteCommandInterfaceID kIOFireWireReadCommandInterfaceID_v2 kIOFireWireReadCommandInterfaceID

YES YES YES YES YES YES YES YES

SetQuads
void ( *SetQuads)( IOFireWireLibWriteQuadletCommandRef self, UInt32 inQuads[], UInt32 inNumQuads);

Discussion IOFireWireLibWriteQuadletCommandRef

Discussion Availability: (for interfaces obtained with ID)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

386

IOFireWireWriteQuadletCommandInterface Instance Methods

kIOFireWireReadCommandInterfaceID

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)

Submit
IOReturn ( *Submit)( IOFireWireLibCommandRef self);

Discussion Description forthcoming

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

387

IOFireWireWriteQuadletCommandInterface Instance Variables

Parameters
self

Instance Variables
revision
UInt32 revision;

Interface revision.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

388

IOFireWireWriteQuadletCommandInterface Instance Variables

version
UInt32 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

389

IOFWAsyncStreamListenerInterface

Declared in

IOFireWireLibIsoch.h

Overview
Represents and provides management functions for a asyn stream listener object.

Tasks
Miscellaneous
ClientCommandIsComplete

(page 391) Notify the async stream object that a packet notification handler has completed. (page 391) get the flags of listener. (page 392) get overrun counter from the DCL program. (page 392) Returns the user refCon value for this async stream interface. (page 392) Is notification on? (page 393) set flags for the listener. (page 393) Set the callback that should be called to handle incoming async stream packets (page 393) Set the callback that should be called when incoming packets are dropped by the address space.

GetFlags

GetOverrunCounter

GetRefCon

NotificationIsOn

SetFlags

SetListenerHandler

SetSkippedPacketHandler

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

390

IOFWAsyncStreamListenerInterface Instance Methods

TurnOffNotification

(page 394) Force packet notification off. (page 394) Try to turn on packet notifications for this channel.

TurnOnNotification

Instance Methods
ClientCommandIsComplete
Notify the async stream object that a packet notification handler has completed.
void ( *ClientCommandIsComplete)( IOFWAsyncStreamListenerInterfaceRef self, FWClientCommandID commandID, IOReturn status);

Parameters
self

The async stream interface to use.

commandID

The ID of the packet notification being completed. This is the same ID that was passed when a packet notification handler is called.
status

The completion status of the packet handler Discussion Packet notifications are received one at a time, in order. This function must be called after a packet handler has completed its work.

GetFlags
get the flags of listener.
UInt32 ( *GetFlags)( IOFWAsyncStreamListenerInterfaceRef self);

Parameters
self

The async stream interface to use.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

391

IOFWAsyncStreamListenerInterface Instance Methods

Return Value flags.

GetOverrunCounter
get overrun counter from the DCL program.
UInt32 ( *GetOverrunCounter)( IOFWAsyncStreamListenerInterfaceRef self);

Parameters
self

The async stream interface to use. Return Value returns the counter value.

GetRefCon
Returns the user refCon value for this async stream interface.
void* ( *GetRefCon)( IOFWAsyncStreamListenerInterfaceRef self);

Parameters
self

The async stream interface to use. Return Value returns the callback object.

NotificationIsOn
Is notification on?
Boolean ( *NotificationIsOn)( IOFWAsyncStreamListenerInterfaceRef self);

The async stream interface to use.

TurnOnNotification
Try to turn on packet notifications for this channel.
Boolean ( *TurnOnNotification)( IOFWAsyncStreamListenerInterfaceRef self);

Parameters
self

The async stream interface to use. Return Value Returns true upon success

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

394

IOFWAsyncStreamListenerInterface Instance Variables

Instance Variables
revision
UInt16 revision;

Interface revision.

version
UInt16 version;

Interface version.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

395

IOHIDDeviceDeviceInterface

Declared in

IOHIDDevicePlugIn.h (page 745)

Overview
The object you use to access HID devices from user space, returned by version 1.5 of the IOHIDFamily. The functions listed here will work with any version of the IOHIDDeviceDeviceInterface. Note: Please note that methods declared in this interface follow the copy/get/set conventions.

Tasks
Miscellaneous
close

(page 397) Closes the task's connection to the IOHIDDevice. (page 397) Obtains a CFArrayRef containing the IOHIDDeviceDeviceInterface elements that match the passed matching dictionary. (page 398) Obtains the event source for this IOHIDDeviceDeviceInterface instance. (page 399) Obtains a property related to the IOHIDDevice. (page 399) Obtains a report of type kIOHIDReportTypeInput or kIOHIDReportTypeFeature from the IOHIDDevice. (page 401) Obtains the current value for an element.

copyMatchingElements

getAsyncEventSource

getProperty

getReport

getValue

open

(page 402) Opens the IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

396

IOHIDDeviceDeviceInterface Instance Methods

setInputReportCallback

(page 402) Sets the input report callback to be used when data is received from the Input pipe. (page 403) Sets a property related to the IOHIDDevice. (page 404) Sends a report of type kIOHIDReportTypeOutput or kIOHIDReportTypeFeature to the IOHIDDevice. (page 405) Sets the value for an element.

setProperty

setReport

setValue

Instance Methods
close
Closes the task's connection to the IOHIDDevice.
IOReturn ( *close)( void *self, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

options

Option bits to be passed down to the user client. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion Releases the client's access to the IOHIDDevice.

copyMatchingElements
Obtains a CFArrayRef containing the IOHIDDeviceDeviceInterface elements that match the passed matching dictionary.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

397

IOHIDDeviceDeviceInterface Instance Methods

IOReturn ( *copyMatchingElements)( void *self, CFDictionaryRef matchingDict, CFArrayRef *pElements, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

matchingDict

CFDictionaryRef containing the element properties to match on.

pElements

CFArrayRef containing matched elements.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion Objects contained in the returned array are of type IOHIDElementRef. Please see IOHIDElement.h for additional API information. Elemenet properties are prefixed by kIOHIDElement and declared in IOHIDKeys.h.

getAsyncEventSource
Obtains the event source for this IOHIDDeviceDeviceInterface instance.
IOReturn ( *getAsyncEventSource)( void *self, CFTypeRef *pSource);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

pSource

Pointer to a CFType to return the run loop event source. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

398

IOHIDDeviceDeviceInterface Instance Methods

Discussion The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef.

getProperty
Obtains a property related to the IOHIDDevice.
IOReturn ( *getProperty)( void *self, CFStringRef key, CFTypeRef *pProperty);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

key

CFStringRef key
pProperty

Pointer to a CFTypeRef property. Return Value Returns kIOReturnSuccess if successful. Discussion Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h.

getReport
Obtains a report of type kIOHIDReportTypeInput or kIOHIDReportTypeFeature from the IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

399

IOHIDDeviceDeviceInterface Instance Methods

IOReturn ( *getReport)( void *self, IOHIDReportType reportType, uint32_t reportID, uint8_t *report, CFIndex *pReportLength, uint32_t timeout, IOHIDReportCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

reportType

The report type.

reportID

The report id.

report

Pointer to a pre-allocated buffer to be filled.

reportLength

Length of the report buffer. When finished, this will contain the actual length of the report.
timeout

Timeout in milliseconds for issuing the getReport.

callback

Callback of type IOHIDReportCallback to be used when report data has been received from the device. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion This method is useful if specific knowledge of the unparsed report is known to the caller. Otherwise, using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction is recommended.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

400

IOHIDDeviceDeviceInterface Instance Methods

Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

getValue
Obtains the current value for an element.
IOReturn ( *getValue)( void *self, IOHIDElementRef element, IOHIDValueRef *pValue, uint32_t timeout, IOHIDValueCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

element

IOHIDElementRef referencing the element of interest.

pValue

Pointer to a IOHIDValueRef to return the element value.

timeout

Time in milliseconds to wait before aborting request.

callback

Callback of type IOHIDReportCallback to be used when element value has been received from the device. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

401

IOHIDDeviceDeviceInterface Instance Methods

Discussion If an element of type kIOHIDElementTypeFeature is passed, this method will issue a request to the IOHIDDevice. Otherwise, this will return the last value reported by the IOHIDDevice. If requesting multiple feature element values, please consider using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction. Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

open
Opens the IOHIDDevice.
IOReturn ( *open)( void *self, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

options

Option bits to be passed down to the user client. Return Value Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid. Discussion Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes a link between the client's task and the actual device. To establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option.

setInputReportCallback
Sets the input report callback to be used when data is received from the Input pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

402

IOHIDDeviceDeviceInterface Instance Methods

IOReturn ( *setInputReportCallback)( void *self, uint8_t *report, CFIndex reportLength, IOHIDReportCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

report

Pointer to a pre-allocated buffer to be filled and passed back via the callback.
reportLength

Length of the report buffer.

callback

Callback of type IOHIDReportCallback to be used when report data has been receieved by the IOHIDDevice.
context

Pointer to data to be passed to the callback.

options

setProperty
Sets a property related to the IOHIDDevice.
IOReturn ( *setProperty)( void *self, CFStringRef key, CFTypeRef property);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

403

IOHIDDeviceDeviceInterface Instance Methods

key

CFStringRef key
property

CFTypeRef property. Return Value Returns kIOReturnSuccess if successful. Discussion Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h.

setReport
Sends a report of type kIOHIDReportTypeOutput or kIOHIDReportTypeFeature to the IOHIDDevice.
IOReturn ( *setReport)( void *self, IOHIDReportType reportType, uint32_t reportID, const uint8_t *report, CFIndex reportLength, uint32_t timeout, IOHIDReportCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

reportType

The report type.

reportID

The report id.

report

Pointer to a buffer containing the report data to be sent.

reportLength

Length of the report buffer.

timeout

Timeout in milliseconds for issuing the setReport.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

404

IOHIDDeviceDeviceInterface Instance Methods

callback

Callback of type IOHIDReportCallback to be used after report data has been sent to the device. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback.

options

setValue
Sets the value for an element.
IOReturn ( *setValue)( void *self, IOHIDElementRef element, IOHIDValueRef value, uint32_t timeout, IOHIDValueCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceDeviceInterface.

element

IOHIDElementRef referencing the element of interest.

value

IOHIDValueRef containing element value to be set.

timeout

Time in milliseconds to wait before aborting request.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

405

IOHIDDeviceDeviceInterface Instance Methods

callback

Callback of type IOHIDValueCallback to be used after report data has been sent to the device. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion If setting multiple element values, please consider using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeOutput direction. Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

406

IOHIDDeviceInterface

Declared in

IOHIDLibObsolete.h (page 813)

Overview
CFPlugin object subclass which provides the primary interface to HID devices.

Tasks
Miscellaneous
allocOutputTransaction

(page 408) Wrapper to return instances of the IOHIDOutputTransactionInterface. (page 408) Wrapper to return instances of the IOHIDQueueInterface. (page 408) Closes the device. (page 409) Creates async eventsource. (page 409) Creates an async port. (page 410) Gets the created async event source. (page 410) Gets the current async port. (page 410) Obtains the most recent value of an element.

allocQueue

createAsyncEventSource

createAsyncPort

getAsyncEventSource

getAsyncPort

getElementValue

open

(page 411) Opens the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

407

IOHIDDeviceInterface Instance Methods

queryElementValue

(page 411) Obtains the current value of an element. (page 412) Sets an element value on the device. (page 413) Sets callback to be used when device is removed. (page 413) Starts data delivery on all queues for this device. (page 413) Stops data delivery on all queues for this device.

setElementValue

setRemovalCallback

startAllQueues

stopAllQueues

Instance Methods
allocOutputTransaction
Wrapper to return instances of the IOHIDOutputTransactionInterface.
IOHIDOutputTransactionInterface ** ( *allocOutputTransaction) ( void *self);

Return Value Returns the created IOHIDOutputTransactionInterface.

allocQueue
Wrapper to return instances of the IOHIDQueueInterface.
IOHIDQueueInterface ** ( *allocQueue) ( void *self);

Return Value Returns the created IOHIDQueueInterface.

close
Closes the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

408

IOHIDDeviceInterface Instance Methods

IOReturn ( close)( void self);

Return Value Returns an IOReturn code.

createAsyncEventSource
Creates async eventsource.
IOReturn ( *createAsyncEventSource)( void *self, CFRunLoopSourceRef *source);

Parameters
source

Reference to CFRunLoopSourceRef that is created. Return Value Returns an IOReturn code. Discussion This method will create an async mach port, if one has not already been created.

createAsyncPort
Creates an async port.
IOReturn ( *createAsyncPort)( void *self, mach_port_t *port);

Parameters
port

Reference to mach port that is created. Return Value Returns an IOReturn code. Discussion The port must be created before any callbacks can be used.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

409

IOHIDDeviceInterface Instance Methods

getAsyncEventSource
Gets the created async event source.
CFRunLoopSourceRef ( *getAsyncEventSource)( void *self);

Return Value Returns a CFRunLoopSourceRef.

getAsyncPort
Gets the current async port.
mach_port_t ( *getAsyncPort)( void *self);

Return Value Returns a mach_port_t.

getElementValue
Obtains the most recent value of an element.
IOReturn ( *getElementValue)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *valueEvent);

Parameters
elementCookie

The element of interest.

valueEvent

The event that will be filled. If a long value is present, it is up to the caller to deallocate it. Return Value Returns an IOReturn code. Discussion This call is most useful for interrupt driven elements, such as input type elements. Since feature type element values need to be polled from the device, it is recommended to use the queryElementValue method to obtain the current value. The timestamp field in the event details the last time the element value was altered.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

410

IOHIDDeviceInterface Instance Methods

open
Opens the device.
IOReturn ( *open)( void *self, uint32_t flags);

Parameters
flags

Flags to be passed down to the user client. Return Value Returns an IOReturn code.

queryElementValue
Obtains the current value of an element.
IOReturn ( *queryElementValue)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *valueEvent, uint32_t timeoutMS, IOHIDElementCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
elementCookie

The element of interest.

valueEvent

The event that will be filled. If a long value is present, it is up to the caller to deallocate it.
timeoutMS

UNSUPPORTED.
callback

UNSUPPORTED.
callbackTarget

UNSUPPORTED.
callbackRefcon

UNSUPPORTED.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

411

IOHIDDeviceInterface Instance Methods

Return Value Returns an IOReturn code. Discussion This call is most useful for feature type elements. This method will poll the device for the current element value.

setElementValue
Sets an element value on the device.
IOReturn ( *setElementValue)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *valueEvent, uint32_t timeoutMS, IOHIDElementCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
elementCookie

The element of interest.

valueEvent

The event that will be filled. If a long value is present, it will be copied.
timeoutMS

UNSUPPORTED.
callback

UNSUPPORTED.
callbackTarget

UNSUPPORTED.
callbackRefcon

UNSUPPORTED. Return Value Returns an IOReturn code. Discussion This call is most useful for feature type elements. It is recommended to use IOOutputTransaction for output type elements.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

412

IOHIDDeviceInterface Instance Methods

setRemovalCallback
Sets callback to be used when device is removed.
IOReturn ( *setRemovalCallback)( void *self, IOHIDCallbackFunction removalCallback, void *removalTarget, void *removalRefcon);

Parameters
removalCallback

Called when the device is removed.

removalTarget

Passed to the callback.

removalRefcon

Passed to the callback. Return Value Returns an IOReturn code.

startAllQueues
Starts data delivery on all queues for this device.
IOReturn ( *startAllQueues)( void *self);

Return Value Returns an IOReturn code.

stopAllQueues
Stops data delivery on all queues for this device.
IOReturn ( *stopAllQueues)( void *self);

Return Value Returns an IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

413

IOHIDDeviceInterface121

Declared in

IOHIDLibObsolete.h (page 813)

Overview
CFPlugin object subclass which provides the primary interface to HID devices. This class is a subclass of IOHIDDeviceInterface.

Tasks
Miscellaneous
getReport

(page 414) Obtains a report from the device. (page 415) Sends a report to the device.

setReport

Instance Methods
getReport
Obtains a report from the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

414

IOHIDDeviceInterface121 Instance Methods

IOReturn ( *getReport) ( void *self, IOHIDReportType reportType, uint32_t reportID, void *reportBuffer, uint32_t *reportBufferSize, uint32_t timeoutMS, IOHIDReportCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
reportType

The report type.

reportID

The report ID.

reportBuffer

Pointer to a preallocated buffer.

reportBufferSize

Size of the reportBuffer in bytes. When finished, will contain the actual size of the report.
timeoutMS callback

If null, this method will behave synchronously.

callbackTarget

The callback target passed to the callback.

callbackRefcon

The callback refcon passed to the callback. Return Value Returns an IOReturn code.

setReport
Sends a report to the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

415

IOHIDDeviceInterface121 Instance Methods

IOReturn ( *setReport) ( void *self, IOHIDReportType reportType, uint32_t reportID, void *reportBuffer, uint32_t reportBufferSize, uint32_t timeoutMS, IOHIDReportCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
reportType

The report type.

reportID

The report id.

reportBuffer

Pointer to a preallocated buffer.

reportBufferSize

Size of the reportBuffer in bytes.

timeoutMS callback

If null, this method will behave synchronously.

callbackTarget

The callback target passed to the callback.

callbackRefcon

The callback refcon passed to the callback. Return Value Returns an IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

416

IOHIDDeviceInterface122

Declared in

IOHIDLibObsolete.h (page 813)

Overview
CFPlugin object subclass which provides the primary interface to HID devices. This class is a subclass of IOHIDDeviceInterface121.

Tasks
Miscellaneous
copyMatchingElements

(page 417) Obtains specific elements defined by the device. (page 418) Sets the report handler callout to be called when the data is received from the Interrupt-In pipe.

setInterruptReportHandlerCallback

Instance Methods
copyMatchingElements
Obtains specific elements defined by the device.
IOReturn ( *copyMatchingElements)( void *self, CFDictionaryRef matchingDict, CFArrayRef *elements);

Parameters
matchingDict

Dictionary containg key/value pairs to match on. Pass a null value to match on all elements.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

417

IOHIDDeviceInterface122 Instance Methods

elements

Pointer to a CFArrayRef that will be returned by this method. It is up to the caller to release it when finished. Return Value Returns an IOReturn code. Discussion Using keys defined in IOHIDKeys.h for elements, create a matching dictonary containing items that you wish to search for. A null array indicates that no elements matching that criteria were found. Each item in the array is a reference to the same dictionary item that represents each element in the I/O Registry. It is up to the caller to release the returned array of elements.

setInterruptReportHandlerCallback
Sets the report handler callout to be called when the data is received from the Interrupt-In pipe.
IOReturn ( *setInterruptReportHandlerCallback)( void *self, void *reportBuffer, uint32_t reportBufferSize, IOHIDReportCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
reportBuffer

Pointer to a preallocated buffer.

reportBufferSize

Size of the reportBuffer in bytes.

callback

If non-NULL, is a callback to be called when data is received from the device.

callbackTarget

The callback target passed to the callback

callbackRefcon

The callback refcon passed to the callback. Return Value Returns an IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

418

IOHIDDeviceInterface122 Instance Methods

Discussion In order for this to work correctly, you must call createAsyncPort and createAsyncEventSource.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

419

IOHIDDeviceQueueInterface

Declared in

IOHIDDevicePlugIn.h (page 745)

Overview
The object you use to access a HID queue from user space, returned by version 1.5 of the IOHIDFamily. The functions listed here will work with any version of the IOHIDDeviceQueueInterface. This behavior is useful when you need to keep track of all values of an input element, rather than just the most recent one. Note:Absolute element values (based on a fixed origin) will only be placed on a queue if there is a change in value.

Tasks
Miscellaneous
addElement

(page 421) Adds an element to this IOHIDDeviceQueueInterface instance. (page 421) Determines whether an element has been added to this IOHIDDeviceQueueInterface instance. (page 422) Dequeues a retained copy of an element value from the head of an IOHIDDeviceQueueInterface. (page 423) Obtains the event source for this IOHIDDeviceQueueInterface instance. (page 423) Obtains the queue depth for this IOHIDDeviceQueueInterface instance. (page 424) Removes an element from this IOHIDDeviceQueueInterface instance.

containsElement

copyNextValue

getAsyncEventSource

pValue

Pointer to a IOHIDValueRef to return the value at the head of the queue.

timeout

Timeout in milliseconds before aborting an attempt to dequeue a value from the head of a queue.
options

Reserved for future use. Ignored in current implementation. Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

422

IOHIDDeviceQueueInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnUnderrun if data is unavailble, or a kern_return_t if unsuccessful. Discussion Because the value is a retained copy, it is up to the caller to release the value using CFRelease. Use with setValueCallback to avoid polling the queue for data.

getAsyncEventSource
Obtains the event source for this IOHIDDeviceQueueInterface instance.
IOReturn ( *getAsyncEventSource)( void *self, CFTypeRef *pSource);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

pSource

Pointer to a CFType to return the run loop event source. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef.

getDepth
Obtains the queue depth for this IOHIDDeviceQueueInterface instance.
IOReturn ( *getDepth)( void *self, uint32_t *pDepth);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

pDepth

Pointer to a uint32_t to obtain the number of elements that can be serviced by the queue.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

423

IOHIDDeviceQueueInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

removeElement
Removes an element from this IOHIDDeviceQueueInterface instance.
IOReturn ( *removeElement)( void *self, IOHIDElementRef element, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

element

IOHIDElementRef referencing the element to be removed from the queue.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

setDepth
Sets the depth for this IOHIDDeviceQueueInterface instance.
IOReturn ( *setDepth)( void *self, uint32_t depth, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

depth

The maximum number of elements in the queue before the oldest elements in the queue begin to be lost.
options

Reserved for future use. Ignored in current implementation. Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

424

IOHIDDeviceQueueInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion Regardless of element value size, queue will guarantee n=depth elements will be serviced.

setValueAvailableCallback
Sets callback to be used when the queue transitions to non-empty.
IOReturn ( *setValueAvailableCallback)( void *self, IOHIDCallback callback, void *context);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

callback

Callback of type IOHIDCallback to be used when data is placed on the queue.

context

Pointer to data to be passed to the callback.

options

start
Starts element value delivery to the queue.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

425

IOHIDDeviceQueueInterface Instance Methods

IOReturn ( start)( void self, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

stop
Stops element value delivery to the queue.
IOReturn ( *stop)( void *self, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceQueueInterface.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

426

IOHIDDeviceTransactionInterface

Declared in

IOHIDDevicePlugIn.h (page 745)

Overview
The object you use to access a HID transaction from user space, returned by version 1.5 of the IOHIDFamily. The functions listed here will work with any version of the IOHIDDeviceTransactionInterface. This functionality is useful when either setting or getting the values for multiple parsed elements.

Tasks
Miscellaneous
addElement

(page 428) Adds an element to this IOHIDDeviceTransactionInterface instance. (page 428) Clears element transaction values for an IOHIDDeviceTransactionInterface. (page 429) Commits element transaction to an IOHIDDevice in this IOHIDDeviceTransactionInterface instance. (page 430) Checks whether an element has been added to this IOHIDDeviceTransactionInterface instance. (page 430) Obtains the event source for this IOHIDDeviceTransactionInterface instance. (page 431) Obtains the direction for this IOHIDDeviceTransactionInterface instance. (page 431) Obtains the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

clear

commit

containsElement

getAsyncEventSource

getDirection

getValue

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

427

IOHIDDeviceTransactionInterface Instance Methods

removeElement

(page 432) Removes an element from this IOHIDDeviceTransactionInterface instance. (page 433) Sets the direction for this IOHIDDeviceTransactionInterface instance. (page 433) Sets the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

setDirection

setValue

Instance Methods
addElement
Adds an element to this IOHIDDeviceTransactionInterface instance.
IOReturn ( *addElement)( void *self, IOHIDElementRef element, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

element

IOHIDElementRef referencing the element to be added to the transaction.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

clear
Clears element transaction values for an IOHIDDeviceTransactionInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

428

IOHIDDeviceTransactionInterface Instance Methods

IOReturn ( clear)( void self, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

options

commit
Commits element transaction to an IOHIDDevice in this IOHIDDeviceTransactionInterface instance.
IOReturn ( *commit)( void *self, uint32_t timeout, IOHIDCallback callback, void *context, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

timeout

Timeout in milliseconds for issuing the transaction.

callback

Callback of type IOHIDCallback to be used when transaction has been completed. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback.

options

Reserved for future use. Ignored in current implementation. Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

429

IOHIDDeviceTransactionInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be used if element values are not set. If neither are set, that element will be omitted from the commit. After a transaction is committed, transaction element values will be cleared and default values preserved. Note: It is possible for elements from different reports to be present in a given transaction causing a commit to transcend multiple reports. Keep this in mind when setting a timeout.

containsElement
Checks whether an element has been added to this IOHIDDeviceTransactionInterface instance.
IOReturn ( *containsElement)( void *self, IOHIDElementRef element, Boolean *pValue, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

element

IOHIDElementRef referencing the element to be be found in the transaction.

pValue

Pointer to a Boolean to return whether or not the element was found in the transaction.
options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

getAsyncEventSource
Obtains the event source for this IOHIDDeviceTransactionInterface instance.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

430

IOHIDDeviceTransactionInterface Instance Methods

IOReturn ( getAsyncEventSource)( void self, CFTypeRef *pSource);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

pSource

getDirection
Obtains the direction for this IOHIDDeviceTransactionInterface instance.
IOReturn ( *getDirection)( void *self, IOHIDTransactionDirectionType *pDirection);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

pDirection

Pointer to a IOHIDTransactionDirectionType to obtain transaction direction. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion Direction constants are declared in IOHIDTransactionDirectionType.

getValue
Obtains the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

431

IOHIDDeviceTransactionInterface Instance Methods

IOReturn ( *getValue)( void *self, IOHIDElementRef element, IOHIDValueRef *pValue, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

element

IOHIDElementRef referencing the element of interest.

pValue

Pointer to an IOHIDValueRef to return the element value of the transaction.

options

See IOHIDTransactionOption. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default element value.

removeElement
Removes an element from this IOHIDDeviceTransactionInterface instance.
IOReturn ( *removeElement)( void *self, IOHIDElementRef element, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

element

IOHIDElementRef referencing the element to be removed from the transaction.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

432

IOHIDDeviceTransactionInterface Instance Methods

setDirection
Sets the direction for this IOHIDDeviceTransactionInterface instance.
IOReturn ( *setDirection)( void *self, IOHIDTransactionDirectionType direction, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

direction

Transaction direction of type IOHIDTransactionDirectionType.

options

Reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion Direction constants are declared in IOHIDTransactionDirectionType. Changing directions is useful when dealing with elements of type kIOHIDElementTypeFeature as you use the transaction to both set and get element values.

setValue
Sets the transaction value for an element in this IOHIDDeviceTransactionInterface instance.
IOReturn ( *setValue)( void *self, IOHIDElementRef element, IOHIDValueRef value, IOOptionBits options);

Parameters
self

Pointer to the IOHIDDeviceTransactionInterface.

element

IOHIDElementRef referencing the element of interest.

value

IOHIDValueRef referencing element value to be used in the transaction.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

433

IOHIDDeviceTransactionInterface Instance Methods

options

See IOHIDTransactionOption. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion This method is intended for use with transaction of direction kIOHIDTransactionDirectionTypeOutput. Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element value.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

434

IOHIDOutputTransactionInterface

Declared in

IOHIDLibObsolete.h (page 813)

Overview
CFPlugin object subclass which privides interface for output transactions to HID devices. Created by a IOHIDDeviceInterface object.

Tasks
Miscellaneous
addElement

(page 436) Adds an element to the transaction. (page 437) Clears the transaction. (page 437) Commits the transaction. (page 438) Creates the current transaction. (page 438) Creates an async event source. (page 438) Creates an async port. (page 439) Disposes of the current transaction. (page 439) Obtains the current event source.

clear

commit

create

createAsyncEventSource

createAsyncPort

dispose

getAsyncEventSource

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

435

IOHIDOutputTransactionInterface Instance Methods

getAsyncPort

(page 439) Obtains the current async port. (page 440) Obtains the default value of an element in a transaction. (page 440) Obtains the value of an element in a transaction. (page 441) Checks whether an element has been added to the transaction. (page 441) Removes an element from the transaction. (page 441) Sets the default value of an element in a transaction. (page 442) Sets the value of an element in a transaction.

getElementDefault

getElementValue

hasElement

removeElement

setElementDefault

setElementValue

Instance Methods
addElement
Adds an element to the transaction.
IOReturn ( *addElement) ( void *self, IOHIDElementCookie elementCookie);

Parameters
elementCookie

The element of interest. Return Value Returns an IOReturn code. Discussion If the element has already been added to transaction, an error will be returned.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

436

IOHIDOutputTransactionInterface Instance Methods

clear
Clears the transaction.
IOReturn ( *clear)( void *self);

Return Value Returns an IOReturn code. Discussion Transaction element values will cleared. Default values will be preserved.

commit
Commits the transaction.
IOReturn ( *commit)( void *self, uint32_t timeoutMS, IOHIDCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
timeoutMS

UNSUPPORTED
callback

UNSUPPORTED
callbackTarget

UNSUPPORTED
callbackRefcon

UNSUPPORTED Return Value Returns an IOReturn code. Discussion Transaction element values, if set, will be sent to the device. Otherwise, the default element value will be used. If neither are set, that element will be omitted from the commit. After a transaction is committed, transaction element values will be cleared. Default values will be preserved.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

437

IOHIDOutputTransactionInterface Instance Methods

create
Creates the current transaction.
IOReturn ( *create)( void *self);

Return Value Returns an IOReturn code. Discussion This method will free any memory that has been allocated for this transaction.

createAsyncEventSource
Creates an async event source.
IOReturn ( *createAsyncEventSource)( void *self, CFRunLoopSourceRef *source);

Parameters
source

The newly created event source Return Value Returns an IOReturn code. Discussion This will be used with setEventCallout.

createAsyncPort
Creates an async port.
IOReturn ( *createAsyncPort)( void *self, mach_port_t *port);

Parameters
port

The newly created async port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

438

IOHIDOutputTransactionInterface Instance Methods

Return Value Returns an IOReturn code. Discussion This will be used with createAsyncEventSource.

dispose
Disposes of the current transaction.
IOReturn ( *dispose)( void *self);

Return Value Returns an IOReturn code. Discussion The transaction will have to be recreated, in order to perform any operations on the transaction.

getAsyncEventSource
Obtains the current event source.
CFRunLoopSourceRef ( *getAsyncEventSource)( void *self);

Return Value Returns a CFRunLoopSourceRef.

getAsyncPort
Obtains the current async port.
mach_port_t ( *getAsyncPort)( void *self);

Return Value Returns a mach_port_t.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

439

IOHIDOutputTransactionInterface Instance Methods

getElementDefault
Obtains the default value of an element in a transaction.
IOReturn ( *getElementDefault)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *outValueEvent);

Parameters
elementCookie

The element of interest.

outValueEvent

The event that will be filled. If a long value is present, it is up to the caller to deallocate it. Return Value Returns an IOReturn code. Discussion An error will be returned if the element has not been added to the transaction.

getElementValue
Obtains the value of an element in a transaction.
IOReturn ( *getElementValue)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *outValueEvent);

Parameters
elementCookie

The element of interest.

outValueEvent

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

440

IOHIDOutputTransactionInterface Instance Methods

hasElement
Checks whether an element has been added to the transaction.
Boolean ( *hasElement) ( void *self, IOHIDElementCookie elementCookie);

Parameters
elementCookie

The element of interest. Return Value Returns a Boolean value. Discussion Will return true if present, otherwise will return false.

removeElement
Removes an element from the transaction.
IOReturn ( *removeElement) ( void *self, IOHIDElementCookie elementCookie);

Parameters
elementCookie

The element of interest. Return Value Returns an IOReturn code. Discussion If the element has not been added to transaction, an error will be returned.

setElementDefault
Sets the default value of an element in a transaction.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

441

IOHIDOutputTransactionInterface Instance Methods

IOReturn ( setElementDefault)( void self, IOHIDElementCookie elementCookie, IOHIDEventStruct *valueEvent);

Parameters
elementCookie

The element of interest.

valueEvent

The event that will be filled. If a long value is present, it will be copied. Return Value Returns an IOReturn code. Discussion An error will be returned if the element has not been added to the transaction.

setElementValue
Sets the value of an element in a transaction.
IOReturn ( *setElementValue)( void *self, IOHIDElementCookie elementCookie, IOHIDEventStruct *valueEvent);

Parameters
elementCookie

The element of interest.

valueEvent

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

442

IOHIDQueueInterface

Declared in

IOHIDLibObsolete.h (page 813)

Overview
CFPlugin object subclass which provides an interface for input queues from HID devices. Created by an IOHIDDeviceInterface object.

Tasks
Miscellaneous
addElement

(page 444) Adds an element to the queue. (page 445) Creates the current queue. (page 445) Creates an async event source. (page 445) Creates an async port. (page 446) Disposes of the current queue. (page 446) Obtains the current event source. (page 446) Obtains the current async port. (page 447) Gets the event callout.

create

createAsyncEventSource

createAsyncPort

dispose

getAsyncEventSource

getAsyncPort

getEventCallout

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

443

IOHIDQueueInterface Instance Methods

getNextEvent

(page 447) Reads next event from the queue. (page 448) Checks whether an element has been added to the queue. (page 448) Removes an element from the queue. (page 449) Sets the event callout to be called when the queue transitions to non-empty. (page 449) Starts event delivery to the queue.

hasElement

removeElement

setEventCallout

start

stop

(page 450) Stops event delivery to the queue.

Instance Methods
addElement
Adds an element to the queue.
IOReturn ( *addElement)( void *self, IOHIDElementCookie elementCookie, uint32_t flags);

Parameters
elementCookie

The element of interest.

flags

Return Value Returns an IOReturn code. Discussion If the element has already been added to queue, an error will be returned.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

444

IOHIDQueueInterface Instance Methods

create
Creates the current queue.
IOReturn ( *create)( void *self, uint32_t flags, uint32_t depth);

Parameters
flags

Pass kIOHIDQueueOptionsTypeEnqueueAll option to force the IOHIDQueue to enqueue all events, relative or absolute, regardless of change.
depth

The maximum number of elements in the queue before the oldest elements in the queue begin to be lost. Return Value Returns an IOReturn code.

createAsyncEventSource
Creates an async event source.
IOReturn ( *createAsyncEventSource)( void *self, CFRunLoopSourceRef *source);

Parameters
source

The newly created event source. Return Value Returns an IOReturn code. Discussion This will be used with setEventCallout.

createAsyncPort
Creates an async port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

445

IOHIDQueueInterface Instance Methods

IOReturn ( createAsyncPort)( void self, mach_port_t *port);

Parameters
port

The newly created async port. Return Value Returns an IOReturn code. Discussion This will be used with createAsyncEventSource.

dispose
Disposes of the current queue.
IOReturn ( *dispose)( void *self);

Return Value Returns an IOReturn code.

getAsyncEventSource
Obtains the current event source.
CFRunLoopSourceRef ( *getAsyncEventSource)( void *self);

Return Value Returns a CFRunLoopSourceRef.

getAsyncPort
Obtains the current async port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

446

IOHIDQueueInterface Instance Methods

mach_port_t ( getAsyncPort)( void self);

Return Value Returns a mach_port_t.

getEventCallout
Gets the event callout.
IOReturn ( *getEventCallout)( void *self, IOHIDCallbackFunction *outCallback, void **outCallbackTarget, void **outCallbackRefcon);

Parameters
outCallback

if non-NULL is a callback to be called when data is inserted to the queue

outCallbackTarget

The callback target passed to the callback

outCallbackRefcon

The callback refcon passed to the callback Return Value Returns an IOReturn code. Discussion This callback will be called the queue transitions to non-empty.

getNextEvent
Reads next event from the queue.
IOReturn ( *getNextEvent)( void *self, IOHIDEventStruct *event, AbsoluteTime maxTime, uint32_t timeoutMS);

Parameters
event

The event that will be filled. If a long value is present, it is up to the caller to deallocate it.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

447

IOHIDQueueInterface Instance Methods

maxTime

UNSUPPORTED. If non-zero, limits read events to those that occurred on or before maxTime.
timeoutMS

UNSUPPORTED. The timeout in milliseconds, a zero timeout will cause this call to be non-blocking (returning queue empty) if there is a NULL callback, and blocking forever until the queue is non-empty if there is a valid callback. Return Value Returns an IOReturn code.

hasElement
Checks whether an element has been added to the queue.
Boolean ( *hasElement)( void *self, IOHIDElementCookie elementCookie);

Parameters
elementCookie

The element of interest. Return Value Returns a Boolean value. Discussion Will return true if present, otherwise will return false.

removeElement
Removes an element from the queue.
IOReturn ( *removeElement)( void *self, IOHIDElementCookie elementCookie);

Parameters
elementCookie

The element of interest.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

448

IOHIDQueueInterface Instance Methods

Return Value Returns an IOReturn code. Discussion If the element has not been added to queue, an error will be returned.

setEventCallout
Sets the event callout to be called when the queue transitions to non-empty.
IOReturn ( *setEventCallout)( void *self, IOHIDCallbackFunction callback, void *callbackTarget, void *callbackRefcon);

Parameters
callback

if non-NULL is a callback to be called when data is inserted to the queue

callbackTarget

The callback target passed to the callback

callbackRefcon

The callback refcon passed to the callback. Return Value Returns an IOReturn code. Discussion In order for this to work correctly, you must call createAsyncPort and createAsyncEventSource.

start
Starts event delivery to the queue.
IOReturn ( *start)( void *self);

Return Value Returns an IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

449

IOHIDQueueInterface Instance Methods

stop
Stops event delivery to the queue.
IOReturn ( *stop)( void *self);

Return Value Returns an IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

450

IOUPSPlugInInterface

Declared in

IOUPSPlugIn.h (page 1138)

Overview
Represents and provides management functions for a UPS device.

Tasks
Miscellaneous
createAsyncEventSource

(page 452) Used to create an async run loop event source of the plugin. (page 452) Used to obtain the capabilities of the UPS device. (page 453) Used to poll the current state of the UPS. (page 453) Used to obtain the properties of the UPS device such as the name and transport. (page 454) Send a command to the UPS. (page 454) Set the callback that should be called to handle an event from the UPS.

getCapabilities

getEvent

getProperties

sendCommand

setEventCallback

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

451

IOUPSPlugInInterface Instance Methods

The address to be targeted by this callback.

callbackRefcon

A user specified reference value. This will be passed to all callback functions. Return Value An IOReturn error code. Discussion The proivided callback method should be called whenever there is a change of state in the UPS. This should be used in conjunction with createAsyncEventSource.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

455

IOUSBDeviceInterface

Declared in

IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by all versions of the IOUSBFamily currently shipping. The functions listed here will work with any version of the IOUSBDeviceInterface, including the one shipped with OS X version 10.0.

Tasks
Miscellaneous
CreateDeviceAsyncEventSource

(page 458) Creates a run loop source for delivery of all asynchronous notifications on this device. (page 458) Creates and registers a mach_port_t for asynchronous communications. (page 459) Creates an iterator to iterate over some or all of the interfaces of a device. (page 459) Sends a USB request on the default control pipe. (page 460) Sends an asynchronous USB request on the default control pipe. (page 461) Gets the current frame number of the bus to which the device is attached. (page 461) Returns the currently selected configuration in the device.

CreateDeviceAsyncPort

CreateInterfaceIterator

DeviceRequest

DeviceRequestAsync

GetBusFrameNumber

GetConfiguration

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

456

IOUSBDeviceInterface Tasks

GetConfigurationDescriptorPtr

(page 462) Returns a pointer to a configuration descriptor for a given index. (page 462) Returns the address of the device on its bus. (page 463) Returns the CFRunLoopSourceRef for this IOService instance. (page 463) Returns the mach_port_t port for this IOService instance. (page 464) Returns the power available to the device. (page 464) Returns the USB Class (bDeviceClass) of the device. (page 465) Returns the USB Product ID (idProduct) of the device. (page 465) Returns the USB Protocol (bDeviceProtocol) of the interface. (page 466) Returns the Device Release Number (bcdDevice) of the device. (page 466) Returns the speed of the device. (page 467) Returns the USB Subclass (bDeviceSubClass) of the device. (page 467) Returns the USB Vendor ID (idVendor) of the device. (page 468) Returns the location ID. (page 468) Returns the number of supported configurations in this device. (page 469) Tells the IOUSBFamily to issue a reset to the device. (page 469) Sets the configuration in the device. (page 470) Closes the task's connection to the IOUSBDevice.

GetDeviceAddress

GetDeviceAsyncEventSource

GetDeviceAsyncPort

GetDeviceBusPowerAvailable

GetDeviceClass

GetDeviceProduct

GetDeviceProtocol

GetDeviceReleaseNumber

GetDeviceSpeed

GetDeviceSubClass

GetDeviceVendor

GetLocationID

GetNumberOfConfigurations

ResetDevice

SetConfiguration

USBDeviceClose

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

457

IOUSBDeviceInterface Instance Methods

USBDeviceOpen

(page 470) Opens the IOUSBDevice for exclusive access.

Instance Methods
CreateDeviceAsyncEventSource
Creates a run loop source for delivery of all asynchronous notifications on this device.
IOReturn ( *CreateDeviceAsyncEventSource)( void *self, CFRunLoopSourceRef *source);

Parameters
self

Pointer to the IOUSBDeviceInterface.

source

Pointer to a CFRunLoopSourceRef to return the newly created run loop event source. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion The OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications (see CreateInterfaceAsyncPort). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the client's CFRunLoop.

CreateDeviceAsyncPort
Creates and registers a mach_port_t for asynchronous communications.
IOReturn ( *CreateDeviceAsyncPort)( void *self, mach_port_t *port);

Parameters
self

Pointer to the IOUSBDeviceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

458

IOUSBDeviceInterface Instance Methods

port

Pointer to a mach_port_t to return the newly created port. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion The OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on this mach port. After receiving a message on this port the client is obliged to call the IOKitLib.h IODispatchCalloutFromMessage() function for decoding the notification message.

CreateInterfaceIterator
Creates an iterator to iterate over some or all of the interfaces of a device.
IOReturn ( *CreateInterfaceIterator)( void *self, IOUSBFindInterfaceRequest *req, io_iterator_t *iter);

Parameters
self

Pointer to the IOUSBDeviceInterface.

req

Pointer an IOUSBFindInterfaceRequest structure describing the desired interfaces.

iter

Pointer to a an io_iterator_t to contain the new iterator. Return Value Returns kIOReturnSuccess if successful or kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

DeviceRequest
Sends a USB request on the default control pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

459

IOUSBDeviceInterface Instance Methods

IOReturn ( DeviceRequest)( void self, IOUSBDevRequest *req);

Parameters
self

Pointer to the IOUSBDeviceInterface.

req

Pointer to an IOUSBDevRequest containing the request. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the device is not open for exclusive access. Discussion The device must be open to issue this call. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

DeviceRequestAsync
Sends an asynchronous USB request on the default control pipe.
IOReturn ( *DeviceRequestAsync)( void *self, IOUSBDevRequest *req, IOAsyncCallback1 callback, void *refCon);

Parameters
self

Pointer to the IOUSBDeviceInterface.

req

Pointer to an IOUSBDevRequest containing the request.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refCon

Arbitrary pointer which is passed as a parameter to the callback routine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

460

IOUSBDeviceInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNotOpen if the device is not open for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created for this interface. Discussion The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

GetBusFrameNumber
Gets the current frame number of the bus to which the device is attached.
IOReturn ( *GetBusFrameNumber)( void *self, UInt64 *frame, AbsoluteTime *atTime);

Parameters
self

Pointer to the IOUSBDeviceInterface.

frame

Pointer to UInt64 to hold the frame number.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

464

IOUSBDeviceInterface Instance Methods

GetDeviceProduct
Returns the USB Product ID (idProduct) of the device.
IOReturn ( *GetDeviceProduct)( void *self, UInt16 *devProduct);

Parameters
self

Pointer to the IOUSBDeviceInterface.

devProduct

Pointer to UInt16 to hold the ProductID. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

GetDeviceProtocol
Returns the USB Protocol (bDeviceProtocol) of the interface.
IOReturn ( *GetDeviceProtocol)( void *self, UInt8 *devProtocol);

devSpeed

Pointer to UInt8 to hold the speed (kUSBDeviceSpeedLow, kUSBDeviceSpeedFull, kUSBDeviceSpeedHigh, or kUSBDeviceSpeedSuper). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

466

IOUSBDeviceInterface Instance Methods

GetDeviceSubClass
Returns the USB Subclass (bDeviceSubClass) of the device.
IOReturn ( *GetDeviceSubClass)( void *self, UInt8 *devSubClass);

Parameters
self

Pointer to the IOUSBDeviceInterface.

devSubClass

Pointer to UInt8 to hold the device Subclass. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

GetDeviceVendor
Returns the USB Vendor ID (idVendor) of the device.
IOReturn ( *GetDeviceVendor)( void *self, UInt16 *devVendor);

Parameters
self

Pointer to the IOUSBDeviceInterface.

devVendor

Pointer to UInt16 to hold the vendorID. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

467

IOUSBDeviceInterface Instance Methods

GetLocationID
Returns the location ID.
IOReturn ( *GetLocationID)( void *self, UInt32 *locationID);

Parameters
self

Pointer to the IOUSBDeviceInterface.

locationID

Pointer to UInt32 to hold the location ID. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The location ID is a 32 bit number which is unique among all USB devices in the system, and which will not change on a system reboot unless the topology of the bus itself changes. The device does not have to be open to use this function.

GetNumberOfConfigurations
Returns the number of supported configurations in this device.
IOReturn ( *GetNumberOfConfigurations)( void *self, UInt8 *numConfig);

Parameters
self

Pointer to the IOUSBDeviceInterface.

numConfig

Pointer to UInt8 to hold the number of configurations. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

468

IOUSBDeviceInterface Instance Methods

ResetDevice
Tells the IOUSBFamily to issue a reset to the device.
IOReturn ( *ResetDevice)( void *self);

Parameters
self

Pointer to the IOUSBDeviceInterface. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the device is not open for exclusive access. Discussion It will not reenumerate the device, which means that the cached device descriptor values will not be updated after the reset. (If you want the IOUSBFamily to reload the cached values, use the call USBDeviceReEnumerate). Prior to version 1.8.5 of the IOUSBFamily, this call also sent a message to all clients of the IOUSBDevice (IOUSBInterfaces and their drivers). The device must be open to use this function. This behavior was eliminated in version 1.8.5 of the IOUSBFamily.

SetConfiguration
Sets the configuration in the device.
IOReturn ( *SetConfiguration)( void *self, UInt8 configNum);

470

IOUSBDeviceInterface182

Inherits from Declared in

IOUSBDeviceInterface
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 1.8.2 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface and some new functions that are available on OS X version 10.0.4 and later.

Tasks
Miscellaneous
DeviceRequestAsyncTO

(page 472) Sends an asynchronous USB request on the default control pipe. (page 473) Sends a USB request on the default control pipe. (page 473) Aborts a transaction on the default control pipe. (page 474) Opens the IOUSBDevice for exclusive access. (page 474) Tells the USB Family to either suspend or resume the port to which a device is attached. (page 475) Returns the manufacturer string index in the device descriptor.

DeviceRequestTO

USBDeviceAbortPipeZero

USBDeviceOpenSeize

USBDeviceSuspend

USBGetManufacturerStringIndex

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

471

IOUSBDeviceInterface182 Instance Methods

USBGetProductStringIndex

(page 475) Returns the product string index in the device descriptor. (page 476) Returns the serial number string index in the device descriptor.

USBGetSerialNumberStringIndex

Instance Methods
DeviceRequestAsyncTO
Sends an asynchronous USB request on the default control pipe.
IOReturn ( *DeviceRequestAsyncTO)( void *self, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);

Parameters
self

Pointer to the IOUSBDeviceInterface.

req

Pointer to an IOUSBDevRequestTO containing the request.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refCon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNotOpen if the device is not open for exclusive access, orkIOUSBNoAsyncPortErr if no Async port has been created for this interface. Discussion This function sends an asynchronous USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

472

IOUSBDeviceInterface182 Instance Methods

DeviceRequestTO
Sends a USB request on the default control pipe.
IOReturn ( *DeviceRequestTO)( void *self, IOUSBDevRequestTO *req);

Parameters
self

Pointer to the IOUSBDeviceInterface.

req

Pointer to an IOUSBDevRequestTO containing the request. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the device is not open for exclusive access. Discussion This function sends a USB request on the default control pipe. The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. The device must be open to issue this command. Care should be taken when issuing a device request which changes the state of the device. Use the API, for example, to change the configuration of the device or to select an alternate setting on an interface.

USBDeviceAbortPipeZero
Aborts a transaction on the default control pipe.
IOReturn ( *USBDeviceAbortPipeZero)( void *self);

Parameters
self

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

473

IOUSBDeviceInterface182 Instance Methods

USBDeviceOpenSeize
Opens the IOUSBDevice for exclusive access.
IOReturn ( *USBDeviceOpenSeize)( void *self);

Parameters
self

Pointer to the IOUSBDeviceInterface. Return Value Returns kIOReturnExclusiveAccess if some other task has the device opened already and refuses to close it, kIOReturnError if the connection with the kernel can not be established or kIOReturnSuccess if successful. Discussion This function opens the IOUSBDevice for exclusive access. If another client has the device opened, an attempt is made to get that client to close it before returning. Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes an exclusive link between the client's task and the actual device.

USBDeviceSuspend
Tells the USB Family to either suspend or resume the port to which a device is attached.
IOReturn ( *USBDeviceSuspend)( void *self, Boolean suspend);

psi

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

475

IOUSBDeviceInterface182 Instance Methods

USBGetSerialNumberStringIndex
Returns the serial number string index in the device descriptor.
IOReturn ( *USBGetSerialNumberStringIndex)( void *self, UInt8 *snsi);

Parameters
self

Pointer to the IOUSBDeviceInterface.

snsi

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

476

IOUSBDeviceInterface187

Inherits from Declared in

IOUSBDeviceInterface182
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 10.8.7 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, and some new functions that are available on OS X version 10.1.2 and later.

Tasks
Miscellaneous
USBDeviceReEnumerate

(page 477) Tells the IOUSBFamily to reenumerate the device.

Instance Methods
USBDeviceReEnumerate
Tells the IOUSBFamily to reenumerate the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

477

IOUSBDeviceInterface187 Instance Methods

IOReturn ( USBDeviceReEnumerate)( void self, UInt32 options);

Parameters
self

Pointer to the IOUSBDeviceInterface.

options

A UInt32 reserved for future use. Ignored in current implementation. Set to zero. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the device is not open for exclusive access. Discussion This function will send a terminate message to all clients of the IOUSBDevice (such as IOUSBInterfaces and their drivers, as well as the current User Client), emulating an unplug of the device. The IOUSBFamily will then enumerate the device as if it had just been plugged in. This call should be used by clients wishing to take advantage of the Device Firmware Update Class specification. The device must be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

478

IOUSBDeviceInterface197

Inherits from Declared in

IOUSBDeviceInterface187
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 1.9.7 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, IOUSBDeviceInterface187, and some new functions that are available on OS X version 10.2.3 and later.

Tasks
Miscellaneous
GetBusMicroFrameNumber

(page 479) Gets the current micro frame number of the bus to which the device is attached. (page 480) Returns the version of the IOUSBLib and the version of the IOUSBFamily.

GetIOUSBLibVersion

Instance Methods
GetBusMicroFrameNumber
Gets the current micro frame number of the bus to which the device is attached.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

479

IOUSBDeviceInterface197 Instance Methods

IOReturn ( GetBusMicroFrameNumber)( void self, UInt64 microFrame, AbsoluteTime atTime);

Parameters
self

Pointer to the IOUSBDeviceInterface.

microFrame

Pointer to UInt64 to hold the microframe number.

atTime

Pointer to an AbsoluteTime, which should be within 1ms of the time when the bus frame number was acquired. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device does not have to be open to use this function.

GetIOUSBLibVersion
Returns the version of the IOUSBLib and the version of the IOUSBFamily.
IOReturn ( *GetIOUSBLibVersion)( void *self, NumVersion *ioUSBLibVersion, NumVersion *usbFamilyVersion);

Parameters
self

Pointer to the IOUSBDeviceInterface.

ioUSBLibVersion

Pointer to a NumVersion structure that on return will contain the version of the IOUSBLib.
usbFamilyVersion

Pointer to a NumVersion structure that on return will contain the version of the IOUSBFamily. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

480

IOUSBDeviceInterface197 Instance Methods

Discussion The device does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

481

IOUSBDeviceInterface245

Inherits from Declared in

IOUSBDeviceInterface197
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 2.4.5 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, IOUSBDeviceInterface187, IOUSBDeviceInterface197, and some new functions that are available on OS X version 10.2.3 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

482

IOUSBDeviceInterface300

Inherits from Declared in

IOUSBDeviceInterface245
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 3.0.0 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, IOUSBDeviceInterface187, IOUSBDeviceInterface197, IOUSBDeviceInterface245, and some new functions that are available on OS X version 10.5 and later.

Tasks
Miscellaneous
GetBusFrameNumberWithTime

(page 483) Gets a recent frame number of the bus to which the device is attached, along with a system time corresponding to the start of that frame

Instance Methods
GetBusFrameNumberWithTime
Gets a recent frame number of the bus to which the device is attached, along with a system time corresponding to the start of that frame

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

483

IOUSBDeviceInterface300 Instance Methods

IOReturn ( GetBusFrameNumberWithTime)( void self, UInt64 frame, AbsoluteTime atTime);

Parameters
self

Pointer to the IOUSBDeviceInterface.

frame

Pointer to UInt64 to hold the frame number.

atTime

Pointer to a returned AbsoluteTime, which is the system time ("wall time") as close as possible to the beginning of that USB frame. The jitter on this value may be as much as 200 microseconds. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnUnsupported is the bus doesn't support this function. Discussion The device does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

484

IOUSBDeviceInterface320

Inherits from Declared in

IOUSBDeviceInterface300
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 3.2.0 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, IOUSBDeviceInterface187, IOUSBDeviceInterface197, IOUSBDeviceInterface245, or IOUSBDeviceInterface300 and some new functions that are available on OS X version 10.5.4 and later.

Tasks
Miscellaneous
GetExtraPowerAllocated

(page 486) Clients can use this API to ask how much extra power has already been reserved by this device. Units are milliAmps (mA). (page 486) Returns status information about the USB device, such as whether the device is captive or whether it is in the suspended state. (page 487) Clients can use this API to reserve extra power for use by this device while the machine is asleep or while it is awake. Units are milliAmps (mA). (page 488) Clients can use this API to tell the system that they will not use power that was previously reserved by using the RequestExtraPower API.

GetUSBDeviceInformation

RequestExtraPower

ReturnExtraPower

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

485

IOUSBDeviceInterface320 Instance Methods

Instance Methods
GetExtraPowerAllocated
Clients can use this API to ask how much extra power has already been reserved by this device. Units are milliAmps (mA).
IOReturn ( *GetExtraPowerAllocated)( void *self, UInt32 type, UInt32 *powerAllocated);

Parameters
self

Pointer to the IOUSBDeviceInterface.

type

Indicates whether the allocated power was to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)
powerAllocated

Amount of power to be returned, in mA. Return Value Value returned can be 0 if no power has been allocated. Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device has to be open to use this function.

GetUSBDeviceInformation
Returns status information about the USB device, such as whether the device is captive or whether it is in the suspended state.
IOReturn ( *GetUSBDeviceInformation)( void *self, UInt32 *info);

Parameters
self

Pointer to the IOUSBDeviceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

486

IOUSBDeviceInterface320 Instance Methods

info

Pointer to a buffer that returns a bit field of information on the device (see the USBDeviceInformationBits in USB.h). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnUnsupported is the bus doesn't support this function. Discussion The device does not have to be open to use this function.

RequestExtraPower
Clients can use this API to reserve extra power for use by this device while the machine is asleep or while it is awake. Units are milliAmps (mA).
IOReturn ( *RequestExtraPower)( void *self, UInt32 type, UInt32 requestedPower, UInt32 *powerAvailable);

Parameters
self

Pointer to the IOUSBDeviceInterface.

type

Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)
requestedPower

Amount of power desired, in mA

powerAvailable

Amount of power that was reserved, in mA Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnUnsupported is the bus doesn't support this function. Discussion The device has to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

487

IOUSBDeviceInterface320 Instance Methods

ReturnExtraPower
Clients can use this API to tell the system that they will not use power that was previously reserved by using the RequestExtraPower API.
IOReturn ( *ReturnExtraPower)( void *self, UInt32 type, UInt32 powerReturned);

Parameters
self

Pointer to the IOUSBDeviceInterface.

type

Indicates whether the power is to be used during wake or sleep (One of kUSBPowerDuringSleep or kUSBPowerDuringWake)
powerReturned

Amount of power to be returned, in mA. Return Value If the returnedPower was not previously allocated, an error will be returned. This will include the case for power that was requested for sleep but was returned for wake. Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The device has to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

488

IOUSBDeviceInterface500

Inherits from Declared in

IOUSBDeviceInterface320
IOUSBLib.h (page 1142)

Overview
The object you use to access USB devices from user space, returned by the IOUSBFamily version 3.2.0 and above. The functions listed here include all of the functions defined for the IOUSBDeviceInterface, IOUSBDeviceInterface182, IOUSBDeviceInterface187, IOUSBDeviceInterface197, IOUSBDeviceInterface245, IOUSBDeviceInterface300, or IOUSBDeviceInterface320 and some new functions that are available on OS X version 10.7.3 and later.

Tasks
Miscellaneous
GetBandwidthAvailableForDevice

(page 489) Returns the amount of bandwidth available on the bus for allocation to periodic pipes. If the device is a high or super speed device, it will be the number of bytes per microframe (125 secs). If it is a full speed device, it will be the number of bytes per frame (1ms)

Instance Methods
GetBandwidthAvailableForDevice
Returns the amount of bandwidth available on the bus for allocation to periodic pipes. If the device is a high or super speed device, it will be the number of bytes per microframe (125 secs). If it is a full speed device, it will be the number of bytes per frame (1ms)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

489

IOUSBDeviceInterface500 Instance Methods

IOReturn ( GetBandwidthAvailableForDevice)( void self, UInt32 *bandwidth);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

bandwidth

Pointer to UInt32 to hold the amount of bandwidth available (in bytes per frame or microframe). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion This function is useful for determining the correct AltInterface setting as well as for using SetPipePolicy. The interface does not have to be open to use this function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

490

IOUSBInterfaceInterface

Declared in

IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by all versions of the IOUSBFamily currently shipping. The functions listed here will work with any version of the IOUSBInterfaceInterface, including the one shipped with OS X version 10.0.

Tasks
Miscellaneous
AbortPipe

(page 493) Aborts any outstanding transactions on the pipe with status kIOReturnAborted. (page 494) Clears the halted bit and the data toggle bit on the pipe's endpoint in the controller. (page 494) Sends a USB request on a control pipe. (page 495) Sends an asynchronous USB request on a control pipe. (page 496) Creates a run loop source for delivery of all asynchronous notifications on this device. (page 497) Creates and registers a mach_port_t for asynchronous communications. (page 497) Returns the alternate setting currently selected in this interface.

ClearPipeStall

ControlRequest

ControlRequestAsync

CreateInterfaceAsyncEventSource

CreateInterfaceAsyncPort

GetAlternateSetting

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

491

IOUSBInterfaceInterface Tasks

GetBusFrameNumber

(page 497) Gets the current frame number of the bus to which the interface and its device are attached. (page 498) Returns the current configuration value set in the device (the interface will be part of that configuration.) (page 499) Returns the device of which this interface is part. (page 499) Returns the USB Product ID (idProduct) of the device of which this interface is a part. (page 500) Returns the Device Release Number (bcdDevice) of the device of which this interface is a part. (page 500) Returns the USB Vendor ID (idVendor) of the device of which this interface is a part. (page 501) Returns the CFRunLoopSourceRef for this IOService instance. (page 501) Returns the mach_port_t port for this IOService instance. (page 501) Returns the USB Class of the interface (bInterfaceClass). (page 502) Returns the interface number (zero-based index) of this interface within the current configuration of the device. (page 502) Returns the USB Protocol of the interface (bInterfaceProtocol). (page 503) Returns the USB Subclass of the interface (bInterfaceSubClass). (page 503) Returns the location ID. (page 504) Returns the number of endpoints in this interface. (page 504) Gets the properties for a pipe. (page 505) Gets the current status of a pipe.

GetConfigurationValue

GetDevice

GetDeviceProduct

GetDeviceReleaseNumber

GetDeviceVendor

GetInterfaceAsyncEventSource

GetInterfaceAsyncPort

GetInterfaceClass

GetInterfaceNumber

GetInterfaceProtocol

GetInterfaceSubClass

GetLocationID

GetNumEndpoints

GetPipeProperties

GetPipeStatus

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

492

IOUSBInterfaceInterface Instance Methods

ReadIsochPipeAsync

(page 506) Performs a read on an ISOCHRONOUS pipe. (page 507) Reads data on a BULK IN or an INTERRUPT pipe. (page 508) Performs an asynchronous read on a BULK IN or an INTERRUPT pipe. (page 509) Equivalent to ClearPipeStall. (page 509) Changes the AltInterface setting. (page 510) Closes the task's connection to the IOUSBInterface. (page 510) Opensthe IOUSBInterface for exclusive access. (page 511) Performs an asynchronous write on an ISOCHRONOUS pipe. (page 512) Writes data on a BULK OUT or INTERRUPT OUT pipe. (page 512) Performs an asynchronous write on a BULK OUT or INTERRUPT OUT pipe.

ReadPipe

ReadPipeAsync

ResetPipe

SetAlternateInterface

USBInterfaceClose

USBInterfaceOpen

WriteIsochPipeAsync

WritePipe

WritePipeAsync

Instance Methods
AbortPipe
Aborts any outstanding transactions on the pipe with status kIOReturnAborted.
IOReturn ( *AbortPipe)( void *self, UInt8 pipeRef);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

493

IOUSBInterfaceInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion If there are outstanding asynchronous transactions on the pipe, the callbacks will happen. Note that this command will also clear the halted bit on the endpoint in the controller, but will NOT clear the data toggle bit. If you want to clear the data toggle bit as well, see ClearPipeStall or ClearPipeStallBothEnds for more information. The interface must be open for the pipe to exist.

ClearPipeStall
Clears the halted bit and the data toggle bit on the pipe's endpoint in the controller.
IOReturn ( *ClearPipeStall)( void *self, UInt8 pipeRef);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion This function also returns any outstanding transactions on the pipe with status kIOUSBTransactionReturned. If there are outstanding asynchronous transactions on the pipe, the callbacks will happen. The data toggle may need to be resynchronized. The driver may handle this by sending a ClearFeature(ENDPOINT_HALT) to the default control pipe, specifying the device's endpoint for this pipe. See also ClearPipeStallBothEnds.

ControlRequest
Sends a USB request on a control pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

494

IOUSBInterfaceInterface Instance Methods

IOReturn ( ControlRequest)( void self, UInt8 pipeRef, IOUSBDevRequest *req);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index of the control pipe to use. Use zero for the default control pipe on the device.
req

Pointer to an IOUSBDevRequest containing the request. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

ControlRequestAsync
Sends an asynchronous USB request on a control pipe.
IOReturn ( *ControlRequestAsync)( void *self, UInt8 pipeRef, IOUSBDevRequest *req, IOAsyncCallback1 callback, void *refCon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index of the control pipe to use. Use zero for the default control pipe on the device.
req

Pointer to an IOUSBDevRequest containing the request.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

495

IOUSBInterfaceInterface Instance Methods

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refCon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNotOpen if the interface is not open for exclusive access, or kIOUSBNoAsyncPortErr if no Async port has been created for this interface. Discussion Use pipeRef=0 for the default device control pipe. If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

CreateInterfaceAsyncEventSource
Creates a run loop source for delivery of all asynchronous notifications on this device.
IOReturn ( *CreateInterfaceAsyncEventSource)( void *self, CFRunLoopSourceRef *source);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

source

Pointer to a CFRunLoopSourceRef to return the newly created run loop event source. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if failed. Discussion The OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on a Mach port (see CreateInterfaceAsyncPort). This routine wraps that port with the appropriate routing code so that the completion notifications can be automatically routed through the client's CFRunLoop.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

496

IOUSBInterfaceInterface Instance Methods

CreateInterfaceAsyncPort
Creates and registers a mach_port_t for asynchronous communications.
IOReturn ( *CreateInterfaceAsyncPort)( void *self, mach_port_t *port);

Parameters
self

Pointer to the IOUSBInterfaceInterface. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if failed. Discussion The OS X kernel does not spawn a thread to callback to the client. Instead it delivers completion notifications on this Mach port. After receiving a message on this port the client is obliged to call the IOKitLib.h: IODispatchCalloutFromMessage() function for decoding the notification message.

GetAlternateSetting
Returns the alternate setting currently selected in this interface.
IOReturn ( *GetAlternateSetting)( void *self, UInt8 *intfAltSetting);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

intfAltSetting

Pointer to UInt8 to hold the alternate setting value. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetBusFrameNumber
Gets the current frame number of the bus to which the interface and its device are attached.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

497

IOUSBInterfaceInterface Instance Methods

IOReturn ( GetBusFrameNumber)( void self, UInt64 frame, AbsoluteTime atTime);

Parameters
self

GetInterfaceAsyncEventSource
Returns the CFRunLoopSourceRef for this IOService instance.
CFRunLoopSourceRef ( *GetInterfaceAsyncEventSource)( void *self);

Parameters
self

Pointer to the IOUSBInterfaceInterface. Return Value Returns the run loop source if one has been created, 0 otherwise. Discussion (description)

GetInterfaceAsyncPort
Returns the mach_port_t port for this IOService instance.
mach_port_t ( *GetInterfaceAsyncPort)( void *self);

Parameters
self

Pointer to the IOUSBInterfaceInterface. Return Value Returns the port if one exists, 0 otherwise.

GetInterfaceClass
Returns the USB Class of the interface (bInterfaceClass).
IOReturn ( *GetInterfaceClass)( void *self, UInt8 *intfClass);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

501

IOUSBInterfaceInterface Instance Methods

intfClass

Pointer to UInt8 to hold the interface Class. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetInterfaceNumber
Returns the interface number (zero-based index) of this interface within the current configuration of the device.
IOReturn ( *GetInterfaceNumber)( void *self, UInt8 *intfNumber);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

intfNumber

Pointer to UInt8 to hold the interface number. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetInterfaceProtocol
Returns the USB Protocol of the interface (bInterfaceProtocol).
IOReturn ( *GetInterfaceProtocol)( void *self, UInt8 *intfProtocol);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

502

IOUSBInterfaceInterface Instance Methods

intfProtocol

Pointer to UInt8 to hold the interface Protocol. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetInterfaceSubClass
Returns the USB Subclass of the interface (bInterfaceSubClass).
IOReturn ( *GetInterfaceSubClass)( void *self, UInt8 *intfSubClass);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

intfSubClass

Pointer to UInt8 to hold the interface Subclass. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetLocationID
Returns the location ID.
IOReturn ( *GetLocationID)( void *self, UInt32 *locationID);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

locationID

Pointer to UInt32 to hold the location ID.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

503

IOUSBInterfaceInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The location ID is a 32 bit number which is unique among all USB devices in the system, and which will not change on a system reboot unless the topology of the bus itself changes. The interface does not have to be open to use this function.

GetNumEndpoints
Returns the number of endpoints in this interface.
IOReturn ( *GetNumEndpoints)( void *self, UInt8 *intfNumEndpoints);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

intfNumEndpoints

Pointer to UInt8 to hold the number of endpoints. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

GetPipeProperties
Gets the properties for a pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

504

IOUSBInterfaceInterface Instance Methods

IOReturn ( *GetPipeProperties)( void *self, UInt8 pipeRef, UInt8 *direction, UInt8 *number, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

direction

Pointer to an UInt8 to get the direction of the pipe.

number

Pointer to an UInt8 to get the pipe number.

transferType

Pointer to an UInt8 to get the transfer type of the pipe.

maxPacketSize

Pointer to an UInt16 to get the maxPacketSize of the pipe.

interval

Pointer to an UInt8 to get the interval for polling the pipe for data (in milliseconds). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion Once an interface is opened, all of the pipes in that interface get created by the kernel. The number of pipes can be retrieved by GetNumEndpoints. The client can then get the properties of any pipe using an index of 1 to GetNumEndpoints. Pipe 0 is the default control pipe in the device.

GetPipeStatus
Gets the current status of a pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

505

IOUSBInterfaceInterface Instance Methods

IOReturn ( GetPipeStatus)( void self, UInt8 pipeRef);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints). Return Value Returns kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Otherwise, the status of the pipe is returned. Returns kIOUSBPipeStalled if the pipe is stalled. See ClearPipeStall or ClearPipeStallBothEnds for more information. Discussion The interface must be open for the pipe to exist.

ReadIsochPipeAsync
Performs a read on an ISOCHRONOUS pipe.
IOReturn ( *ReadIsochPipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

frameStart

The bus frame number on which to start the read (obtained from GetBusFrameNumber).

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

506

IOUSBInterfaceInterface Instance Methods

numFrames

The number of frames for which to transfer data.

frameList

A pointer to an array of IOUSBIsocFrame structures describing the frames.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

ReadPipe
Reads data on a BULK IN or an INTERRUPT pipe.
IOReturn ( *ReadPipe)( void *self, UInt8 pipeRef, void *buf, UInt32 *size);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

On entry: a pointer to the size of the buffer pointed to by buf. On exit: a pointer to the number of bytes actually read from the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

507

IOUSBInterfaceInterface Instance Methods

ReadPipeAsync
Performs an asynchronous read on a BULK IN or an INTERRUPT pipe.
IOReturn ( *ReadPipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the buffer pointed to by buf.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the interface is not open for exclusive access.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

508

IOUSBInterfaceInterface Instance Methods

Discussion The interface must be open for the pipe to exist.

ResetPipe
Equivalent to ClearPipeStall.
IOReturn ( *ResetPipe)( void *self, UInt8 pipeRef);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

SetAlternateInterface
Changes the AltInterface setting.
IOReturn ( *SetAlternateInterface)( void *self, UInt8 alternateSetting);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

alternateSetting

The new alternate setting for the interface. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

509

IOUSBInterfaceInterface Instance Methods

Discussion The interface must be open to use this function.

USBInterfaceClose
Closes the task's connection to the IOUSBInterface.
IOReturn ( *USBInterfaceClose)( void *self);

Parameters
self

Pointer to the IOUSBInterfaceInterface. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion Releases the client's exclusive access to the IOUSBInterface.

USBInterfaceOpen
Opensthe IOUSBInterface for exclusive access.
IOReturn ( *USBInterfaceOpen)( void *self);

Parameters
self

Pointer to the IOUSBInterfaceInterface. Return Value Returns kIOReturnExclusiveAccess if some other task has the device opened already, kIOReturnError if the connection with the kernel cannot be established or kIOReturnSuccess if successful. Discussion Before the client can transfer data to and from the interface, it must have succeeded in opening the interface. This establishes an exclusive link between the client's task and the actual interface device. Opening the interface causes pipes to be created on each endpoint contained in the interface. If the interface contains isochronous endpoints, an attempt is made to allocate bandwidth on the bus for each of those pipes. If there is not enough bandwidth available, an isochronous pipe may be created with a bandwidth of zero. The software must then call SetPipePolicy to change the size of that pipe before it can be used for I/O.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

510

IOUSBInterfaceInterface Instance Methods

WriteIsochPipeAsync
Performs an asynchronous write on an ISOCHRONOUS pipe.
IOReturn ( *WriteIsochPipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, IOUSBIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

frameStart

The bus frame number on which to start the write (obtained from GetBusFrameNumber).
numFrames

The number of frames for which to transfer data.

frameList

A pointer to an array of IOUSBIsocFrame structures describing the frames.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

511

IOUSBInterfaceInterface Instance Methods

WritePipe
Writes data on a BULK OUT or INTERRUPT OUT pipe.
IOReturn ( *WritePipe)( void *self, UInt8 pipeRef, void *buf, UInt32 size);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the data buffer. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion The interface must be open for the pipe to exist.

WritePipeAsync
Performs an asynchronous write on a BULK OUT or INTERRUPT OUT pipe.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

512

IOUSBInterfaceInterface Instance Methods

IOReturn ( *WritePipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt32 size, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the buffer pointed to by buf.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

513

IOUSBInterfaceInterface182

Inherits from Declared in

IOUSBInterfaceInterface
IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.8.2 and above. The functions listed here include all of the functions defined for the IOUSBInterfaceInterface and some new functions that are available on OS X version 10.0.4 and later.

Tasks
Miscellaneous
ControlRequestAsyncTO

(page 515) Sends an asynchronous USB request on a control pipe. (page 516) Sends a USB request on a control pipe. (page 516) Performs an asynchronous read on a BULK IN pipe, with specified timeout values. (page 518) Performs a read on a BULK IN pipe, specifying timeout values. (page 519) Returns the string index in the interface descriptor. (page 519) Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

ControlRequestTO

ReadPipeAsyncTO

ReadPipeTO

USBInterfaceGetStringIndex

WritePipeAsyncTO

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

514

IOUSBInterfaceInterface182 Instance Methods

WritePipeTO

(page 521) Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

Instance Methods
ControlRequestAsyncTO
Sends an asynchronous USB request on a control pipe.
IOReturn ( *ControlRequestAsyncTO)( void *self, UInt8 pipeRef, IOUSBDevRequestTO *req, IOAsyncCallback1 callback, void *refCon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index of the control pipe to use. Use zero for the default control pipe on the device.
req

Pointer to an IOUSBDevRequestTO containing the request.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refCon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. Use pipeRef=0 for the default device control pipe. If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

515

IOUSBInterfaceInterface182 Instance Methods

ControlRequestTO
Sends a USB request on a control pipe.
IOReturn ( *ControlRequestTO)( void *self, UInt8 pipeRef, IOUSBDevRequestTO *req);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index of the control pipe to use. Use zero for the default control pipe on the device.
req

Pointer to an IOUSBDevRequestTO containing the request. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnAborted if the thread is interrupted before the call completes, kIOReturnNotOpen if the interface is not open for exclusive access. Discussion The IOUSBDevRequestTO structure allows the client to specify timeout values for this request. If the request is a standard request which will change the state of the device, the device must be open, which means you should be using the IOUSBDeviceInterface for this command.

ReadPipeAsyncTO
Performs an asynchronous read on a BULK IN pipe, with specified timeout values.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

516

IOUSBInterfaceInterface182 Instance Methods

IOReturn ( *ReadPipeAsyncTO)( void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the buffer pointed to by buf.

noDataTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.
callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Returns kIOReturnBadArgument if timeout values are specified for an interrupt pipe. If an error is returned, the size parameter is not updated and the buffer will NOT contain any valid data. Discussion The interface must be open for the pipe to exist.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

517

IOUSBInterfaceInterface182 Instance Methods

If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds. Timeouts do not apply to interrupt pipes, so you should use the ReadPipeAsync API to perform an asynchronous read from an interrupt pipe.

ReadPipeTO
Performs a read on a BULK IN pipe, specifying timeout values.
IOReturn ( *ReadPipeTO)( void *self, UInt8 pipeRef, void *buf, UInt32 *size, UInt32 noDataTimeout, UInt32 completionTimeout);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

Pointer to the size of the buffer pointed to by buf.

noDataTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the interface is not open for exclusive access. Returns kIOReturnBadArgument if timeout values are specified for an interrupt pipe. If an error is returned, the size parameter is not updated and the buffer will NOT contain any valid data.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

518

IOUSBInterfaceInterface182 Instance Methods

Discussion The interface must be open for the pipe to exist. If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds. Timeouts do not apply to interrupt pipes, so you should use the ReadPipe API to perform a read from an interrupt pipe.

USBInterfaceGetStringIndex
Returns the string index in the interface descriptor.
IOReturn ( *USBInterfaceGetStringIndex)( void *self, UInt8 *si);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

Pointer to UInt8 to hold the string index. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion The interface does not have to be open to use this function.

WritePipeAsyncTO
Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

519

IOUSBInterfaceInterface182 Instance Methods

IOReturn ( *WritePipeAsyncTO)( void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the buffer pointed to by buf.

noDataTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned.
callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion The interface must be open for the pipe to exist. If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

520

IOUSBInterfaceInterface182 Instance Methods

WritePipeTO
Performs an asynchronous write on a BULK OUT pipe, with specified timeout values.
IOReturn ( *WritePipeTO)( void *self, UInt8 pipeRef, void *buf, UInt32 size, UInt32 noDataTimeout, UInt32 completionTimeout);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data.

size

The size of the buffer pointed to by buf.

noDataTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if no data is transferred in this amount of time, the request will be aborted and returned.
completionTimeout

Specifies a time value in milliseconds. Once the request is queued on the bus, if the entire request is not completed in this amount of time, the request will be aborted and returned. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnAborted if the thread is interrupted before the call completes, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion The interface must be open for the pipe to exist. If a timeout is specified and the request times out, the driver may need to resynchronize the data toggle. See ClearPipeStall or ClearPipeStallBothEnds.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

521

IOUSBInterfaceInterface183

Inherits from Declared in

IOUSBInterfaceInterface182
IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.8.3 and above. The functions listed here include all of the functions defined for the IOUSBInterfaceInterface, IOUSBInterfaceInterface182, and some new functions that are available on OS X version 10.1 and later.

Tasks
Miscellaneous
USBInterfaceOpenSeize

(page 522) Opens the IOUSBInterface for exclusive access.

Instance Methods
USBInterfaceOpenSeize
Opens the IOUSBInterface for exclusive access.
IOReturn ( *USBInterfaceOpenSeize)( void *self);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

522

IOUSBInterfaceInterface183 Instance Methods

Return Value Returns kIOReturnExclusiveAccess if some other task has the interface open already and refuses to close it, kIOReturnError if the connection with the kernel cannot be established or kIOReturnSuccess if successful. Discussion If another client has the device open, an attempt is made to get that client to close it before returning. Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes an exclusive link between the clients task and the actual device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

523

IOUSBInterfaceInterface190

Inherits from Declared in

IOUSBInterfaceInterface183
IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9 and above. The functions listed here include all of the functions defined for the IOUSBInterfaceInterface, IOUSBInterfaceInterface182, IOUSBInterfaceInterface183, and some new functions that are available on OS X version 10.2 and later.

Tasks
Miscellaneous
ClearPipeStallBothEnds

(page 525) Equivalent to ClearPipeStall. (page 525) Returns the amount of bandwidth available on the bus for allocation to isochronous pipes. If the device is a high speed device, it will be the number of bytes per microframe (125 secs). If it is a full speed device, it will be the number of bytes per frame (1ms) (page 526) Returns the transfer type, max packet size, and interval of a specified endpoint, whether or not the endpoint has a pipe currently established. (page 527) Changes the amount of bandwidth of an isochronous pipe or interrupt pipe, or the polling interval of an interrupt pipe.

GetBandwidthAvailable

GetEndpointProperties

SetPipePolicy

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

524

IOUSBInterfaceInterface190 Instance Methods

Instance Methods
ClearPipeStallBothEnds
Equivalent to ClearPipeStall.
IOReturn ( *ClearPipeStallBothEnds)( void *self, UInt8 pipeRef);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Discussion This function is equivalent to ClearPipeStall except that it also attempts to clear the halt and toggle bits on the device's endpoint for the pipe by sending a ClearFeature(ENDPOINT_HALT) to the default control pipe in the device, specifying the endpoint for the pipe represented by pipeRef. For most devices, this resynchronizes the data toggle between the two endpoints to ensure that there is no loss of data.

GetBandwidthAvailable
Returns the amount of bandwidth available on the bus for allocation to isochronous pipes. If the device is a high speed device, it will be the number of bytes per microframe (125 secs). If it is a full speed device, it will be the number of bytes per frame (1ms)
IOReturn ( *GetBandwidthAvailable)( void *self, UInt32 *bandwidth);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

bandwidth

Pointer to UInt32 to hold the amount of bandwidth available (in bytes per 1ms frame).

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

525

IOUSBInterfaceInterface190 Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. Discussion This function is useful for determining the correct AltInterface setting as well as for using SetPipePolicy. The interface does not have to be open to use this function.

GetEndpointProperties
Returns the transfer type, max packet size, and interval of a specified endpoint, whether or not the endpoint has a pipe currently established.
IOReturn ( *GetEndpointProperties)( void *self, UInt8 alternateSetting, UInt8 endpointNumber, UInt8 direction, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

alternateSetting

Specifies the alternate setting within the current interface.

endpointNumber

Specifies the desired endpoint number.

direction

Specifies the desired direction.

transferType

Pointer to UInt8 to hold the endpoint's transfer type (kUSBControl, kUSBIsoc, etc).
maxPacketSize

Pointer to UInt16 to hold the maxPacketSize of the endpoint.

interval

Pointer to UInt8 to hold the polling interval for interrupt endpoints. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

526

IOUSBInterfaceInterface190 Instance Methods

Discussion This function may be useful for determining which alternate interface to select when trying to balance bandwidth allocations among isochronous pipes. The interface does not have to be open to use this function.

SetPipePolicy
Changes the amount of bandwidth of an isochronous pipe or interrupt pipe, or the polling interval of an interrupt pipe.
IOReturn ( *SetPipePolicy)( void *self, UInt8 pipeRef, UInt16 maxPacketSize, UInt8 maxInterval);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

maxPacketSize

The desired size for the isochronous or interrupt pipe. Valid values are 0 through the maxPacketSize defined in the endpoint descriptor.
maxInterval

the desired polling interval in milliseconds, up to a maximum of 128 ms. The system can only poll devices powers of 2 (1, 2, 4, 8, 16, 32, 64, or 128 ms). A value of 0 is illegal. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. May also return kIOReturnNoBandwidth if there is not enough bandwidth available on the bus, or kIOReturnBadArgument if the desired maxPacketSize is outside of the allowed range. Discussion A pipe may be made smaller or larger (up to the maxPacketSize specified in the endpoint descriptor). When an interface is first opened, all pipes are created with their descriptor-supplied maxPacketSize. For isochronous or interrupt pipes, if there is not enough bandwidth on the bus to allocate to the pipe, the pipe is created with a reserved bandwidth of zero. Any attempts to transfer data on a pipe with zero bandwidth will result in a kIOReturnNoBandwidth error. The pipe must first be given some bandwidth using this call. This can also be

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

527

IOUSBInterfaceInterface190 Instance Methods

used to return bandwidth for an isochronous or an interrupt pipe. If the driver knows that the device will not be sending the maxPacketSize data, it can use this call to return that unused bandwidth to the system. If an interrupt pipe wants to change the polling interval, it can do so with this call. The interface must be open for the pipe to exist.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

528

IOUSBInterfaceInterface192

Inherits from Declared in

IOUSBInterfaceInterface190
IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9.2 and above. The functions listed here include all of the functions defined for the IOUSBInterfaceInterface, IOUSBInterfaceInterface182, IOUSBInterfaceInterface183, IOUSBInterfaceInterface190, and some new functions that are available on OS X version 10.2.3 and later.

Tasks
Miscellaneous
LowLatencyCreateBuffer

(page 530) Allocates a buffer of type bufferType. (page 531) Releases a buffer that was previously allocated using LowLatencyCreateBuffer(). (page 531) Performs an asynchronous read on a isochronous pipe and updates the frame list at primary interrupt time. (page 534) Performs an asynchronous write on an isochronous pipe and updates the frame list at primary interrupt time.

LowLatencyDestroyBuffer

LowLatencyReadIsochPipeAsync

LowLatencyWriteIsochPipeAsync

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

529

IOUSBInterfaceInterface192 Instance Methods

Instance Methods
LowLatencyCreateBuffer
Allocates a buffer of type bufferType.
IOReturn ( *LowLatencyCreateBuffer)( void *self, void **buffer, IOByteCount size, UInt32 bufferType);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

buffer

Pointer to a pointer that will receive the pointer to the buffer created by this call.
size

The size of the buffer to be created in bytes.

bufferType

Type of buffer: one of kUSBLowLatencyWriteBuffer, kUSBLowLatencyReadBuffer, or kUSBLowLatencyFrameListBuffer. See the documentation for USB.h. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. If the buffer can't be allocated, it will return kIOReturnNoMemory. Discussion This function allocates a buffer of type bufferType. The buffer can then be used with the LowLatencyIsochReadPipeAsync() or LowLatencyIsochWritePipeAsync() calls. The LowLatencyIsochReadPipeAsync() or LowLatencyIsochWritePipeAsync() calls require the clients to pre-allocate the data buffer and the frame list buffer parameters. This call is used to allocate those buffers. After the client is done using the buffers, they need to be released through the LowLatencyDestroyBuffer() call. If the buffer is to be used for reading data, the type passed in should be kUSBLowLatencyReadBuffer. If the buffer is to be used for writing data, the type should be kUSBLowLatencyWriteBuffer. For frame list data, the type should be kUSBLowLatencyFrameListBuffer.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

530

IOUSBInterfaceInterface192 Instance Methods

The client can create multiple data and frame list buffers, or it can allocate a large buffer and then use only a portion of the buffer in calls to LowLatencyReadIsochPipeAsync() or LowLatencyWriteIsochPipeAsync(). The interface must be open for the pipe to exist.

LowLatencyDestroyBuffer
Releases a buffer that was previously allocated using LowLatencyCreateBuffer().
IOReturn ( *LowLatencyDestroyBuffer) ( void *self, void *buffer );

Parameters
self

Pointer to the IOUSBInterfaceInterface.

buffer

Pointer to the buffer previously allocated using LowLatencyCreateBuffer(). Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. If the buffer was not previously allocated using LowLatencyCreateBuffer() it will return kIOReturnBadArgument. Discussion The interface must be open for the pipe to exist.

LowLatencyReadIsochPipeAsync
Performs an asynchronous read on a isochronous pipe and updates the frame list at primary interrupt time.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

531

IOUSBInterfaceInterface192 Instance Methods

IOReturn ( *LowLatencyReadIsochPipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency, IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data, previously allocated with LowLatencyCreateBuffer() using a kUSBLowLatencyReadBuffer type.
frameStart

The bus frame number on which to start the read (obtained from GetBusFrameNumber).
numFrames

The number of frames for which to transfer data.

updateFrequency

Specifies how often, in milliseconds, the frame list data should be updated. Valid range is 0 - 8. If 0, it means that the framelist should be updated at the end of the transfer.
frameList

A pointer to an array of IOUSBLowLatencyIsocFrame structures describing the frames.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

Arbitrary pointer which is passed as a parameter to the callback routine. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Will return kIOUSBLowLatencyBufferNotPreviouslyAllocated or kIOUSBLowLatencyFrameListNotPreviouslyAllocated if the buffer or the frameList were not previously allocated using LowLatencyCreateBuffer().

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

532

IOUSBInterfaceInterface192 Instance Methods

Discussion The LowLatencyReadIsochPipeAsync() and LowLatencyWriteIsochPipeAsync() calls are analogous to ReadIsochPipeAsync() and WriteIsochPipeAsync(). They differ in that the frame list data is updated at primary interrupt time . This means that the client can inspect the frStatus and frActCount fields as soon as the transaction completes, without having to wait for the callback to happen (depending on the value of updateFrequency). The callback will still happen when all the frames have been received. The client can specify how often the USB stack should update the frame list data by specifying the updateFrequency: this value can range from 0 - 8. If the value is between 1 and 8, the frame list will be updated every updateFrequency milliseconds. If the value is 0, the frame list will only be updated once all the frames in the transfer have been received. For example, consider a transfer with numFrames equal to 64. If the update frequency is 4, the frame list data will be updated every 4 milliseconds. If the update frequency is 0, the frame list will only be updated at the end of the transfer, after the 64 frames have been sent or received. The difference between using an update frequency of 0 and using the non-low latency isoch calls is that in the former case, the frame list will be updated at primary interrupt time, while in the latter, it will be updated at secondary interrupt time. Regardless of the value of updateFrequency, the frame list will always be updated on the last frame of a transfer. The rationale for adding this call is that because completion routines run on the USB Workloop, they can be scheduled to run a number of milliseconds after the USB transfer has finished. This latency is variable and depends on what other higher priority threads are running on the system. This latency presents a problem for applications, such as audio processing, that depend on receiving data, processing it, and sending it back out, and need to do this as fast as possible. Since applications that use isochronous data know when the data should be available, they can look at the frame list at the expected time and note the frActCount and frStatus (and frTimeStamp if needed) and determine how many valid bytes are in their data buffer and whether there was an error. They can then access their data buffer and process the actual data. In order to update the frame list at primary interrupt time and to allow the client to see that update, the frame list buffer needs to be shared between the kernel and user space. The same thing applies to the data buffer. This is a difference between the low latency isoch calls and the regular isoch calls. The LowLatencyCreateBuffer() call is used to pre-allocate the buffers. The client must use that call to allocate the data and the frame list buffers. The client can pass a portion of the buffer that was previously allocated. The USB stack will range-check the data and frame list buffers to make sure they are within the ranges of the buffers previously allocated. This allows the client, if it so desires, to allocate a large data buffer and pass portions of it to the read or write calls. The same applies to the frame list buffers. Of course, the client can also pre-allocate several data buffers and several frame list buffers and use those for each transfer. Once the transfer completes, the buffers can be reused in subsequent calls. When all transfers are finished, the client needs to call LowLatencyDestroyBuffer() for each buffer that was created with LowLatencyCreateBuffer(). The interface must be open for the pipe to exist. The buf pointer and the frameList pointer need to be pre-allocated using LowLatencyCreateBuffer(). After using them, they should be freed using LowLatencyDestroyBuffer().

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

533

IOUSBInterfaceInterface192 Instance Methods

LowLatencyWriteIsochPipeAsync
Performs an asynchronous write on an isochronous pipe and updates the frame list at primary interrupt time.
IOReturn ( *LowLatencyWriteIsochPipeAsync)( void *self, UInt8 pipeRef, void *buf, UInt64 frameStart, UInt32 numFrames, UInt32 updateFrequency, IOUSBLowLatencyIsocFrame *frameList, IOAsyncCallback1 callback, void *refcon);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

buf

Buffer to hold the data, previously allocated with LowLatencyCreateBuffer() using a kUSBLowLatencyWriteBuffer type.
frameStart

The bus frame number on which to start the write (obtained from GetBusFrameNumber).
numFrames

The number of frames for which to transfer data.

updateFrequency

Specifies how often, in milliseconds, should the frame list data be updated. Valid range is 0 - 8. If 0, it means that the framelist should be updated at the end of the transfer.
frameList

A pointer to an array of IOUSBLowLatencyIsocFrame structures describing the frames.

callback

An IOAsyncCallback1 method. A message addressed to this callback is posted to the Async port upon completion.
refcon

Arbitrary pointer which is passed as a parameter to the callback routine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

534

IOUSBInterfaceInterface192 Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access. Will return kIOUSBLowLatencyBufferNotPreviouslyAllocated or kIOUSBLowLatencyFrameListNotPreviouslyAllocated if the buffer or the frameList were not previously allocated using LowLatencyCreateBuffer(). Discussion The LowLatencyReadIsochPipeAsync() and LowLatencyWriteIsochPipeAsync() calls are analogous to ReadIsochPipeAsync() and WriteIsochPipeAsync(). They differ in that the frame list data is updated at primary interrupt time . This means that the client can inspect the frStatus and frActCount fields as soon as the transaction completes, without having to wait for the callback to happen (depending on the value of updateFrequency). The callback will still happen when the all the frames have been received. The client can specify how often the USB stack should update the frame list data by specifying the updateFrequency: this value can range from 0 - 8. If the value is between 1 and 8, the frame list will be updated every updateFrequency milliseconds. If the value is 0, the frame list will only be updated once all the frames in the transfer have been received. For example, consider a transfer with numFrames equal to 64. If the update frequency is 4, the frame list data will be updated every 4 milliseconds. If the update frequency is 0, the frame list will only be updated at the end of the transfer, after the 64 frames have been sent or received. The difference between using an update frequency of 0 and using the non-low latency isoch calls is that in the former case, the frame list will be updated at primary interrupt time, while in the latter, it will be updated at secondary interrupt time. Regardless of the value of updateFrequency, the frame list will always be updated on the last frame of a transfer. The rationale for adding this call is that because completion routines run on the USB Workloop, they can be scheduled to run a number of milliseconds after the USB transfer has finished. This latency is variable and depends on what other higher priority threads are running on the system. This latency presents a problem for applications, such as audio processing, that depend on receiving data, processing it, and sending it back out, and need to do this as fast as possible. Since applications that use isochronous data know when the data should be available, they can look at the frame list at the expected time and note the frActCount and frStatus (and frTimeStamp if needed) and determine how many valid bytes are in their data buffer and whether there was an error. They can then access their data buffer and process the actual data. In order to update the frame list at primary interrupt time and to allow the client to see that update, the frame list buffer needs to be shared between the kernel and user space. The same thing applies to the data buffer. This is a difference between the low latency isoch calls and the regular isoch calls. The LowLatencyCreateBuffer() call is used to pre-allocate the buffers. The client must use that call to allocate the data and the frame list buffers. The client can pass a portion of the buffer that was previously allocated. The USB stack will range-check the data and frame list buffers to make sure they are within the ranges of the buffers previously allocated. This allows the client, if it so desires, to allocate a large data buffer and pass portions of it to the read or write calls. The same applies to the frame list buffers. Of course, the client can also pre-allocate several data buffers and

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

535

IOUSBInterfaceInterface192 Instance Methods

several frame list buffers and use those for each transfer. Once the transfer completes, the buffers can be reused in subsequent calls. When all transfers are finished, the client needs to call LowLatencyDestroyBuffer() for each buffer that was created with LowLatencyCreateBuffer(). The interface must be open for the pipe to exist. The buf pointer and the frameList pointer need to be pre-allocated using LowLatencyCreateBuffer(). After using them, they should be freed using LowLatencyDestroyBuffer().

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

536

IOUSBInterfaceInterface197

Inherits from Declared in

IOUSBInterfaceInterface192
IOUSBLib.h (page 1142)

Overview
The object you use to access a USB device interface from user space, returned by the IOUSBFamily version 1.9.7 and above. The functions listed here include all of the functions defined for the IOUSBInterfaceInterface, IOUSBInterfaceInterface182, IOUSBInterfaceInterface183, IOUSBInterfaceInterface190, IOUSBInterfaceInterface192, and some new functions that are available on OS X version 10.2.5 and later.

Tasks
Miscellaneous
GetBusMicroFrameNumber

(page 537) Gets the current micro frame number of the bus to which the interface and its device are attached. (page 538) Returns the number of microseconds in each USB Frame. (page 539) Returns the version of the IOUSBLib and the version of the IOUSBFamily.

GetFrameListTime

GetIOUSBLibVersion

Instance Methods
GetBusMicroFrameNumber
Gets the current micro frame number of the bus to which the interface and its device are attached.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

537

IOUSBInterfaceInterface197 Instance Methods

IOReturn ( GetBusMicroFrameNumber)( void self, UInt64 microFrame, AbsoluteTime atTime);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

microFrame

Pointer to UInt64 to hold the microrame number.

atTime

GetFrameListTime
Returns the number of microseconds in each USB Frame.
IOReturn ( *GetFrameListTime)( void *self, UInt32 *microsecondsInFrame);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

microsecondsInFrame

Pointer to UInt32 to hold the number of microseconds in each USB frame. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

538

IOUSBInterfaceInterface197 Instance Methods

Discussion This function can be used to determine whether the device is functioning in full speed or a high speed. In the case of a full speed device, the returned value will be kUSBFullSpeedMicrosecondsInFrame. In the case of a high speed device, the return value will be kUSBHighSpeedMicrosecondsInFrame. (This API should really be called GetUSBFrameTime). The interface does not have to be open to use this function.

GetIOUSBLibVersion
Returns the version of the IOUSBLib and the version of the IOUSBFamily.
IOReturn ( *GetIOUSBLibVersion)( void *self, NumVersion *ioUSBLibVersion, NumVersion *usbFamilyVersion);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

ioUSBLibVersion

Pointer to a NumVersion structure that on return will contain the version of the IOUSBLib.
usbFamilyVersion

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

539

MMCDeviceInterface

Declared in

SCSITaskLib.h (page 1311)

Overview
Basic interface for an MMC-2 Compliant Device. After rendezvous with a MMC-2 Compliant Device in the IORegistry you can create an instance of this interface as a proxy to the IOService. Once you have this interface, or one of its subclasses, you can issue some select MMC-2 calls to the device without getting exclusive access first.

Tasks
Miscellaneous
GetConfiguration

(page 541) Issues a GET_CONFIGURATION command to the device as defined in MMC-2. (page 542) Issues a GET_PERFORMANCE command to the device as defined in MMC-2. (page 544) Issues a GET_PERFORMANCE command to the device as defined in Mt. Fuji 5. (page 545) Gets a handle to the SCSITaskDeviceInterface without closing the user client connection which was initiated by IOCreateCFPlugInForService. (page 545) Issues a GET_EVENT_STATUS_NOTIFICATION command to the device as defined in MMC-2. (page 546) Issues an INQUIRY command to the device as defined in SPC-2. (page 547) Issues a MODE_SENSE_10 command to the device as defined in SPC-2.

GetPerformance

GetPerformanceV2

GetSCSITaskDeviceInterface

GetTrayState

Inquiry

ModeSense10

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

540

MMCDeviceInterface Instance Methods

ReadDiscInformation

(page 548) Issues a READ_DISC_INFORMATION command to the device as defined in MMC-2. (page 549) Issues a READ_DISC_INFORMATION command to the device as defined in MMC-5. (page 550) Issues a READ_DISC_STRUCTURE command to the device as defined in MMC-5. (page 551) Issues a READ_DVD_STRUCTURE command to the device as defined in MMC-2. (page 552) Issues a READ_FORMAT_CAPACITIES command to the device as defined in MMC-2. (page 553) Issues a READ_TOC_PMA_ATIP command to the device as defined in MMC-2/SFF-8020i. (page 554) Issues a READ_TRACK_INFORMATION command to the device as defined in MMC-2. (page 555) Issues a READ_TRACK_INFORMATION command to the device as defined in Mt. Fuji 5. (page 556) Issues a SET_CD_SPEED command to the device as defined in MMC-2. (page 557) Issues a SET_STREAMING command to the device as defined in MMC-5. (page 558) Issues a START_STOP_UNIT command to the device as defined in SBC-3. (page 559) Issues a MODE_SELECT command to the device as defined in SPC-2 with the Write Parameters Mode Page Code as defined in MMC-2. (page 559) Issues a TEST_UNIT_READY command to the device as defined in SPC-2.

ReadDiscInformationV2

ReadDiscStructure

ReadDVDStructure

ReadFormatCapacities

ReadTableOfContents

ReadTrackInformation

ReadTrackInformationV2

SetCDSpeed

SetStreaming

SetTrayState

SetWriteParametersModePage

TestUnitReady

Instance Methods
GetConfiguration
Issues a GET_CONFIGURATION command to the device as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

541

MMCDeviceInterface Instance Methods

IOReturn ( *GetConfiguration )( void *self, SCSICmdField1Byte RT, SCSICmdField2Byte STARTING_FEATURE_NUMBER, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

The RT field as described for the GET_CONFIGURATION command in MMC-2.

STARTING_FEATURE_NUMBER

The STARTING_FEATURE_NUMBER field as described in MMC-2 for the GET_CONFIGURATION command.

buffer

Pointer to the buffer where the mode sense data should be placed.
bufferSize

Size of the buffer.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened, the client may send this command to get configuration information from the device.

GetPerformance
Issues a GET_PERFORMANCE command to the device as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

542

MMCDeviceInterface Instance Methods

IOReturn ( *GetPerformance )( void *self, SCSICmdField2Bit TOLERANCE, SCSICmdField1Bit WRITE, SCSICmdField2Bit EXCEPT, SCSICmdField4Byte STARTING_LBA, SCSICmdField2Byte MAXIMUM_NUMBER_OF_DESCRIPTORS, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

TOLERANCE

The TOLERANCE field as described for the GET_PERFORMANCE command in MMC-2.

WRITE

The WRITE bit as described in MMC-2 for the GET_PERFORMANCE command.

EXCEPT

The EXCEPT field as described in MMC-2 for the GET_PERFORMANCE command.

STARTING_LBA

The STARTING_LBA field as described in MMC-2 for the GET_PERFORMANCE command.

MAXIMUM_NUMBER_OF_DESCRIPTORS

The MAXIMUM_NUMBER_OF_DESCRIPTORS field as described in MMC-2 for the GET_PERFORMANCE command.

buffer

Pointer to the buffer where the mode sense data should be placed.
bufferSize

Size of the buffer.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

543

MMCDeviceInterface Instance Methods

Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened, the client may send this command to get performance information from the device.

GetPerformanceV2
Issues a GET_PERFORMANCE command to the device as defined in Mt. Fuji 5.
IOReturn ( *GetPerformanceV2 )( void *self, SCSICmdField5Bit DATA_TYPE, SCSICmdField4Byte STARTING_LBA, SCSICmdField2Byte MAXIMUM_NUMBER_OF_DESCRIPTORS, SCSICmdField1Byte TYPE, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

DATA_TYPE

The DATA_TYPE field as described for the GET_PERFORMANCE command in Mt. Fuji 5.
STARTING_LBA

The STARTING_LBA field as described in Mt. Fuji 5 for the GET_PERFORMANCE command.
MAXIMUM_NUMBER_OF_DESCRIPTORS

The MAXIMUM_NUMBER_OF_DESCRIPTORS field as described in Mt. Fuji 5 for the GET_PERFORMANCE command.
TYPE

The TYPE field as described for the GET_PERFORMANCE command in Mt. Fuji 5.
buffer

Pointer to the buffer where the mode sense data should be placed.
bufferSize

Size of the buffer.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

544

MMCDeviceInterface Instance Methods

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

GetSCSITaskDeviceInterface
Gets a handle to the SCSITaskDeviceInterface without closing the user client connection which was initiated by IOCreateCFPlugInForService.
SCSITaskDeviceInterface ** ( *GetSCSITaskDeviceInterface )( void *self );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService. Return Value Returns a handle to a SCSITaskDeviceInterface if successful, otherwise NULL. Discussion Once an MMCDeviceInterface is opened the client may use this function to get a handle to the interface used to create and send SCSITasks directly to the device.

GetTrayState
Issues a GET_EVENT_STATUS_NOTIFICATION command to the device as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

545

MMCDeviceInterface Instance Methods

IOReturn ( GetTrayState )( void self, UInt8 *trayState );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

trayState

Pointer to a UInt8 which will hold the tray state on completion of the routine. The tray state can be one of two values, kMMCDeviceTrayClosed or kMMCDeviceTrayOpen. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened, the client may send this command to find out if the device's medium tray is open.

Inquiry
Issues an INQUIRY command to the device as defined in SPC-2.
IOReturn ( *Inquiry )( void *self, SCSICmd_INQUIRY_StandardData *inquiryBuffer, UInt32 inqBufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

inquiryBuffer

A pointer to a buffer the size of the SCSICmd_INQUIRY_StandardData struct found in SCSICmds_INQUIRY_Definitions.h.

inqBufferSize

The amount of INQUIRY data to ask the device for (some devices return less INQUIRY data than the size of SCSICmd_INQUIRY_StandardData and will need to be reset if more than that amount is specified). This value must be less than the size of SCSICmd_INQUIRY_StandardData.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

546

MMCDeviceInterface Instance Methods

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

ModeSense10
Issues a MODE_SENSE_10 command to the device as defined in SPC-2.
IOReturn ( *ModeSense10 )( void *self, SCSICmdField1Bit LLBAA, SCSICmdField1Bit DBD, SCSICmdField2Bit PC, SCSICmdField6Bit PAGE_CODE, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

LLBAA

The LLBAA bit as defined in SPC-2 for the MODE_SENSE_10 command.

DBD

The DBD bit as defined in SPC-2 for the MODE_SENSE_10 command.

The PC bits as defined in SPC-2 for the MODE_SENSE_10 command.

PAGE_CODE

The PAGE_CODE bits as defined in SPC-2 for the MODE_SENSE_10 command.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

547

MMCDeviceInterface Instance Methods

buffer

Pointer to the buffer where the mode sense data should be placed.
bufferSize

Size of the buffer.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

ReadDiscInformation
Issues a READ_DISC_INFORMATION command to the device as defined in MMC-2.
IOReturn ( *ReadDiscInformation ) ( void *self, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

548

MMCDeviceInterface Instance Methods

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about the disc (CD-R/RW, (un)finalized, etc..

ReadDiscInformationV2
Issues a READ_DISC_INFORMATION command to the device as defined in MMC-5.
IOReturn ( *ReadDiscInformationV2 ) ( void *self, SCSICmdField3Bit DATA_TYPE, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

DATA_TYPE

The DATA_TYPE field as defined in MMC-5.

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

549

MMCDeviceInterface Instance Methods

senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about the disc (CD-R/RW, (un)finalized, etc..

ReadDiscStructure
Issues a READ_DISC_STRUCTURE command to the device as defined in MMC-5.
IOReturn ( *ReadDiscStructure ) ( void *self, SCSICmdField4Bit MEDIA_TYPE, SCSICmdField4Byte ADDRESS, SCSICmdField1Byte LAYER_NUMBER, SCSICmdField1Byte FORMAT, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

MEDIA_TYPE

The MEDIA_TYPE field as defined in MMC-5.

ADDRESS

The ADDRESS field as defined in MMC-5.

LAYER_NUMBER

The LAYER_NUMBER field as defined in MMC-5.

FORMAT

The FORMAT field as defined in MMC-5.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

550

MMCDeviceInterface Instance Methods

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about Disc specific structures on the disc.

ReadDVDStructure
Issues a READ_DVD_STRUCTURE command to the device as defined in MMC-2.
IOReturn ( *ReadDVDStructure ) ( void *self, SCSICmdField4Byte ADDRESS, SCSICmdField1Byte LAYER_NUMBER, SCSICmdField1Byte FORMAT, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

ADDRESS

The ADDRESS field as defined in MMC-2.

LAYER_NUMBER

The LAYER_NUMBER field as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

551

MMCDeviceInterface Instance Methods

FORMAT

The FORMAT field as defined in MMC-2.

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about DVD specific structures on the disc.

ReadFormatCapacities
Issues a READ_FORMAT_CAPACITIES command to the device as defined in MMC-2.
IOReturn ( *ReadFormatCapacities ) ( void *self, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

buffer

Pointer to the buffer where the mode sense data should be placed.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

552

MMCDeviceInterface Instance Methods

bufferSize

Size of the buffer.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to get format capacity information from the media.

ReadTableOfContents
Issues a READ_TOC_PMA_ATIP command to the device as defined in MMC-2/SFF-8020i.
IOReturn ( *ReadTableOfContents )( void *self, SCSICmdField1Bit MSF, SCSICmdField4Bit FORMAT, SCSICmdField1Byte TRACK_SESSION_NUMBER, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

MSF

The MSF bit as defined in MMC-2/SFF-8020i.

FORMAT

The FORMAT field as defined in MMC-2/SFF-8020i.

TRACK_SESSION_NUMBER

The TRACK_SESSION_NUMBER field as defined in MMC-2/SFF-8020i.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

553

MMCDeviceInterface Instance Methods

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read the table of contents from the media.

ReadTrackInformation
Issues a READ_TRACK_INFORMATION command to the device as defined in MMC-2.
IOReturn ( *ReadTrackInformation ) ( void *self, SCSICmdField2Bit ADDRESS_NUMBER_TYPE, SCSICmdField4Byte LOGICAL_BLOCK_ADDRESS_TRACK_SESSION_NUMBER, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

ADDRESS_NUMBER_TYPE

The ADDRESS/NUMBER_TYPE field as defined in MMC-2.

LOGICAL_BLOCK_ADDRESS_TRACK_SESSION_NUMBER

The LOGICAL_BLOCK_ADDRESS/SESSION_NUMBER field as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

554

MMCDeviceInterface Instance Methods

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about selected tracks on the disc.

ReadTrackInformationV2
Issues a READ_TRACK_INFORMATION command to the device as defined in Mt. Fuji 5.
IOReturn ( *ReadTrackInformationV2 ) ( void *self, SCSICmdField1Bit OPEN, SCSICmdField2Bit ADDRESS_NUMBER_TYPE, SCSICmdField4Byte LOGICAL_BLOCK_ADDRESS_TRACK_SESSION_NUMBER, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

OPEN

The OPEN field as defined in Mt. Fuji 5.

ADDRESS_NUMBER_TYPE

The ADDRESS/NUMBER_TYPE field as defined in Mt. Fuji 5.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

555

MMCDeviceInterface Instance Methods

LOGICAL_BLOCK_ADDRESS_TRACK_SESSION_NUMBER

The LOGICAL_BLOCK_ADDRESS/SESSION_NUMBER field as defined in Mt. Fuji 5.

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to read information about selected tracks on the disc.

SetCDSpeed
Issues a SET_CD_SPEED command to the device as defined in MMC-2.
IOReturn ( *SetCDSpeed ) ( void *self, SCSICmdField2Byte LOGICAL_UNIT_READ_SPEED, SCSICmdField2Byte LOGICAL_UNIT_WRITE_SPEED, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

LOGICAL_UNIT_READ_SPEED

The LOGICAL_UNIT_READ_SPEED field as defined in MMC-2.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

556

MMCDeviceInterface Instance Methods

LOGICAL_UNIT_WRITE_SPEED

The LOGICAL_UNIT_WRITE_SPEED field as defined in MMC-2.

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to change the read and/or write CD speed of the drive.

SetStreaming
Issues a SET_STREAMING command to the device as defined in MMC-5.
IOReturn ( *SetStreaming ) ( void *self, SCSICmdField1Byte TYPE, void *buffer, SCSICmdField2Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

TYPE

The TYPE field as defined in MMC-5.

buffer

Pointer to the buffer to be used for this function.

bufferSize

The size of the data transfer requested.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

557

MMCDeviceInterface Instance Methods

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data struct found in SCSICmds_REQUEST_SENSE_Defs.h. The sense data is only valid if the SCSITaskStatus is kSCSITaskStatus_CHECK_CONDITION. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNoMemory if a SCSITask couldn't be created, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened the client may send this command to change streaming attributes. Clients should check for the Real-time Streaming Feature (107h) before using this command.

SetTrayState
Issues a START_STOP_UNIT command to the device as defined in SBC-3.
IOReturn ( *SetTrayState )( void *self, UInt8 trayState );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

trayState

A UInt8 describing which tray state is desired. The tray state can be one of two values, kMMCDeviceTrayClosed or kMMCDeviceTrayOpen. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnNotPermitted if media is inserted, or kIOReturnExclusiveAccess if the device is already opened for exclusive access by another client. Discussion Once an MMCDeviceInterface is opened and all volumes associated with that device's media have been unmounted, the client may send this command to eject the tray.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

558

MMCDeviceInterface Instance Methods

SetWriteParametersModePage
Issues a MODE_SELECT command to the device as defined in SPC-2 with the Write Parameters Mode Page Code as defined in MMC-2.
IOReturn ( *SetWriteParametersModePage )( void *self, void *buffer, SCSICmdField1Byte bufferSize, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
buffer

Pointer to buffer (including mode parameter header).

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

TestUnitReady
Issues a TEST_UNIT_READY command to the device as defined in SPC-2.
IOReturn ( *TestUnitReady )( void *self, SCSITaskStatus *taskStatus, SCSI_Sense_Data *senseDataBuffer );

Parameters
self

Pointer to an MMCDeviceInterface for one IOService.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

559

MMCDeviceInterface Instance Variables

taskStatus

Pointer to a SCSITaskStatus to get the status of the SCSITask which was executed. Valid SCSITaskStatus values are defined in SCSITask.h
senseDataBuffer

Instance Variables
revision
UInt16 revision;

Interface revision

version
UInt16 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

560

SCSITaskDeviceInterface

Declared in

SCSITaskLib.h (page 1311)

Overview
Basic interface for a SCSITask Device. After rendezvous with a SCSITask Device in the IORegistry you can create an instance of this interface as a proxy to the IOService. Once you have this interface, or one of its subclasses, you can create SCSITasks to send to the device. Use the CreateSCSITask method to create new SCSITask instances for this device.

Tasks
Miscellaneous
AddCallbackDispatcherToRunLoop

(page 562) Convenience method to add asynchronous callback mechanisms to the CFRunLoop of choice. (page 562) Method to create SCSITasks. (page 563) Method to find out if the device can be opened exclusively by the caller. (page 563) Method to obtain exclusive access to the device so that SCSITasks can be sent to it. (page 564) Method to release exclusive access to the device so that other clients can send commands to it. (page 564) Convenience method to remove asynchronous callback mechanisms from the CFRunLoop.

CreateSCSITask

IsExclusiveAccessAvailable

ObtainExclusiveAccess

ReleaseExclusiveAccess

RemoveCallbackDispatcherFromRunLoop

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

561

SCSITaskDeviceInterface Instance Methods

Instance Methods
AddCallbackDispatcherToRunLoop
Convenience method to add asynchronous callback mechanisms to the CFRunLoop of choice.
IOReturn ( *AddCallbackDispatcherToRunLoop ) ( void *self, CFRunLoopRef cfRunLoopRef );

Parameters
self

Pointer to a SCSITaskDeviceInterface instance.

cfRunLoopRef

The CFRunLoop to which asynchronous callback notifications should be attached. Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNoMemory if a mach port could not be allocated and initialized properly. Discussion Once a SCSITaskDeviceInterface is opened, the client may make synchronous or asynchronous requests to the device. This method creates and initializes a mach_port_t for receiving asynchronous callback notifications via the CFRunLoop mechanism.

CreateSCSITask
Method to create SCSITasks.
SCSITaskInterface ** ( *CreateSCSITask )( void *self );

Parameters
self

Pointer to a SCSITaskDeviceInterface instance. Return Value Returns a handle to an instance of a SCSITaskInterface or NULL if one could not be allocated.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

562

SCSITaskDeviceInterface Instance Methods

Discussion Once a SCSITaskDeviceInterface is opened, the client may request exclusive access to the device. Once the client has successfully gained exclusive access, it becomes the Logical Unit Driver. It then can use this method to allocate SCSITasks to be sent to the device.

IsExclusiveAccessAvailable
Method to find out if the device can be opened exclusively by the caller.
Boolean ( *IsExclusiveAccessAvailable ) ( void *self );

Parameters
self

Pointer to an instance of an SCSITaskDeviceInterface. Return Value Returns false if the device has been opened for exclusive access, otherwise true. Discussion Method to find out if the device can be opened exclusively by the caller.

ObtainExclusiveAccess
Method to obtain exclusive access to the device so that SCSITasks can be sent to it.
IOReturn ( *ObtainExclusiveAccess ) ( void *self );

Parameters
self

Pointer to a SCSITaskDeviceInterface instance. Return Value Returns kIOReturnSuccess if exclusive access was granted, else if media is still mounted it returns kIOReturnBusy. If another client already has exclusive access, kIOReturnExclusiveAccess is returned. Discussion Once a SCSITaskDeviceInterface is opened, the client may request exclusive access to the device. Once the client has successfully gained exclusive access, it becomes the Logical Unit Driver and all in-kernel Logical Unit Drivers are quiesced.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

563

SCSITaskDeviceInterface Instance Methods

ReleaseExclusiveAccess
Method to release exclusive access to the device so that other clients can send commands to it.
IOReturn ( *ReleaseExclusiveAccess ) ( void *self );

Parameters
self

Pointer to a SCSITaskDeviceInterface instance. Return Value Returns kIOReturnSuccess if exclusive access was released, else some appropriate error. Discussion Once a SCSITaskDeviceInterface is opened, the client may request exclusive access to the device. Once the client has successfully gained exclusive access, it becomes the Logical Unit Driver and all in-kernel Logical Unit Drivers (if any are matched on the device) are quiesced. This method releases this access and unquiesces the in-kernel drivers (if any).

RemoveCallbackDispatcherFromRunLoop
Convenience method to remove asynchronous callback mechanisms from the CFRunLoop.
void ( *RemoveCallbackDispatcherFromRunLoop ) ( void *self );

Parameters
self

Pointer to a SCSITaskDeviceInterface instance. Discussion Once a SCSITaskDeviceInterface is opened, the client may make synchronous or asynchronous requests to the device. This method removes the asynchronous notifications delivered via the CFRunLoop. This should be called only after calling AddCallbackDispatcherToRunLoop.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

564

SCSITaskDeviceInterface Instance Variables

Instance Variables
revision
UInt16 revision;

Interface revision

version
UInt16 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

565

SCSITaskInterface

Declared in

SCSITaskLib.h (page 1311)

Overview
Basic interface for a SCSITask. After rendezvous with a SCSITask Device in the IORegistry you can create an instance of this interface using the CreateSCSITask method in the SCSITaskDeviceInterface. Once you have this interface, or one of its subclasses, you can manipulate SCSITasks to send to the device.

Tasks
Miscellaneous
AbortTask

(page 567) Method to abort the SCSITask. (page 568) Method to execute the SCSITask asynchronously. (page 568) Method to execute the SCSITask synchronously. (page 569) Method to get the auto-sense data from the SCSITask. (page 570) Method to get the task's SCSICommandDescriptorBlock. (page 570) Method to get the task's SCSICommandDescriptorBlock size. (page 571) Method to get the actual transfer count in bytes from the SCSITask.

ExecuteTaskAsync

ExecuteTaskSync

GetAutoSenseData

GetCommandDescriptorBlock

GetCommandDescriptorBlockSize

GetRealizedDataTransferCount

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

566

SCSITaskInterface Instance Methods

GetSCSIServiceResponse

(page 571) Method to get the SCSIServiceResponse from the SCSITask. (page 572) Method to get the task's attribute. (page 572) Method to get the SCSITaskState from the SCSITask. (page 573) Method to get the SCSITaskStatus from the SCSITask. (page 573) Method to get the timeout duration for the SCSITask. (page 573) Method to find out if the task is active or not. (page 574) Method to reset the SCSITask to defaults. (page 574) Method to set the auto-sense data for the SCSITask. (page 575) Method to set the task's SCSICommandDescriptorBlock. (page 576) Method to set the task's scatter-gather list entries. (page 576) Method to set the task's attribute. (page 577) Method to set the asynchronous completion routine for the SCSITask. (page 578) Method to set the timeout duration for the SCSITask.

GetTaskAttribute

GetTaskState

GetTaskStatus

GetTimeoutDuration

IsTaskActive

ResetForNewTask

SetAutoSenseDataBuffer

SetCommandDescriptorBlock

SetScatterGatherEntries

SetTaskAttribute

SetTaskCompletionCallback

SetTimeoutDuration

Instance Methods
AbortTask
Method to abort the SCSITask.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

567

SCSITaskInterface Instance Methods

IOReturn ( AbortTask ) ( void task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns kIOReturnSuccess, kIOReturnUnsupported or kIOReturnError. Discussion This method can be used to abort an SCSITask which is already in progress.

ExecuteTaskAsync
Method to execute the SCSITask asynchronously.
IOReturn ( *ExecuteTaskAsync ) ( void *task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns a valid IOReturn code such as kIOReturnSuccess, kIOReturnError, kIOReturnVMError, kIOReturnCannotWire, etc. It will return kIOReturnNotPermitted if the client has not called AddCallbackDispatcherToRunLoop on the SCSITaskDeviceInterface. NOTE: IOReturn is defined as kern_return_t and as such, you may get errors back that do not fall under the IOKit subsystem error domain (sys_iokit) defined in IOReturn.h. Discussion This method can be used to execute the SCSITask asynchronously.

ExecuteTaskSync
Method to execute the SCSITask synchronously.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

568

SCSITaskInterface Instance Methods

IOReturn ( *ExecuteTaskSync ) ( void *task, SCSI_Sense_Data *senseDataBuffer, SCSITaskStatus *outStatus, UInt64 *realizedTransferCount );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

senseDataBuffer

Pointer to a buffer for REQUEST_SENSE data. May be NULL if caller does not wish to have sense data returned. If caller has previously called SetAutoSenseDataBuffer(), this parameter is ignored.
outStatus

Pointer to an SCSITaskStatus. May be NULL if caller does not wish to have task status returned.
realizedTransferCount

Pointer to an UInt64 which reflects how much data was actually transferred. May be NULL if caller does not wish to know how many bytes were transferred. Return Value Returns a valid IOReturn code such as kIOReturnSuccess, kIOReturnError, kIOReturnVMError, kIOReturnCannotWire, etc. NOTE: IOReturn is defined as kern_return_t and as such, you may get errors back that do not fall under the IOKit subsystem error domain (sys_iokit) defined in IOReturn.h. Discussion This method can be used to execute the SCSITask synchronously.

GetAutoSenseData
Method to get the auto-sense data from the SCSITask.
IOReturn ( *GetAutoSenseData ) ( void *task, SCSI_Sense_Data *senseDataBuffer );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

senseDataBuffer

Pointer to a buffer the size of the SCSI_Sense_Data structure. If caller has previously called SetAutoSenseDataBuffer(), this routine will return an error.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

569

SCSITaskInterface Instance Methods

Return Value Returns kIOReturnSuccess if sense data is valid, otherwise kIOReturnError. Discussion This method can be used to get the auto-sense data from the SCSITask.

GetCommandDescriptorBlock
Method to get the task's SCSICommandDescriptorBlock.
IOReturn ( *GetCommandDescriptorBlock ) ( void *task, UInt8 *outCDB );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

outCDB

Pointer to an array the size of the SCSICommandDescriptorBlock in question. Clients should call GetCommandDescriptorBlockSize first to find out how large an array should be passed in. Return Value Returns kIOReturnSucces or kIOReturnError. Discussion This method can be used to get the SCSITasks' SCSICommandDescriptorBlock.

GetCommandDescriptorBlockSize
Method to get the task's SCSICommandDescriptorBlock size.
UInt8 ( *GetCommandDescriptorBlockSize ) ( void *task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value UInt8 which is the size of the SCSICommandDescriptorBlock. Valid values are 6, 10, 12, and 16 which have enums defined in SCSITask.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

570

SCSITaskInterface Instance Methods

Discussion This method can be used to get the size of the SCSITask's SCSICommandDescriptorBlock.

GetRealizedDataTransferCount
Method to get the actual transfer count in bytes from the SCSITask.
UInt64 ( *GetRealizedDataTransferCount ) ( void *task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns a UInt64 value of bytes transferred. Discussion This method can be used to get the actual transfer count in bytes from the SCSITask.

GetSCSIServiceResponse
Method to get the SCSIServiceResponse from the SCSITask.
IOReturn ( *GetSCSIServiceResponse ) ( void *task, SCSIServiceResponse *outServiceResponse );

outState

Pointer to an SCSITaskState. Return Value Returns kIOReturnSuccess or kIOReturnError. Discussion This method can be used to get the SCSITaskState from the SCSITask.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

572

SCSITaskInterface Instance Methods

GetTaskStatus
Method to get the SCSITaskStatus from the SCSITask.
IOReturn ( *GetTaskStatus ) ( void *task, SCSITaskStatus *outStatus );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

outStatus

Pointer to an SCSITaskStatus. Return Value Returns kIOReturnSuccess or kIOReturnError. Discussion This method can be used to get the SCSITaskStatus from the SCSITask.

GetTimeoutDuration
Method to get the timeout duration for the SCSITask.
UInt32 ( *GetTimeoutDuration ) ( void *task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns a value between zero and ULONG_MAX. Discussion This method can be used to get the timeout duration for the SCSITask. The timeout duration is counted in milliseconds.

IsTaskActive
Method to find out if the task is active or not.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

573

SCSITaskInterface Instance Methods

Boolean ( IsTaskActive ) ( void task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns 0 if the task is not active, non-zero if it is active. Discussion Method to find out if the task is active or not. The task is considered "active" if the SCSITaskState is not kSCSITaskState_NEW nor kSCSITaskState_ENDED.

ResetForNewTask
Method to reset the SCSITask to defaults.
IOReturn ( *ResetForNewTask ) ( void *task );

Parameters
task

Pointer to an instance of an SCSITaskInterface. Return Value Returns kIOReturnSuccess if reset was successful, otherwise kIOReturnError. Discussion This method can be used to reset the SCSITask to defaults.

SetAutoSenseDataBuffer
Method to set the auto-sense data for the SCSITask.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

574

SCSITaskInterface Instance Methods

IOReturn ( SetAutoSenseDataBuffer ) ( void task, SCSI_Sense_Data *senseDataBuffer, UInt8 senseDataLength );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

senseDataBuffer

Pointer to a buffer. May be be NULL if the caller wants to restrict the size to be less than the normal 18 bytes of sense data.
senseDataLength

Amount of sense data to retrieve. Zero is not a valid value. Return Value Returns kIOReturnSuccess if sense data buffer was set, otherwise kIOReturnError. Discussion This method can be used to set the auto-sense data buffer for the SCSITask.

SetCommandDescriptorBlock
Method to set the task's SCSICommandDescriptorBlock.
IOReturn ( *SetCommandDescriptorBlock ) ( void *task, UInt8 *inCDB, UInt8 inSize );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

inCDB

Pointer to an array of values to be stored in the SCSITask's SCSICommandDescriptorBlock.

inSize

The size of the array inCDB. Valid values are 6, 10, 12, and 16 which have enums defined in SCSITask.h. Return Value Returns kIOReturnSuccess or kIOReturnError. Discussion This method can be used to set the SCSITasks' SCSICommandDescriptorBlock.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

575

SCSITaskInterface Instance Methods

SetScatterGatherEntries
Method to set the task's scatter-gather list entries.
IOReturn ( *SetScatterGatherEntries ) ( void *task, SCSITaskSGElement *inScatterGatherList, UInt8 inScatterGatherEntries, UInt64 inTransferCount, UInt8 inTransferDirection );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

inScatterGatherList

Pointer to an array of SCSITaskSGElements.

inScatterGatherEntries

The size of the inScatterGatherList array.

inTransferCount

The TOTAL amount of data to transfer. The length of all the entries in the scatter-gather list should at least add up to the amount in inTransferCount.
inTransferDirection

The transfer direction as defined in SCSITask.h. Valid values are kSCSIDataTransfer_NoDataTransfer, kSCSIDataTransfer_FromTargetToInitiator, and kSCSIDataTransfer_FromInitiatorToTarget. Return Value Returns kIOReturnSucces or kIOReturnError. Discussion This method can be used to set the SCSITask's scatter-gather list entries. Scatter-gather lists are represented as an array of SCSITaskSGElements. The SCSITaskSGElement structure has two elements, the address of the buffer and the length of the buffer.

SetTaskAttribute
Method to set the task's attribute.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

576

SCSITaskInterface Instance Methods

IOReturn ( SetTaskAttribute ) ( void task, SCSITaskAttribute inAttribute );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

inAttribute

The new attribute value to be stored in the SCSITask. Return Value Returns kIOReturnSuccess or kIOReturnError. Discussion This method can be used to set the SCSITask's SCSITaskAttribute field. Valid values are defined in SCSITask.h

SetTaskCompletionCallback
Method to set the asynchronous completion routine for the SCSITask.
IOReturn ( *SetTaskCompletionCallback ) ( void *task, SCSITaskCallbackFunction callback, void *refCon );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

callback

SCSITaskCallbackFunction to be called upon completion of the SCSITask.

refCon

A value to be returned to the caller upon completion of the routine. This field is not used by the SCSITaskInterface. Return Value Returns kIOReturnSuccess, kIOReturnError, or kIOReturnNotPermitted if the client has not called AddCallbackDispatcherToRunLoop on the SCSITaskDeviceInterface. Discussion This method can be used to set the asynchronous completion routine for the SCSITask.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

577

SCSITaskInterface Instance Variables

SetTimeoutDuration
Method to set the timeout duration for the SCSITask.
IOReturn ( *SetTimeoutDuration ) ( void *task, UInt32 inTimeoutDurationMS );

Parameters
task

Pointer to an instance of an SCSITaskInterface.

inTimeoutDurationMS

UInt32 representing the timeout in milliseconds. Return Value Returns kIOReturnSucces or kIOReturnError. Discussion This method can be used to set the timeout duration for the SCSITask. The timeout duration is counted in milliseconds. A value of zero is equivalent to "Wait Forever", but on some buses, this isn't possible, so ULONG_MAX is used.

Instance Variables
revision
UInt16 revision;

Interface revision

version
UInt16 version;

Interface version

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

578

Other References

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

579

ATASMARTLib.h Reference

Declared in

ATASMARTLib.h

Overview
ATASMARTLib implements non-kernel task access to ATA SMART data.

Included Headers

<IOKit/IOReturn.h> <IOKit/IOTypes.h> <CoreFoundation/CFPlugIn.h> <CoreFoundation/CFPlugInCOM.h> <IOKit/IOCFPlugIn.h> <IOKit/storage/ata/IOATAStorageDefines.h>

Constants
See the Overview for header-level documentation.

Defines

#define kIOATASMARTInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x08, 0xAB, 0xE2, 0x1C, 0x20, 0xD4, 0x11,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

580

ATASMARTLib.h Reference Constants

0xD6, \ 0x8D, 0xF6, 0x00, 0x03, 0x93, 0x5A, 0x76, 0xB2) #define kIOATASMARTLibFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x5E, 0x65, 0x9F, 0x92, 0x20, 0xD3, 0x11, 0xD6, \ 0xBD, 0xB5, 0x00, 0x03, 0x93, 0x5A, 0x76, 0xB2) #define kIOATASMARTUserClientTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x24, 0x51, 0x4B, 0x7A, 0x28, 0x04, 0x11, 0xD6, \ 0x8A, 0x02, 0x00, 0x30, 0x65, 0x70, 0x48, 0x66) #define kIOPropertySMARTCapableKey "SMART Capable"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

581

ATASMARTLib.h Reference Constants

Constants
kIOATASMARTInterfaceID

InterfaceID for IOATASMARTInterface. Available in OS X v10.2 and later. Declared in ATASMARTLib.h.

kIOATASMARTLibFactoryID

UUID for the IOATASMARTInterface Factory. Available in OS X v10.2 and later. Declared in ATASMARTLib.h.
kIOATASMARTUserClientTypeID

Factory ID for creating an ATA SMART user client. Available in OS X v10.2 and later. Declared in ATASMARTLib.h.
kIOPropertySMARTCapableKey

Property to search for in IORegistry to find SMART capable devices without hardcoding the search to a particular device class. Available in OS X v10.4 and later. Declared in ATASMARTLib.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

582

IOAudioDefines.h User-Space Reference

Declared in

IOAudioDefines.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOAudioControlChannelIDKey "IOAudioControlChannelID" kIOAudioControlChannelNameAll "All Channels" kIOAudioControlChannelNameCenter "Center" kIOAudioControlChannelNameFrontLeftCenter "FrontLeftCenter" kIOAudioControlChannelNameFrontRightCenter "FrontRightCenter" kIOAudioControlChannelNameKey "IOAudioControlChannelName" kIOAudioControlChannelNameLeft "Left" kIOAudioControlChannelNameLeftRear "LeftRear" kIOAudioControlChannelNameRearCenter "RearCenter" kIOAudioControlChannelNameRight "Right" kIOAudioControlChannelNameRightRear "RightRear" kIOAudioControlChannelNameSub "Sub" kIOAudioControlChannelNameSurroundLeft "SurroundLeft" kIOAudioControlChannelNameSurroundRight "SurroundRight" kIOAudioControlTypeKey "IOAudioControlType" kIOAudioControlValueIsReadOnlyKey "IOAudioControlValueIsReadOnly" kIOAudioControlValueKey "IOAudioControlValue" kIOAudioDeviceIconNameKey "IOAudioDeviceIconName" kIOAudioDeviceIconNameKey "IOAudioDeviceIconName" kIOAudioDeviceManufacturerNameKey "IOAudioDeviceManufacturerName" kIOAudioDeviceNameKey "IOAudioDeviceName" kIOAudioEngineFullChannelCategoryNamesKey "IOAudioEngineChannelCategoryNames" kIOAudioEngineFullChannelNamesKey "IOAudioEngineChannelNames"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

583

IOAudioDefines.h User-Space Reference Constants

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOAudioEngineFullChannelCategoryNamesKey "IOAudioEngineChannelCategoryNames" kIOAudioEngineFullChannelNumberNamesKey "IOAudioEngineChannelNumberNames" kIOAudioEngineFullChannelNumberNamesKey "IOAudioEngineChannelNumberNames" kIOAudioEngineOutputSampleLatencyKey "IOAudioEngineOutputSampleLatency" kIOAudioEngineStateKey "IOAudioEngineState" kIOAudioLevelControlMaxDBKey "IOAudioLevelControlMaxDB" kIOAudioLevelControlMaxValueKey "IOAudioLevelControlMaxValue" kIOAudioLevelControlMinDBKey "IOAudioLevelControlMinDB" kIOAudioLevelControlMinValueKey "IOAudioLevelControlMinValue" kIOAudioPortNameKey "IOAudioPortName" kIOAudioPortSubTypeKey "IOAudioPortSubType" kIOAudioPortTypeKey "IOAudioPortType" kIOAudioSampleRateKey "IOAudioSampleRate" kIOAudioStreamDirectionKey "IOAudioStreamDirection" kIOAudioStreamSampleLatencyKey "IOAudioStreamSampleLatency"

Constants
kIOAudioControlChannelIDKey

The key in the IORegistry for the IOAudioControl channel ID attribute The value for this key is an integer which may be driver defined. Default values for common channel types are provided in the following defines. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameAll

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for all channels. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameCenter

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the center channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameFrontLeftCenter

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the FrontLeftCenter channel. Available in OS X v10.6 and later. Declared in IOAudioDefines.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

584

IOAudioDefines.h User-Space Reference Constants

kIOAudioControlChannelNameFrontRightCenter

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the FrontRightCenter channel. Available in OS X v10.6 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameKey

The key in the IORegistry for the IOAudioControl name attribute. This name should be a human-readable name for the channel(s) represented by the port. *** NOTE *** We really need to make all of the human-readable attributes that have potential to be used in a GUI localizable. There will need to be localized strings in the kext bundle matching the text. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameLeft

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the left channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameLeftRear

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the left rear channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameRearCenter

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the RearCenter channel. Available in OS X v10.6 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameRight

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the right channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameRightRear

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the right rear channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

585

IOAudioDefines.h User-Space Reference Constants

kIOAudioControlChannelNameSub

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the sub/LFE channel. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameSurroundLeft

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the SurroundLeft channel. Available in OS X v10.6 and later. Declared in IOAudioDefines.h.
kIOAudioControlChannelNameSurroundRight

The value for the kIOAudioControlChannelNameKey in the IORegistry representing the channel name for the SurroundRight channel. Available in OS X v10.6 and later. Declared in IOAudioDefines.h.
kIOAudioControlTypeKey

The key in the IORegistry for the IOAudioCntrol type attribute. The value of this text attribute may be defined by the driver, however system-defined types recognized by the upper-level software are "Level", "Mute", "Selector". Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioControlValueIsReadOnlyKey

The key in the IORegistry for the IOAudioControl value-is-read-only attribute. The value returned by this key is a 32-bit integer but the value doesn't have any direct meaning. Instead, the presence of this key indicates that the value for the control is read-only Available in OS X v10.2 and later. Declared in IOAudioDefines.h.
kIOAudioControlValueKey

The key in the IORegistry for the IOAudioControl value attribute. The value returned by this key is a 32-bit integer representing the current value of the IOAudioControl. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioDeviceIconName

The key in the IORegistry for the IOAudioDevice icon name attribute.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

586

IOAudioDefines.h User-Space Reference Constants

kIOAudioDeviceIconNameKey

The key in the IORegistry for the IOAudioDevice icon name attribute. Available in OS X v10.5 and later. Declared in IOAudioDefines.h.
kIOAudioDeviceManufacturerNameKey

The key in the IORegistry for the IOAudioDevice manufacturer name attribute. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioDeviceNameKey

The key in the IORegistry for the IOAudioDevice name attribute. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioEngineFullChannelCategoryNamesKey

The key in the IORegistry for the IOAudioEngine's dictionary of category names for each channel keyed by the device channel Available in OS X v10.2 and later. Declared in IOAudioDefines.h.
kIOAudioEngineFullChannelNamesKey

The key in the IORegistry for the IOAudioEngine's dictionary of fully constructed names for each channel keyed by the device channel Available in OS X v10.2 and later. Declared in IOAudioDefines.h.
kIOAudioEngineFullChannelNamesKey

The key in the IORegistry for the IOAudioEngine's dictionary of number names for each channel keyed by the device channel Available in OS X v10.2 and later. Declared in IOAudioDefines.h.
kIOAudioEngineFullChannelNumberNamesKey

The key in the IORegistry for the IOAudioEngine's dictionary of number names for each channel keyed by the device channel Available in OS X v10.2 and later. Declared in IOAudioDefines.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

587

IOAudioDefines.h User-Space Reference Constants

kIOAudioEngineOutputSampleLatencyKey

The key in the IORegistry for the IOAudioEngine output sample latency key Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioEngineStateKey

The key in the IORegistry for the IOAudioEngine state atrribute The value for this key may be one of: "Running", "Stopped" or "Paused". Currently the "Paused" state is unimplemented. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioLevelControlMaxDBKey

The key in the IORgistry for the IOAudioControl maximum db value attribute. The value returned by this key is a fixed point value in 16.16 format represented as a 32-bit integer. It represents the maximum value in db for the IOAudioControl. This value matches the maximum value attribute. This is currently valid for Level controls or other driver-defined controls that have a minimum and maximum db value. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioLevelControlMaxValueKey

The key in the IORegistry for the IOAudioControl maximum value attribute. The value returned by this key is a 32-bit integer representing the maximum value for the IOAudioControl. This is currently only valid for Level controls or other driver-defined controls that have a minimum and maximum value. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioLevelControlMinDBKey

The key in the IORgistry for the IOAudioControl minimum db value attribute. The value returned by this key is a fixed point value in 16.16 format represented as a 32-bit integer. It represents the minimum value in db for the IOAudioControl. This value matches the minimum value attribute. This is currently valid for Level controls or other driver-defined controls that have a minimum and maximum db value. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

588

IOAudioDefines.h User-Space Reference Constants

kIOAudioLevelControlMinValueKey

The key in the IORegistry for the IOAudioControl minimum value attribute. The value returned by this key is a 32-bit integer representing the minimum value for the IOAudioControl. This is currently only valid for Level controls or other driver-defined controls that have a minimum and maximum value. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioPortNameKey

The key in the IORegistry for the IOAudioPort name attribute. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioPortSubTypeKey

The key in the IORegistry for the IOAudioPort subtype attribute. The IOAudioPort subtype is a driver-defined text attribute designed to complement the type attribute. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioPortTypeKey

The key in the IORegistry for the IOAudioPort type attribute. This is a driver-defined text attribute that may contain any type. Common types are defined as: "Speaker", "Headphones", "Microphone", "CD", "Line", "Digital", "Mixer", "PassThru". Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioSampleRateKey

The key in the IORegistry for the IOAudioEngine sample rate attribute This value is represented as an integer in samples per second. Available in OS X v10.1 and later. Declared in IOAudioDefines.h.
kIOAudioStreamDirectionKey

The key in the IORegistry for the IOAudioStream direction attribute. The value for this key may be either "Output" or "Input". Available in OS X v10.1 and later. Declared in IOAudioDefines.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

589

IOAudioDefines.h User-Space Reference Constants

kIOAudioStreamSampleLatencyKey

The key in the IORegistry for the IOAudioStream output sample latency key Tells the HAL how much latency is on a particular stream. If two streams on the same engine have different latencies (e.g. one is analog, one is digital), then set this property on both streams to inform the HAL of the latency differences. Alternately, you can set the engine latency, and just include the latency additional to that for the particular stream. The HAL will add the engine and stream latency numbers together to get the total latency. Available in OS X v10.3 and later. Declared in IOAudioDefines.h. See Also
kIOAudioDeviceIconNameKey kIOAudioDeviceIconName kIOAudioEngineFullChannelNamesKey kIOAudioEngineFullChannelCategoryNamesKey kIOAudioEngineFullChannelNumberNamesKey kIOAudioEngineFullChannelNamesKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

590

IOAudioLib.h Reference

Declared in

IOAudioLib.h

Overview
C interface to IOAudio functions

Included Headers

Functions
See the Overview for header-level documentation.

IOAudioFlush
Indicate the position at which the audio stream can be stopped.

kern_return_t IOAudioFlush( io_connect_t connect, IOAudioStreamPosition *end);

Parameters
connect

the audio stream

end

the position Return Value kern_return_t

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

591

IOAudioLib.h Reference Functions

IOAudioIsOutput
Determines if the audio stream is an output stream

kern_return_t IOAudioIsOutput( io_service_t service, int *out);

Parameters
service out

Return Value kern_return_t

IOAudioSetErase
Set autoerase flag, returns old value

kern_return_t IOAudioSetErase( io_connect_t connect, int erase, int *oldVal);

Parameters
connect

the audio stream

erase

true to turn off, false otherwise

oldVal

previous value Return Value kern_return_t

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

592

IOAudioTypes.h User-Space Reference

Declared in

IOAudioTypes.h

Overview
Included Headers

<libkern/OSTypes.h> <mach/message.h> <device/device_types.h>

Data Types
See the Overview for header-level documentation.

IOAudioControlCalls
The set of constants passed to IOAudioControlUserClient::getExternalMethodForIndex() when making calls from the IOAudioFamily user client code.

typedef enum _IOAudioControlCalls { kIOAudioControlCallSetValue = 0, kIOAudioControlCallGetValue = 1 } IOAudioControlCalls;

Constants
kIOAudioControlCallSetValue

Used to set the value of an IOAudioControl. Available in OS X v10.1 and later. Declared in IOAudioTypes.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

593

IOAudioTypes.h User-Space Reference Data Types

kIOAudioControlCallGetValue

Used to get the value of an IOAudioControl. Available in OS X v10.1 and later. Declared in IOAudioTypes.h. Availability Available in OS X v10.1 and later. Declared in
IOAudioTypes.h

IOAudioControlNotifications
The set of constants passed in the type field of IOAudioControlUserClient::registerNotificaitonPort().

typedef enum _IOAudioControlNotifications { kIOAudioControlValueChangeNotification = 0, kIOAudioControlRangeChangeNotification = 1 } IOAudioControlNotifications;

Constants
kIOAudioControlValueChangeNotification

Used to request value change notifications. Available in OS X v10.1 and later. Declared in IOAudioTypes.h.
kIOAudioControlRangeChangeNotification

Used to request range change notifications. Available in OS X v10.2 and later. Declared in IOAudioTypes.h. Availability Available in OS X v10.1 and later. Declared in
IOAudioTypes.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

594

IOAudioTypes.h User-Space Reference Data Types

IOAudioEngineCalls
The set of constants passed to IOAudioEngineUserClient::getExternalMethodForIndex() when making calls from the IOAudioFamily user client code.

typedef enum _IOAudioEngineCalls { kIOAudioEngineCallRegisterClientBuffer = 0, kIOAudioEngineCallUnregisterClientBuffer = 1, kIOAudioEngineCallGetConnectionID = 2, kIOAudioEngineCallStart = 3, kIOAudioEngineCallStop = 4, kIOAudioEngineCallGetNearestStartTime = 5 } IOAudioEngineCalls;

Availability Available in OS X v10.1 and later. Declared in

IOAudioTypes.h

IOAudioEngineMemory
Used to identify the type of memory requested by a client process to be mapped into its process space

typedef enum _IOAudioEngineMemory { kIOAudioStatusBuffer = 0, kIOAudioSampleBuffer = 1, kIOAudioMixBuffer = 2, kIOAudioBytesInInputBuffer = 3, kIOAudioBytesInOutputBuffer = 4 } IOAudioEngineMemory;

Constants
kIOAudioSampleBuffer

This requests the IOAudioEngine's sample buffer Available in OS X v10.2 and later. Declared in IOAudioTypes.h.
kIOAudioStatusBuffer

This requests the IOAudioEngine's status buffer. It's type is IOAudioEngineStatus. Available in OS X v10.2 and later. Declared in IOAudioTypes.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

595

IOAudioTypes.h User-Space Reference Data Types

kIOAudioMixBuffer

This requests the IOAudioEngine's mix buffer Available in OS X v10.2 and later. Declared in IOAudioTypes.h. Discussion This is the parameter to the type field of IOMapMemory when called on an IOAudioEngine. This is only intended for use by the Audio Device API library. Availability Available in OS X v10.1 and later. Declared in
IOAudioTypes.h

IOAudioEngineState
Represents the state of an IOAudioEngine

typedef enum _IOAudioEngineState { kIOAudioEngineStopped = 0, kIOAudioEngineRunning = 1, kIOAudioEnginePaused = 2, kIOAudioEngineResumed = 3 } IOAudioEngineState;

Constants
kIOAudioEngineRunning

The IOAudioEngine is currently running - it is transferring data to or from the device. Available in OS X v10.1 and later. Declared in IOAudioTypes.h.
kIOAudioEngineStopped

The IOAudioEngine is currently stopped - no activity is occurring. Available in OS X v10.1 and later. Declared in IOAudioTypes.h. Availability Available in OS X v10.1 and later. Declared in
IOAudioTypes.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

596

IOAudioTypes.h User-Space Reference Data Types

IOAudioEngineStatus
Shared-memory structure giving audio engine status

typedef struct _IOAudioEngineStatus { UInt32 fVersion; volatile UInt32 fCurrentLoopCount; volatile AbsoluteTime fLastLoopTime; volatile UInt32 fEraseHeadSampleFrame; } IOAudioEngineStatus;

Availability Available in OS X v10.1 and later. Declared in

IOAudioTypes.h

IOAudioNotificationMessage
Used in the mach message for IOAudio notifications.

typedef struct _IOAudioNotificationMessage { mach_msg_header_t messageHeader; UInt32 type; UInt32 ref; void *sender; } IOAudioNotificationMessage;

Availability Available in OS X v10.1 and later. Declared in

IOAudioTypes.h

IOAudioSMPTETime
A structure for holding a SMPTE time.

typedef struct _IOAudioSMPTETime { SInt16 fSubframes; SInt16 fSubframeDivisor; UInt32 fCounter; UInt32 fType;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

597

IOAudioTypes.h User-Space Reference Data Types

UInt32 fFlags; SInt16 fHours; SInt16 fMinutes; SInt16 fSeconds; SInt16 fFrames; } IOAudioSMPTETime;

Availability Available in OS X v10.3 and later. See Also

SMPTETime

Declared in
IOAudioTypes.h

IOAudioStreamDirection
Represents the direction of an IOAudioStream

typedef enum _IOAudioStreamDirection { kIOAudioStreamDirectionOutput = 0, kIOAudioStreamDirectionInput = 1 } IOAudioStreamDirection;

Constants
kIOAudioStreamDirectionOutput

Output buffer Available in OS X v10.1 and later. Declared in IOAudioTypes.h.

kIOAudioStreamDirectionInput

Input buffer Available in OS X v10.1 and later. Declared in IOAudioTypes.h. Availability Available in OS X v10.1 and later. Declared in
IOAudioTypes.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

598

IOAudioTypes.h User-Space Reference Constants

SMPTETime
A structure for holding a SMPTE time.

typedef struct _IOAudioSMPTETime { SInt16 fSubframes; SInt16 fSubframeDivisor; UInt32 fCounter; UInt32 fType; UInt32 fFlags; SInt16 fHours; SInt16 fMinutes; SInt16 fSeconds; SInt16 fFrames; } IOAudioSMPTETime;

Availability Available in OS X v10.3 and later. See Also

IOAudioSMPTETime (page 599)

Declared in
IOAudioTypes.h

Constants
See the Overview for header-level documentation.

Defines

#define kIOAudioControlNumCalls 2 #define kIOAudioEngineDefaultMixBufferSampleSize sizeof(float) #define kIOAudioEngineNumCalls 6

Constants
kIOAudioControlNumCalls

The number of elements in the IOAudioControlCalls enum. Available in OS X v10.1 and later. Declared in IOAudioTypes.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

599

IOAudioTypes.h User-Space Reference Constants

kIOAudioEngineDefaultMixBufferSampleSize

Available in OS X v10.1 and later. Declared in IOAudioTypes.h.

kIOAudioEngineNumCalls

The number of elements in the IOAudioEngineCalls enum. Available in OS X v10.1 and later. Declared in IOAudioTypes.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

600

IOBDBlockStorageDevice.h User-Space Reference

Declared in

IOBDBlockStorageDevice.h

Overview
This header contains the IOBDBlockStorageDevice class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define kIOBDBlockStorageDeviceClass "IOBDBlockStorageDevice"

Constants
kIOBDBlockStorageDeviceClass

kIOBDBlockStorageDeviceClass is the name of the IOBDBlockStorageDevice class. kIOBDBlockStorageDeviceClass is the name of the IOBDBlockStorageDevice class. Available in OS X v10.5 and later. Declared in IOBDBlockStorageDevice.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

601

IOBDMedia.h User-Space Reference

Declared in

IOBDMedia.h

Overview
This header contains the IOBDMedia class definition.

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define

kIOBDMediaClass "IOBDMedia" kIOBDMediaTypeKey "Type" kIOBDMediaTypeR "BD-R" kIOBDMediaTypeRE "BD-RE" kIOBDMediaTypeROM "BD-ROM"

Constants
kIOBDMediaClass

kIOBDMediaClass is the name of the IOBDMedia class. kIOBDMediaClass is the name of the IOBDMedia class. Available in OS X v10.5 and later. Declared in IOBDMedia.h.
kIOBDMediaTypeKey

kIOBDMediaTypeKey is a property of IOBDMedia objects. It has an OSString value. The kIOBDMediaTypeKey property identifies the BD media type (BD-ROM, BD-R, BD-RE, etc). See the kIOBDMediaType contants for possible values. Available in OS X v10.5 and later. Declared in IOBDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

602

IOBDMedia.h User-Space Reference Constants

kIOBDMediaTypeR

The kIOBDMediaTypeKey constant for BD-R media. Available in OS X v10.5 and later. Declared in IOBDMedia.h.
kIOBDMediaTypeRE

The kIOBDMediaTypeKey constant for BD-RE media. Available in OS X v10.5 and later. Declared in IOBDMedia.h.
kIOBDMediaTypeROM

The kIOBDMediaTypeKey constant for BD-ROM media. Available in OS X v10.5 and later. Declared in IOBDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

603

IOBlockStorageDevice.h User-Space Reference

Declared in

IOBlockStorageDevice.h

Overview
This header contains the IOBlockStorageDevice class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define kIOBlockStorageDeviceClass "IOBlockStorageDevice" #define kIOBlockStorageDeviceWriteCacheStateKey "WriteCacheState"

Constants
kIOBlockStorageDeviceClass

The name of the IOBlockStorageDevice class. Available in OS X v10.2 and later. Declared in IOBlockStorageDevice.h.
kIOBlockStorageDeviceWriteCacheStateKey

The name of the property used to get or set the write cache state of the block storage device. Available in OS X v10.3 and later. Declared in IOBlockStorageDevice.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

604

IOBlockStorageDriver.h User-Space Reference

Declared in

IOBlockStorageDriver.h

Overview
This header contains the IOBlockStorageDriver class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOBlockStorageDriverClass "IOBlockStorageDriver" kIOBlockStorageDriverStatisticsBytesReadKey "Bytes (Read)" kIOBlockStorageDriverStatisticsBytesWrittenKey "Bytes (Write)" kIOBlockStorageDriverStatisticsKey "Statistics" kIOBlockStorageDriverStatisticsLatentReadTimeKey "Latency Time (Read)" kIOBlockStorageDriverStatisticsLatentWriteTimeKey "Latency Time (Write)" kIOBlockStorageDriverStatisticsReadErrorsKey "Errors (Read)" kIOBlockStorageDriverStatisticsReadRetriesKey "Retries (Read)" kIOBlockStorageDriverStatisticsReadsKey "Operations (Read)" kIOBlockStorageDriverStatisticsTotalReadTimeKey "Total Time (Read)" kIOBlockStorageDriverStatisticsTotalWriteTimeKey "Total Time (Write)" kIOBlockStorageDriverStatisticsWriteErrorsKey "Errors (Write)" kIOBlockStorageDriverStatisticsWriteRetriesKey "Retries (Write)" kIOBlockStorageDriverStatisticsWritesKey "Operations (Write)"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

605

IOBlockStorageDriver.h User-Space Reference Constants

Constants
kIOBlockStorageDriverClass

The name of the IOBlockStorageDriver class. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsBytesReadKey

Describes the number of bytes read since the block storage driver was instantiated. This property describes the number of bytes read since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsBytesWrittenKey

Describes the number of bytes written since the block storage driver was instantiated. This property describes the number of bytes written since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsKey

Holds a table of numeric values describing the driver's operating statistics. This property holds a table of numeric values describing the driver's operating statistics. The table is an OSDictionary, where each entry describes one given statistic. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsLatentReadTimeKey

Describes the number of nanoseconds of latency during reads since the block storage driver was instantiated. This property describes the number of nanoseconds of latency during reads since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

606

IOBlockStorageDriver.h User-Space Reference Constants

kIOBlockStorageDriverStatisticsLatentWriteTimeKey

Describes the number of nanoseconds of latency during writes since the block storage driver was instantiated. This property describes the number of nanoseconds of latency during writes since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsReadErrorsKey

Describes the number of read errors encountered since the block storage driver was instantiated. This property describes the number of read errors encountered since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsReadRetriesKey

Describes the number of read retries required since the block storage driver was instantiated. This property describes the number of read retries required since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsReadsKey

Describes the number of read operations processed since the block storage driver was instantiated. This property describes the number of read operations processed since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsTotalReadTimeKey

Describes the number of nanoseconds spent performing reads since the block storage driver was instantiated. This property describes the number of nanoseconds spent performing reads since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

607

IOBlockStorageDriver.h User-Space Reference Constants

kIOBlockStorageDriverStatisticsTotalWriteTimeKey

Describes the number of nanoseconds spent performing writes since the block storage driver was instantiated. This property describes the number of nanoseconds spent performing writes since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsWriteErrorsKey

Describes the number of write errors encountered since the block storage driver was instantiated. This property describes the number of write errors encountered since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsWriteRetriesKey

Describes the number of write retries required since the block storage driver was instantiated. This property describes the number of write retries required since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.
kIOBlockStorageDriverStatisticsWritesKey

Describes the number of write operations processed since the block storage driver was instantiated. This property describes the number of write operations processed since the block storage driver was instantiated. It is one of the statistic entries listed under the top-level kIOBlockStorageDriverStatisticsKey property table. It has an OSNumber value. Available in OS X v10.0 and later. Declared in IOBlockStorageDriver.h.

IOMediaState
The different states that getMediaState() can report.

enum { kIOMediaStateOffline = 0, kIOMediaStateOnline = 1,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

608

IOBlockStorageDriver.h User-Space Reference Constants

kIOMediaStateBusy = 2 };

Constants
kIOMediaStateOffline

Media is not available. Available in OS X v10.4 and later. Declared in IOBlockStorageDriver.h.

kIOMediaStateOnline

Media is available and ready for operations. Available in OS X v10.4 and later. Declared in IOBlockStorageDriver.h.
kIOMediaStateBusy

Media is available, but not ready for operations. Available in OS X v10.4 and later. Declared in IOBlockStorageDriver.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

609

IOCDBlockStorageDevice.h User-Space Reference

Declared in

IOCDBlockStorageDevice.h

Overview
This header contains the IOCDBlockStorageDevice class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define kIOCDBlockStorageDeviceClass "IOCDBlockStorageDevice"

Constants
kIOCDBlockStorageDeviceClass

kIOCDBlockStorageDeviceClass is the name of the IOCDBlockStorageDevice class. kIOCDBlockStorageDeviceClass is the name of the IOCDBlockStorageDevice class. Available in OS X v10.2 and later. Declared in IOCDBlockStorageDevice.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

610

IOCDMedia.h User-Space Reference

Declared in

IOCDMedia.h

Overview
This header contains the IOCDMedia class definition.

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define

kIOCDMediaClass "IOCDMedia" kIOCDMediaTOCKey "TOC" kIOCDMediaTypeKey "Type" kIOCDMediaTypeR "CD-R" kIOCDMediaTypeROM "CD-ROM" kIOCDMediaTypeRW "CD-RW"

Constants
kIOCDMediaClass

kIOCDMediaClass is the name of the IOCDMedia class. kIOCDMediaClass is the name of the IOCDMedia class. Available in OS X v10.0 and later. Declared in IOCDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

611

IOCDMedia.h User-Space Reference Constants

kIOCDMediaTOCKey

kIOCDMediaTOCKey is a property of IOCDMedia objects. It has an OSData value and a CDTOC structure. The kIOCDMediaTOCKey property contains the CD's full table of contents, formatted as a CDTOC structure. The CDTOC structure is same as what is returned by a READ TOC command, format 0x02. All fields in the TOC are guaranteed to be binary-encoded (no BCD-encoded numbers are ever passed). Available in OS X v10.0 and later. Declared in IOCDMedia.h.
kIOCDMediaTypeKey

kIOCDMediaTypeKey is a property of IOCDMedia objects. It has an OSString value. The kIOCDMediaTypeKey property identifies the CD media type (CD-ROM, CD-R, CD-RW, etc). See the kIOCDMediaType contants for possible values. Available in OS X v10.0 and later. Declared in IOCDMedia.h.
kIOCDMediaTypeR

The kIOCDMediaTypeKey constant for CD Recordable (CD-R) media. Available in OS X v10.0 and later. Declared in IOCDMedia.h.
kIOCDMediaTypeROM

The kIOCDMediaTypeKey constant for CD-ROM media (inclusive of the CD-I, CD-ROM XA, and CD Audio standards, and mixed mode combinations thereof ). Available in OS X v10.0 and later. Declared in IOCDMedia.h.
kIOCDMediaTypeRW

The kIOCDMediaTypeKey constant for CD ReWritable (CD-RW) media. Available in OS X v10.0 and later. Declared in IOCDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

612

IODVDBlockStorageDevice.h User-Space Reference

Declared in

IODVDBlockStorageDevice.h

Overview
This header contains the IODVDBlockStorageDevice class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define kIODVDBlockStorageDeviceClass "IODVDBlockStorageDevice"

Constants
kIODVDBlockStorageDeviceClass

kIODVDBlockStorageDeviceClass is the name of the IODVDBlockStorageDevice class. kIODVDBlockStorageDeviceClass is the name of the IODVDBlockStorageDevice class. Available in OS X v10.2 and later. Declared in IODVDBlockStorageDevice.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

613

IODVDMedia.h User-Space Reference

Declared in

IODVDMedia.h

Overview
This header contains the IODVDMedia class definition.

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define

kIODVDMediaClass "IODVDMedia" kIODVDMediaTypeHDR "HD DVD-R" kIODVDMediaTypeHDRAM "HD DVD-RAM" kIODVDMediaTypeHDROM "HD DVD-ROM" kIODVDMediaTypeHDRW "HD DVD-RW" kIODVDMediaTypeKey "Type" kIODVDMediaTypePlusR "DVD+R" kIODVDMediaTypePlusRW "DVD+RW" kIODVDMediaTypeR "DVD-R" kIODVDMediaTypeRAM "DVD-RAM" kIODVDMediaTypeROM "DVD-ROM" kIODVDMediaTypeRW "DVD-RW"

Constants
kIODVDMediaClass

kIODVDMediaClass is the name of the IODVDMedia class. kIODVDMediaClass is the name of the IODVDMedia class. Available in OS X v10.0 and later. Declared in IODVDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

614

IODVDMedia.h User-Space Reference Constants

kIODVDMediaTypeHDR

The kIODVDMediaTypeKey constant for HD DVD Recordable (HD DVD-R) media. Available in OS X v10.5 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeHDRAM

The kIODVDMediaTypeKey constant for HD DVD-RAM media. Available in OS X v10.5 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeHDROM

The kIODVDMediaTypeKey constant for HD DVD-ROM media. Available in OS X v10.5 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeHDRW

The kIODVDMediaTypeKey constant for HD DVD ReWritable (HD DVD-RW) media. Available in OS X v10.5 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeKey

kIODVDMediaTypeKey is a property of IODVDMedia objects. It has an OSString value. The kIODVDMediaTypeKey property identifies the DVD media type (DVD-ROM, DVD-R, DVD-RW, DVD+RW, DVD-RAM, etc). See the kIODVDMediaType contants for possible values. Available in OS X v10.0 and later. Declared in IODVDMedia.h.
kIODVDMediaTypePlusR

The kIODVDMediaTypeKey constant for DVD "Plus" Recordable (DVD+R) media. Available in OS X v10.3 and later. Declared in IODVDMedia.h.
kIODVDMediaTypePlusRW

The kIODVDMediaTypeKey constant for DVD "Plus" ReWritable (DVD+RW) media. Available in OS X v10.0 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeR

The kIODVDMediaTypeKey constant for DVD Recordable (DVD-R) media. Available in OS X v10.0 and later. Declared in IODVDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

615

IODVDMedia.h User-Space Reference Constants

kIODVDMediaTypeRAM

The kIODVDMediaTypeKey constant for DVD-RAM media. Available in OS X v10.0 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeROM

The kIODVDMediaTypeKey constant for DVD-ROM media. Available in OS X v10.0 and later. Declared in IODVDMedia.h.
kIODVDMediaTypeRW

The kIODVDMediaTypeKey constant for DVD ReWritable (DVD-RW) media. Available in OS X v10.0 and later. Declared in IODVDMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

616

IODataQueueClient.h Reference

Declared in

IODataQueueClient.h

Overview
Included Headers

<sys/cdefs.h> <AvailabilityMacros.h> <libkern/OSTypes.h> <mach/port.h> <IOKit/IOReturn.h> <IOKit/IODataQueueShared.h>

Functions
See the Overview for header-level documentation.

IODataQueueAllocateNotificationPort
Allocates and returns a new mach port able to receive data available notifications from an IODataQueue.

mach_port_t IODataQueueAllocateNotificationPort();

Return Value Returns a newly allocated mach port on success. On failure, it returns MACH_PORT_NULL.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

617

IODataQueueClient.h Reference Functions

Discussion This port is intended to be passed down into the kernel and into an IODataQueue to allow it to send the appropriate notification. The returned mach port is allocated with a queue limit of one message. This allows only one mach message to be queued up at a time. The IODataQueue code is written with the restriction in mind and will only queue up a message if no messages alread have been sent. Availability Available in OS X v10.0 and later. Declared in
IODataQueueClient.h

IODataQueueDataAvailable
Used to determine if more data is avilable on the queue.

Boolean IODataQueueDataAvailable( IODataQueueMemory *dataQueue);

Parameters
dataQueue

The IODataQueueMemory region mapped from the kenel. Return Value Returns true if data is available and false if not. Availability Available in OS X v10.0 and later. Declared in
IODataQueueClient.h

IODataQueueDequeue
Dequeues the next available entry on the queue and copies it into the given data pointer.

IOReturn IODataQueueDequeue( IODataQueueMemory dataQueue, void data, uint32_t *dataSize);

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

618

IODataQueueClient.h Reference Functions

Parameters
dataQueue

The IODataQueueMemory region mapped from the kernel.

data

A pointer to the data memory region in which to copy the next entry data on the queue. If this parameter is 0 (NULL), it will simply move to the next entry.
dataSize

A pointer to the size of the data parameter. On return, this contains the size of the actual entry data even if the original size was not large enough. Return Value Returns kIOReturnSuccess on success. Other return values possible are: kIOReturnUnderrun - queue is empty, kIOReturnBadArgument - no dataQueue or no dataSize, kIOReturnNoSpace - dataSize is too small for entry. Discussion This function will dequeue the next available entry on the queue. If a data pointer is provided, it will copy the data into the memory region if there is enough space available as specified in the dataSize parameter. If no data pointer is provided, it will simply move the head value past the current entry. Availability Available in OS X v10.0 and later. Declared in
IODataQueueClient.h

IODataQueueEnqueue
Enqueues a new entry on the queue.

IOReturn IODataQueueEnqueue( IODataQueueMemory dataQueue, void data, uint32_t dataSize)AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
dataQueue

The IODataQueueMemory region mapped from the kernel created from an IOSharedDataQueue.
data

Pointer to the data to be added to the queue.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

619

IODataQueueClient.h Reference Functions

dataSize

Size of the data pointed to by data. Return Value Returns kIOReturnSuccess on success. Other return values possible are: kIOReturnOverrun - queue is full. Discussion This method adds a new data entry of dataSize to the queue. It sets the size parameter of the entry pointed to by the tail value and copies the memory pointed to by the data parameter in place in the queue. Once that is done, it moves the tail to the next available location. When attempting to add a new entry towards the end of the queue and there isn't enough space at the end, it wraps back to the beginning. If the queue is empty when a new entry is added, the port specified in IODataQueueSetNotificationPort will be used to send a message to the client process that data is now available.
Please note that using this method without mapped memory create from an IOSharedDataQueue will result in undefined behavior.

Availability Available in OS X v10.5 and later. Declared in

IODataQueueClient.h

IODataQueuePeek
Used to peek at the next entry on the queue.

IODataQueueEntry IODataQueuePeek( IODataQueueMemory dataQueue);

Parameters
dataQueue

The IODataQueueMemory region mapped from the kernel. Return Value Returns a pointer to the next IODataQueueEntry if one is available. Zero is returned if the queue is empty. Discussion This function can be used to look at the next entry which allows the entry to be received without having to copy it with IODataQueueDequeue. In order to do this, call IODataQueuePeek to get the entry. Then call IODataQueueDequeue with a NULL data pointer. That will cause the head to be moved to the next entry, but no memory to be copied.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

620

IODataQueueClient.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IODataQueueClient.h

IODataQueueSetNotificationPort
Creates a simple mach message targeting the mach port specified in port.

IOReturn IODataQueueSetNotificationPort( IODataQueueMemory *dataQueue, mach_port_t notifyPort)AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
dataQueue

The IODataQueueMemory region mapped from the kernel created from an IOSharedDataQueue.
notifyPort

The mach port to target with the notification message. Return Value Returns kIOReturnSuccess on success. Returns kIOReturnBadArgument if either dataQueue is 0 (NULL). Discussion This message is sent when data is added to an empty queue. It is to notify another user process that new data has become available. Please note that using this method without mapped memory create from an IOSharedDataQueue will result
in undefined behavior.

Availability Available in OS X v10.5 and later. Declared in

IODataQueueClient.h

IODataQueueWaitForAvailableData
Wait for an incoming dataAvailable message on the given notifyPort.

IOReturn IODataQueueWaitForAvailableData( IODataQueueMemory *dataQueue, mach_port_t notificationPort);

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

621

IODataQueueClient.h Reference Functions

Parameters
dataQueue

The IODataQueueMemory region mapped from the kernel.

notifyPort

Mach port on which to listen for incoming messages. Return Value Returns kIOReturnSuccess on success. Returns kIOReturnBadArgument if either dataQueue is 0 (NULL) or notiryPort is MACH_PORT_NULL. Returns the result of the mach_msg() listen call on the given port. Discussion This method will simply wait for an incoming message on the given notifyPort. Once it is received, the return from mach_msg() is returned. Availability Available in OS X v10.0 and later. Declared in
IODataQueueClient.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

622

IODataQueueShared.h User-Space Reference

Declared in

IODataQueueShared.h

Overview
Included Headers

<libkern/OSTypes.h> <mach/port.h> <mach/message.h>

Data Types
See the Overview for header-level documentation.

IODataQueueAppendix
A struct mapping to the appendix region of a data queue.

typedef struct _IODataQueueAppendix { UInt32 version; mach_msg_header_t msgh; } IODataQueueAppendix;

Discussion This struct is variable sized dependent on the version. The struct represents the data queue appendix information. Availability Available in OS X v10.5 and later. Declared in
IODataQueueShared.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

623

IODataQueueShared.h User-Space Reference Data Types

IODataQueueEntry
Represents an entry within the data queue

typedef struct _IODataQueueEntry{ UInt32 size; UInt8 data[4]; } IODataQueueEntry;

Discussion This is a variable sized struct. The data field simply represents the start of the data region. The size of the data region is stored in the size field. The whole size of the specific entry is the size of a UInt32 plus the size of the data region. Availability Available in OS X v10.0 and later. Declared in
IOSharedDataQueue.h

IODataQueueMemory
A struct mapping to the header region of a data queue.

typedef struct _IODataQueueMemory { UInt32 queueSize; volatile UInt32 head; volatile UInt32 tail; IODataQueueEntry queue[1]; } IODataQueueMemory;

Discussion This struct is variable sized. The struct represents the data queue header information plus a pointer to the actual data queue itself. The size of the struct is the combined size of the header fields (3 * sizeof(UInt32)) plus the actual size of the queue region. This size is stored in the queueSize field. Availability Available in OS X v10.0 and later. Declared in
IODataQueue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

624

IODataQueueShared.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define DATA_QUEUE_ENTRY_HEADER_SIZE (sizeof(IODataQueueEntry) - 4) #define DATA_QUEUE_MEMORY_APPENDIX_SIZE (sizeof(IODataQueueAppendix)) #define DATA_QUEUE_MEMORY_HEADER_SIZE (sizeof(IODataQueueMemory) - sizeof(IODataQueueEntry))

Constants
DATA_QUEUE_ENTRY_HEADER_SIZE

Represents the size of the data queue entry header independent of the actual size of the data in the entry. This is the overhead of each entry in the queue. The total size of an entry is equal to this value plus the size stored in the entry's size field (in IODataQueueEntry). Available in OS X v10.0 and later. Declared in IODataQueueShared.h.
DATA_QUEUE_MEMORY_APPENDIX_SIZE

Represents the size of the data queue memory appendix independent of the actual size of the queue data itself. The total size of the queue memory is equal to this value plus the size of queue header and size of the queue data region which is stored in the queueSize field of IODataQueueMeory. Available in OS X v10.5 and later. Declared in IODataQueueShared.h.
DATA_QUEUE_MEMORY_HEADER_SIZE

Represents the size of the data queue memory header independent of the actual size of the queue data itself. The total size of the queue memory is equal to this value plus the size of the queue appendix and the size of the queue data region which is stored in the queueSize field of IODataQueueMeory. Available in OS X v10.0 and later. Declared in IODataQueueShared.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

625

IOEthernetController.h User-Space Reference

Declared in

IOEthernetController.h

Overview
Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define kIOEthernetAddressSize 6 #define kIOEthernetControllerClass "IOEthernetController" #define kIOEthernetCRCSize 4 #define kIOEthernetDisabledWakeOnLANFilterGroup \ "IOEthernetDisabledWakeOnLANFilterGroup" #define kIOEthernetMaxPacketSize 1518 #define kIOEthernetMinPacketSize 64 #define kIOEthernetWakeOnLANFilterGroup "IOEthernetWakeOnLANFilterGroup"

Constants
kIOEthernetAddressSize

The number of bytes in an Ethernet hardware address. Available in OS X v10.0 and later. Declared in IOEthernetController.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

626

IOEthernetController.h User-Space Reference Constants

kIOEthernetControllerClass

kIOEthernetControllerClass is the name of the IOEthernetController class. Available in OS X v10.0 and later. Declared in IOEthernetController.h.
kIOEthernetCRCSize

The size in bytes of the 32-bit CRC value appended to the end of each Ethernet frame. Available in OS X v10.0 and later. Declared in IOEthernetController.h.
kIOEthernetDisabledWakeOnLANFilterGroup

kIOEthernetDisabledWakeOnLANFilterGroup describes the name assigned to the disabled Ethernet Wake-On-LAN filter group. This group represents wake filters that are currently disabled. Membership in this group is dynamic. Available in OS X v10.6 and later. Declared in IOEthernetController.h.
kIOEthernetMaxPacketSize

The maximum size of an Ethernet packet, including the FCS bytes. Available in OS X v10.0 and later. Declared in IOEthernetController.h.
kIOEthernetMinPacketSize

The minimum size of an Ethernet packet, including the FCS bytes. Available in OS X v10.0 and later. Declared in IOEthernetController.h.
kIOEthernetWakeOnLANFilterGroup

kIOEthernetWakeOnLANFilterGroup describes the name assigned to the Ethernet Wake-On-LAN filter group. This group represents wake filters that are supported by the controller. Available in OS X v10.0 and later. Declared in IOEthernetController.h.

Wake On LAN Filters

All filters in the Wake-on-LAN filter group.

enum { kIOEthernetWakeOnMagicPacket = 0x00000001, kIOEthernetWakeOnPacketAddressMatch = 0x00000002 };

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

627

IOEthernetController.h User-Space Reference Constants

Constants
kIOEthernetWakeOnMagicPacket

Reception of a Magic Packet. Available in OS X v10.0 and later. Declared in IOEthernetController.h.

kIOEthernetWakeOnPacketAddressMatch

Reception of a packet which passes through any of the address filtering mechanisms based on its destination Ethernet address. This may include unicast, broadcast, or multicast addresses depending on the current state and setting of the corresponding packet filters. Available in OS X v10.1 and later. Declared in IOEthernetController.h. Discussion Each filter listed will respond to a network event that will trigger a system wake-up.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

628

IOEthernetInterface.h User-Space Reference

Declared in

IOEthernetInterface.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define

kIOActivePacketFilters "IOActivePacketFilters" kIOEthernetInterfaceClass "IOEthernetInterface" kIOMulticastAddressList "IOMulticastAddressList" kIORequiredPacketFilters "IORequiredPacketFilters"

Constants
kIOActivePacketFilters

A property of IOEthernetInterface objects. The kIOActivePacketFilters property has an OSDictionary value that describes the current set of packet filters that have been successfully activated. Each entry in the dictionary is a key/value pair consisting of the filter group name, and an OSNumber describing the set of active filters for that group. Entries in this dictionary will mirror those in kIORequiredPacketFilters if the controller has reported success for all filter change requests from the IOEthernetInterface object. Available in OS X v10.0 and later. Declared in IOEthernetInterface.h.
kIOEthernetInterfaceClass

The name of the IOEthernetInterface class. Available in OS X v10.0 and later. Declared in IOEthernetInterface.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

629

IOEthernetInterface.h User-Space Reference Constants

kIOMulticastAddressList

A property of IOEthernetInterface objects. The kIOMulticastAddressList property is an OSData object that describes the list of multicast addresses that are being used by the controller to match against the destination address of an incoming frame. Available in OS X v10.0 and later. Declared in IOEthernetInterface.h.
kIORequiredPacketFilters

A property of IOEthernetInterface objects. The kIORequiredPacketFilters property has an OSDictionary value that describes the current set of required packet filters. Each entry in the dictionary is a key/value pair consisting of the filter group name, and an OSNumber describing the set of required filters for that group. Available in OS X v10.0 and later. Declared in IOEthernetInterface.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

630

IOEthernetStats.h User-Space Reference

Declared in

IOEthernetStats.h

Overview
Ethernet statistics.

Data Types
See the Overview for header-level documentation.

IODot3CollEntry

typedef struct { UInt32 collFrequencies[16]; } IODot3CollEntry;

Discussion Collision statistics structure. Availability Available in OS X v10.0 and later. Declared in
IOEthernetStats.h

IODot3RxExtraEntry

typedef struct { UInt32 overruns; UInt32 watchdogTimeouts; UInt32 frameTooShorts;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

631

IOEthernetStats.h User-Space Reference Data Types

UInt32 collisionErrors; UInt32 phyErrors; UInt32 timeouts; UInt32 interrupts; UInt32 resets; UInt32 resourceErrors; UInt32 reserved[4]; } IODot3RxExtraEntry;

Discussion Extra receiver statistics not defined by RFC1650. Availability Available in OS X v10.0 and later. Declared in
IOEthernetStats.h

IODot3StatsEntry

typedef struct { UInt32 alignmentErrors; UInt32 fcsErrors; UInt32 singleCollisionFrames; UInt32 multipleCollisionFrames; UInt32 sqeTestErrors; UInt32 deferredTransmissions; UInt32 lateCollisions; UInt32 excessiveCollisions; UInt32 internalMacTransmitErrors; UInt32 carrierSenseErrors; UInt32 frameTooLongs; UInt32 internalMacReceiveErrors; UInt32 etherChipSet; UInt32 missedFrames; } IODot3StatsEntry;

Discussion Ethernet MIB statistics structure. Availability Available in OS X v10.0 and later. Declared in
IOEthernetStats.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

632

IOEthernetStats.h User-Space Reference Data Types

IODot3TxExtraEntry

typedef struct { UInt32 underruns; UInt32 jabbers; UInt32 phyErrors; UInt32 timeouts; UInt32 interrupts; UInt32 resets; UInt32 resourceErrors; UInt32 reserved[4]; } IODot3TxExtraEntry;

Discussion Extra transmitter statistics not defined by RFC1650. Availability Available in OS X v10.0 and later. Declared in
IOEthernetStats.h

IOEthernetStats

typedef struct { IODot3StatsEntry dot3StatsEntry; IODot3CollEntry dot3CollEntry; IODot3RxExtraEntry dot3RxExtraEntry; IODot3TxExtraEntry dot3TxExtraEntry; } IOEthernetStats;

Discussion Aggregate Ethernet statistics structure. Availability Available in OS X v10.0 and later. Declared in
IOEthernetStats.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

633

IOEthernetStats.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define kIOEthernetStatsKey "IOEthernetStatsKey"

Constants
kIOEthernetStatsKey

Defines the name of an IONetworkData that contains an IOEthernetStats. Available in OS X v10.0 and later. Declared in IOEthernetStats.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

634

IOFilterScheme.h User-Space Reference

Declared in

IOFilterScheme.h

Overview
This header contains the IOFilterScheme class definition.

Constants
See the Overview for header-level documentation.

Defines

#define kIOFilterSchemeClass "IOFilterScheme"

Constants
kIOFilterSchemeClass

The name of the IOFilterScheme class. kIOFilterSchemeClass is the name of the IOFilterScheme class. Available in OS X v10.3 and later. Declared in IOFilterScheme.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

635

IOFireWireAVCLib.h Reference

Declared in

IOFireWireAVCLib.h

Overview
Included Headers

<IOKit/IOCFPlugIn.h> <IOKit/firewire/IOFireWireFamilyCommon.h> <IOKit/avc/IOFireWireAVCConsts.h>

Callbacks
See the Overview for header-level documentation.

IOFWAVCCommandHandlerCallback
Callback called when a incoming AVC command matching a registered command handler is received.

typedef IOReturn ( *IOFWAVCCommandHandlerCallback)( void *refCon, UInt32 generation, UInt16 srcNodeID, IOFWSpeed speed, const UInt8 *command, UInt32 cmdLen);

Parameters
refCon

The refcon supplied when a client is registered

generation

The FireWire bus generation value at the time the command was received

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

636

IOFireWireAVCLib.h Reference Callbacks

srcNodeID

The node ID of the device who sent us this command

speed

The speed the AVC command packet

command

A pointer to the command bytes

cmdLen

The length of the AVC command bytes buffer in bytes Return Value The callback handler should return success if it will send the AVC response, or an error if it doesn't want to handle the command Availability Available in OS X v10.3 and later. Declared in
IOFireWireAVCLib.h

IOFWAVCPCRCallback
Callback called after a successful lock transaction to a CMP plug.

typedef void ( *IOFWAVCPCRCallback)( void *refcon, UInt32 generation, UInt16 nodeID, UInt32 plug, UInt32 oldVal, UInt32 newVal);

Parameters
refcon

refcon supplied when a client is registered

generation

Bus generation command was received in

nodeID

is the node originating the request

plug

is the plug number

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

637

IOFireWireAVCLib.h Reference Callbacks

oldVal

is the value the plug used to contain

newVal

is the quad written into the plug Availability Available in OS X v10.2 and later. Declared in
IOFireWireAVCLib.h

IOFWAVCRequestCallback
This Callback has been deprecated. Use installAVCCommandHandler instead.

typedef IOReturn ( *IOFWAVCRequestCallback)( void *refCon, UInt32 generation, UInt16 srcNodeID, const UInt8 *command, UInt32 cmdLen, UInt8 *response, UInt32 *responseLen);

Availability Available in OS X v10.2 and later. Declared in

IOFireWireAVCLib.h

IOFWAVCSubunitPlugHandlerCallback
Callback called when a incoming AVC command matching a registered command handler is received.

typedef IOReturn ( *IOFWAVCSubunitPlugHandlerCallback)( void *refCon, UInt32 subunitTypeAndID, IOFWAVCPlugTypes plugType, UInt32 plugNum,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

638

IOFireWireAVCLib.h Reference Callbacks

IOFWAVCSubunitPlugMessages plugMessage, UInt32 messageParams);

Parameters
refCon

The refcon supplied when a client is registered

subunitTypeAndID

The subunit type and id of this plug

plugType

The type of plug receiving the message

plugNum

The number of the plug receiving the message

plugMessage

The plug message

messageParams

The parameters associated with the plug message Return Value The return value is only pertinent for the kIOFWAVCSubunitPlugMsgSignalFormatModified message. Return an error if not accepting the sig format change. Availability Available in OS X v10.3 and later. Declared in
IOFireWireAVCLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

639

IOFireWireFamilyCommon.h User-Space Reference

Declared in

IOFireWireFamilyCommon.h

Overview
This file contains useful definitions for working with FireWire in the kernel and in user space

Included Headers

Constants
See the Overview for header-level documentation.

NodeFlags
Flags that specify characteristics of the FireWire device node.

enum { kIOFWDisablePhysicalAccess = ( 1 << 0), kIOFWDisableAllPhysicalAccess = ( 1 << 1), kIOFWEnableRetryOnAckD = ( 1 << 2), kIOFWLimitAsyncPacketSize = ( 1 << 3), kIOFWDisablePhyOnSleep = ( 1 << 4), kIOFWMustBeRoot = ( 1 << 5), kIOFWMustNotBeRoot = (

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

640

IOFireWireFamilyCommon.h User-Space Reference Constants

1 << 6), kIOFWMustHaveGap63 = ( 1 << 7) };

Constants
kIOFWDisablePhysicalAccess

Disable physical memory access Available in OS X v10.1 and later. Declared in IOFireWireFamilyCommon.h.
kIOFWDisableAllPhysicalAccess

Disable all physical memory access Available in OS X v10.1 and later. Declared in IOFireWireFamilyCommon.h.
kIOFWEnableRetryOnAckD

Enable retry on Ack D Available in OS X v10.2 and later. Declared in IOFireWireFamilyCommon.h.

kIOFWLimitAsyncPacketSize

Limit async packet size Available in OS X v10.3 and later. Declared in IOFireWireFamilyCommon.h.
kIOFWDisablePhyOnSleep

Disable Phy, when machine is in Sleep mode Available in OS X v10.3 and later. Declared in IOFireWireFamilyCommon.h.
kIOFWMustBeRoot

Attempt to make this device root, There is no guarentee Mac OS will succeed in making the device root. Available in OS X v10.5 and later. Declared in IOFireWireFamilyCommon.h.
kIOFWMustNotBeRoot

Attempt to prevent this device from being root, There is no guarentee Mac OS will succeed in preventing the device from being root. Available in OS X v10.5 and later. Declared in IOFireWireFamilyCommon.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

641

IOFireWireFamilyCommon.h User-Space Reference Constants

kIOFWMustHaveGap63

Attempt to ensure the gap count is 63, when this device is on the bus. Gap 63 reduces bus performance significantly, so this flag should be used only when absolutely necessary. There is no guarentee Mac OS will succeed in forcing the gap count to 63. Available in OS X v10.5 and later. Declared in IOFireWireFamilyCommon.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

642

IOFireWireLib.h Reference

Declared in

IOFireWireLib.h

Overview
IOFireWireLib is the software used by user space software to communicate with FireWire devices and control the FireWire bus. IOFireWireLib is the lowest-level FireWire interface available in user space. To communicate with a device on the FireWire bus, an instance of IOFireWireDeviceInterface (a struct which is defined below) is created. The methods of IOFireWireDeviceInterface allow you to communicate with the device and create instances of other interfaces which provide extended functionality (for example, creation of unit directories on the local machine). References to interfaces should be kept using the interface reference typedefs defined herein. For example, you should use IOFireWireLibDeviceRef to refer to instances of IOFireWireDeviceInterface, IOFireWireLibCommandRef to refer to instances of IOFireWireCommandInterface, and so on. To obtain an IOFireWireDeviceInterface for a device on the FireWire bus, use the function IOCreatePlugInInterfaceForService() defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is always upper-case.) Quick usage reference:

'service' is a reference to the IOKit registry entry of the kernel object (usually of type IOFireWireDevice) representing the device of interest. This reference can be obtained using the functions defined in IOKit/IOKitLib.h. 'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID) 'interfaceType' should be CFUUIDGetUUIDBytes(kIOFireWireLibTypeID) when using IOFireWireLib

The interface returned by IOCreatePlugInInterfaceForService() should be deallocated using IODestroyPlugInInterface(). Do not call Release() on it.

Included Headers

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

643

IOFireWireLib.h Reference Functions

Functions
See the Overview for header-level documentation.

IOVirtualRangeMake

CF_INLINE IOVirtualRange IOVirtualRangeMake( IOVirtualAddress address, IOByteCount length )

Discussion Description forthcoming Availability Available in OS X v10.3 and later. Declared in

IOFireWireLib.h

Callbacks
See the Overview for header-level documentation.

IOFireWireBusResetDoneHandler
Called when a bus reset has occured and FireWire has completed configuring the bus.

typedef void ( *IOFireWireBusResetDoneHandler)( IOFireWireLibDeviceRef interface, FWClientCommandID commandID ); // parameters may change

Parameters
interface

A reference to the device on which the callback was installed

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

644

IOFireWireLib.h Reference Callbacks

Availability Available in OS X v10.0 and later. Declared in

IOFireWireLib.h

IOFireWireBusResetHandler
Called when a bus reset has occured, but before FireWire has completed configuring the bus.

typedef void ( *IOFireWireBusResetHandler)( IOFireWireLibDeviceRef interface, FWClientCommandID commandID ); // parameters may change

Parameters
interface

A reference to the device on which the callback was installed

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete() Availability Available in OS X v10.0 and later. Declared in

IOFireWireLib.h

IOFireWireLibCommandCallback
Callback called when an asynchronous command has completed executing

typedef void ( IOFireWireLibCommandCallback)( void refCon, IOReturn completionStatus);

Parameters
refCon

A user specified reference value set before command object was submitted Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

645

IOFireWireLib.h Reference Callbacks

Declared in
IOFireWireLib.h

IOFireWireLibIRMAllocationLostNotificationProc
Callback called when an IOFireWireLibIRMAllocationRef fails to reclaim IRM resources after a bus-reset

typedef void ( IOFireWireLibIRMAllocationLostNotificationProc)( IOFireWireLibIRMAllocationRef irmAllocation, void refCon);

Availability Available in OS X v10.5 and later. Declared in

IOFireWireLib.h

IOFireWireLibPHYPacketCallback
Callback called to handle incoming PHY packets

typedef void ( *IOFireWireLibPHYPacketCallback)( IOFireWireLibPHYPacketListenerRef listener, FWClientCommandID commandID, UInt32 data1, UInt32 data2, void *refCon );

Parameters
listener

The listener which received the callback

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

data1

first quad of received PHY packet

data2

second quad of received PHY packet

refCon

user specified reference value specified on the listener

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

646

IOFireWireLib.h Reference Callbacks

Availability Available in OS X v10.5 and later. Declared in

IOFireWireLib.h

IOFireWireLibPHYPacketSkippedCallback
Callback called when incoming packets have been dropped from the internal queue

typedef void ( *IOFireWireLibPHYPacketSkippedCallback)( IOFireWireLibPHYPacketListenerRef listener, FWClientCommandID commandID, UInt32 skippedPacketCount, void *refCon );

Parameters
listener

The listener which dropped the packets

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

skippedPacketCount

The number of skipped packets

refCon

user specified reference value specified on the listener Availability Available in OS X v10.5 and later. Declared in
IOFireWireLib.h

IOFireWirePseudoAddressSpaceReadHandler
This callback is called to handle read requests to pseudo address spaces. This function should fill in the specified area in the pseudo address space backing store and call ClientCommandIsComplete with the specified command ID

typedef UInt32 ( *IOFireWirePseudoAddressSpaceReadHandler)( IOFireWireLibPseudoAddressSpaceRef addressSpace,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

647

IOFireWireLib.h Reference Callbacks

FWClientCommandID commandID, UInt32 packetLen, UInt32 packetOffset, UInt16 srcNodeID, // nodeID of requester UInt32 destAddressHi, // destination on this node UInt32 destAddressLo, void *refCon);

Parameters
addressSpace

The address space to which the request is being made

commandID

An FWClientCommandID which should be passed to ClientCommandIsComplete when the buffer has been filled in
packetLen

number of bytes requested

packetOffset

number of bytes from beginning of address space backing store

srcNodeID

nodeID of the requester

destAddressHi

high 16 bits of destination address on this computer

destAddressLo

low 32 bits of destination address on this computer

refCon

user specified reference number passed in when the address space was created Availability Available in OS X v10.0 and later. Declared in
IOFireWireLib.h

IOFireWirePseudoAddressSpaceSkippedPacketHandler
Callback called when incoming packets have been dropped from the internal queue

typedef void ( *IOFireWirePseudoAddressSpaceSkippedPacketHandler)( IOFireWireLibPseudoAddressSpaceRef addressSpace,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

648

IOFireWireLib.h Reference Callbacks

FWClientCommandID commandID, UInt32 skippedPacketCount);

Parameters
addressSpace

The address space which dropped the packet(s)

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

skippedPacketCount

The number of skipped packets Availability Available in OS X v10.0 and later. Declared in
IOFireWireLib.h

IOFireWirePseudoAddressSpaceWriteHandler
Callback called to handle write requests to a pseudo address space.

typedef UInt32 ( *IOFireWirePseudoAddressSpaceWriteHandler)( IOFireWireLibPseudoAddressSpaceRef addressSpace, FWClientCommandID commandID, UInt32 packetLen, void *packet, UInt16 srcNodeID, // nodeID of sender UInt32 destAddressHi, // destination on this node UInt32 destAddressLo, void *refCon);

Parameters
addressSpace

The address space to which the write is being made

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

packetLen

Length in bytes of incoming packet

packet

Pointer to the received data

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

649

IOFireWireLib.h Reference Callbacks

srcNodeID

Node ID of the sender

destAddressHi

high 16 bits of destination address on this computer

destAddressLo

low 32 bits of destination address on this computer

refCon

user specified reference number passed in when the address space was created Availability Available in OS X v10.0 and later. Declared in
IOFireWireLib.h

IOFWAsyncStreamListenerHandler
Callback called to handle Async Stream packets.

typedef UInt32 ( *IOFWAsyncStreamListenerHandler)( IOFWAsyncStreamListenerInterfaceRef listener, FWClientCommandID commandID, UInt32 size, void *packet, void *refCon);

Parameters
listener

The listener which received the callback

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

packet

Pointer to the received data

refCon

user specified reference number passed in when async stream interface is created Availability Available in OS X v10.5 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

650

IOFireWireLib.h Reference Data Types

Declared in
IOFireWireLib.h

IOFWAsyncStreamListenerSkippedPacketHandler
Callback called when incoming packets have been dropped from the internal queue

typedef void ( *IOFWAsyncStreamListenerSkippedPacketHandler)( IOFWAsyncStreamListenerInterfaceRef listener, FWClientCommandID commandID, UInt32 skippedPacketCount);

Parameters
listener

The listener which dropped the packets

commandID

An FWClientCommandID to be passed to ClientCommandIsComplete()

skippedPacketCount

The number of skipped packets Availability Available in OS X v10.5 and later. Declared in
IOFireWireLib.h

Data Types
See the Overview for header-level documentation.

FWAddressSpaceFlags

typedef enum { kFWAddressSpaceNoFlags = 0, kFWAddressSpaceNoWriteAccess = ( 1 << 0), kFWAddressSpaceNoReadAccess = ( 1 << 1), kFWAddressSpaceAutoWriteReply = ( 1 << 2),

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

651

IOFireWireLib.h Reference Constants

kFWAddressSpaceAutoReadReply = ( 1 << 3), kFWAddressSpaceAutoCopyOnWrite = ( 1 << 4), kFWAddressSpaceShareIfExists = ( 1 << 5), kFWAddressSpaceExclusive = ( 1 << 6) } FWAddressSpaceFlags;

Discussion FireWire address space creation flags Availability Available in OS X v10.0 and later. Declared in
IOFireWireLib.h

Constants
See the Overview for header-level documentation.

IOFireWireLib Additional Command Flags

Flags for IOFireWireLib commands

enum { kFireWireCommandUseCopy = ( 1 << 16), kFireWireCommandAbsolute = ( 1 << 17) };

Discussion Pass these flags to the object's SetFlags callback.

IOFireWireLib Command Flags

Flags for IOFireWireLib command objects

enum {

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

652

IOFireWireLib.h Reference Constants

kFWCommandNoFlags = 0, kFWCommandInterfaceForceNoCopy = ( 1 << 0), kFWCommandInterfaceForceCopyAlways = ( 1 << 1), kFWCommandInterfaceSyncExecute = ( 1 << 2), kFWCommandInterfaceAbsolute = ( 1 << 3), kFWVectorCommandInterfaceOrdered = ( 1 << 4), kFWCommandInterfaceForceBlockRequest = ( 1 << 5) };

Discussion Pass these flags to the object's SetFlags callback.

IOFireWireLib failOnReset Flags

Flags for IOFireWireLib commands

enum { kFWDontFailOnReset = false, kFWFailOnReset = true };

Discussion Pass these flags in the failOnReset of various commands.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

653

IOFireWireSBP2Lib.h Reference

Declared in

IOFireWireSBP2Lib.h

Overview
Included Headers

Callbacks
See the Overview for header-level documentation.

IOFWSBP2FetchAgentWriteCallback

typedef void ( IOFWSBP2FetchAgentWriteCallback)( void refCon, IOReturn status, void *orbRefCon );

Parameters
refCon

Reference constant supplied when the notification was registered.

status

Indicates success or failure of operation.

orbRefCon

refCon from last orb in chain. Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

654

IOFireWireSBP2Lib.h Reference Callbacks

Declared in
IOFireWireSBP2Lib.h

IOFWSBP2LoginCallback

typedef void ( IOFWSBP2LoginCallback)( void refCon, FWSBP2LoginCompleteParams *params );

Parameters
refCon

Reference constant supplied when the notification was registered.

params

Structure containing additional information about the status of the login. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

IOFWSBP2LogoutCallback

typedef void ( IOFWSBP2LogoutCallback)( void refCon, FWSBP2LogoutCompleteParams *params );

Parameters
refCon

Reference constant supplied when the notification was registered.

params

Structure containing additional information about the status of the logout. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

655

IOFireWireSBP2Lib.h Reference Callbacks

IOFWSBP2NotifyCallback

typedef void ( IOFWSBP2NotifyCallback)( void refCon, FWSBP2NotifyParams *params);

Parameters
refCon

Reference constant supplied when the notification was registered.

params

FWSBP2NotifyParams containing notification information. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

IOFWSBP2ORBAppendCallback

typedef void ( IOFWSBP2ORBAppendCallback)( void refCon, IOReturn status, void *orb );

Parameters
refCon

Reference constant supplied when the notification was registered.

status

Indicates success or failure of operation.

orb

refCon set on management orb. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

656

IOFireWireSBP2Lib.h Reference Callbacks

IOFWSBP2ORBCompleteCallback

typedef void ( IOFWSBP2ORBCompleteCallback)( void refCon, IOReturn status, void *orb );

Parameters
refCon

Reference constant supplied when the notification was registered.

status

Indicates success or failure of operation.

orb

refCon set on management orb. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

IOFWSBP2StatusCallback

typedef void ( IOFWSBP2StatusCallback)( void refCon, IOReturn status);

Parameters
refCon

Reference constant supplied when the notification was registered.

status

IOFireWireSBP2Login.h

FWSBP2ReconnectParams

typedef struct { void *refCon; // refCon from lun object UInt32 generation; // generation this login was attempted in IOReturn status; // status of reconnect attempt FWSBP2StatusBlock *reconnectStatusBlock; // pointer to statusBlock buffer UInt32 reconnectStatusBlockLength; // size of statusBlock buffer } FWSBP2ReconnectParams;

Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

659

IOFireWireSBP2Lib.h Reference Constants

Declared in
IOFireWireSBP2Login.h

FWSBP2StatusBlock

typedef struct { UInt8 details; UInt8 sbpStatus; UInt16 orbOffsetHi; UInt32 orbOffsetLo; UInt32 status[6]; } FWSBP2StatusBlock;

Availability Available in OS X v10.0 and later. Declared in

IOFireWireSBP2Login.h

FWSBP2VirtualRange

typedef struct { void *address; UInt32 length; } FWSBP2VirtualRange;

Discussion Virtual address range for SBP2. Availability Available in OS X v10.0 and later. Declared in
IOFireWireSBP2Lib.h

Constants
See the Overview for header-level documentation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

660

IOFireWireSBP2Lib.h Reference Constants

IODirection

enum IODirection { kIODirectionNone = 0, kIODirectionIn = 1, // User land 'read' kIODirectionOut = 2, // User land 'write' kIODirectionOutIn = 3 };

Discussion Direction of transfer, with respect to the described memory.

Login Option Flags

enum { kFWSBP2DontSynchronizeMgmtAgent = ( 1 << 0), kFWSBP2ExclusiveLogin = ( 1 << 5) };

Discussion Passed to the setLoginFlags member function.

ORB Option Flags

enum { kFWSBP2CommandCompleteNotify = ( 1 << 0), kFWSBP2CommandTransferDataFromTarget = ( 1 << 1), kFWSBP2CommandImmediate = ( 1 << 2), kFWSBP2CommandNormalORB = ( 1 << 5), kFWSBP2CommandReservedORB = ( 1 << 6), kFWSBP2CommandVendorORB = ( 1 << 7), kFWSBP2CommandDummyORB = ( 1 << 8), kFWSBP2CommandCheckGeneration = (

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

661

IOFireWireSBP2Lib.h Reference Constants

1 << 9), kFWSBP2CommandFixedSize = ( 1 << 10), kFWSBP2CommandVirtualORBs = ( 1 << 11) // handy for debugging };

Discussion Passed to the setCommandFlags member function.

SBP2 Notification Events

enum { kFWSBP2NormalCommandStatus = 6, kFWSBP2NormalCommandTimeout = 7, kFWSBP2UnsolicitedStatus = 8, kFWSBP2NormalCommandReset = 9 };

Discussion Passed to the setStatusNotifyProc member function.

SBP2 setCommandFunction values

enum { kFWSBP2QueryLogins = 1, kFWSBP2AbortTask = 0xb, kFWSBP2AbortTaskSet = 0xc, kFWSBP2LogicalUnitReset = 0xe, kFWSBP2TargetReset = 0xf };

Discussion Passed to the setCommandFunction member function.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

662

IOFireWireStorageCharacteristics.h User-Space Reference

Declared in IOFireWireStorageCharacteristics.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define kIOPropertyBridgeCharacteristicsKey "Bridge Characteristics"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

663

IOFireWireStorageCharacteristics.h User-Space Reference Constants

Constants
kIOPropertyBridgeCharacteristicsKey

This key is used to define Bridge Characteristics for a particular devices's bridge chipset. It has an associated dictionary which lists the bridge characteristics. Requirement: Optional Example:

<dict> <key>Bridge Characteristics</key> <dict> <key>Bridge Vendor Name</key> <string>Oxford Semiconductor</string> <key>Bridge Model Name</key> <string>FW911</string> <key>Bridge Revision Level</key> <string>3.7</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOFireWireStorageCharacteristics.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

664

IOFramebufferShared.h User-Space Reference

Declared in

IOFramebufferShared.h

Overview
The IOFramebufferShared.h header contains definitions of objects and types shared between a kernel level IOFrameBuffer service and a non-kernel window server. In OS X this structure is used by the CoreGraphics server and IOGraphics Family, and is not available to other clients. IOFramebuffer subclasses and IOFramebuffer clients within the kernel should also not rely on this structure definition and constants. It is public only for use on Darwin based window servers. Cursor and window server state data is exchanged by kernel and non-kernel tasks through a slice of shared memory containing a StdFBShmem_t structure. For a non-kernel task to get access to this slice of shared memory, a connection to an IOFramebuffer service must be made. A connection is made with the IOServiceOpen() function described in IOKitLib.h. A connection type of kIOFBServerConnectType or kIOFBSharedConnectType (for read-only access) should be specified. An io_connect_t handle is returned by IOServiceOpen(). This handle must be passed to IOFBCreateSharedCursor() to create the slice of shared memory. Then IOConnectMapMemory() may be called with a memory type of kIOFBCursorMemory to map the shared memory into the non-kernel task.

Included Headers

<IOKit/hidsystem/IOHIDTypes.h> <IOKit/graphics/IOGraphicsTypes.h> <libkern/OSAtomic.h>

Data Types
See the Overview for header-level documentation.

bm12Cursor
Cursor image for 1-bit cursor.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

665

IOFramebufferShared.h User-Space Reference Data Types

struct bm12Cursor { unsigned int image[4][16]; unsigned int mask[4][16]; unsigned int save[16]; };

Fields
image

This array contains the cursor images.

mask

This array contains the cursor mask.

save

This array stores the pixel values of the region underneath the cursor in its last drawn position. Discussion This structure stores 16 pixel x 16 pixel cursors to be used with 1-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm18Cursor
Cursor image for 8-bit cursor.

struct bm18Cursor { unsigned char image[4][256]; unsigned char mask[4][256]; unsigned char save[256]; };

Fields
image

This array contains cursor color values, which are converted to displayed colors through the color table. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel.
mask

This array contains the cursor alpha mask. The array is two dimensional with the same indexing as the image. If an alpha mask pixel is 0 and the corresponding image pixel is set to white for the display, then this cursor pixel will invert pixels on the display.
save

This array stores the color values of the region underneath the cursor in its last drawn position.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

666

IOFramebufferShared.h User-Space Reference Data Types

Discussion This structure stores 16 pixel x 16 pixel cursors to be used with 8-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm34Cursor
Cursor image for 15-bit cursor.

struct bm34Cursor { unsigned short image[4][256]; unsigned short save[256]; };

Fields
image

This array defines the cursor color values and transparency. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel. A value of 0 means the pixel is transparent. Non-zero values are stored with the red, green, blue, and alpha values encoded with the following masks: red mask = 0xF000 blue mask 0x0F00 green mask 0x00F0 alpha mask = 0x000F Note, only 4 bits are allocated for each color component.
save

This array stores the color values of the region underneath the cursor in its last drawn position. Discussion This structure stores 16 pixel x 16 pixel cursors to be used with 15-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

bm38Cursor
Cursor image for 24-bit cursor.

struct bm38Cursor { unsigned int image[4][256];

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

667

IOFramebufferShared.h User-Space Reference Data Types

unsigned int save[256]; };

Fields
image

This array defines the cursor color values and transparency. The array is two dimensional and its first index is the cursor frame and the second index is the cursor pixel. The lower 24 bits of a pixel's value contain the RGB color, while the upper 8 bits contain the alpha value.
save

This array stores the color values of the region underneath the cursor in its last drawn position. Discussion This structure stores 16 pixel x 16 pixel cursors to be used with 24-bit color depth. This structure is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined.

StdFBShmem_t

struct StdFBShmem_t { OSSpinLock cursorSema; int frame; char cursorShow; char cursorObscured; char shieldFlag; char shielded; IOGBounds saveRect; IOGBounds shieldRect; IOGPoint cursorLoc; IOGBounds cursorRect; IOGBounds oldCursorRect; IOGBounds screenBounds; int version; int structSize; AbsoluteTime vblTime; AbsoluteTime vblDelta; unsigned long long int vblCount; #if IOFB_ARBITRARY_FRAMES_CURSOR unsigned long long int vblDrift; unsigned long long int vblDeltaMeasured; unsigned int reservedC[24]; #else unsigned int reservedC[27]; unsigned char hardwareCursorFlags[kIOFBNumCursorFrames]; #endif unsigned char hardwareCursorCapable;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

668

IOFramebufferShared.h User-Space Reference Data Types

unsigned char hardwareCursorActive; unsigned char hardwareCursorShields; unsigned char reservedB[1]; #if IOFB_ARBITRARY_FRAMES_CURSOR IOGSize cursorSize[kIOFBNumCursorIndex]; IOGPoint hotSpot[kIOFBNumCursorIndex]; #else IOGSize cursorSize[kIOFBNumCursorFrames]; IOGPoint hotSpot[kIOFBNumCursorFrames]; #endif #ifndef IOFB_ARBITRARY_SIZE_CURSOR union { struct bm12Cursor bw; struct bm18Cursor bw8; struct bm34Cursor rgb; struct bm38Cursor rgb24; } cursor; #else /* IOFB_ARBITRARY_SIZE_CURSOR */ unsigned char cursor[0]; #endif /* IOFB_ARBITRARY_SIZE_CURSOR */ };

Fields
cursorSema

Semaphore lock for write access to the shared data in this structure.
frame

The current cursor frame index.

cursorShow

The cursor is displayed when cursorShow is 0.

cursorObscured

If this is true, the cursor has been obscured and cursorShow should not be 0. The cursor will be shown again the next time it is moved.
shieldFlag

When this is set to true the cursor will not be displayed in the region specified by shieldRect.
shielded

True if the cursor has been hidden because it entered the shielded region.
saveRect

The region that is saved underneath the cursor in software cursor mode.
shieldRect

The region that the cursor will not be displayed in if shieldFlag is true.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

669

IOFramebufferShared.h User-Space Reference Data Types

cursorLoc

The location of the cursor hot spot.

cursorRect

The region that the cursor image currently occupies in software cursor mode.
oldCursorRect

The region that the cursor image occupied the last time the cursor was drawn in software cursor mode.
screenBounds

The region that the current screen occupies.

version

Contains kIOFBCurrentShmemVersion so that a user client can ensure it is using the same version of this structure as the kernel.
structSize

Contains the size of this structure.

vblTime

The time of the most recent vertical blanking.

vblDelta

The interval between the two most recent vertical blankings.

vblCount

A running count of vertical blank interrupts.

reservedC

Reserved for future use.

hardwareCursorCapable

True if the hardware is capable of using hardware cursor mode.

hardwareCursorActive

True if currently using the hardware cursor mode.

reservedB

Reserved for future use.

cursorSize

This array contains the cursor sizes indexed by frame.

hotSpot

This array contains the location of the cursor hot spots indexed by frame. The hot spots coordinates are given relative to the top left corner of the cursor image.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

670

IOFramebufferShared.h User-Space Reference Constants

cursor

A union of structures that define the cursor images. The structure used depends on the framebuffer's bit depth. These structures are defined above. Discussion This structure contains cursor and window server state data and occupies a slice of shared memory between the kernel and window server. Several elements of this structure are only used in software cursor mode. Unless otherwise indicated, the coordinates in this structure are given in display space. Display space is the coordinate space that encompasses all the screens. The positions of the screens within display space indicate their location relative to each other as the cursor moves between them. If there is only one screen, the screen coordinates and display space coordinates will be the same.

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define

CURSORHEIGHT 16 /* height in pixels / CURSORWIDTH 16 / width in pixels */ IOFB_ARBITRARY_SIZE_CURSOR IOFRAMEBUFFER_CONFORMSTO "IOFramebuffer"

Constants
CURSORHEIGHT

The maximum height of the cursor image in pixels. This is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.
CURSORWIDTH

The maximum width of the cursor image in pixels. This is only defined if IOFB_ARBITRARY_SIZE_CURSOR is not defined. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

671

IOFramebufferShared.h User-Space Reference Constants

IOFB_ARBITRARY_SIZE_CURSOR

When IOFB_ARBITRARY_SIZE_CURSOR is not defined, the maximum cursor size is assumed to be CURSORWIDTH x CURSORHEIGHT and this header file will define a number of structures for storing cursor images accordingly. A non-kernel task may define IOFB_ARBITRARY_SIZE_CURSOR and use cursors up to the size specified when IOFBCreateSharedCursor() was called. In this case appropriate structures for storing cursor images must be defined elsewhere. In the kernel, IOFB_ARBITRARY_SIZE_CURSOR is always defined. Available in OS X v10.7 through OS X v10.7. Declared in IOFramebufferShared.h.
IOFRAMEBUFFER_CONFORMSTO

The class name of the framebuffer service. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.

CursorParameters

enum { #if IOFB_ARBITRARY_FRAMES_CURSOR kIOFBMainCursorIndex = 0, kIOFBWaitCursorIndex = 1, kIOFBNumCursorIndex = 4, #else kIOFBNumCursorFrames = 4, kIOFBNumCursorFramesShift = 2, #endif kIOFBMaxCursorDepth = 32 };

Constants
kIOFBNumCursorFrames

The number of cursor images stored in the StdFBShmem_t structure. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.
kIOFBNumCursorFramesShift

Used with waiting cursors. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

672

IOFramebufferShared.h User-Space Reference Constants

kIOFBMaxCursorDepth

The maximum cursor pixel depth. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.

FramebufferConstants

enum { // version for IOFBCreateSharedCursor kIOFBShmemVersionMask = 0x000000ff, kIOFBTenPtOneShmemVersion = 2, kIOFBTenPtTwoShmemVersion = 3, kIOFBCurrentShmemVersion = 2, // number of frames in animating cursor (if > kIOFBTenPtTwoShmemVersion) kIOFBShmemCursorNumFramesMask = 0x00ff0000, kIOFBShmemCursorNumFramesShift = 16, // memory types for IOConnectMapMemory. kIOFBCursorMemory = 100 };

Constants
kIOFBCurrentShmemVersion

The current version of the slice of shared memory that contains the cursor and window server state data in the StdFBShmem_t structure. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.
kIOFBCursorMemory

The memory type for IOConnectMapMemory() to get a slice of shared memory that contains the StdFBShmem_t structure. Available in OS X v10.0 and later. Declared in IOFramebufferShared.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

673

IOGraphicsLib.h Reference

Declared in

IOGraphicsLib.h

Overview
IOGraphicsLib implements non-kernel task access to IOGraphics family object types - IOFramebuffer and IOAccelerator. These functions implement a graphics family specific API. A connection to a graphics IOService must be made before these functions are called. A connection is made with the IOServiceOpen() function described in IOKitLib.h. An io_connect_t handle is returned by IOServiceOpen(), which must be passed to the IOGraphicsLib functions. The appropriate connection type from IOGraphicsTypes.h must be specified in the call to IOServiceOpen(). All of the IOFramebuffer functions can only be called from a kIOFBServerConnectType connection. Except as specified below, functions whose names begin with IOFB are IOFramebuffer functions. Functions whose names begin with IOPS are IOAccelerator functions and must be called from connections of type kIOFBEngineControllerConnectType or kIOFBEngineConnectType. The functions in IOGraphicsLib use a number of special types. The display mode is the screen's resolution and refresh rate. The known display modes are referred to by an index of type IODisplayModeID. The display depth is the number of significant color bits used in representing each pixel. Depths are also referred to by an index value that is 0 for 8 bits, 1 for 15 bits, and 2 for 24 bits. A combination of display mode and depth may have a number of supported pixel formats. The pixel aperture is an index of supported pixel formats for a display mode and depth. This index is of type IOPixelAperture. All of these graphics specific types are defined in IOGraphicsTypes.h.

Included Headers

<IOKit/IOKitLib.h> <IOKit/graphics/IOFramebufferShared.h> <IOKit/graphics/IOGraphicsInterface.h>

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

674

IOGraphicsLib.h Reference Functions

Functions
See the Overview for header-level documentation.

IOCreateDisplayInfoDictionary

#define IOCreateDisplayInfoDictionary(f,o) \ IODisplayCreateInfoDictionary(f,o)

Discussion IOCreateDisplayInfoDictionary() was renamed IODisplayCreateInfoDictionary(). IOCreateDisplayInfoDictionary() is now a macro for IODisplayCreateInfoDictionary() for compatibility with older code. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IODisplayCreateInfoDictionary
Create a CFDictionary with information about display hardware.

CFDictionaryRef IODisplayCreateInfoDictionary( io_service_t framebuffer, IOOptionBits options );

Parameters
framebuffer

The IOService handle for an IOFramebuffer service.

options

Use IODisplayDictionaryOptions to specify which keys to include. Return Value The returned CFDictionary that should be released by the caller with CFRelease(). Discussion The CFDictionary created by this function contains information about the display hardware associated with a framebuffer. The keys for the dictionary are listed in IOGraphicsTypes.h. Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

675

IOGraphicsLib.h Reference Functions

Related Sample Code ScreenSnapshot

Declared in
IOGraphicsLib.h

IODisplayMatchDictionaries
Match two display information dictionaries to see if they are for the same display.

SInt32 IODisplayMatchDictionaries( CFDictionaryRef matching1, CFDictionaryRef matching2, IOOptionBits options );

Parameters
matching1

A CFDictionary returned from IODisplayCreateInfoDictionary().

matching2

Another CFDictionary returned from IODisplayCreateInfoDictionary().

options

No options are currently defined. Return Value Returns FALSE if the two displays are not equivalent or TRUE if they are. Discussion By comparing two CFDictionaries returned from IODisplayCreateInfoDictionary(), this function determines if the displays are the same. The information compared is what is returned by calling IODisplayCreateInfoDictionary() with an option of kIODisplayMatchingInfo. This includes information such as the vendor, product, and serial number. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

676

IOGraphicsLib.h Reference Functions

IOFBCreateDisplayModeDictionary
Create a CFDictionary with information about a display mode.

CFDictionaryRef IOFBCreateDisplayModeDictionary( io_service_t framebuffer, IODisplayModeID displayMode );

Parameters
framebuffer

The IOService handle for an IOFramebuffer service.

displayMode

A display mode index. Return Value The returned CFDictionary that should be released by the caller with CFRelease(). Discussion This function creates a dictionary containing information about a display mode. The display mode properties that are represented by the kernel as OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, or OSBoolean are converted to their CF counterparts and put in the dictionary. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBCreateSharedCursor
Create shared cursor memory.

extern kern_return_t IOFBCreateSharedCursor( io_connect_t connect, unsigned int version, unsigned int maxWidth, unsigned int maxHeight );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

677

IOGraphicsLib.h Reference Functions

version

The version of cursor shared memory to use. For the current version, pass kIOFBCurrentShmemVersion.
maxWidth

The maximum width of the cursor.

maxHeight

The maximum height of the cursor. Return Value A kern_return_t error code. Discussion This function allocates memory, containing details about the cursor, that can be shared with a calling non-kernel task. The memory contains a StdFBShmem_t structure, which is defined in IOFrameBufferShared.h. This structure contains information on the cursor image, whether it is current shown, its location, etc. The allocated memory can be mapped to the non-kernel task's memory space by calling IOConnectMapMemory() and passing kIOFBCursorMemory for memoryType. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetCurrentDisplayModeAndDepth
Get the current display mode and depth.

extern kern_return_t IOFBGetCurrentDisplayModeAndDepth( io_connect_t connect, IODisplayModeID displayMode, IOIndex depth );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

The ID of the current display mode is returned.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

678

IOGraphicsLib.h Reference Functions

depth

The current display depth is returned (0 = 8 bits, 1 = 15 bits, 2 = 24 bits) Return Value A kern_return_t error code. Discussion The display mode index returned by this function can be used to determine information about the current display mode and its supported pixel formats through calls to IOFBGetDisplayModeInformation(), IOFBGetPixelFormats(), and IOFBGetPixelInformation(). Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetDisplayModeCount
Get the number of display modes.

kern_return_t IOFBGetDisplayModeCount( io_connect_t connect, UInt32 *count );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
count

The display mode count is returned. Return Value A kern_return_t error code. Discussion IOFBGetDisplayModeCount returns the number of display modes that the IOFramebuffer service is aware of. Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

679

IOGraphicsLib.h Reference Functions

Declared in
IOGraphicsLib.h

IOFBGetDisplayModeInformation
Get information about a display mode.

kern_return_t IOFBGetDisplayModeInformation( io_connect_t connect, IODisplayModeID displayMode, IODisplayModeInformation *info );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

The display mode index.

info

A pointer to an IODisplayModeInformation structure where the display mode information will be returned. Return Value A kern_return_t error code. Discussion Display modes are referred to by their index of type IODisplayModeID. This function returns a structure containing the width, height, refresh rate, maximum depth, etc. of a display mode. The IODisplayModeInformation structure is defined in IOGraphicsTypes.h. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetDisplayModes
Get an array of known display modes.

kern_return_t IOFBGetDisplayModes(

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

680

IOGraphicsLib.h Reference Functions

io_connect_t connect, UInt32 count, IODisplayModeID *allDisplayModes );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
count

The number of display modes to get.

allDisplayModes

An array of IODisplayModeID's with enough space for all entries. The array is filled in upon return. Return Value A kern_return_t error code. Discussion This function returns an array containing the display modes that the framebuffer service is aware of. To get all display modes, pass the count from IOFBGetDisplayModeCount(). Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetFramebufferInformationForAperture
Get framebuffer information for a pixel format.

extern kern_return_t IOFBGetFramebufferInformationForAperture( io_connect_t connect, IOPixelAperture aperture, IOFramebufferInformation *info );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

681

IOGraphicsLib.h Reference Functions

aperture

The pixel aperture to retrieve information on. The pixel aperture is an index into supported pixel formats for a display mode and depth. To get information for the current aperture, use kIOFBSystemAperture.
info

A pointer to an IOFramebufferInformation structure where the information will be returned. Return Value A kern_return_t error code. Discussion This function returns framebuffer information for a pixel format that is supported for the current display mode and depth. The returned IOFrameBufferInformation structure contains details on the physical address of the framebuffer, height, width, etc. This structure is defined in IOGraphicsTypes.h. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetFramebufferOffsetForAperture
Get the byte offset for a framebuffer's VRAM.

extern kern_return_t IOFBGetFramebufferOffsetForAperture( mach_port_t connect, IOPixelAperture aperture, IOByteCount *offset );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
aperture

The pixel aperture to retrieve information on. The pixel aperture is an index into supported pixel formats. To get information for the current aperture, use kIOFBSystemAperture.
offset

The number of bytes offset is returned on success.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

682

IOGraphicsLib.h Reference Functions

Return Value A kern_return_t error code. Discussion [place holder] Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetPixelFormat
Get pixel format information.

extern kern_return_t IOFBGetPixelFormat( io_connect_t connect, IODisplayModeID displayMode, IOIndex depth, IOPixelAperture aperture, IOPixelEncoding *pixelFormat );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

A display mode index.

depth

A display depth index.

aperture

The pixel aperture to retrieve the pixel format for. The pixel aperture is an index into supported pixel formats. To get information on the current aperture, use kIOFBSystemAperture.
pixelFormat

The returned pixel format. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

683

IOGraphicsLib.h Reference Functions

Discussion Displayed colors are encoded in framebuffer memory in a variety of ways. IOFBGetPixelFormat returns a pixel encoding array specifying how each bit of a particular pixel should be interpreted. The definition of the IOPixelEncoding array returned and common Apple pixel formats are described in IOGraphicsTypes.h. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetPixelFormats
Get pixel formats that are supported for a display mode and depth.

kern_return_t IOFBGetPixelFormats( io_connect_t connect, IODisplayModeID displayMode, IOIndex depth, UInt32 *mask );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

A display mode index.

depth

A display depth index.

mask

The returned mask of pixel formats. Return Value A kern_return_t error code. Discussion This function returns a mask of all supported pixel formats for a particular display mode and depth. [How should the mask be interpreted?]

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

684

IOGraphicsLib.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IOGraphicsLib.h

IOFBGetPixelInfoDictionary
Get a CFDictionary with information about a pixel format.

CFDictionaryRef IOFBGetPixelInfoDictionary( CFDictionaryRef modeDictionary, IOIndex depth, IOPixelAperture aperture );

Parameters
modeDictionary

The CFDictionary containing information about a display mode.

depth

A depth index.
aperture

The pixel aperture to information about. The pixel aperture is an index into supported pixel formats. To get information on the current aperture, use kIOFBSystemAperture. Return Value The returned CFDictionary that should be released by the caller with CFRelease(). Discussion This function extracts a CFDictionary containing information about a supported pixel format from a larger CFDictionary describing a display mode. IOFBCreateDisplayModeDictionary() must be called first to generate the CFDictionary for a display mode. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBGetPixelInformation
Get information about a pixel format.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

685

IOGraphicsLib.h Reference Functions

kern_return_t IOFBGetPixelInformation( io_connect_t connect, IODisplayModeID displayMode, IOIndex depth, IOPixelAperture aperture, IOPixelInformation *pixelInfo );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

A display mode index.

depth

A display depth index.

aperture

A pixel aperture. The pixel aperture is an index into supported pixel formats for a display mode and depth. To get information on the current aperture, use kIOFBSystemAperture.
pixelInfo

A pointer to an IOPixelInformation structure where the pixel information will be returned. Return Value A kern_return_t error code. Discussion IOFBGetPixelInformation returns a structure containing information about a pixel format such as the bits per pixel, pixel format, etc. The IOPixelInformation structure is defined in IOGraphicsTypes.h. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSet256To888Table
[place holder]

extern kern_return_t IOFBSet256To888Table(

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

686

IOGraphicsLib.h Reference Functions

io_connect_t connect, const unsigned int *table );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value A kern_return_t error code. Discussion [place holder] Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSet444To555Table
[place holder]

extern kern_return_t IOFBSet444To555Table( io_connect_t connect, const unsigned char *table );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value A kern_return_t error code. Discussion [place holder]

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

687

IOGraphicsLib.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IOGraphicsLib.h

IOFBSet555To444Table
[place holder]

extern kern_return_t IOFBSet555To444Table( io_connect_t connect, const unsigned char *table );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value A kern_return_t error code. Discussion [place holder] Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSet888To256Table
[place holder]

extern kern_return_t IOFBSet888To256Table( io_connect_t connect, const unsigned char *table );

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

688

IOGraphicsLib.h Reference Functions

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
table

Return Value A kern_return_t error code. Discussion [place holder] Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSetBounds
Set the location of the framebuffer within display space.

extern kern_return_t IOFBSetBounds( io_connect_t connect, IOGBounds *rect );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
rect

An IOGBounds structure specifying a rectangular region of the framebuffer. Return Value A kern_return_t error code. Discussion If there is more than one screen in use, the locations of the screens relative to each other must be specified. These locations are specified in a "display space" that encompasses all the screens. The bounding regions of the screens within display space indicate their location relative to each other as the cursor moves between

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

689

IOGraphicsLib.h Reference Functions

them. This function sets the bounding region for a framebuffer within display space. If there is only one screen, this does not need to specified, because by default the screen coordinates and display space coordinates will be the same. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSetCLUT
Set the color table.

extern kern_return_t IOFBSetCLUT( io_connect_t connect, UInt32 startIndex, UInt32 numEntries, IOOptionBits options, IOColorEntry *colors );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
startIndex

The first index to set in the color table.

numEntries

The number of entries to set.

options

kSetCLUTByValue may be set to use the index member of the IOColorEntry structure to determine where the entry should be written to the color table. Otherwise the index is taken from the location in the IOColorEntry array. kSetClutImmediately may be set to change the color table immediately instead of waiting for vertical blanking interval. kSetClubWithLuminance may be set to use luminance rather than RGB entries.
colors

The array of color table entries to set. The IOColorEntry structure is defined in IOGraphicsTypes.h. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

690

IOGraphicsLib.h Reference Functions

Discussion Indexed pixel formats require a color table to convert from the index stored in a pixel memory location to a displayed color. IOFBSetCLUT sets one or more entries of the color table. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSetCursorPosition
Set the hardware cursor position.

kern_return_t IOFBSetCursorPosition( io_connect_t connect, long int x, long int y );

This parameter is currently not used and must be 0.

frame

An index to the cursor image to use that must be less than kIOFBNumCursorFrames. Currently only frame 0 is supported.
options

No options are currently defined. Return Value A kern_return_t error code. Discussion A non-kernel task interacts with the IOFramebuffer service through a slice of shared memory that is created with the IOFBCreateSharedCursor function. The shared memory is a structure of type StdFBShmem_t. In this shared memory several cursor images, or frames may be defined. The maximum number of frames is kIOFBNumCursorFrames. StdFBShmem_t and kIOFBNumCursorFrames are defined in IOFramebufferShared.h. This function sets a new frame to be used as the current cursor image and activates the hardware cursor. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

694

IOGraphicsLib.h Reference Functions

IOFBSetStartupDisplayModeAndDepth
Set the display mode and depth to use on startup.

kern_return_t IOFBSetStartupDisplayModeAndDepth( io_connect_t connect, IODisplayModeID displayMode, IOIndex depth );

Parameters
connect

The connect handle from IOServiceOpen() to an IOFramebuffer service with a kIOFBServerConnectType connection.
displayMode

The index of the new display mode.

depth

The index of the new depth. Return Value A kern_return_t error code. Availability Available in OS X v10.0 and later. Declared in
IOGraphicsLib.h

IOFBSetVirtualBounds
Set the location of the framebuffer within display space and within desktop space.

extern kern_return_t IOFBSetVirtualBounds( io_connect_t connect, IOGBounds screenBounds, IOGBounds desktopBounds );

Parameters
connect

The connect handle from IOServiceOpen to an IOFramebuffer service with a kIOFBServerConnectType connection.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

695

IOGraphicsLib.h Reference Constants

screenBounds

An IOGBounds structure specifying a rectangular region of the framebuffer in display space.

desktopBounds

An IOGBounds structure specifying a rectangular region of the framebuffer in desktop space. Return Value A kern_return_t error code. Discussion If there is more than one screen in use, the locations of the screens relative to each other must be specified. Each physical screen will have a rectangular region of "display space" that it is responsible for showing. When the "display space" does not have a 1:1 mapping to the "desktop space" (e.g when using zooming, or HiDPI), this function is used to define how "desktop space" maps into "display space". Note that "desktop space" and "display space" should be contiguous, and the mapping between them should be functional (i.e. 1-to-1, though not necessarily contiguous). Availability Available in OS X v10.7 and later. Declared in
IOGraphicsLib.h

Constants
See the Overview for header-level documentation.

IODisplayDictionaryOptions

enum { kIODisplayMatchingInfo = 0x00000100, kIODisplayOnlyPreferredName = 0x00000200, kIODisplayNoProductName = 0x00000400 };

Constants
kIODisplayMatchingInfo

Include only the keys necessary to match two displays with IODisplayMatchDictionaries(). Available in OS X v10.0 and later. Declared in IOGraphicsLib.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

696

IOGraphicsLib.h Reference Constants

kIODisplayOnlyPreferredName

The kDisplayProductName property includes only the localized names returned by CFBundleCopyPreferredLocalizationsFromArray(). Available in OS X v10.4 and later. Declared in IOGraphicsLib.h.
kIODisplayNoProductName

The kDisplayProductName property is not included in the returned dictionary. Available in OS X v10.4 and later. Declared in IOGraphicsLib.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

697

IOGraphicsTypes.h User-Space Reference

Declared in

IOGraphicsTypes.h

Overview
Included Headers

Data Types
See the Overview for header-level documentation.

IOColorEntry
A structure defining one entry of a color lookup table.

struct IOColorEntry UInt16 index; IOColorComponent IOColorComponent IOColorComponent };

{ red; green; blue;

Fields
index

Number of pixels visible per row.

red

Value of red component 0-65535.

green

Value of green component 0-65535.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

698

IOGraphicsTypes.h User-Space Reference Data Types

blue

Value of blue component 0-65535. Discussion This structure is used by IOFramebuffer to define an entry of a color lookup table.

IODetailedTimingInformationV2
A structure defining the detailed timing information of a display mode.

struct IODetailedTimingInformationV2 { UInt32 __reservedA[3]; // Init to 0 UInt32 horizontalScaledInset; // pixels UInt32 verticalScaledInset; // lines UInt32 scalerFlags; UInt32 horizontalScaled; UInt32 verticalScaled; UInt32 signalConfig; UInt32 signalLevels; UInt64 pixelClock; // Hz UInt64 minPixelClock; // Hz - With error what is slowest actual clock UInt64 maxPixelClock; // Hz - With error what is fasted actual clock UInt32 horizontalActive; // pixels UInt32 horizontalBlanking; // pixels UInt32 horizontalSyncOffset; // pixels UInt32 horizontalSyncPulseWidth; // pixels UInt32 verticalActive; // lines UInt32 verticalBlanking; // lines UInt32 verticalSyncOffset; // lines UInt32 verticalSyncPulseWidth; // lines UInt32 horizontalBorderLeft; // pixels UInt32 horizontalBorderRight; // pixels UInt32 verticalBorderTop; // lines UInt32 verticalBorderBottom; // lines UInt32 horizontalSyncConfig; UInt32 horizontalSyncLevel; // Future use (init to 0) UInt32 verticalSyncConfig; UInt32 verticalSyncLevel; // Future use (init to 0) UInt32 numLinks; UInt32 __reservedB[7]; // Init to 0 };

Fields
__reservedA

Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

699

IOGraphicsTypes.h User-Space Reference Data Types

horizontalScaledInset

If the mode is scaled, sets the number of active pixels to remove the left and right edges in order to display an underscanned image.
verticalScaledInset

If the mode is scaled, sets the number of active lines to remove the top and bottom edges in order to display an underscanned image.
scalerFlags

If the mode is scaled, kIOScaleStretchToFit may be set to allow stretching. kIOScaleRotateFlags is mask which may have the value given by kIOScaleRotate90, kIOScaleRotate180, kIOScaleRotate270 to display a rotated framebuffer.
horizontalScaled

If the mode is scaled, sets the size of the image before scaling or rotation.
verticalScaled

If the mode is scaled, sets the size of the image before scaling or rotation.
signalConfig

kIOAnalogSetupExpected set if display expects a blank-to-black setup or pedestal. See VESA signal standards. kIOInterlacedCEATiming set for a CEA style interlaced timing: Field 1 vertical blanking = half specified vertical blanking lines. Field 2 vertical blanking = (half vertical blanking lines) + 1 line. Field 1 vertical offset = half specified vertical sync offset. Field 2 vertical offset = (half specified vertical sync offset) + 0.5 lines.
signalLevels

One of: kIOAnalogSignalLevel_0700_0300 0.700 - 0.300 V p-p. kIOAnalogSignalLevel_0714_0286 0.714 - 0.286 V p-p. kIOAnalogSignalLevel_1000_0400 1.000 - 0.400 V p-p. kIOAnalogSignalLevel_0700_0000 0.700 - 0.000 V p-p.
pixelClock

Pixel clock frequency in Hz.

minPixelClock

Minimum pixel clock frequency in Hz, with error.

maxPixelClock

Maximum pixel clock frequency in Hz, with error.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

700

IOGraphicsTypes.h User-Space Reference Data Types

horizontalActive

Pixel clocks per line.

horizontalBlanking

Blanking clocks per line.

horizontalSyncOffset

First clock of horizontal sync.

horizontalSyncPulseWidth

Width of horizontal sync.

verticalActive

Number of lines per frame.

verticalBlanking

Blanking lines per frame.

verticalSyncOffset

First line of vertical sync.

verticalSyncPulseWidth

Height of vertical sync.

horizontalBorderLeft

Number of pixels in left horizontal border.

horizontalBorderRight

Number of pixels in right horizontal border.

verticalBorderTop

Number of lines in top vertical border.

verticalBorderBottom

Number of lines in bottom vertical border.

horizontalSyncConfig

kIOSyncPositivePolarity for positive polarity horizontal sync (0 for negative).

horizontalSyncLevel

Zero.
verticalSyncConfig

kIOSyncPositivePolarity for positive polarity vertical sync (0 for negative).

verticalSyncLevel

Zero.
numLinks

number of links to be used by a dual link timing, if zero, assume one link.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

701

IOGraphicsTypes.h User-Space Reference Data Types

__reservedB

Reserved set to zero. Discussion This structure is used by IOFramebuffer to define detailed timing information for a display mode. The VESA EDID document has more information.

IODisplayModeInformation
A structure defining the format of a framebuffer.

struct IODisplayModeInformation { UInt32 nominalWidth; UInt32 nominalHeight; IOFixed1616 refreshRate; IOIndex maxDepthIndex; UInt32 flags; UInt16 imageWidth; UInt16 imageHeight; UInt32 reserved[ 3 ]; };

Fields
nominalWidth

Number of pixels visible per row.

nominalHeight

Number of visible pixel rows.

refreshRate

Refresh rate in fixed point 16.16.

maxDepthIndex

Highest depth index available in this display mode.

flags

Flags for the mode, including: kDisplayModeInterlacedFlag mode is interlaced. kDisplayModeSimulscanFlag mode is available on multiple display connections. kDisplayModeNotPresetFlag mode is not a factory preset for the display (geometry may need correction). kDisplayModeStretchedFlag mode is stretched/distorted to match the display aspect ratio.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

702

IOGraphicsTypes.h User-Space Reference Data Types

imageWidth

Physical width of active image if known, in millimeters, otherwise zero.

imageHeight

Physical height of active image if known, in millimeters, otherwise zero.

reserved

Set to zero. Discussion This structure is used by IOFramebuffer to define the format of the pixels.

IODisplayScalerInformation
A structure defining the scaling capabilities of a framebuffer.

struct IODisplayScalerInformation UInt32 __reservedA[1]; // Init UInt32 version; // Init to 0 UInt32 __reservedB[2]; // Init IOOptionBits scalerFeatures; UInt32 maxHorizontalPixels; UInt32 maxVerticalPixels; UInt32 __reservedC[5]; // Init };

{ to 0 to 0

to 0

Fields
__reservedA

Set to zero.
version

Set to zero.
__reservedB

Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

703

IOGraphicsTypes.h User-Space Reference Data Types

scalerFeatures

Mask of scaling features. The following are defined: kIOScaleStretchOnly If set the framebuffer can only provide stretched scaling with non-square pixels, without borders. kIOScaleCanUpSamplePixels If set framebuffer can scale up from a smaller number of source pixels to a larger native timing (eg. 640x480 pixels on a 1600x1200 timing). kIOScaleCanDownSamplePixels If set framebuffer can scale down from a larger number of source pixels to a smaller native timing (eg. 1600x1200 pixels on a 640x480 timing). kIOScaleCanScaleInterlaced If set framebuffer can scale an interlaced detailed timing. kIOScaleCanSupportInset If set framebuffer can support scaled modes with non-zero horizontalScaledInset, verticalScaledInset fields. kIOScaleCanRotate If set framebuffer can support some of the flags in the kIOScaleRotateFlags mask. kIOScaleCanBorderInsetOnly If set framebuffer can support scaled modes with non-zero horizontalScaledInset, verticalScaledInset fields, but requires the active pixels to be equal in size to the inset area, ie. can do insets with a border versus scaling an image.
maxHorizontalPixels

Maximum number of horizontal source pixels (horizontalScaled).

maxVerticalPixels

Maximum number of vertical source pixels (verticalScaled).

__reservedC

Set to zero. Discussion This structure is used to define the limits for modes programmed as detailed timings by the OS. A data property with this structure under the key kIOFBScalerInfoKey in a framebuffer will allow the OS to program detailed timings that are scaled to a displays native resolution.

IODisplayTimingRange
A structure defining the limits and attributes of a display or framebuffer.

struct IODisplayTimingRange { UInt32 __reservedA[2]; // Init to 0 UInt32 version; // Init to 0 UInt32 __reservedB[5]; // Init to 0 UInt64 minPixelClock; // Min dot clock in Hz UInt64 maxPixelClock; // Max dot clock in Hz

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

704

IOGraphicsTypes.h User-Space Reference Data Types

UInt32 maxPixelError; // Max dot clock error UInt32 supportedSyncFlags; UInt32 supportedSignalLevels; UInt32 supportedSignalConfigs; UInt32 minFrameRate; // Hz UInt32 maxFrameRate; // Hz UInt32 minLineRate; // Hz UInt32 maxLineRate; // Hz UInt32 maxHorizontalTotal; // Clocks - Maximum total (active + blanking) UInt32 maxVerticalTotal; // Clocks - Maximum total (active + blanking) UInt32 __reservedD[2]; // Init to 0 UInt8 charSizeHorizontalActive; UInt8 charSizeHorizontalBlanking; UInt8 charSizeHorizontalSyncOffset; UInt8 charSizeHorizontalSyncPulse; UInt8 charSizeVerticalActive; UInt8 charSizeVerticalBlanking; UInt8 charSizeVerticalSyncOffset; UInt8 charSizeVerticalSyncPulse; UInt8 charSizeHorizontalBorderLeft; UInt8 charSizeHorizontalBorderRight; UInt8 charSizeVerticalBorderTop; UInt8 charSizeVerticalBorderBottom; UInt8 charSizeHorizontalTotal; // Character size for active + blanking UInt8 charSizeVerticalTotal; // Character size for active + blanking UInt16 __reservedE; // Reserved (Init to 0) UInt32 minHorizontalActiveClocks; UInt32 maxHorizontalActiveClocks; UInt32 minHorizontalBlankingClocks; UInt32 maxHorizontalBlankingClocks; UInt32 minHorizontalSyncOffsetClocks; UInt32 maxHorizontalSyncOffsetClocks; UInt32 minHorizontalPulseWidthClocks; UInt32 maxHorizontalPulseWidthClocks; UInt32 minVerticalActiveClocks; UInt32 maxVerticalActiveClocks; UInt32 minVerticalBlankingClocks; UInt32 maxVerticalBlankingClocks; UInt32 minVerticalSyncOffsetClocks; UInt32 maxVerticalSyncOffsetClocks; UInt32 minVerticalPulseWidthClocks; UInt32 maxVerticalPulseWidthClocks; UInt32 minHorizontalBorderLeft; UInt32 maxHorizontalBorderLeft; UInt32 minHorizontalBorderRight; UInt32 maxHorizontalBorderRight; UInt32 minVerticalBorderTop; UInt32 maxVerticalBorderTop; UInt32 minVerticalBorderBottom;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

705

IOGraphicsTypes.h User-Space Reference Data Types

UInt32 UInt32 UInt32 UInt32 UInt32 UInt32 UInt32 };

maxVerticalBorderBottom; maxNumLinks; // number of links, minLink0PixelClock; // min pixel maxLink0PixelClock; // max pixel minLink1PixelClock; // min pixel maxLink1PixelClock; // max pixel __reservedF[3]; // Init to 0

if zero, assume link 1 clock for link (kHz) clock for link (kHz) clock for link 1 (kHz) clock for link 1 (kHz)

Fields
__reservedA

Set to zero.
version

Set to zero.
__reservedB

Set to zero.
minPixelClock

minimum pixel clock frequency in range, in Hz. maximum pixel clock frequency in range, in Hz.
maxPixelError

largest variation between specified and actual pixel clock frequency, in Hz.
supportedSyncFlags

mask of supported sync attributes. The following are defined: kIORangeSupportsSeparateSyncs - digital separate syncs. kIORangeSupportsSyncOnGreen - sync on green. kIORangeSupportsCompositeSync - composite sync. kIORangeSupportsVSyncSerration - vertical sync has serration and equalization pulses.
supportedSignalLevels

mask of possible signal levels. The following are defined: kIORangeSupportsSignal_0700_0300 0.700 - 0.300 V p-p. kIORangeSupportsSignal_0714_0286 0.714 - 0.286 V p-p. kIORangeSupportsSignal_1000_0400 1.000 - 0.400 V p-p. kIORangeSupportsSignal_0700_0000 0.700 - 0.000 V p-p.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

706

IOGraphicsTypes.h User-Space Reference Data Types

supportedSignalConfigs

mask of possible signal configurations. The following are defined: kIORangeSupportsInterlacedCEATiming Supports CEA style interlaced timing: Field 1 vertical blanking = specified vertical blanking lines. Field 2 vertical blanking = vertical blanking lines + 1 line. Field 1 vertical offset = specified vertical sync offset. Field 2 vertical offset = specified vertical sync offset + 0.5 lines. kIORangeSupportsInterlacedCEATimingWithConfirm Supports CEA style interlaced timing, but require a confirm.
minFrameRate

minimum frame rate (vertical refresh frequency) in range, in Hz.

maxFrameRate

maximum frame rate (vertical refresh frequency) in range, in Hz.

minLineRate

minimum line rate (horizontal refresh frequency) in range, in Hz.

maxLineRate

maximum line rate (horizontal refresh frequency) in range, in Hz.

maxHorizontalTotal

maximum clocks in horizontal line (active + blanking).

maxVerticalTotal

maximum lines in vertical frame (active + blanking).

__reservedD

Set to zero.
charSizeHorizontalActive

horizontalActive must be a multiple of charSizeHorizontalActive.

charSizeHorizontalBlanking

horizontalBlanking must be a multiple of charSizeHorizontalBlanking.

charSizeHorizontalSyncOffset

horizontalSyncOffset must be a multiple of charSizeHorizontalSyncOffset.

charSizeHorizontalSyncPulse

horizontalSyncPulse must be a multiple of charSizeHorizontalSyncPulse.

charSizeVerticalActive

verticalActive must be a multiple of charSizeVerticalActive.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

707

IOGraphicsTypes.h User-Space Reference Data Types

charSizeVerticalBlanking

verticalBlanking must be a multiple of charSizeVerticalBlanking.

charSizeVerticalSyncOffset

verticalSyncOffset must be a multiple of charSizeVerticalSyncOffset.

charSizeVerticalSyncPulse

verticalSyncPulse must be a multiple of charSizeVerticalSyncPulse.

charSizeHorizontalBorderLeft

horizontalBorderLeft must be a multiple of charSizeHorizontalBorderLeft.

charSizeHorizontalBorderRight

horizontalBorderRight must be a multiple of charSizeHorizontalBorderRight.

charSizeVerticalBorderTop

verticalBorderTop must be a multiple of charSizeVerticalBorderTop.

charSizeVerticalBorderBottom

verticalBorderBottom must be a multiple of charSizeVerticalBorderBottom.

charSizeHorizontalTotal

(horizontalActive + horizontalBlanking) must be a multiple of charSizeHorizontalTotal.

charSizeVerticalTotal

(verticalActive + verticalBlanking) must be a multiple of charSizeVerticalTotal.

__reservedE

Set to zero.
minHorizontalActiveClocks

minimum value of horizontalActive.

maxHorizontalActiveClocks

maximum value of horizontalActive.

minHorizontalBlankingClocks

minimum value of horizontalBlanking.

maxHorizontalBlankingClocks

maximum value of horizontalBlanking.

minHorizontalSyncOffsetClocks

minimum value of horizontalSyncOffset.

maxHorizontalSyncOffsetClocks

maximum value of horizontalSyncOffset.

minHorizontalPulseWidthClocks

minimum value of horizontalPulseWidth.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

708

IOGraphicsTypes.h User-Space Reference Data Types

maxHorizontalPulseWidthClocks

maximum value of horizontalPulseWidth.

minVerticalActiveClocks

minimum value of verticalActive.

maxVerticalActiveClocks

maximum value of verticalActive.

minVerticalBlankingClocks

minimum value of verticalBlanking.

maxVerticalBlankingClocks

maximum value of verticalBlanking.

minVerticalSyncOffsetClocks

minimum value of verticalSyncOffset.

maxVerticalSyncOffsetClocks

maximum value of verticalSyncOffset.

minVerticalPulseWidthClocks

minimum value of verticalPulseWidth.

maxVerticalPulseWidthClocks

maximum value of verticalPulseWidth.

minHorizontalBorderLeft

minimum value of horizontalBorderLeft.

maxHorizontalBorderLeft

maximum value of horizontalBorderLeft.

minHorizontalBorderRight

minimum value of horizontalBorderRight.

maxHorizontalBorderRight

maximum value of horizontalBorderRight.

minVerticalBorderTop

minimum value of verticalBorderTop.

maxVerticalBorderTop

maximum value of verticalBorderTop.

minVerticalBorderBottom

minimum value of verticalBorderBottom.

maxVerticalBorderBottom

maximum value of verticalBorderBottom.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

709

IOGraphicsTypes.h User-Space Reference Data Types

maxNumLinks

number of links supported, if zero, 1 link is assumed.

minLink0PixelClock

minimum pixel clock for link 0 (kHz).

maxLink0PixelClock

maximum pixel clock for link 0 (kHz).

minLink1PixelClock

minimum pixel clock for link 1 (kHz).

maxLink1PixelClock

maximum pixel clock for link 1 (kHz).

__reservedF

Set to zero. Discussion This structure is used to define the limits for modes programmed as detailed timings by the OS. The VESA EDID is useful background information for many of these fields. A data property with this structure under the key kIOFBTimingRangeKey in a framebuffer will allow the OS to program detailed timings that fall within its range.

IOHardwareCursorDescriptor
A structure defining the format of a hardware cursor.

struct IOHardwareCursorDescriptor { UInt16 majorVersion; UInt16 minorVersion; UInt32 height; UInt32 width; UInt32 bitDepth; // bits per pixel, or a QD/QT pixel type UInt32 maskBitDepth; // unused UInt32 numColors; // number of colors in the colorMap. ie. UInt32 *colorEncodings; UInt32 flags; UInt32 supportedSpecialEncodings; UInt32 specialEncodings[16]; };

Fields
majorVersion

Set to kHardwareCursorDescriptorMajorVersion.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

710

IOGraphicsTypes.h User-Space Reference Data Types

minorVersion

Set to kHardwareCursorDescriptorMinorVersion.
height

Maximum size of the cursor.

width

Maximum size of the cursor.

bitDepth

Number bits per pixel, or a QD/QT pixel type, for example kIO8IndexedPixelFormat, kIO32ARGBPixelFormat.
maskBitDepth

Unused.
numColors

Number of colors for indexed pixel types.

colorEncodings

An array pointer specifying the pixel values corresponding to the indices into the color table, for indexed pixel types.
flags

None defined, set to zero.

supportedSpecialEncodings

Mask of supported special pixel values, eg. kTransparentEncodedPixel, kInvertingEncodedPixel.

specialEncodings

Array of pixel values for each supported special encoding. Discussion This structure is used by IOFramebuffer to define the format of a hardware cursor.

IOHardwareCursorInfo
A structure defining the converted data of a hardware cursor.

struct IOHardwareCursorInfo { UInt16 majorVersion; UInt16 minorVersion; UInt32 cursorHeight; UInt32 cursorWidth; // nil or big enough for hardware's max colors IOColorEntry *colorMap; UInt8 *hardwareCursorData; UInt16 cursorHotSpotX;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

711

IOGraphicsTypes.h User-Space Reference Data Types

UInt16 cursorHotSpotY; UInt32 reserved[5]; };

Fields
majorVersion

Set to kHardwareCursorInfoMajorVersion.
minorVersion

Set to kHardwareCursorInfoMinorVersion.
cursorHeight

The actual size of the cursor is returned.

cursorWidth

The actual size of the cursor is returned.

colorMap

Pointer to array of IOColorEntry structures, with the number of elements set by the numColors field of the IOHardwareCursorDescriptor. Zero should be passed for direct pixel formats.
hardwareCursorData

Buffer to receive the converted cursor data.

cursorHotSpotX

Cursor's hotspot.
cursorHotSpotY

Cursor's hotspot.
reserved

Reserved, set to zero. Discussion This structure is used by IOFramebuffer to return the data of a hardware cursor by convertCursorImage() after conversion based on the IOHardwareCursorDescriptor passed to that routine.

IOPixelInformation
A structure defining the format of a framebuffer.

struct IOPixelInformation { UInt32 bytesPerRow; UInt32 bytesPerPlane; UInt32 bitsPerPixel; UInt32 pixelType;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

712

IOGraphicsTypes.h User-Space Reference Data Types

UInt32 componentCount; UInt32 bitsPerComponent; UInt32 componentMasks[ 8 * 2 ]; IOPixelEncoding pixelFormat; UInt32 flags; UInt32 activeWidth; UInt32 activeHeight; UInt32 reserved[ 2 ]; };

Fields
bytesPerRow

The number of bytes per row.

bytesPerPlane

Not used.
bitsPerPixel

The number of bits per pixel, including unused bits and alpha.
pixelType

One of kIOCLUTPixels (indexed pixels with changeable CLUT), kIORGBDirectPixels (direct pixels).
componentCount

One for indexed pixels, three for direct pixel formats.

bitsPerComponent

Number of bits per component in each pixel.

componentMasks

Mask of the bits valid for each component of the pixel - in R, G, B order for direct pixels.
pixelFormat

String description of the pixel format - IO32BitDirectPixels, IO16BitDirectPixels etc.

flags

None defined - set to zero.

activeWidth

Number of pixels visible per row.

activeHeight

Number of visible pixel rows.

reserved

Set to zero. Discussion This structure is used by IOFramebuffer to define the format of the pixels.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

713

IOHIDBase.h Reference

Declared in

IOHIDBase.h

Overview
Included Headers

Callbacks
See the Overview for header-level documentation.

IOHIDCallback

typedef void ( IOHIDCallback)( void context, IOReturn result, void *sender);

Parameters
context

void * pointer to your data, often a pointer to an object.

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

714

IOHIDBase.h Reference Callbacks

Discussion Type and arguments of callout C function that is used when a completion routine is called. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

IOHIDDeviceCallback

typedef void ( *IOHIDDeviceCallback) ( void *context, IOReturn result, void *sender, IOHIDDeviceRef device);

Parameters
context

void * pointer to more data.

result

Completion result of desired operation.

device

IOHIDDeviceRef containing the sending device. Discussion Type and arguments of callout C function that is used when a device routine is called. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

IOHIDReportCallback

typedef void ( IOHIDReportCallback) ( void context, IOReturn result, void *sender,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

715

IOHIDBase.h Reference Callbacks

IOHIDReportType type, uint32_t reportID, uint8_t *report, CFIndex reportLength);

Parameters
context

void * pointer to your data, often a pointer to an object.

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine.

type

The type of the report that was completed.

reportID

The ID of the report that was completed.

report

Pointer to the buffer containing the contents of the report.

reportLength

Size of the buffer received upon completion. Discussion Type and arguments of callout C function that is used when a HID report completion routine is called. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

IOHIDValueCallback

typedef void ( IOHIDValueCallback) ( void context, IOReturn result,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

716

IOHIDBase.h Reference Callbacks

void *sender, IOHIDValueRef value);

Parameters
context

void * pointer to more data.

result

Completion result of desired operation.

sender

Interface instance sending the completion routine.

value

IOHIDValueRef containing the returned element value. Discussion Type and arguments of callout C function that is used when an element value completion routine is called. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

IOHIDValueMultipleCallback

typedef void ( *IOHIDValueMultipleCallback) ( void *context, IOReturn result, void *sender, CFDictionaryRef multiple);

Parameters
context

void * pointer to more data.

result

Completion result of desired operation.

sender

Interface instance sending the completion routine.

multiple

CFDictionaryRef containing the returned element key value pairs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

717

IOHIDBase.h Reference Data Types

Discussion Type and arguments of callout C function that is used when an element value completion routine is called. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

Data Types
See the Overview for header-level documentation.

IOHIDDeviceRef

typedef struct __IOHIDDevice * IOHIDDeviceRef;

Discussion This is the type of a reference to the IOHIDDevice. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

IOHIDElementRef

typedef struct __IOHIDElement * IOHIDElementRef;

Discussion This is the type of a reference to the IOHIDElement. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

718

IOHIDBase.h Reference Constants

IOHIDValueRef

typedef struct __IOHIDValue * IOHIDValueRef;

Discussion This is the type of a reference to the IOHIDValue. Availability Available in OS X v10.5 and later. Declared in
IOHIDBase.h

Constants
See the Overview for header-level documentation.

IOHIDTransactionDirectionType
Direction for an IOHIDDeviceTransactionInterface.

enum { kIOHIDTransactionDirectionTypeInput, kIOHIDTransactionDirectionTypeOutput }; typedef uint32_t IOHIDTransactionDirectionType;

Constants
kIOHIDTransactionDirectionTypeInput

Transaction direction used for requesting element values from a device. Available in OS X v10.5 and later. Declared in IOHIDBase.h.
kIOHIDTransactionDirectionTypeOutput

Transaction direction used for dispatching element values to a device. Available in OS X v10.5 and later. Declared in IOHIDBase.h. See Also
IOHIDTransactionDirectionType (page 719)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

719

IOHIDBase.h Reference Constants

IOHIDTransactionOption
Options to be used in conjuntion with an IOHIDDeviceTransactionInterface.

enum { kIOHIDTransactionOptionDefaultOutputValue = 0x0001 };

Constants
kIOHIDTransactionOptionDefaultOutputValue

Option to set the default element value to be used with an IOHIDDeviceTransactionInterface of direction kIOHIDTransactionDirectionTypeOutput. Available in OS X v10.5 and later. Declared in IOHIDBase.h.

IOHIDValueScaleType
Describes different types of scaling that can be performed on element values.

enum { kIOHIDValueScaleTypeCalibrated, kIOHIDValueScaleTypePhysical }; typedef uint32_t IOHIDValueScaleType;

Constants
kIOHIDValueScaleTypeCalibrated

Type for value that is scaled with respect to the calibration properties. Available in OS X v10.5 and later. Declared in IOHIDBase.h.
kIOHIDValueScaleTypePhysical

Type for value that is scaled with respect to the physical min and physical max of the element. Available in OS X v10.5 and later. Declared in IOHIDBase.h. See Also
IOHIDValueScaleType (page 720)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

720

IOHIDDevice.h User-Space Reference

Declared in

IOHIDDevice.h

Overview
IOHIDDevice defines a Human Interface Device (HID) object, which interacts with an IOHIDDevicePlugIn object that typically maps to an object in the kernel. IOHIDDevice is used to communicate with a single HID device in order to obtain or set device properties, element values, and reports. IOHIDDevice is also a CFType object and as such conforms to all the conventions expected such object. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts n the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDDevice.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDDevice.h.

Included Headers

Functions
See the Overview for header-level documentation.

IOHIDDeviceClose
Closes communication with a HID device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

721

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT IOReturn IOHIDDeviceClose( IOHIDDeviceRef device, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
options

Option bits to be sent down to the device. Return Value Returns kIOReturnSuccess if successful. Discussion This closes a link between the client's task and the actual device. Availability Available in OS X v10.5 and later.
Related Sample Code HID Dumper

Declared in
IOHIDDevice.h

IOHIDDeviceConformsTo
Convenience function that scans the Application Collection elements to see if it conforms to the provided usagePage and usage.

CF_EXPORT Boolean IOHIDDeviceConformsTo( IOHIDDeviceRef device, uint32_t usagePage, uint32_t usage) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
usagePage

Device usage page

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

722

IOHIDDevice.h User-Space Reference Functions

usage

Device usage Return Value Returns TRUE if device conforms to provided usage. Discussion Examples of Application Collection usages pairs are: usagePage = kHIDPage_GenericDesktop usage = kHIDUsage_GD_Mouse
or

usagePage = kHIDPage_GenericDesktop usage = kHIDUsage_GD_Keyboard Availability Available in OS X v10.5 and later.

Related Sample Code HID LED test tool

Declared in
IOHIDDevice.h

IOHIDDeviceCopyMatchingElements
Obtains HID elements that match the criteria contained in the matching dictionary.

CF_EXPORT CFArrayRef IOHIDDeviceCopyMatchingElements( IOHIDDeviceRef device, CFDictionaryRef matching, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
matching

CFDictionaryRef containg element matching criteria.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

723

IOHIDDevice.h User-Space Reference Functions

options

Reserved for future use. Return Value Returns CFArrayRef containing multiple IOHIDElement object. Discussion Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result in all device elements being returned. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDDevice.h

IOHIDDeviceCopyValueMultiple
Copies a values for multiple elements.

CF_EXPORT IOReturn IOHIDDeviceCopyValueMultiple( IOHIDDeviceRef device, CFArrayRef elements, CFDictionaryRef *pMultiple) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
elements

CFArrayRef containing multiple IOHIDElementRefs whose values are to be obtained.

pMultiple

Pointer to CFDictionaryRef where the keys are the provided elements and the values are the requested values.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

724

IOHIDDevice.h User-Space Reference Functions

Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves synchronously and return back immediately for input type element. If requesting a value for a feature element, this will block until the report has been issued to the device. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceCopyValueMultipleWithCallback
Copies a values for multiple elements and returns status via a completion callback.

CF_EXPORT IOReturn IOHIDDeviceCopyValueMultipleWithCallback( IOHIDDeviceRef device, CFArrayRef elements, CFDictionaryRef *pMultiple, CFTimeInterval timeout, IOHIDValueMultipleCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
elements

CFArrayRef containing multiple IOHIDElementRefs whose values are to be obtained.

pMultiple

Pointer to CFDictionaryRef where the keys are the provided elements and the values are the requested values.
timeout

CFTimeInterval containing the timeout.

callback

Pointer to a callback method of type IOHIDValueMultipleCallback.

context

Pointer to data to be passed to the callback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

725

IOHIDDevice.h User-Space Reference Functions

Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronusly and is only relevent for either output or feature type elements. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceCreate
Creates an element from an io_service_t.

CF_EXPORT IOHIDDeviceRef IOHIDDeviceCreate( CFAllocatorRef allocator, io_service_t service) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

Allocator to be used during creation.

io_service_t

Reference to service object in the kernel. Return Value Returns a new IOHIDDeviceRef. Discussion The io_service_t passed in this method must reference an object in the kernel of type IOHIDDevice. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceGetProperty
Obtains a property from an IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

726

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT CFTypeRef IOHIDDeviceGetProperty( IOHIDDeviceRef device, CFStringRef key) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
key

CFStringRef containing key to be used when querying the device. Return Value Returns CFTypeRef containing the property. Discussion Property keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDDevice.h

IOHIDDeviceGetReport
Obtains a report from the device.

CF_EXPORT IOReturn IOHIDDeviceGetReport( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, uint8_t *report, CFIndex *pReportLength) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

727

IOHIDDevice.h User-Space Reference Functions

reportType

Type of report being requested.

reportID

ID of the report being requested.

report

Pointer to preallocated buffer in which to copy inbound report data.

pReportLength

Pointer to length of preallocated buffer. This value will be modified to refect the length of the returned report. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves synchronously and will block until the report has been received from the device. This is only intended for feature reports because of sporadic devicesupport for polling input reports. Please defer to using IOHIDDeviceRegisterInputReportCallback for obtaining input reports. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceGetReportWithCallback
Obtains a report from the device.

CF_EXPORT IOReturn IOHIDDeviceGetReportWithCallback( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, uint8_t *report, CFIndex *pReportLength, CFTimeInterval timeout, IOHIDReportCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

728

IOHIDDevice.h User-Space Reference Functions

reportType

Type of report being requested.

reportID

ID of the report being requested.

report

Pointer to preallocated buffer in which to copy inbound report data.

pReportLength

Pointer to length of preallocated buffer. Pointer to length of preallocated buffer. This value will be modified to refect the length of the returned report.
callback

Pointer to a callback method of type IOHIDReportCallback.

context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronously and will block until the report has been received from the device. This is only intended for feature reports because of sporadic devicesupport for polling input reports. Please defer to using IOHIDDeviceRegisterInputReportCallback for obtaining input reports. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceGetService
Returns the io_service_t for an IOHIDDevice, if it has one.

CF_EXPORT io_service_t IOHIDDeviceGetService( IOHIDDeviceRef device) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

729

IOHIDDevice.h User-Space Reference Functions

Return Value Returns the io_service_t if the IOHIDDevice has one, or MACH_PORT_NULL if it does not. Discussion If the IOHIDDevice references an object in the kernel, this is used to get the io_service_t for that object. Availability Available in OS X v10.6 and later. Declared in
IOHIDDevice.h

IOHIDDeviceGetTypeID
Returns the type identifier of all IOHIDDevice instances.

CF_EXPORT CFTypeID IOHIDDeviceGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDDevice.h

IOHIDDeviceGetValue
Gets a value for an element.

CF_EXPORT IOReturn IOHIDDeviceGetValue( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef *pValue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

730

IOHIDDevice.h User-Space Reference Functions

element

IOHIDElementRef whose value is to be obtained.

pValue

Pointer to IOHIDValueRef to be obtained. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves synchronously and return back immediately for input type element. If requesting a value for a feature element, this will block until the report has been issued to the device. If obtaining values for multiple elements you may want to consider using IOHIDDeviceCopyValueMultiple or IOHIDTransaction. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDDevice.h

IOHIDDeviceGetValueWithCallback
Gets a value for an element and returns status via a completion callback.

CF_EXPORT IOReturn IOHIDDeviceGetValueWithCallback( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef *pValue, CFTimeInterval timeout, IOHIDValueCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
element

IOHIDElementRef whose value is to be obtained.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

731

IOHIDDevice.h User-Space Reference Functions

pValue

Pointer to IOHIDValueRef to be passedback.

timeout

CFTimeInterval containing the timeout.

callback

Pointer to a callback method of type IOHIDValueCallback.

context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronusly and is only relevent for either output or feature type elements. If obtaining values for multiple elements you may want to consider using IOHIDDeviceCopyValueMultipleWithCallback or IOHIDTransaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceOpen
Opens a HID device for communication.

CF_EXPORT IOReturn IOHIDDeviceOpen( IOHIDDeviceRef device, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
options

Option bits to be sent down to the device. Return Value Returns kIOReturnSuccess if successful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

732

IOHIDDevice.h User-Space Reference Functions

Discussion Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes a link between the client's task and the actual device. To establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option. Availability Available in OS X v10.5 and later.
Related Sample Code HID Dumper

Declared in
IOHIDDevice.h

IOHIDDeviceRegisterInputReportCallback
Registers a callback to be used when an input report is issued by the device.

CF_EXPORT void IOHIDDeviceRegisterInputReportCallback( IOHIDDeviceRef device, uint8_t *report, CFIndex reportLength, IOHIDReportCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
report

Pointer to preallocated buffer in which to copy inbound report data.

reportLength

Length of preallocated buffer.

callback

Pointer to a callback method of type IOHIDReportCallback.

context

Pointer to data to be passed to the callback. Discussion An input report is an interrupt driver report issued by the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

733

IOHIDDevice.h User-Space Reference Functions

Availability Available in OS X v10.5 and later. Declared in

IOHIDDevice.h

IOHIDDeviceRegisterInputValueCallback
Registers a callback to be used when an input value is issued by the device.

CF_EXPORT void IOHIDDeviceRegisterInputValueCallback( IOHIDDeviceRef device, IOHIDValueCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
callback

Pointer to a callback method of type IOHIDValueCallback.

context

Pointer to data to be passed to the callback. Discussion An input element refers to any element of type kIOHIDElementTypeInput and is usually issued by interrupt driven reports. If more specific element values are desired, you can specify matching criteria via IOHIDDeviceSetInputValueMatching and IOHIDDeviceSetInputValueMatchingMultiple. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDDevice.h

IOHIDDeviceRegisterRemovalCallback
Registers a callback to be used when a IOHIDDevice is removed.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

734

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT void IOHIDDeviceRegisterRemovalCallback( IOHIDDeviceRef device, IOHIDCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
callback

Pointer to a callback method of type IOHIDCallback.

context

Pointer to data to be passed to the callback. Discussion In most cases this occurs when a device is unplugged. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceScheduleWithRunLoop
Schedules HID device with run loop.

CF_EXPORT void IOHIDDeviceScheduleWithRunLoop( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

735

IOHIDDevice.h User-Space Reference Functions

Discussion Formally associates device with client's run loop. Scheduling this device with the run loop is necessary before making use of any asynchronous APIs. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceSetInputValueMatching
Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

CF_EXPORT void IOHIDDeviceSetInputValueMatching( IOHIDDeviceRef device, CFDictionaryRef matching) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDDevice.
matching

CFDictionaryRef containg device matching criteria. Discussion Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the hid manager to release previously matched input elements and restart the matching process using the revised criteria. If interested in multiple, specific device elements, please defer to using IOHIDDeviceSetInputValueMatchingMultiple. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceSetInputValueMatchingMultiple
Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

736

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT void IOHIDDeviceSetInputValueMatchingMultiple( IOHIDDeviceRef device, CFArrayRef multiple) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDDevice.
multiple

CFArrayRef containing multiple CFDictionaryRef objects containg input element matching criteria. Discussion Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. This method is useful if interested in multiple, specific elements . Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDDevice.h

IOHIDDeviceSetProperty
Sets a property for an IOHIDDevice.

CF_EXPORT Boolean IOHIDDeviceSetProperty( IOHIDDeviceRef device, CFStringRef key, CFTypeRef property) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
key

CFStringRef containing key to be used when modifiying the device property.

property

CFTypeRef containg the property to be set.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

737

IOHIDDevice.h User-Space Reference Functions

Return Value Returns TRUE if successful. Discussion Property keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDDevice.h

IOHIDDeviceSetReport
Sends a report to the device.

CF_EXPORT IOReturn IOHIDDeviceSetReport( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, const uint8_t *report, CFIndex reportLength) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
reportType

Type of report being sent.

reportID

ID of the report being sent. If the device supports multiple reports, this should also be set in the first byte of the report.
report

The report bytes to be sent to the device.

reportLength

The length of the report to be sent to the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

738

IOHIDDevice.h User-Space Reference Functions

Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type reports. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceSetReportWithCallback
Sends a report to the device.

CF_EXPORT IOReturn IOHIDDeviceSetReportWithCallback( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, const uint8_t *report, CFIndex reportLength, CFTimeInterval timeout, IOHIDReportCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
reportType

Type of report being sent.

reportID

ID of the report being sent. If the device supports multiple reports, this should also be set in the first byte of the report.
report

The report bytes to be sent to the device.

reportLength

The length of the report to be sent to the device.

timeout

CFTimeInterval containing the timeout.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

739

IOHIDDevice.h User-Space Reference Functions

callback

Pointer to a callback method of type IOHIDReportCallback.

context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type reports. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceSetValue
Sets a value for an element.

CF_EXPORT IOReturn IOHIDDeviceSetValue( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
element

IOHIDElementRef whose value is to be modified.

value

IOHIDValueRef containing value to be set. Return Value Returns kIOReturnSuccess if successful.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

740

IOHIDDevice.h User-Space Reference Functions

Discussion This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type elements. If setting values for multiple elements you may want to consider using IOHIDDeviceSetValueMultiple or IOHIDTransaction. Availability Available in OS X v10.5 and later.
Related Sample Code HID LED test tool

Declared in
IOHIDDevice.h

IOHIDDeviceSetValueMultiple
Sets multiple values for multiple elements.

CF_EXPORT IOReturn IOHIDDeviceSetValueMultiple( IOHIDDeviceRef device, CFDictionaryRef multiple) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
muliple

CFDictionaryRef where key is IOHIDElementRef and value is IOHIDValueRef. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type elements. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

741

IOHIDDevice.h User-Space Reference Functions

IOHIDDeviceSetValueMultipleWithCallback
Sets multiple values for multiple elements and returns status via a completion callback.

CF_EXPORT IOReturn IOHIDDeviceSetValueMultipleWithCallback( IOHIDDeviceRef device, CFDictionaryRef multiple, CFTimeInterval timeout, IOHIDValueMultipleCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
muliple

CFDictionaryRef where key is IOHIDElementRef and value is IOHIDValueRef.

timeout

CFTimeInterval containing the timeout.

callback

Pointer to a callback method of type IOHIDValueMultipleCallback.

context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronously and will invoke the callback once the report has been issued to the device. It is only relevent for either output or feature type elements. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceSetValueWithCallback
Sets a value for an element and returns status via a completion callback.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

742

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT IOReturn IOHIDDeviceSetValueWithCallback( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef value, CFTimeInterval timeout, IOHIDValueCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
element

IOHIDElementRef whose value is to be modified.

value

IOHIDValueRef containing value to be set.

timeout

CFTimeInterval containing the timeout.

callback

Pointer to a callback method of type IOHIDValueCallback.

context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful. Discussion This method behaves asynchronously and will invoke the callback once the report has been issued to the device. It is only relevent for either output or feature type elements. If setting values for multiple elements you may want to consider using IOHIDDeviceSetValueWithCallback or IOHIDTransaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDDevice.h

IOHIDDeviceUnscheduleFromRunLoop
Unschedules HID device with run loop.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

743

IOHIDDevice.h User-Space Reference Functions

CF_EXPORT void IOHIDDeviceUnscheduleFromRunLoop( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
device

Reference to an IOHIDDevice.
runLoop

RunLoop to be used when unscheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when unscheduling any asynchronous activity. Discussion Formally disassociates device with client's run loop. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDDevice.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

744

IOHIDDevicePlugIn.h Reference

Declared in

IOHIDDevicePlugIn.h

Overview
This documentation describes the details of the programming interface for accessing Human Interface Devices and interfaces from code running in user space. It is intended that user mode HID drivers properly inplement all interfaces described here in order to be visible via the HID Manager. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDLib.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDDevicePlugIn.h.

Included Headers

<sys/cdefs.h> <CoreFoundation/CoreFoundation.h> <CoreFoundation/CFPlugInCOM.h> <IOKit/IOTypes.h> <IOKit/IOReturn.h> <IOKit/IOCFPlugIn.h> <IOKit/hid/IOHIDBase.h> <IOKit/hid/IOHIDKeys.h> <IOKit/hid/IOHIDLibObsolete.h>

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

745

IOHIDDevicePlugIn.h Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define kIOHIDDeviceDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x47, 0x4b, 0xdc, 0x8e, 0x9f, 0x4a, 0x11, 0xda, \ 0xb3, 0x66, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2 ) #define kIOHIDDeviceFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x13, 0xAA, 0x9C, 0x44, 0x6F, 0x1B, 0x11, 0xD4, \ 0x90, 0x7C, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5) #define kIOHIDDeviceQueueInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

746

IOHIDDevicePlugIn.h Reference Constants

0x2e, 0xc7, 0x8b, 0xdb, 0x9f, 0x4e, 0x11, 0xda, \ 0xb6, 0x5c, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2) #define kIOHIDDeviceTransactionInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x1f, 0x2e, 0x78, 0xfa, 0x9f, 0xfa, 0x11, 0xda, \ 0x90, 0xb4, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2) #define kIOHIDDeviceTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x7d, 0xde, 0xec, 0xa8, 0xa7, 0xb4, 0x11, 0xda, \ 0x8a, 0x0e,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

747

IOHIDDevicePlugIn.h Reference Constants

0x00, 0x14, 0x51, 0x97, 0x58, 0xef)

Constants
kIOHIDDeviceDeviceInterfaceID

This UUID constant is used to obtain a device interface corresponding to an IOHIDDevice service in the kernel. The type of this device interface is IOHIDDeviceDeviceInterface. This device interface is obtained after the IOCFPlugInInterface for the service itself has been obtained. Note: Please note that subsequent calls to QueryInterface with the UUID kIOHIDDeviceTransactionInterfaceID, will return a retained instance of an existing IOHIDDeviceTransactionInterface. Example:

IOCFPluginInterface IOHIDDeviceDeviceInterface IOReturn

iodev; dev; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOHIDDeviceDeviceInterfaceID), (LPVoid)&dev);

Available in OS X v10.5 and later. Declared in IOHIDDevicePlugIn.h.

kIOHIDDeviceFactoryID

This UUID constant is used internally by the system, and should not have to be used by any driver code to access the device interfaces. Available in OS X v10.0 and later. Declared in IOHIDDevicePlugIn.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

748

IOHIDDevicePlugIn.h Reference Constants

kIOHIDDeviceQueueInterfaceID

This UUID constant is used to obtain a queue interface corresponding to an IOHIDDevice service in the kernel. The type of this queue interface is IOHIDDeviceQueueInterface. This device interface is obtained after the device interface for the service itself has been obtained. Note: Please note that subsequent calls to QueryInterface with the UUID kIOHIDDeviceQueueInterfaceID, will return a retained instance of a new IOHIDDeviceQueueInterface. Example:

IOCFPluginInterface IOHIDDeviceQueueInterface IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOHIDDeviceQueueInterfaceID), (LPVoid)&intf);

Available in OS X v10.5 and later. Declared in IOHIDDevicePlugIn.h.

kIOHIDDeviceTransactionInterfaceID

This UUID constant is used to obtain a transaction interface corresponding to an IOHIDDevice service in the kernel. The type of this queue interface is IOHIDDeviceTransactionInterface. This device interface is obtained after the device interface for the service itself has been obtained. Note: Please note that subsequent calls to QueryInterface with the UUID kIOHIDDeviceTransactionInterfaceID, will return a retained instance of a new IOHIDDeviceTransactionInterface. Example:

IOCFPluginInterface IOHIDDeviceTransactionInterface IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOHIDDeviceTransactionInterfaceID), (LPVoid)&intf);

Available in OS X v10.5 and later. Declared in IOHIDDevicePlugIn.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

749

IOHIDDevicePlugIn.h Reference Constants

kIOHIDDeviceTypeID

This UUID constant is used to obtain a device interface corresponding to an io_service_t corresponding to an IOHIDDevice in the kernel. Once you have obtained the IOCFPlugInInterface for the service, you must use the QueryInterface function to obtain the device interface for the user client itself. Example:

io_service_t IOCFPlugInInterface SInt32 IOReturn

hidDeviceRef; **iodev; score; err;

// obtained earlier // fetching this now // not used

err = IOCreatePlugInInterfaceForService(hidDeviceRef, kIOHIDDeviceTypeID, kIOCFPlugInInterfaceID, &iodev, &score);

Available in OS X v10.5 and later. Declared in IOHIDDevicePlugIn.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

750

IOHIDElement.h Reference

Declared in

IOHIDElement.h

Overview
IOHIDElement defines a parsed item contained within a Human Interface Device (HID) object. It is used to obtain properties of the parsed. It can also be used to set properties such as calibration settings. IOHIDElement is a CFType object and as such conforms to all the conventions expected such object. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDElement.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDElement.h.

Included Headers

<CoreFoundation/CoreFoundation.h> <IOKit/hid/IOHIDKeys.h> <IOKit/hid/IOHIDBase.h>

Functions
See the Overview for header-level documentation.

IOHIDElementAttach
Establish a relationship between one or more elements.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

751

IOHIDElement.h Reference Functions

CF_EXPORT void IOHIDElementAttach( IOHIDElementRef element, IOHIDElementRef toAttach) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
toAttach

The element to be attached. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Discussion This is useful for grouping HID elements with related functionality. Availability Available in OS X v10.5 and later. Declared in
IOHIDElement.h

IOHIDElementCollectionType
Retrieves the collection type for the element.

CF_EXPORT IOHIDElementCollectionType IOHIDElementGetCollectionType( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the IOHIDElementCollectionType for the element. Discussion The value returned by this method only makes sense if the element type is kIOHIDElementTypeCollection.

IOHIDElementCopyAttached
Obtain attached elements.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

752

IOHIDElement.h Reference Functions

CF_EXPORT CFArrayRef IOHIDElementCopyAttached( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns a copy of the current attached elements. Discussion Attached elements are those that have been grouped via IOHIDElementAttach. Availability Available in OS X v10.5 and later. Declared in
IOHIDElement.h

IOHIDElementCreateWithDictionary
Creates an element from a dictionary.

CF_EXPORT IOHIDElementRef IOHIDElementCreateWithDictionary( CFAllocatorRef allocator, CFDictionaryRef dictionary) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

Allocator to be used during creation.

dictionary

dictionary containing values in which to create element. Return Value Returns a new IOHIDElementRef. Discussion The dictionary should contain keys defined in IOHIDKeys.h and start with kIOHIDElement. This call is meant be used by a IOHIDDeviceDeviceInterface object. Availability Available in OS X v10.5 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

753

IOHIDElement.h Reference Functions

Declared in
IOHIDElement.h

IOHIDElementDetach
Remove a relationship between one or more elements.

CF_EXPORT void IOHIDElementDetach( IOHIDElementRef element, IOHIDElementRef toDetach) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
toDetach

The element to be detached. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Discussion This is useful for grouping HID elements with related functionality. Availability Available in OS X v10.5 and later. Declared in
IOHIDElement.h

IOHIDElementGetChildren
Returns the children for the element.

CF_EXPORT CFArrayRef IOHIDElementGetChildren( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns an CFArrayRef containing element objects of type IOHIDElementRef.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

754

IOHIDElement.h Reference Functions

Discussion An element of type kIOHIDElementTypeCollection usually contains children. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetCollectionType
Retrieves the collection type for the element.

CF_EXPORT IOHIDElementCollectionType IOHIDElementGetCollectionType( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

755

IOHIDElement.h Reference Functions

IOHIDElementGetCookie
Retrieves the cookie for the element.

CF_EXPORT IOHIDElementCookie IOHIDElementGetCookie( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the IOHIDElementCookie for the element. Discussion The IOHIDElementCookie represent a unique identifier for an element within a device. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetDevice
Obtain the device associated with the element.

CF_EXPORT IOHIDDeviceRef IOHIDElementGetDevice( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

IOHIDElement to be queried. Return Value Returns the a reference to the device.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

756

IOHIDElement.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetLogicalMax
Returns the maximum value possible for the element.

CF_EXPORT CFIndex IOHIDElementGetLogicalMax( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the logical maximum. Discussion This corresponds to the logical maximum, which indicates the upper bounds of a variable element. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetLogicalMin
Returns the minimum value possible for the element.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

757

IOHIDElement.h Reference Functions

CF_EXPORT CFIndex IOHIDElementGetLogicalMin( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the logical minimum. Discussion This corresponds to the logical minimun, which indicates the lower bounds of a variable element. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetMax
Returns the maximum value possible for the element.

CF_EXPORT CFIndex IOHIDElementGetLogicalMax( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

758

IOHIDElement.h Reference Functions

IOHIDElementGetName
Returns the name for the element.

CF_EXPORT CFStringRef IOHIDElementGetName( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns CFStringRef containing the element name. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetParent
Returns the parent for the element.

CF_EXPORT IOHIDElementRef IOHIDElementGetParent( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns an IOHIDElementRef referencing the parent element. Discussion The parent element can be an element of type kIOHIDElementTypeCollection.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

759

IOHIDElement.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetPhysicalMax
Returns the scaled maximum value possible for the element.

CF_EXPORT CFIndex IOHIDElementGetPhysicalMax( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the physical maximum. Discussion Maximum value for the physical extent of a variable element. This represents the value for the logical maximum with units applied to it. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

760

IOHIDElement.h Reference Functions

IOHIDElementGetPhysicalMin
Returns the scaled minimum value possible for the element.

CF_EXPORT CFIndex IOHIDElementGetPhysicalMin( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the physical minimum. Discussion Minimum value for the physical extent of a variable element. This represents the value for the logical minimum with units applied to it. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetProperty
Returns the an element property.

CF_EXPORT CFTypeRef IOHIDElementGetProperty( IOHIDElementRef element, CFStringRef key) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
key

The key to be used when querying the element.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

761

IOHIDElement.h Reference Functions

Return Value Returns the property. Discussion Property keys are prefixed by kIOHIDElement and declared in IOHIDKeys.h. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetReportCount
Returns the report count for the element.

CF_EXPORT uint32_t IOHIDElementGetReportCount( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the report count. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

762

IOHIDElement.h Reference Functions

IOHIDElementGetReportID
Returns the report ID for the element.

CF_EXPORT uint32_t IOHIDElementGetReportID( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the report ID. Discussion The report ID represents what report this particular element belongs to. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetReportSize
Returns the report size in bits for the element.

CF_EXPORT uint32_t IOHIDElementGetReportSize( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the report size.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

763

IOHIDElement.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetType
Retrieves the type for the element.

CF_EXPORT IOHIDElementType IOHIDElementGetType( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the IOHIDElementType for the element. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetTypeID
Returns the type identifier of all IOHIDElement instances.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

764

IOHIDElement.h Reference Functions

CF_EXPORT CFTypeID IOHIDElementGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetUnit
Returns the unit property for the element.

CF_EXPORT uint32_t IOHIDElementGetUnit( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the unit. Discussion The unit property is described in more detail in Section 6.2.2.7 of the "Device Class Definition for Human Interface Devices(HID)" Specification, Version 1.11. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

765

IOHIDElement.h Reference Functions

IOHIDElementGetUnitExponent
Returns the unit exponenet in base 10 for the element.

CF_EXPORT uint32_t IOHIDElementGetUnitExponent( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the unit exponent. Discussion The unit exponent property is described in more detail in Section 6.2.2.7 of the "Device Class Definition for Human Interface Devices(HID)" Specification, Version 1.11. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetUsage
Retrieves the usage for an element.

CF_EXPORT uint32_t IOHIDElementGetUsage( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the usage for the element.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

766

IOHIDElement.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDElement.h

IOHIDElementGetUsagePage
Retrieves the usage page for an element.

CF_EXPORT uint32_t IOHIDElementGetUsagePage( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns the usage page for the element. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDElement.h

IOHIDElementHasNullState
Returns the null state property for the element.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

767

IOHIDElement.h Reference Functions

CF_EXPORT Boolean IOHIDElementHasNullState( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns TRUE if null state or FALSE if no null state. Discussion Indicates whether the element has a state in which it is not sending meaningful data. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementHasPreferredState
Returns the preferred state property for the element.

CF_EXPORT Boolean IOHIDElementHasPreferredState( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns TRUE if preferred state or FALSE if no preferred state. Discussion Indicates whether the element has a preferred state to which it will return when the user is not physically interacting with the control.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

768

IOHIDElement.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementIsArray
Returns the array property for the element.

CF_EXPORT Boolean IOHIDElementIsArray( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns TRUE if array or FALSE if variable. Discussion Indicates whether the element represents variable or array data values. Variable values represent data from a physical control. An array returns an index in each field that corresponds to the pressed button (like keyboard scan codes).
Note:

The HID Manager will represent most elements as "variable" including the possible usages of an array.

Array indices will remain as "array" elements with a usage of 0xffffffff. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

769

IOHIDElement.h Reference Functions

IOHIDElementIsNonLinear
Returns the linear property for the element.

CF_EXPORT Boolean IOHIDElementIsNonLinear( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns TRUE if non linear or FALSE if linear. Discussion Indicates whether the value for the element has been processed in some way, and no longer represents a linear relationship between what is measured and the value that is reported. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementIsRelative
Returns the relative property for the element.

CF_EXPORT Boolean IOHIDElementIsRelative( IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined. Return Value Returns TRUE if wrapping or FALSE if non-wrapping. Discussion Wrap indicates whether the data "rolls over" when reaching either the extreme high or low value. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

IOHIDElementSetProperty
Sets an element property.

CF_EXPORT Boolean IOHIDElementSetProperty( IOHIDElementRef element, CFStringRef key, CFTypeRef property) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
element

The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
key

The key to be used when querying the element.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

772

IOHIDElement.h Reference Functions

Return Value Returns TRUE if successful. Discussion This method can be used to set arbitrary element properties, such as application specific references. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDElement.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

773

IOHIDKeys.h User-Space Reference

Declared in

IOHIDKeys.h

Overview
Included Headers

Data Types
See the Overview for header-level documentation.

IOHIDElementCookie
Abstract data type used as a unique identifier for an element.

#ifdef __LP64__ typedef uint32_t IOHIDElementCookie; #else typedef void * IOHIDElementCookie; #endif

Availability Available in OS X v10.0 and later. Declared in

IOHIDKeys.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

774

IOHIDKeys.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

HID Device Property Keys

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOHIDCountryCodeKey "CountryCode" kIOHIDDeviceKeyboardLanguageKey "DeviceKeyboardLanguage" kIOHIDDeviceKeyboardStandardTypeKey "DeviceKeyboardStandardType" kIOHIDDeviceUsageKey "DeviceUsage" kIOHIDDeviceUsagePageKey "DeviceUsagePage" kIOHIDDeviceUsagePairsKey "DeviceUsagePairs" kIOHIDLocationIDKey "LocationID" kIOHIDManufacturerKey "Manufacturer" kIOHIDMaxFeatureReportSizeKey "MaxFeatureReportSize" kIOHIDMaxInputReportSizeKey "MaxInputReportSize" kIOHIDMaxOutputReportSizeKey "MaxOutputReportSize" kIOHIDPrimaryUsageKey "PrimaryUsage" kIOHIDPrimaryUsagePageKey "PrimaryUsagePage" kIOHIDProductIDKey "ProductID" kIOHIDProductKey "Product" kIOHIDReportDescriptorKey "ReportDescriptor" kIOHIDReportIntervalKey "ReportInterval" kIOHIDResetKey "Reset" kIOHIDSerialNumberKey "SerialNumber" kIOHIDStandardTypeKey "StandardType" kIOHIDTransportKey "Transport" kIOHIDVendorIDKey "VendorID" kIOHIDVendorIDSourceKey "VendorIDSource" kIOHIDVersionNumberKey "VersionNumber"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

775

IOHIDKeys.h User-Space Reference Constants

Constants
kIOHIDCountryCodeKey

Keys that represent properties of a paticular device. Keys that represent properties of a paticular device. Can be added to your matching dictionary when refining searches for HID devices. Please note: kIOHIDPrimaryUsageKey and kIOHIDPrimaryUsagePageKey are no longer rich enough to describe a device's capabilities. Take, for example, a device that describes both a keyboard and a mouse in the same descriptor. The previous behavior was to only describe the keyboard behavior with the primary usage and usage page. Needless to say, this would sometimes cause a program interested in mice to skip this device when matching. Thus we have added 3 additional keys:

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

kIOHIDDeviceUsagePairsKey is used to represent an array of dictionaries containing key/value pairs referenced by kIOHIDDeviceUsageKey and kIOHIDDeviceUsagePageKey. These usage pairs describe all application type collections (behaviors) defined by the device. An application intersted in only matching on one criteria would only add the kIOHIDDeviceUsageKey and kIOHIDDeviceUsagePageKey keys to the matching dictionary. If it is interested in a device that has multiple behaviors, the application would instead add an array or dictionaries referenced by kIOHIDDeviceUsagePairsKey to his matching dictionary. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

776

IOHIDKeys.h User-Space Reference Constants

kIOHIDDeviceKeyboardLanguageKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

777

IOHIDKeys.h User-Space Reference Constants

kIOHIDDeviceKeyboardStandardTypeKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

778

IOHIDKeys.h User-Space Reference Constants

kIOHIDDeviceUsageKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

779

IOHIDKeys.h User-Space Reference Constants

kIOHIDDeviceUsagePageKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

780

IOHIDKeys.h User-Space Reference Constants

kIOHIDDeviceUsagePairsKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

781

IOHIDKeys.h User-Space Reference Constants

kIOHIDLocationIDKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

782

IOHIDKeys.h User-Space Reference Constants

kIOHIDManufacturerKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

783

IOHIDKeys.h User-Space Reference Constants

kIOHIDMaxFeatureReportSizeKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

784

IOHIDKeys.h User-Space Reference Constants

kIOHIDMaxInputReportSizeKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

785

IOHIDKeys.h User-Space Reference Constants

kIOHIDMaxOutputReportSizeKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

786

IOHIDKeys.h User-Space Reference Constants

kIOHIDPrimaryUsageKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

787

IOHIDKeys.h User-Space Reference Constants

kIOHIDPrimaryUsagePageKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

788

IOHIDKeys.h User-Space Reference Constants

kIOHIDProductIDKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

789

IOHIDKeys.h User-Space Reference Constants

kIOHIDProductKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

790

IOHIDKeys.h User-Space Reference Constants

kIOHIDReportDescriptorKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

791

IOHIDKeys.h User-Space Reference Constants

kIOHIDReportIntervalKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

792

IOHIDKeys.h User-Space Reference Constants

kIOHIDResetKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

793

IOHIDKeys.h User-Space Reference Constants

kIOHIDSerialNumberKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

794

IOHIDKeys.h User-Space Reference Constants

kIOHIDStandardTypeKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

795

IOHIDKeys.h User-Space Reference Constants

kIOHIDTransportKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

796

IOHIDKeys.h User-Space Reference Constants

kIOHIDVendorIDKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

797

IOHIDKeys.h User-Space Reference Constants

kIOHIDVendorIDSourceKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

798

IOHIDKeys.h User-Space Reference Constants

kIOHIDVersionNumberKey

kIOHIDDeviceUsageKey kIOHIDDeviceUsagePageKey kIOHIDDeviceUsagePairsKey

HID Element Dictionary Keys

#define #define #define #define #define #define #define #define #define #define #define #define

kIOHIDElementCollectionTypeKey "CollectionType" kIOHIDElementCookieKey "ElementCookie" kIOHIDElementDuplicateIndexKey "DuplicateIndex" kIOHIDElementFlagsKey "Flags" kIOHIDElementHasNullStateKey "HasNullState" kIOHIDElementHasPreferredStateKey "HasPreferredState" kIOHIDElementIsArrayKey "IsArray" kIOHIDElementIsNonLinearKey "IsNonLinear" kIOHIDElementIsRelativeKey "IsRelative" kIOHIDElementIsWrappingKey "IsWrapping" kIOHIDElementMaxKey "Max" kIOHIDElementMinKey "Min"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

799

IOHIDKeys.h User-Space Reference Constants

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOHIDElementNameKey "Name" kIOHIDElementParentCollectionKey "ParentCollection" kIOHIDElementReportCountKey "ReportCount" kIOHIDElementReportIDKey "ReportID" kIOHIDElementReportSizeKey "ReportSize" kIOHIDElementScaledMaxKey "ScaledMax" kIOHIDElementScaledMinKey "ScaledMin" kIOHIDElementSizeKey "Size" kIOHIDElementTypeKey "Type" kIOHIDElementUnitExponentKey "UnitExponent" kIOHIDElementUnitKey "Unit" kIOHIDElementUsageKey "Usage" kIOHIDElementUsagePageKey "UsagePage" kIOHIDElementValueLocationKey "ValueLocation" kIOHIDElementVendorSpecificKey "VendorSpecific"

Constants
kIOHIDElementCollectionTypeKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementCookieKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementFlagsKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

800

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementHasNullStateKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.1 and later. Declared in IOHIDKeys.h.
kIOHIDElementIsArrayKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.2 and later. Declared in IOHIDKeys.h.
kIOHIDElementIsNonLinearKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

801

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementMaxKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementReportCountKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.2 and later. Declared in IOHIDKeys.h.
kIOHIDElementReportIDKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

802

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementReportSizeKey

Keys that represent properties of a particular elements. These keys can also be added to a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.2 and later. Declared in IOHIDKeys.h.
kIOHIDElementScaledMaxKey

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

803

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementUnitKey

HID Element Match Keys

#define kIOHIDElementCookieMaxKey "ElementCookieMax" #define kIOHIDElementCookieMinKey "ElementCookieMin"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

804

IOHIDKeys.h User-Space Reference Constants

#define kIOHIDElementUsageMaxKey "UsageMax" #define kIOHIDElementUsageMinKey "UsageMin"

Constants
kIOHIDElementCookieMaxKey

Keys used for matching particular elements. These keys should only be used with a matching dictionary when searching for elements via copyMatchingElements. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCookieMinKey

Miscellaneous Defines

#define #define #define #define #define #define #define

kIOHIDElementCalibrationDeadZoneMaxKey "CalibrationDeadZoneMax" kIOHIDElementCalibrationDeadZoneMinKey "CalibrationDeadZoneMin" kIOHIDElementCalibrationGranularityKey "CalibrationGranularity" kIOHIDElementCalibrationMaxKey "CalibrationMax" kIOHIDElementCalibrationMinKey "CalibrationMin" kIOHIDElementCalibrationSaturationMaxKey "CalibrationSaturationMax" kIOHIDElementCalibrationSaturationMinKey "CalibrationSaturationMin"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

805

IOHIDKeys.h User-Space Reference Constants

#define kIOHIDElementKey "Elements" #define kIOHIDElementVendorSpecificKey "VendorSpecifc"

Constants
kIOHIDElementCalibrationDeadZoneMaxKey

The maximum bounds near the midpoint of a logical value in which the value is ignored. The dead zone property is used to allow for slight differences in the idle value returned by an element. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCalibrationDeadZoneMinKey

The minimum bounds near the midpoint of a logical value in which the value is ignored. The dead zone property is used to allow for slight differences in the idle value returned by an element. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCalibrationGranularityKey

The scale or level of detail returned in a calibrated element value. Values are rounded off such that if granularity=0.1, values after calibration are 0, 0.1, 0.2, 0.3, etc. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCalibrationMaxKey

The maximum bounds for a calibrated value. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCalibrationMinKey

The minimum bounds for a calibrated value. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementCalibrationSaturationMaxKey

The maximum tolerance to be used when calibrating a logical element value. The saturation property is used to allow for slight differences in the minimum and maximum value returned by an element. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

806

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementCalibrationSaturationMinKey

The mininum tolerance to be used when calibrating a logical element value. The saturation property is used to allow for slight differences in the minimum and maximum value returned by an element. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.
kIOHIDElementKey

Keys that represents an element property. Property for a HID Device or element dictionary. Elements can be heirarchical, so they can contain other elements. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementVendorSpecificKey

IOHIDElementCollectionType
Describes different types of HID collections.

enum IOHIDElementCollectionType{ kIOHIDElementCollectionTypePhysical = 0x00, kIOHIDElementCollectionTypeApplication, kIOHIDElementCollectionTypeLogical, kIOHIDElementCollectionTypeReport, kIOHIDElementCollectionTypeNamedArray, kIOHIDElementCollectionTypeUsageSwitch, kIOHIDElementCollectionTypeUsageModifier }; typedef enum IOHIDElementCollectionType IOHIDElementCollectionType;

Constants
kIOHIDElementCollectionTypePhysical

Used for a set of data items that represent data points collected at one geometric point. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

807

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementCollectionTypeApplication

Identifies item groups serving different purposes in a single device. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementCollectionTypeLogical

Used when a set of data items form a composite data structure. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementCollectionTypeReport

Wraps all the fields in a report. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementCollectionTypeNamedArray

Contains an array of selector usages. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementCollectionTypeUsageSwitch

Modifies the meaning of the usage it contains. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.
kIOHIDElementCollectionTypeUsageModifier

Modifies the meaning of the usage attached to the encompassing collection. Available in OS X v10.3 and later. Declared in IOHIDKeys.h. Discussion Collections identify a relationship between two or more elements. See Also
IOHIDElementCollectionType (page 807)

IOHIDElementType
Describes different types of HID elements.

enum IOHIDElementType { kIOHIDElementTypeInput_Misc = 1,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

808

IOHIDKeys.h User-Space Reference Constants

kIOHIDElementTypeInput_Button = 2, kIOHIDElementTypeInput_Axis = 3, kIOHIDElementTypeInput_ScanCodes = 4, kIOHIDElementTypeOutput = 129, kIOHIDElementTypeFeature = 257, kIOHIDElementTypeCollection = 513 }; typedef enum IOHIDElementType IOHIDElementType;

Constants
kIOHIDElementTypeInput_Misc

Misc input data field or varying size. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeInput_Button

One bit input data field. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeInput_Axis

Input data field used to represent an axis. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeInput_ScanCodes

Input data field used to represent a scan code or usage selector. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeOutput

Used to represent an output data field in a report. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeFeature

Describes input and output elements not intended for consumption by the end user. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.
kIOHIDElementTypeCollection

Element used to identify a relationship between two or more elements. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

809

IOHIDKeys.h User-Space Reference Constants

Discussion Used by the IOHIDFamily to identify the type of element processed. Represented by the key kIOHIDElementTypeKey in the dictionary describing the element. See Also
IOHIDElementType (page 808)

IOHIDOptionsType
Options for opening a device via IOHIDLib.

enum { kIOHIDOptionsTypeNone = 0x00, kIOHIDOptionsTypeSeizeDevice = 0x01 }; typedef uint32_t IOHIDOptionsType;

Constants
kIOHIDOptionsTypeNone

Default option. Available in OS X v10.3 and later. Declared in IOHIDKeys.h.

kIOHIDOptionsTypeSeizeDevice

Used to open exclusive communication with the device. This will prevent the system and other clients from receiving events from the device. Available in OS X v10.3 and later. Declared in IOHIDKeys.h. See Also
IOHIDOptionsType (page 810)

IOHIDQueueOptionsType
Options for creating a queue via IOHIDLib.

enum { kIOHIDQueueOptionsTypeNone = 0x00, kIOHIDQueueOptionsTypeEnqueueAll = 0x01 };

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

810

IOHIDKeys.h User-Space Reference Constants

typedef uint32_t IOHIDQueueOptionsType;

Constants
kIOHIDQueueOptionsTypeNone

Default option. Available in OS X v10.5 and later. Declared in IOHIDKeys.h.

kIOHIDQueueOptionsTypeEnqueueAll

Force the IOHIDQueue to enqueue all events, relative or absolute, regardless of change. Available in OS X v10.5 and later. Declared in IOHIDKeys.h. See Also
IOHIDQueueOptionsType (page 810)

IOHIDReportType
Describes different type of HID reports.

enum IOHIDReportType{ kIOHIDReportTypeInput = 0, kIOHIDReportTypeOutput, kIOHIDReportTypeFeature, kIOHIDReportTypeCount }; typedef enum IOHIDReportType IOHIDReportType;

Constants
kIOHIDReportTypeInput

Input report. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.

kIOHIDReportTypeOutput

Output report. Available in OS X v10.0 and later. Declared in IOHIDKeys.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

811

IOHIDKeys.h User-Space Reference Constants

kIOHIDReportTypeFeature

Feature report. Available in OS X v10.0 and later. Declared in IOHIDKeys.h. Discussion Used by the IOHIDFamily to identify the type of report being processed. See Also
IOHIDReportType (page 811)

IOHIDStandardType
Type to define what industrial standard the device is referencing.

enum { kIOHIDStandardTypeANSI = 0, kIOHIDStandardTypeISO = 1, kIOHIDStandardTypeJIS = 2 }; typedef uint32_t IOHIDStandardType;

Constants
kIOHIDStandardTypeANSI

ANSI. Available in OS X v10.7 and later. Declared in IOHIDKeys.h.

kIOHIDStandardTypeISO

ISO. Available in OS X v10.7 and later. Declared in IOHIDKeys.h.

kIOHIDStandardTypeJIS

JIS. Available in OS X v10.7 and later. Declared in IOHIDKeys.h. See Also

IOHIDStandardType (page 812)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

812

IOHIDLibObsolete.h Reference

Declared in

IOHIDLibObsolete.h

Overview
Included Headers

<sys/cdefs.h> <CoreFoundation/CoreFoundation.h> <CoreFoundation/CFPlugInCOM.h> <IOKit/IOTypes.h> <IOKit/IOReturn.h> <IOKit/hid/IOHIDKeys.h>

Callbacks
See the Overview for header-level documentation.

IOHIDCallbackFunction

typedef void ( *IOHIDCallbackFunction)( void *target, IOReturn result, void *refcon, void *sender);

Parameters
target

void * pointer to your data, often a pointer to an object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

813

IOHIDLibObsolete.h Reference Callbacks

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine. Discussion Type and arguments of callout C function that is used when a completion routine is called, see IOHIDLib.h:setRemovalCallback(). Availability Available in OS X v10.0 and later. Declared in
IOHIDLibObsolete.h

IOHIDElementCallbackFunction

typedef void ( *IOHIDElementCallbackFunction) ( void *target, IOReturn result, void *refcon, void *sender, IOHIDElementCookie elementCookie);

Parameters
target

void * pointer to your data, often a pointer to an object.

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine.

elementCookie

Element within interface instance sending completion.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

814

IOHIDLibObsolete.h Reference Callbacks

Discussion Type and arguments of callout C function that is used when a completion routine is called, see IOHIDLib.h:setElementValue(). Availability Available in OS X v10.0 and later. Declared in
IOHIDLibObsolete.h

IOHIDReportCallbackFunction

typedef void ( *IOHIDReportCallbackFunction) ( void *target, IOReturn result, void *refcon, void *sender, uint32_t bufferSize);

Parameters
target

void * pointer to your data, often a pointer to an object.

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine.

bufferSize

Size of the buffer received upon completion. Discussion Type and arguments of callout C function that is used when a completion routine is called, see IOHIDLib.h:setReport(). Availability Available in OS X v10.2 and later. Declared in
IOHIDLibObsolete.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

815

IOHIDLibObsolete.h Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define kIOHIDDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x78, 0xBD, 0x42, 0x0C, 0x6F, 0x14, 0x11, 0xD4, \ 0x94, 0x74, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5) #define kIOHIDDeviceInterfaceID121 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x7d, 0xb, 0x51, 0xe, 0x16, 0xd5, 0x11, 0xd7, \ 0x9e, 0x9b, 0x0, 0x3, 0x93, 0x99, 0x2e, 0x38) #define kIOHIDDeviceInterfaceID122 CFUUIDGetConstantUUIDWithBytes(NULL, \

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

816

IOHIDLibObsolete.h Reference Constants

0xb7, 0xa, 0xbf, 0x31, 0x16, 0xd5, 0x11, 0xd7, \ 0xab, 0x35, 0x0, 0x3, 0x93, 0x99, 0x2e, 0x38) #define kIOHIDOutputTransactionInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x80, 0xCD, 0xCC, 0x00, 0x75, 0x5D, 0x11, 0xD4, \ 0x80, 0xEF, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5) #define kIOHIDQueueInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x81, 0x38, 0x62, 0x9E, 0x6F, 0x14, 0x11, 0xD4, \ 0x97, 0x0E,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

817

IOHIDLibObsolete.h Reference Constants

0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)

Constants
kIOHIDDeviceInterfaceID

Interface ID for the IOHIDDeviceInterface. Corresponds to an available HID device. Available in OS X v10.0 and later. Declared in IOHIDLibObsolete.h.
kIOHIDDeviceInterfaceID121

Interface ID for the IOHIDDeviceInterface121. Corresponds to an available HID device that includes methods from IOHIDDeviceInterface. This interface is available on IOHIDLib 1.2.1 and OS X v10.2.3 or later. Available in OS X v10.3 and later. Declared in IOHIDLibObsolete.h.
kIOHIDDeviceInterfaceID122

Interface ID for the IOHIDDeviceInterface122. Corresponds to an available HID device that includes methods from IOHIDDeviceInterface and IOHIDDeviceInterface121. This interface is available on IOHIDLib 1.2.2 and OS X v10.3 or later. Available in OS X v10.3 and later. Declared in IOHIDLibObsolete.h.
kIOHIDOutputTransactionInterfaceID

Interface ID for the kIOHIDOutputTransactionInterfaceID. Corresponds to an output transaction for one or more report IDs on a specific device. Available in OS X v10.0 and later. Declared in IOHIDLibObsolete.h.
kIOHIDQueueInterfaceID

Interface ID for the kIOHIDQueueInterfaceID. Corresponds to a queue for a specific HID device. Available in OS X v10.0 and later. Declared in IOHIDLibObsolete.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

818

IOHIDManager.h Reference

Declared in

IOHIDManager.h

Overview
IOHIDManager defines an Human Interface Device (HID) managment object. It provides global interaction with managed HID devices such as discovery/removal and receiving input events. IOHIDManager is also a CFType object and as such conforms to all the conventions expected such object. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts n the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDManager.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDManager.h.

Included Headers

<IOKit/IOTypes.h> <IOKit/IOReturn.h> <IOKit/hid/IOHIDLib.h> <CoreFoundation/CoreFoundation.h>

Functions
See the Overview for header-level documentation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

819

IOHIDManager.h Reference Functions

IOHIDManagerClose
Closes the IOHIDManager.

CF_EXPORT IOReturn IOHIDManagerClose( IOHIDManagerRef manager, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
options

Option bits to be sent down to the manager and device. Return Value Returns kIOReturnSuccess if successful. Discussion This will also close all devices that are currently enumerated. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDManager.h

IOHIDManagerCopyDevices
Obtains currently enumerated devices.

CF_EXPORT CFSetRef IOHIDManagerCopyDevices( IOHIDManagerRef manager) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager. Return Value CFSetRef containing IOHIDDeviceRefs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

820

IOHIDManager.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDManager.h

IOHIDManagerCreate
Creates an IOHIDManager object.

CF_EXPORT IOHIDManagerRef IOHIDManagerCreate( CFAllocatorRef allocator, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

Allocator to be used during creation.

options

Supply kIOHIDManagerOptionUsePersistentProperties to load properties from the default persistent property store. Otherwise supply kIOHIDManagerOptionNone (or 0). Return Value Returns a new IOHIDManagerRef. Discussion The IOHIDManager object is meant as a global management system for communicating with HID devices. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

821

IOHIDManager.h Reference Functions

Declared in
IOHIDManager.h

IOHIDManagerGetProperty
Obtains a property of an IOHIDManager.

CF_EXPORT CFTypeRef IOHIDManagerGetProperty( IOHIDManagerRef manager, CFStringRef key) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
key

CFStringRef containing key to be used when querying the manager. Return Value Returns CFTypeRef containing the property. Discussion Property keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>. Availability Available in OS X v10.5 and later. Declared in
IOHIDManager.h

IOHIDManagerGetTypeID
Returns the type identifier of all IOHIDManager instances.

CF_EXPORT CFTypeID IOHIDManagerGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later. Declared in

IOHIDManager.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

822

IOHIDManager.h Reference Functions

IOHIDManagerOpen
Opens the IOHIDManager.

CF_EXPORT IOReturn IOHIDManagerOpen( IOHIDManagerRef manager, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
options

Option bits to be sent down to the manager and device. Return Value Returns kIOReturnSuccess if successful. Discussion This will open both current and future devices that are enumerated. To establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID LED test tool HID Utilities

Declared in
IOHIDManager.h

IOHIDManagerRegisterDeviceMatchingCallback
Registers a callback to be used a device is enumerated.

CF_EXPORT void IOHIDManagerRegisterDeviceMatchingCallback( IOHIDManagerRef manager, IOHIDDeviceCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

823

IOHIDManager.h Reference Functions

Parameters
manager

Reference to an IOHIDManagerRef.
callback

Pointer to a callback method of type IOHIDDeviceCallback.

context

Pointer to data to be passed to the callback. Discussion Only device matching the set criteria will be enumerated. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDManager.h

IOHIDManagerRegisterDeviceRemovalCallback
Registers a callback to be used when any enumerated device is removed.

CF_EXPORT void IOHIDManagerRegisterDeviceRemovalCallback( IOHIDManagerRef manager, IOHIDDeviceCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManagerRef.
callback

Pointer to a callback method of type IOHIDDeviceCallback.

context

Pointer to data to be passed to the callback. Discussion In most cases this occurs when a device is unplugged.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

824

IOHIDManager.h Reference Functions

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save

Declared in
IOHIDManager.h

IOHIDManagerRegisterInputReportCallback
Registers a callback to be used when an input report is issued by any enumerated device.

CF_EXPORT void IOHIDManagerRegisterInputReportCallback( IOHIDManagerRef manager, IOHIDReportCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManagerRef.
callback

Pointer to a callback method of type IOHIDReportCallback.

context

Pointer to data to be passed to the callback. Discussion An input report is an interrupt driver report issued by a device. Availability Available in OS X v10.5 and later. Declared in
IOHIDManager.h

IOHIDManagerRegisterInputValueCallback
Registers a callback to be used when an input value is issued by any enumerated device.

CF_EXPORT void IOHIDManagerRegisterInputValueCallback( IOHIDManagerRef manager,

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

825

IOHIDManager.h Reference Functions

IOHIDValueCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManagerRef.
callback

Pointer to a callback method of type IOHIDValueCallback.

context

IOHIDManagerSaveToPropertyDomain
Used to write out the current properties to a specific domain.

CF_EXPORT void IOHIDManagerSaveToPropertyDomain( IOHIDManagerRef manager, CFStringRef applicationID, CFStringRef userName, CFStringRef hostName, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
applicationID

Reference to a CFPreferences applicationID.

userName

Reference to a CFPreferences userName.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

826

IOHIDManager.h Reference Functions

hostName

Reference to a CFPreferences hostName.

options

Reserved for future use. Discussion Using this function will cause the persistent properties to be saved out replacing any properties that already existed in the specified domain. All arguments must be non-NULL except options. Availability Available in OS X v10.7 and later. Declared in
IOHIDManager.h

IOHIDManagerScheduleWithRunLoop
Schedules HID manager with run loop.

CF_EXPORT void IOHIDManagerScheduleWithRunLoop( IOHIDManagerRef manager, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity. Discussion Formally associates manager with client's run loop. Scheduling this device with the run loop is necessary before making use of any asynchronous APIs. This will propagate to current and future devices that are enumerated. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

827

IOHIDManager.h Reference Functions

Declared in
IOHIDManager.h

IOHIDManagerSetDeviceMatching
Sets matching criteria for device enumeration.

CF_EXPORT void IOHIDManagerSetDeviceMatching( IOHIDManagerRef manager, CFDictionaryRef matching) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
matching

CFDictionaryRef containg device matching criteria. Discussion Matching keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the hid manager to release previously enumerated devices and restart the enuerate process using the revised criteria. If interested in multiple, specific device classes, please defer to using IOHIDManagerSetDeviceMatchingMultiple. Availability Available in OS X v10.5 and later.
Related Sample Code HID Dumper HID LED test tool

Declared in
IOHIDManager.h

IOHIDManagerSetDeviceMatchingMultiple
Sets multiple matching criteria for device enumeration.

CF_EXPORT void IOHIDManagerSetDeviceMatchingMultiple( IOHIDManagerRef manager, CFArrayRef multiple) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

828

IOHIDManager.h Reference Functions

Parameters
manager

Reference to an IOHIDManager.
multiple

CFArrayRef containing multiple CFDictionaryRef objects containg device matching criteria. Discussion Matching keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>. This method is useful if interested in multiple, specific device classes. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDManager.h

IOHIDManagerSetInputValueMatching
Sets matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.

CF_EXPORT void IOHIDManagerSetInputValueMatching( IOHIDManagerRef manager, CFDictionaryRef matching) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
matching

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

829

IOHIDManager.h Reference Functions

Availability Available in OS X v10.5 and later. Declared in

IOHIDManager.h

IOHIDManagerSetInputValueMatchingMultiple
Sets multiple matching criteria for input values received via IOHIDManagerRegisterInputValueCallback.

CF_EXPORT void IOHIDManagerSetInputValueMatchingMultiple( IOHIDManagerRef manager, CFArrayRef multiple) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
multiple

CFArrayRef containing multiple CFDictionaryRef objects containing input element matching criteria. Discussion Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. This method is useful if interested in multiple, specific elements . Availability Available in OS X v10.5 and later. Declared in
IOHIDManager.h

IOHIDManagerSetProperty
Sets a property for an IOHIDManager.

CF_EXPORT Boolean IOHIDManagerSetProperty( IOHIDManagerRef manager, CFStringRef key, CFTypeRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

830

IOHIDManager.h Reference Functions

Parameters
manager

Reference to an IOHIDManager.
key

CFStringRef containing key to be used when modifiying the device property.

value

CFTypeRef containing the property value to be set. Return Value Returns TRUE if successful. Discussion Property keys are prefixed by kIOHIDDevice and kIOHIDManager and declared in <IOKit/hid/IOHIDKeys.h>. This method will propagate any relevent properties to current and future devices that are enumerated. Availability Available in OS X v10.5 and later. Declared in
IOHIDManager.h

IOHIDManagerUnscheduleFromRunLoop
Unschedules HID manager with run loop.

CF_EXPORT void IOHIDManagerUnscheduleFromRunLoop( IOHIDManagerRef manager, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
manager

Reference to an IOHIDManager.
runLoop

RunLoop to be used when unscheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when unscheduling any asynchronous activity. Discussion Formally disassociates device with client's run loop. This will propagate to current devices that are enumerated.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

831

IOHIDManager.h Reference Data Types

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save

Declared in
IOHIDManager.h

Data Types
See the Overview for header-level documentation.

IOHIDManagerOptions
Various options that can be supplied to IOHIDManager functions.

typedef enum { kIOHIDManagerOptionNone = 0x0, kIOHIDManagerOptionUsePersistentProperties = 0x1, kIOHIDManagerOptionDoNotLoadProperties = 0x2, kIOHIDManagerOptionDoNotSaveProperties = 0x4, } IOHIDManagerOptions;

Constants
kIOHIDManagerOptionNone

For those times when supplying 0 just isn't explicit enough. Available in OS X v10.7 and later. Declared in IOHIDManager.h.
kIOHIDManagerOptionUsePersistentProperties

This constant can be supplied to IOHIDManagerCreate (page 821) to create and/or use a persistent properties store. Available in OS X v10.7 and later. Declared in IOHIDManager.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

832

IOHIDManager.h Reference Data Types

kIOHIDManagerOptionDoNotLoadProperties

This constant can be supplied to when you wish to overwrite the persistent properties store without loading it first. const kIOHIDManagerOptionDoNotSaveProperties This constant can be supplied to IOHIDManagerCreate (page 821) when you want to use the persistent property store but do not want to add to it. (page 821) Available in OS X v10.7 and later. Declared in IOHIDManager.h. Availability Available in OS X v10.7 and later. Declared in
IOHIDManager.h

IOHIDManagerRef
This is the type of a reference to the IOHIDManager.

typedef struct __IOHIDManager * IOHIDManagerRef;

Availability Available in OS X v10.5 and later. Declared in

IOHIDManager.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

833

IOHIDQueue.h Reference

Declared in

IOHIDQueue.h

Overview
IOHIDQueue defines an object used to queue values from input parsed items (IOHIDElement) contained within a Human Interface Device (HID) object. This object is useful when you need to keep track of all values of an input element, rather than just the most recent one. IOHIDQueue is a CFType object and as such conforms to all the conventions expected such object. IOHIDQueue should be considered optional and is only useful for working with complex input elements. These elements include those whose length are greater than sizeof(CFIndex) or elements that are duplicate items. Whenever possible please defer to using IOHIDManagerRegisterInputValueCallback or IOHIDDeviceRegisterInputValueCallback. Note:Absolute element values (based on a fixed origin) will only be placed on a queue if there is a change in value. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDQueue.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDQueue.h.

Included Headers

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

834

IOHIDQueue.h Reference Functions

Functions
See the Overview for header-level documentation.

IOHIDQueueAddElement
Adds an element to the queue

CF_EXPORT void IOHIDQueueAddElement( IOHIDQueueRef queue, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be modified.

element

Element to be added to the queue. Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueContainsElement
Queries the queue to determine if elemement has been added.

CF_EXPORT Boolean IOHIDQueueContainsElement( IOHIDQueueRef queue, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be queried.

element

Element to be queried.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

835

IOHIDQueue.h Reference Functions

Return Value Returns true or false depending if element is present. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueCopyNextValue
Dequeues a retained copy of an element value from the head of an IOHIDQueue.

CF_EXPORT IOHIDValueRef IOHIDQueueCopyNextValue( IOHIDQueueRef queue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be queried. Return Value Returns valid IOHIDValueRef if data is available. Discussion Because the value is a retained copy, it is up to the caller to release the value using CFRelease. Use with setValueCallback to avoid polling the queue for data. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDQueue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

836

IOHIDQueue.h Reference Functions

IOHIDQueueCopyNextValueWithTimeout
Dequeues a retained copy of an element value from the head of an IOHIDQueue. This method will block until either a value is available or it times out.

CF_EXPORT IOHIDValueRef IOHIDQueueCopyNextValueWithTimeout( IOHIDQueueRef queue, CFTimeInterval timeout) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be queried.

timeout

Timeout before aborting an attempt to dequeue a value from the head of a queue. Return Value Returns valid IOHIDValueRef if data is available. Discussion Because the value is a retained copy, it is up to the caller to release the value using CFRelease. Use with setValueCallback to avoid polling the queue for data. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueCreate
Creates an IOHIDQueue object for the specified device.

CF_EXPORT IOHIDQueueRef IOHIDQueueCreate( CFAllocatorRef allocator, IOHIDDeviceRef device, CFIndex depth, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

837

IOHIDQueue.h Reference Functions

Parameters
allocator

Allocator to be used during creation.

device

IOHIDDevice object
depth

The number of values that can be handled by the queue.

options

Reserved for future use. Return Value Returns a new IOHIDQueueRef. Discussion Take care in specifying an appropriate depth to prevent dropping events. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueGetDepth
Obtain the depth of the queue.

CF_EXPORT CFIndex IOHIDQueueGetDepth( IOHIDQueueRef queue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue to be queried. Return Value Returns the queue depth.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

838

IOHIDQueue.h Reference Functions

Availability Available in OS X v10.5 and later. Declared in

IOHIDQueue.h

IOHIDQueueGetDevice
Obtain the device associated with the queue.

CF_EXPORT IOHIDDeviceRef IOHIDQueueGetDevice( IOHIDQueueRef queue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue to be queried. Return Value Returns the a reference to the device. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDQueue.h

IOHIDQueueGetTypeID
Returns the type identifier of all IOHIDQueue instances.

CF_EXPORT CFTypeID IOHIDQueueGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

839

IOHIDQueue.h Reference Functions

Declared in
IOHIDQueue.h

IOHIDQueueRegisterValueAvailableCallback
Sets callback to be used when the queue transitions to non-empty.

CF_EXPORT void IOHIDQueueRegisterValueAvailableCallback( IOHIDQueueRef queue, IOHIDCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be modified.

callback

Callback of type IOHIDCallback to be used when data is placed on the queue.

context

Pointer to data to be passed to the callback. Discussion In order to make use of asynchronous behavior, the queue needs to be scheduled with the run loop. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDQueue.h

IOHIDQueueRemoveElement
Removes an element from the queue

CF_EXPORT void IOHIDQueueRemoveElement( IOHIDQueueRef queue, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

840

IOHIDQueue.h Reference Functions

Parameters
queue

IOHIDQueue object to be modified.

element

Element to be removed from the queue. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueScheduleWithRunLoop
Schedules queue with run loop.

CF_EXPORT void IOHIDQueueScheduleWithRunLoop( IOHIDQueueRef queue, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be modified.

runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity. Discussion Formally associates queue with client's run loop. Scheduling this queue with the run loop is necessary before making use of any asynchronous APIs. Availability Available in OS X v10.5 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

841

IOHIDQueue.h Reference Functions

Related Sample Code HID Config Save

Declared in
IOHIDQueue.h

IOHIDQueueSetDepth
Sets the depth of the queue. @disussion Set the appropriate depth value based on the number of elements contained in a queue.

CF_EXPORT void IOHIDQueueSetDepth( IOHIDQueueRef queue, CFIndex depth) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be modified.

depth

The new queue depth. Availability Available in OS X v10.5 and later. Declared in
IOHIDQueue.h

IOHIDQueueStart
Starts element value delivery to the queue.

CF_EXPORT void IOHIDQueueStart( IOHIDQueueRef queue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be started. Availability Available in OS X v10.5 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

842

IOHIDQueue.h Reference Functions

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueStop
Stops element value delivery to the queue.

CF_EXPORT void IOHIDQueueStop( IOHIDQueueRef queue) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be stopped. Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDQueue.h

IOHIDQueueUnscheduleFromRunLoop
Unschedules queue with run loop.

CF_EXPORT void IOHIDQueueUnscheduleFromRunLoop( IOHIDQueueRef queue, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
queue

IOHIDQueue object to be modified.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

843

IOHIDQueue.h Reference Data Types

runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity. Discussion Formally disassociates queue with client's run loop. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDQueue.h

Data Types
See the Overview for header-level documentation.

IOHIDQueueRef

typedef struct __IOHIDQueue * IOHIDQueueRef;

Discussion This is the type of a reference to the IOHIDQueue. Availability Available in OS X v10.5 and later. Declared in
IOHIDQueue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

844

IOHIDTransaction.h Reference

Declared in

IOHIDTransaction.h

Overview
IOHIDTransaction defines an object used to manipulate multiple parsed items (IOHIDElement) contained within a Human Interface Device (HID) object. It is used to minimize device communication when interacting with feature and output type elements that are grouped by their report IDs. IOHIDTransaction is a CFType object and as such conforms to all the conventions expected such object. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDTransaction.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDTransaction.h.

Included Headers

Functions
See the Overview for header-level documentation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

845

IOHIDTransaction.h Reference Functions

IOHIDTransactionAddElement
Adds an element to the transaction @disussion To minimize device traffic it is important to add elements that share a common report type and report id.

CF_EXPORT void IOHIDTransactionAddElement( IOHIDTransactionRef transaction, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

element

Element to be added to the transaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionClear
Clears element transaction values.

CF_EXPORT void IOHIDTransactionClear( IOHIDTransactionRef transaction) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified. Discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be preserved. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

846

IOHIDTransaction.h Reference Functions

IOHIDTransactionCommit
Synchronously commits element transaction to the device.

CF_EXPORT IOReturn IOHIDTransactionCommit( IOHIDTransactionRef transaction) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be used if element values are not set. If neither are set, that element will be omitted from the commit. After a transaction is committed, transaction element values will be cleared and default values preserved. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionCommitWithCallback
Commits element transaction to the device.

CF_EXPORT IOReturn IOHIDTransactionCommitWithCallback( IOHIDTransactionRef transaction, CFTimeInterval timeout, IOHIDCallback callback, void *context) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

timeout

Timeout for issuing the transaction.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

847

IOHIDTransaction.h Reference Functions

callback

Callback of type IOHIDCallback to be used when transaction has been completed. If null, this method will behave synchronously.
context

Pointer to data to be passed to the callback. Return Value Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. Discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be used if element values are not set. If neither are set, that element will be omitted from the commit. After a transaction is committed, transaction element values will be cleared and default values preserved.
Note: It is possible for elements from different reports to be present in a given transaction causing a commit to

transcend multiple reports. Keep this in mind when setting a appropriate timeout. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionContainsElement
Queries the transaction to determine if elemement has been added.

CF_EXPORT Boolean IOHIDTransactionContainsElement( IOHIDTransactionRef transaction, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be queried.

element

Element to be queried. Return Value Returns true or false depending if element is present.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

848

IOHIDTransaction.h Reference Functions

Availability Available in OS X v10.5 and later. Declared in

IOHIDTransaction.h

IOHIDTransactionCreate
Creates an IOHIDTransaction object for the specified device.

CF_EXPORT IOHIDTransactionRef IOHIDTransactionCreate( CFAllocatorRef allocator, IOHIDDeviceRef device, IOHIDTransactionDirectionType direction, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

Allocator to be used during creation.

device

IOHIDDevice object
direction

The direction, either in or out, for the transaction.

options

Reserved for future use. Return Value Returns a new IOHIDTransactionRef. Discussion IOHIDTransaction objects can be used to either send or receive multiple element values. As such the direction used should represent they type of objects added to the transaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

849

IOHIDTransaction.h Reference Functions

IOHIDTransactionGetDevice
Obtain the device associated with the transaction.

CF_EXPORT IOHIDDeviceRef IOHIDTransactionGetDevice( IOHIDTransactionRef transaction) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction to be queried. Return Value Returns the a reference to the device. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionGetDirection
Obtain the direction of the transaction.

CF_EXPORT IOHIDTransactionDirectionType IOHIDTransactionGetDirection( IOHIDTransactionRef transaction) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction to be queried. Return Value Returns the transaction direction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

850

IOHIDTransaction.h Reference Functions

IOHIDTransactionGetTypeID
Returns the type identifier of all IOHIDTransaction instances.

CF_EXPORT CFTypeID IOHIDTransactionGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later. Declared in

IOHIDTransaction.h

IOHIDTransactionGetValue
Obtains the value for a transaction element.

CF_EXPORT IOHIDValueRef IOHIDTransactionGetValue( IOHIDTransactionRef transaction, IOHIDElementRef element, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be queried.

element

Element to be queried.
options

See IOHIDTransactionOption. Return Value Returns IOHIDValueRef for the given element. Discussion If the transaction direction is kIOHIDTransactionDirectionTypeInput the value represents what was obtained from the device from the transaction. Otherwise, if the transaction direction is kIOHIDTransactionDirectionTypeOutput the value represents the pending value to be sent to the device. Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default element value. Availability Available in OS X v10.5 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

851

IOHIDTransaction.h Reference Functions

Declared in
IOHIDTransaction.h

IOHIDTransactionRemoveElement
Removes an element to the transaction

CF_EXPORT void IOHIDTransactionRemoveElement( IOHIDTransactionRef transaction, IOHIDElementRef element) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

element

Element to be removed to the transaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionScheduleWithRunLoop
Schedules transaction with run loop.

CF_EXPORT void IOHIDTransactionScheduleWithRunLoop( IOHIDTransactionRef transaction, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

852

IOHIDTransaction.h Reference Functions

Discussion Formally associates transaction with client's run loop. Scheduling this transaction with the run loop is necessary before making use of any asynchronous APIs. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionSetDirection
Sets the direction of the transaction @disussion This method is useful for manipulating bi-direction (feature) elements such that you can set or get element values without creating an additional transaction object.

CF_EXPORT void IOHIDTransactionSetDirection( IOHIDTransactionRef transaction, IOHIDTransactionDirectionType direction) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

direction

The new transaction direction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionSetValue
Sets the value for a transaction element.

CF_EXPORT void IOHIDTransactionSetValue( IOHIDTransactionRef transaction, IOHIDElementRef element, IOHIDValueRef value, IOOptionBits options) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

853

IOHIDTransaction.h Reference Functions

Parameters
transaction

IOHIDTransaction object to be modified.

element

Element to be modified after a commit.

value

Value to be set for the given element.

options

See IOHIDTransactionOption. Discussion The value set is pended until the transaction is committed and is only used if the transaction direction is kIOHIDTransactionDirectionTypeOutput. Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element value. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

IOHIDTransactionUnscheduleFromRunLoop
Unschedules transaction with run loop.

CF_EXPORT void IOHIDTransactionUnscheduleFromRunLoop( IOHIDTransactionRef transaction, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
transaction

IOHIDTransaction object to be modified.

runLoop

RunLoop to be used when scheduling any asynchronous activity.

runLoopMode

Run loop mode to be used when scheduling any asynchronous activity.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

854

IOHIDTransaction.h Reference Data Types

Discussion Formally disassociates transaction with client's run loop. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

Data Types
See the Overview for header-level documentation.

IOHIDTransactionRef

typedef struct __IOHIDTransaction * IOHIDTransactionRef;

Discussion This is the type of a reference to the IOHIDTransaction. Availability Available in OS X v10.5 and later. Declared in
IOHIDTransaction.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

855

IOHIDValue.h Reference

Declared in

IOHIDValue.h

Overview
IOHIDValue defines a value at a given time from an parsed item (IOHIDElement) contained within a Human Interface Device (HID) object. It is used to obtain either integer or data element values along with scaled values based on physical or calibrated settings. IOHIDValue is a CFType object and as such conforms to all the conventions expected such object. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Human Interface Device & Force Feedback . Please review documentation before using this reference. All of the information described in this document is contained in the header file IOHIDValue.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDValue.h.

Included Headers

<CoreFoundation/CoreFoundation.h> <IOKit/hid/IOHIDBase.h> <IOKit/hid/IOHIDKeys.h>

Functions
See the Overview for header-level documentation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

856

IOHIDValue.h Reference Functions

IOHIDValueCreateWithBytes
Creates a new element value using byte data.

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithBytes( CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, const uint8_t *bytes, CFIndex length) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

The CFAllocator which should be used to allocate memory for the value. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
element

IOHIDElementRef associated with this value.

timeStamp

OS absolute time timestamp for this value.

bytes

Pointer to a buffer of uint8_t to be copied to this object.

length

Number of bytes in the passed buffer. Return Value Returns a reference to a new IOHIDValueRef. Discussion IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h> Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

IOHIDValueCreateWithBytesNoCopy
Creates a new element value using byte data without performing a copy.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

857

IOHIDValue.h Reference Functions

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithBytesNoCopy( CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, const uint8_t *bytes, CFIndex length) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

IOHIDElementRef associated with this value.

timeStamp

OS absolute time timestamp for this value.

bytes

Pointer to a buffer of uint8_t to be referenced by this object.

length

Number of bytes in the passed buffer. Return Value Returns a reference to a new IOHIDValueRef. Discussion The timestamp value passed should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h> Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

IOHIDValueCreateWithIntegerValue
Creates a new element value using an integer value.

CF_EXPORT IOHIDValueRef IOHIDValueCreateWithIntegerValue(

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

858

IOHIDValue.h Reference Functions

CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, CFIndex value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
allocator

IOHIDElementRef associated with this value.

timeStamp

OS absolute time timestamp for this value.

value

Integer value to be copied to this object. Return Value Returns a reference to a new IOHIDValueRef. Discussion IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime. To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h> Availability Available in OS X v10.5 and later.
Related Sample Code HID LED test tool

Declared in
IOHIDValue.h

IOHIDValueGetBytePtr
Returns a byte pointer to the value contained in this IOHIDValueRef.

CF_EXPORT const uint8_t * IOHIDValueGetBytePtr( IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

859

IOHIDValue.h Reference Functions

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined. Return Value Returns a pointer to the value. Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

IOHIDValueGetElement
Returns the element value associated with this IOHIDValueRef.

CF_EXPORT IOHIDElementRef IOHIDValueGetElement( IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined. Return Value Returns a IOHIDElementRef referenced by this value. Availability Available in OS X v10.5 and later.
Related Sample Code HID Config Save

Declared in
IOHIDValue.h

IOHIDValueGetIntegerValue
Returns an integer representaion of the value contained in this IOHIDValueRef.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

860

IOHIDValue.h Reference Functions

CF_EXPORT CFIndex IOHIDValueGetIntegerValue( IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined. Return Value Returns an integer representation of the value. Discussion The value is based on the logical element value contained in the report returned by the device. Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

IOHIDValueGetLength
Returns the size, in bytes, of the value contained in this IOHIDValueRef.

CF_EXPORT CFIndex IOHIDValueGetLength( IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined. Return Value Returns length of the value. Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

861

IOHIDValue.h Reference Functions

IOHIDValueGetScaledValue
Returns an scaled representaion of the value contained in this IOHIDValueRef based on the scale type.

CF_EXPORT double_t IOHIDValueGetScaledValue( IOHIDValueRef value, IOHIDValueScaleType type) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
type

The type of scaling to be performed. Return Value Returns an scaled floating point representation of the value. Discussion The scaled value is based on the range described by the scale type's min and max, such that: scaledValue = ((value - min) * (scaledMax - scaledMin) / (max - min)) + scaledMin
Note:

There are currently two types of scaling that can be applied:

kIOHIDValueScaleTypePhysical: Scales element value using the physical bounds of the device such that scaledMin = physicalMin and scaledMax = physicalMax. kIOHIDValueScaleTypeCalibrated: Scales element value such that scaledMin = -1 and scaledMax = 1. This value will also take into account the calibration properties associated with this element.

Availability Available in OS X v10.5 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities

Declared in
IOHIDValue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

862

IOHIDValue.h Reference Functions

IOHIDValueGetTimeStamp
Returns the timestamp value contained in this IOHIDValueRef.

CF_EXPORT uint64_t IOHIDValueGetTimeStamp( IOHIDValueRef value) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
value

The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined. Return Value Returns a uint64_t representing the timestamp of this value. Discussion The timestamp value returned represents OS AbsoluteTime, not CFAbsoluteTime. Availability Available in OS X v10.5 and later. Declared in
IOHIDValue.h

IOHIDValueGetTypeID
Returns the type identifier of all IOHIDValue instances.

CF_EXPORT CFTypeID IOHIDValueGetTypeID( void) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Availability Available in OS X v10.5 and later. Declared in

IOHIDValue.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

863

IOI2CInterface.h User-Space Reference

Declared in

IOI2CInterface.h

Overview Functions
See the Overview for header-level documentation.

IOFBCopyI2CInterfaceForBus
Returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair.

IOReturn IOFBCopyI2CInterfaceForBus( io_service_t framebuffer, IOOptionBits bus, io_service_t *interface );

Parameters
bus

The zero based index of the bus on the requested framebuffer.

interface

The interface instance is returned. The caller should release this instance with IOObjectRelease(). Return Value An IOReturn code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

864

IOI2CInterface.h User-Space Reference Functions

Discussion Some graphics devices will allow access to an I2C bus routed through a display connector in order to control external devices on that bus. This function returns an instance of an I2C bus interface, associated with an IOFramebuffer instance / bus index pair. The number of I2C buses is available from the IOFBGetI2CInterfaceCount() call. The interface may be used with the IOI2CInterfaceOpen/Close/SendRequest() calls to carry out I2C transactions on that bus. Not all graphics devices support this functionality. Availability Available in OS X v10.3 and later. Declared in
IOI2CInterface.h

IOFBGetI2CInterfaceCount
Returns a count of I2C interfaces available associated with an IOFramebuffer instance.

IOReturn IOFBGetI2CInterfaceCount( io_service_t framebuffer, IOItemCount *count );

Parameters
framebuffer

The io_service_t of an IOFramebuffer instance. CoreGraphics will provide this for a CGDisplay with the CGDisplayIOServicePort() call.
count

Interface count is returned. Return Value An IOReturn code. Discussion Returns a count of I2C interfaces available associated with an IOFramebuffer instance. Availability Available in OS X v10.3 and later. Declared in
IOI2CInterface.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

865

IOI2CInterface.h User-Space Reference Functions

IOI2CInterfaceClose
Closes an IOI2CConnectRef.

IOReturn IOI2CInterfaceClose( IOI2CConnectRef connect, IOOptionBits options );

Parameters
connect

The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen().

options

Pass kNilOptions. Return Value An IOReturn code. Discussion Frees the resources associated with an IOI2CConnectRef. Availability Available in OS X v10.3 and later. Declared in
IOI2CInterface.h

IOI2CInterfaceOpen
Opens an instance of an I2C bus interface, allowing I2C requests to be made.

IOReturn IOI2CInterfaceOpen( io_service_t interface, IOOptionBits options, IOI2CConnectRef *connect );

Parameters
interface

An I2C bus interface (see IOFBCopyI2CInterfaceForBus). The interface may be released after this call is made.
options

Pass kNilOptions.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

866

IOI2CInterface.h User-Space Reference Functions

connect

The opaque IOI2CConnectRef is returned, for use with IOI2CSendRequest() and IOI2CInterfaceClose(). Return Value An IOReturn code. Discussion An instance of an I2C bus interface, obtained by IOFBCopyI2CInterfaceForBus, is opened with this function allowing I2C requests to be made. Availability Available in OS X v10.3 and later. Declared in
IOI2CInterface.h

IOI2CSendRequest
Carries out the I2C transaction specified by an IOI2CRequest structure.

IOReturn IOI2CSendRequest( IOI2CConnectRef connect, IOOptionBits options, IOI2CRequest *request );

Parameters
connect

The opaque IOI2CConnectRef returned by IOI2CInterfaceOpen().

options

Pass kNilOptions.
request

Pass a pointer to a IOI2CRequest structure describing the request. If an asynchronous request (with a non-NULL completion routine) the request structure must be valid for the life of the request. Return Value An IOReturn code reflecting only the result of starting the transaction. If the result of IOI2CSendRequest() is kIOReturnSuccess, the I2C transaction result is returned in the result field of the request structure. Discussion Frees the resources associated with an IOI2CConnectRef.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

867

IOI2CInterface.h User-Space Reference Data Types

Availability Available in OS X v10.3 and later. Declared in

IOI2CInterface.h

Data Types
See the Overview for header-level documentation.

IOI2CBusTiming
A structure defining low level timing for an I2C bus.

struct IOI2CBusTiming { AbsoluteTime bitTimeout; AbsoluteTime byteTimeout; AbsoluteTime acknowledgeTimeout; AbsoluteTime startTimeout; AbsoluteTime holdTime; AbsoluteTime riseFallTime; UInt32 __reservedA[8]; };

Fields
bitTimeout

Maximum time a slave can delay (by pulling the clock line low) a single bit response.
byteTimeout

Maximum time a slave can delay (by pulling the clock line low) the first bit of a byte response.
acknowledgeTimeout

Maximum time to wait for a slave to respond with an ACK after writing a byte.
startTimeout

Maximum time to wait for a slave to respond after a start signal.

riseFallTime

Time to wait after any change in output signal.

__reservedA

Set to zero.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

868

IOI2CInterface.h User-Space Reference Data Types

Discussion This structure is used to specify timeouts and pulse widths for an I2C bus implementation.

IOI2CRequest
A structure defining an I2C bus transaction.

struct IOI2CRequest { IOOptionBits sendTransactionType; IOOptionBits replyTransactionType; uint32_t sendAddress; uint32_t replyAddress; uint8_t sendSubAddress; uint8_t replySubAddress; uint8_t __reservedA[2]; uint64_t minReplyDelay; IOReturn result; IOOptionBits commFlags; #if defined(__LP64__) uint32_t __padA; #else vm_address_t sendBuffer; #endif uint32_t sendBytes; uint32_t __reservedB[2]; #if defined(__LP64__) uint32_t __padB; #else vm_address_t replyBuffer; #endif uint32_t replyBytes; IOI2CRequestCompletion completion; #if !defined(__LP64__) uint32_t __padC[5]; #else vm_address_t sendBuffer; vm_address_t replyBuffer; #endif uint32_t __reservedC[10]; #ifdef __ppc__ uint32_t __reservedD; #endif };

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

869

IOI2CInterface.h User-Space Reference Data Types

Fields
__reservedA

Set to zero.
result

The result of the transaction. Common errors are kIOReturnNoDevice if there is no device responding at the given address, kIOReturnUnsupportedMode if the type of transaction is unsupported on the requested bus.
completion

A completion routine to be executed when the request completes. If NULL is passed, the request is synchronous, otherwise it may execute asynchronously.
commFlags

Flags that modify the I2C transaction type. The following flags are defined: kIOI2CUseSubAddressCommFlag Transaction includes a subaddress.
minReplyDelay

Minimum delay as absolute time between send and reply transactions.

sendAddress

I2C address to write.

sendSubAddress

I2C subaddress to write.

__reservedB

Set to zero.
sendTransactionType

The following types of transaction are defined for the send part of the request: kIOI2CNoTransactionType No send transaction to perform. kIOI2CSimpleTransactionType Simple I2C message. kIOI2CCombinedTransactionType Combined format I2C R/~W transaction.
sendBuffer

Pointer to the send buffer.

sendBytes

Number of bytes to send. Set to actual bytes sent on completion of the request.
replyAddress

I2C Address from which to read.

replySubAddress

I2C Address from which to read.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

870

IOI2CInterface.h User-Space Reference Data Types

__reservedC

Set to zero.
replyTransactionType

The following types of transaction are defined for the reply part of the request: kIOI2CNoTransactionType No reply transaction to perform. kIOI2CSimpleTransactionType Simple I2C message. kIOI2CDDCciReplyTransactionType DDC/ci message (with embedded length). See VESA DDC/ci specification. kIOI2CCombinedTransactionType Combined format I2C R/~W transaction.
replyBuffer

Pointer to the reply buffer.

replyBytes

Max bytes to reply (size of replyBuffer). Set to actual bytes received on completion of the request.
__reservedD

Set to zero. Discussion This structure is used to request an I2C transaction consisting of a send (write) to and reply (read) from a device, either of which is optional, to be carried out atomically on an I2C bus.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

871

IOKitLib.h Reference

Declared in

IOKitLib.h

Overview
IOKitLib implements non-kernel task access to common IOKit object types - IORegistryEntry, IOService, IOIterator etc. These functions are generic - families may provide API that is more specific. IOKitLib represents IOKit objects outside the kernel with the types io_object_t, io_registry_entry_t, io_service_t, & io_connect_t. Function names usually begin with the type of object they are compatible with - eg. IOObjectRelease can be used with any io_object_t. Inside the kernel, the c++ class hierarchy allows the subclasses of each object type to receive the same requests from user level clients, for example in the kernel, IOService is a subclass of IORegistryEntry, which means any of the IORegistryEntryXXX functions in IOKitLib may be used with io_service_t's as well as io_registry_t's. There are functions available to introspect the class of the kernel object which any io_object_t et al. represents. IOKit objects returned by all functions should be released with IOObjectRelease.

Included Headers

<sys/cdefs.h> types.h <mach/mach_types.h> <mach/mach_init.h> <CoreFoundation/CFBase.h> <CoreFoundation/CFDictionary.h> <CoreFoundation/CFRunLoop.h> <IOKit/IOTypes.h> <IOKit/IOKitKeys.h> <IOKit/OSMessageNotification.h> <AvailabilityMacros.h>

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

872

IOKitLib.h Reference Functions

Functions
See the Overview for header-level documentation.

IOBSDNameMatching
Create a matching dictionary that specifies an IOService match based on BSD device name.

CFMutableDictionaryRef IOBSDNameMatching( mach_port_t masterPort, uint32_t options, const char *bsdName );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
options

No options are currently defined.

bsdName

The BSD name, as a const char *. Return Value The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. Discussion IOServices that represent BSD devices have an associated BSD name. This function creates a matching dictionary that will match IOService's with a given BSD name. Availability Available in OS X v10.0 and later.
Related Sample Code VolumeToBSDNode

Declared in
IOLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

873

IOKitLib.h Reference Functions

IOConnectAddClient
Inform a connection of a second connection.

kern_return_t IOConnectAddClient( io_connect_t connect, io_connect_t client );

Parameters
connect

The connect handle created by IOServiceOpen.

client

Another connect handle created by IOServiceOpen. Return Value A kern_return_t error code returned by the family. Discussion This is a generic method to inform a family connection of a second connection, and is rarely used. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectAddRef
Adds a reference to the connect handle.

kern_return_t IOConnectAddRef( io_connect_t connect );

Parameters
connect

The connect handle created by IOServiceOpen. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

874

IOKitLib.h Reference Functions

Discussion Adds a reference to the connect handle. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectGetService
Returns the IOService a connect handle was opened on.

kern_return_t IOConnectGetService( io_connect_t connect, io_service_t *service );

Parameters
connect

The connect handle created by IOServiceOpen.

service

On succes, the service handle the connection was opened on, which should be released with IOObjectRelease. Return Value A kern_return_t error code. Discussion Finds the service object a connection was opened on. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectMapMemory
Map hardware or shared memory into the caller's task.

#if !LP64 || defined(IOCONNECT_MAPMEMORY_10_6)

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

875

IOKitLib.h Reference Functions

kern_return_t IOConnectMapMemory( io_connect_t connect, uint32_t memoryType, task_port_t intoTask, vm_address_t *atAddress, vm_size_t *ofSize, IOOptionBits options ); #else kern_return_t IOConnectMapMemory( io_connect_t connect, uint32_t memoryType, task_port_t intoTask, mach_vm_address_t *atAddress, mach_vm_size_t *ofSize, IOOptionBits options ); #endif /* !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) */

Parameters
connect

The connect handle created by IOServiceOpen.

memoryType

What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings.
intoTask

The task port for the task in which to create the mapping. This may be different to the task which the opened the connection.
atAddress

An in/out parameter - if the kIOMapAnywhere option is not set, the caller should pass the address where it requests the mapping be created, otherwise nothing need to set on input. The address of the mapping created is passed back on sucess.
ofSize

The size of the mapping created is passed back on success. Return Value A kern_return_t error code. Discussion This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

876

IOKitLib.h Reference Functions

Availability Available in OS X v10.0 and later.

Related Sample Code AppleSamplePCI

Declared in
IOKitLib.h

IOConnectMapMemory64
Map hardware or shared memory into the caller's task.

kern_return_t IOConnectMapMemory64( io_connect_t connect, uint32_t memoryType, task_port_t intoTask, mach_vm_address_t *atAddress, mach_vm_size_t *ofSize, IOOptionBits options );

Parameters
connect

The connect handle created by IOServiceOpen.

memoryType

What is being requested to be mapped, not interpreted by IOKit and family defined. The family may support physical hardware or shared memory mappings.
intoTask

The task port for the task in which to create the mapping. This may be different to the task which the opened the connection.
atAddress

The size of the mapping created is passed back on success. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

877

IOKitLib.h Reference Functions

Discussion This is a generic method to create a mapping in the callers task. The family will interpret the type parameter to determine what sort of mapping is being requested. Cache modes and placed mappings may be requested by the caller. Availability Available in OS X v10.5 and later. Declared in
IOKitLib.h

IOConnectRelease
Remove a reference to the connect handle.

kern_return_t IOConnectRelease( io_connect_t connect );

Parameters
connect

The connect handle created by IOServiceOpen. Return Value A kern_return_t error code. Discussion Removes a reference to the connect handle. If the last reference is removed an implicit IOServiceClose is performed. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectSetCFProperties
Set CF container based properties on a connection.

kern_return_t IOConnectSetCFProperties(

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

878

IOKitLib.h Reference Functions

io_connect_t connect, CFTypeRef properties );

Parameters
connect

The connect handle created by IOServiceOpen.

properties

A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. Return Value A kern_return_t error code returned by the family. Discussion This is a generic method to pass a CF container of properties to the connection. The properties are interpreted by the family and commonly represent configuration settings, but may be interpreted as anything. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectSetCFProperty
Set a CF container based property on a connection.

kern_return_t IOConnectSetCFProperty( io_connect_t connect, CFStringRef propertyName, CFTypeRef property );

Parameters
connect

The connect handle created by IOServiceOpen.

propertyName

The name of the property as a CFString.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

879

IOKitLib.h Reference Functions

property

A CF container - should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. Return Value A kern_return_t error code returned by the object. Discussion This is a generic method to pass a CF property to the connection. The property is interpreted by the family and commonly represent configuration settings, but may be interpreted as anything. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectSetNotificationPort
Set a port to receive family specific notifications.

kern_return_t IOConnectSetNotificationPort( io_connect_t connect, uint32_t type, mach_port_t port, uintptr_t reference );

Parameters
connect

The connect handle created by IOServiceOpen.

type

The type of notification requested, not interpreted by IOKit and family defined.
port

The port to which to send notifications.

reference

Some families may support passing a reference parameter for the callers use with the notification. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

880

IOKitLib.h Reference Functions

Discussion This is a generic method to pass a mach port send right to be be used by family specific notifications. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectUnmapMemory
Remove a mapping made with IOConnectMapMemory.

#if !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) kern_return_t IOConnectUnmapMemory( io_connect_t connect, uint32_t memoryType, task_port_t fromTask, vm_address_t atAddress ); #else kern_return_t IOConnectUnmapMemory( io_connect_t connect, uint32_t memoryType, task_port_t fromTask, mach_vm_address_t atAddress ); #endif /* !__LP64__ || defined(IOCONNECT_MAPMEMORY_10_6) */

Parameters
connect

The connect handle created by IOServiceOpen.

memoryType

The memory type originally requested in IOConnectMapMemory.

fromTask

The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection.
atAddress

The address of the mapping to be removed. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

881

IOKitLib.h Reference Functions

Discussion This is a generic method to remove a mapping in the callers task. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOConnectUnmapMemory64
Remove a mapping made with IOConnectMapMemory64.

kern_return_t IOConnectUnmapMemory64( io_connect_t connect, uint32_t memoryType, task_port_t fromTask, mach_vm_address_t atAddress );

Parameters
connect

The connect handle created by IOServiceOpen.

memoryType

The memory type originally requested in IOConnectMapMemory.

fromTask

The task port for the task in which to remove the mapping. This may be different to the task which the opened the connection.
atAddress

The address of the mapping to be removed. Return Value A kern_return_t error code. Discussion This is a generic method to remove a mapping in the callers task. Availability Available in OS X v10.5 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

882

IOKitLib.h Reference Functions

IOCreateReceivePort
Creates and returns a mach port suitable for receiving IOKit messages of the specified type.

kern_return_t IOCreateReceivePort( uint32_t msgType, mach_port_t *recvPort );

Parameters
msgType

Type of message to be sent to this port (kOSNotificationMessageID or kOSAsyncCompleteMessageID)

recvPort

The created port is returned. Return Value A kern_return_t error code. Discussion In the future IOKit may use specialized messages and ports instead of the standard ports created by mach_port_allocate(). Use this function instead of mach_port_allocate() to ensure compatibility with future revisions of IOKit. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IODispatchCalloutFromMessage
Dispatches callback notifications from a mach message.

void IODispatchCalloutFromMessage( void unused, mach_msg_header_t msg, void *reference );

Parameters
unused

Not used, set to zero.

msg

A pointer to the message received.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

883

IOKitLib.h Reference Functions

reference

Pass the IONotificationPortRef for the object. Discussion A notification object may deliver notifications to a mach messaging client, which should call this function to generate the callbacks associated with the notifications arriving on the port. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOIteratorIsValid
Checks an iterator is still valid.

boolean_t IOIteratorIsValid( io_iterator_t iterator );

Parameters
iterator

An IOKit iterator handle. Return Value True if the iterator handle is valid, otherwise false is returned. Discussion Some iterators will be made invalid if changes are made to the structure they are iterating over. This function checks the iterator is still valid and should be called when IOIteratorNext returns zero. An invalid iterator can be reset and the iteration restarted. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOIteratorNext
Returns the next object in an iteration.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

884

IOKitLib.h Reference Functions

io_object_t IOIteratorNext( io_iterator_t iterator );

Parameters
iterator

An IOKit iterator handle. Return Value If the iterator handle is valid, the next element in the iteration is returned, otherwise zero is returned. The element should be released by the caller when it is finished. Discussion This function returns the next object in an iteration, or zero if no more remain or the iterator is invalid. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI Deva_Example GLUT STUCAuthoringDeviceTool STUCOtherDeviceTool

Declared in
IOKitLib.h

IOIteratorReset
Resets an iteration back to the beginning.

void IOIteratorReset( io_iterator_t iterator );

Parameters
iterator

An IOKit iterator handle. Discussion If an iterator is invalid, or if the caller wants to start over, IOIteratorReset will set the iteration back to the beginning.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

885

IOKitLib.h Reference Functions

Availability Available in OS X v10.0 and later.

Related Sample Code Deva_Example

Declared in
IOKitLib.h

IOKitGetBusyState
Returns the busyState of all IOServices.

kern_return_t IOKitGetBusyState( mach_port_t masterPort, uint32_t *busyState );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
busyState

The busyState count is returned. Return Value A kern_return_t error code. Discussion Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients. IOKitGetBusyState returns the busy state of the root of the service plane which reflects the busy state of all IOServices. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

886

IOKitLib.h Reference Functions

IOKitWaitQuiet
Wait for a all IOServices' busyState to be zero.

kern_return_t IOKitWaitQuiet( mach_port_t masterPort, mach_timespec_t *waitTime );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
waitTime

Specifies a maximum time to wait. Return Value Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess. Discussion Blocks the caller until all IOServices are non busy, see IOKitGetBusyState. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOMasterPort
Returns the mach port used to initiate communication with IOKit.

kern_return_t IOMasterPort( mach_port_t bootstrapPort, mach_port_t *masterPort );

Parameters
bootstrapPort

Pass MACH_PORT_NULL for the default.

masterPort

The master port is returned.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

887

IOKitLib.h Reference Functions

Return Value A kern_return_t error code. Discussion Functions that don't specify an existing object require the IOKit master port to be passed. This function obtains that port. Availability Available in OS X v10.0 and later.
Related Sample Code Deva_Example GLUT

Declared in
IOKitLib.h

IONotificationPortCreate
Creates and returns a notification object for receiving IOKit notifications of new devices or state changes.

IONotificationPortRef IONotificationPortCreate( mach_port_t masterPort );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. Return Value A reference to the notification object. Discussion Creates the notification object to receive notifications from IOKit of new device arrivals or state changes. The notification object can be supply a CFRunLoopSource, or mach_port_t to be used to listen for events. Availability Available in OS X v10.0 and later.
Related Sample Code STUCAuthoringDeviceTool STUCOtherDeviceTool USBPrivateDataSample

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

888

IOKitLib.h Reference Functions

Declared in
IOKitLib.h

IONotificationPortDestroy
Destroys a notification object created with IONotificationPortCreate. Also destroys any mach_port's or CFRunLoopSources obatined from IONotificationPortGetRunLoopSource (page 890) or
IONotificationPortGetMachPort (page 889)

void IONotificationPortDestroy( IONotificationPortRef notify );

Parameters
notify

A reference to the notification object. Availability Available in OS X v10.0 and later.

Related Sample Code STUCAuthoringDeviceTool STUCOtherDeviceTool

Declared in
IOKitLib.h

IONotificationPortGetMachPort
Returns a mach_port to be used to listen for notifications.

mach_port_t IONotificationPortGetMachPort( IONotificationPortRef notify );

Parameters
notify

The notification object. Return Value A mach_port for the notification object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

889

IOKitLib.h Reference Functions

Discussion A notification object may deliver notifications to a mach messaging client if they listen for messages on the port obtained from this function. Callbacks associated with the notifications may be delivered by calling IODispatchCalloutFromMessage with messages received. The caller should not release this mach_port_t. Just call IONotificationPortDestroy (page 889) to dispose of the mach_port_t and IONotificationPortRef when done. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IONotificationPortGetRunLoopSource
Returns a CFRunLoopSource to be used to listen for notifications.

CFRunLoopSourceRef IONotificationPortGetRunLoopSource( IONotificationPortRef notify );

Parameters
notify

The notification object. Return Value A CFRunLoopSourceRef for the notification object. Discussion A notification object may deliver notifications to a CFRunLoop by adding the run loop source returned by this function to the run loop. The caller should not release this CFRunLoopSource. Just call IONotificationPortDestroy (page 889) to dispose of the IONotificationPortRef and the CFRunLoopSource when done. Availability Available in OS X v10.0 and later.
Related Sample Code STUCAuthoringDeviceTool STUCOtherDeviceTool USBPrivateDataSample

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

890

IOKitLib.h Reference Functions

Declared in
IOKitLib.h

IONotificationPortSetDispatchQueue
Sets a dispatch queue to be used to listen for notifications.

void IONotificationPortSetDispatchQueue( IONotificationPortRef notify, dispatch_queue_t queue ) __OSX_AVAILABLE_STARTING( __MAC_10_6, __IPHONE_4_3);

Parameters
notify

The notification object.

queue

A dispatch queue. Discussion A notification object may deliver notifications to a dispatch client. Availability Available in OS X v10.7 and later. Declared in
IOKitLib.h

IOObjectConformsTo
Performs an OSDynamicCast operation on an IOKit object.

boolean_t IOObjectConformsTo( io_object_t object, const io_name_t className );

Parameters
object

An IOKit object.
className

The name of the class, as a C-string.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

891

IOKitLib.h Reference Functions

Return Value If the object handle is valid, and represents an object in the kernel that dynamic casts to the class true is returned, otherwise false. Discussion This function uses the OSMetaClass system in the kernel to determine if the object will dynamic cast to a class, specified as a C-string. In other words, if the object is of that class or a subclass. Availability Available in OS X v10.0 and later.
Related Sample Code VolumeToBSDNode

Declared in
IOKitLib.h

IOObjectCopyBundleIdentifierForClass
Return the bundle identifier of the given class.

CFStringRef IOObjectCopyBundleIdentifierForClass( CFStringRef classname) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters
classname

The name of the class as a CFString. Return Value The resulting CFStringRef. This should be released by the caller. If a valid class name is not passed in, then NULL is returned. Discussion This function uses the OSMetaClass system in the kernel to derive the name of the kmod, which is the same as the bundle identifier. Availability Available in OS X v10.4 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

892

IOKitLib.h Reference Functions

IOObjectCopyClass
Return the class name of an IOKit object.

CFStringRef IOObjectCopyClass( io_object_t object) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters
object

The IOKit object. Return Value The resulting CFStringRef. This should be released by the caller. If a valid object is not passed in, then NULL is returned. Discussion This function does the same thing as IOObjectGetClass, but returns the result as a CFStringRef. Availability Available in OS X v10.4 and later. Declared in
IOKitLib.h

IOObjectCopySuperclassForClass
Return the superclass name of the given class.

CFStringRef IOObjectCopySuperclassForClass( CFStringRef classname) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters
classname

The name of the class as a CFString. Return Value The resulting CFStringRef. This should be released by the caller. If there is no superclass, or a valid class name is not passed in, then NULL is returned. Discussion This function uses the OSMetaClass system in the kernel to derive the name of the superclass of the class.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

893

IOKitLib.h Reference Functions

Availability Available in OS X v10.4 and later. Declared in

Declared in
IOKitLib.h

IOObjectGetUserRetainCount
Returns the retain count for the current process of an IOKit object.

uint32_t IOObjectGetUserRetainCount( io_object_t object ) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

Parameters
object

An IOKit object. Return Value If the object handle is valid, the objects user retain count is returned, otherwise zero is returned. Discussion This function may be used in diagnostics to determine the current retain count for the calling process of the kernel object. Availability Available in OS X v10.6 and later. Declared in
IOKitLib.h

IOObjectIsEqualTo
Checks two object handles to see if they represent the same kernel object.

boolean_t IOObjectIsEqualTo( io_object_t object, io_object_t anObject );

Parameters
object

An IOKit object.
anObject

Another IOKit object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

896

IOKitLib.h Reference Functions

Return Value If both object handles are valid, and represent the same object in the kernel true is returned, otherwise false. Discussion If two object handles are returned by IOKitLib functions, this function will compare them to see if they represent the same kernel object. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOObjectRelease
Releases an object handle previously returned by IOKitLib.

kern_return_t IOObjectRelease( io_object_t object );

Parameters
object

The IOKit object to release. Return Value A kern_return_t error code. Discussion All objects returned by IOKitLib should be released with this function when access to them is no longer needed. Using the object after it has been released may or may not return an error, depending on how many references the task has to the same object in the kernel. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI Deva_Example GLUT STUCAuthoringDeviceTool STUCOtherDeviceTool

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

897

IOKitLib.h Reference Functions

Declared in
IOKitLib.h

IOObjectRetain
Retains an object handle previously returned by IOKitLib.

kern_return_t IOObjectRetain( io_object_t object );

Parameters
object

The IOKit object to retain. Return Value A kern_return_t error code. Discussion Gives the caller an additional reference to an existing object handle previously returned by IOKitLib. Availability Available in OS X v10.1 and later.
Related Sample Code SMARTQuery VolumeToBSDNode

Declared in
IOKitLib.h

IORegistryCreateIterator
Create an iterator rooted at the registry root.

kern_return_t IORegistryCreateIterator( mach_port_t masterPort, const io_name_t plane, IOOptionBits options, io_iterator_t *iterator );

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

898

IOKitLib.h Reference Functions

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
options

kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator.
iterator

A created iterator handle, to be released by the caller when it has finished with it. Return Value A kern_return_t error code. Discussion This method creates an IORegistryIterator in the kernel that is set up with options to iterate children of the registry root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryEntryCreateCFProperties
Create a CF dictionary representation of a registry entry's property table.

kern_return_t IORegistryEntryCreateCFProperties( io_registry_entry_t entry, CFMutableDictionaryRef *properties, CFAllocatorRef allocator, IOOptionBits options );

Parameters
entry

The registry entry handle whose property table to copy.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

899

IOKitLib.h Reference Functions

properties

A CFDictionary is created and returned the caller on success. The caller should release with CFRelease.
allocator

The CF allocator to use when creating the CF containers.

options

No options are currently defined. Return Value A kern_return_t error code. Discussion This function creates an instantaneous snapshot of a registry entry's property table, creating a CFDictionary analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI GLUT STUCOtherDeviceTool VirtualScanner

Declared in
IOKitLib.h

IORegistryEntryCreateCFProperty
Create a CF representation of a registry entry's property.

CFTypeRef IORegistryEntryCreateCFProperty( io_registry_entry_t entry, CFStringRef key, CFAllocatorRef allocator, IOOptionBits options );

Parameters
entry

The registry entry handle whose property to copy.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

900

IOKitLib.h Reference Functions

key

A CFString specifying the property name.

allocator

The CF allocator to use when creating the CF container.

options

No options are currently defined. Return Value A CF container is created and returned the caller on success. The caller should release with CFRelease. Discussion This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. Availability Available in OS X v10.0 and later.
Related Sample Code CDROMSample GetPrimaryMACAddress GLUT VolumeToBSDNode

Declared in
IOKitLib.h

IORegistryEntryCreateIterator
Create an iterator rooted at a given registry entry.

kern_return_t IORegistryEntryCreateIterator( io_registry_entry_t entry, const io_name_t plane, IOOptionBits options, io_iterator_t *iterator );

Parameters
entry

The root entry to begin the iteration at.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

901

IOKitLib.h Reference Functions

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
options

kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned from IOIteratorNext calls on the registry iterator. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated.
iterator

A created iterator handle, to be released by the caller when it has finished with it. Return Value A kern_return_t error code. Discussion This method creates an IORegistryIterator in the kernel that is set up with options to iterate children or parents of a root entry, and to recurse automatically into entries as they are returned, or only when instructed with calls to IORegistryIteratorEnterEntry. The iterator object keeps track of entries that have been recursed into previously to avoid loops. Availability Available in OS X v10.0 and later.
Related Sample Code VolumeToBSDNode

Declared in
IOKitLib.h

IORegistryEntryFromPath
Looks up a registry entry by path.

io_registry_entry_t IORegistryEntryFromPath( mach_port_t masterPort, const io_string_t path );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

902

IOKitLib.h Reference Functions

path

A C-string path. Return Value A handle to the IORegistryEntry witch was found with the path, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure. Discussion This function parses paths to lookup registry entries. The path should begin with '<plane name>:' If there are characters remaining unparsed after an entry has been looked up, this is considered an invalid lookup. Paths are further documented in IORegistryEntry.h Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryEntryGetChildEntry
Returns the first child of a registry entry in a plane.

kern_return_t IORegistryEntryGetChildEntry( io_registry_entry_t entry, const io_name_t plane, io_registry_entry_t *child );

Parameters
entry

The registry entry whose child to look up.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
child

The first child of the registry entry, on success. The child must be released by the caller. Return Value A kern_return_t error code. Discussion This function will return the child which first attached to a registry entry in a plane.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

903

IOKitLib.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IOKitLib.h

IORegistryEntryGetChildIterator
Returns an iterator over an registry entry's child entries in a plane.

kern_return_t IORegistryEntryGetChildIterator( io_registry_entry_t entry, const io_name_t plane, io_iterator_t *iterator );

Parameters
entry

The registry entry whose children to iterate over.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
iterator

The created iterator over the children of the entry, on success. The iterator must be released when the iteration is finished. Return Value A kern_return_t error code. Discussion This method creates an iterator which will return each of a registry entry's child entries in a specified plane. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryEntryGetLocationInPlane
Returns a C-string location assigned to a registry entry, in a specified plane.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

904

IOKitLib.h Reference Functions

kern_return_t IORegistryEntryGetLocationInPlane( io_registry_entry_t entry, const io_name_t plane, io_name_t location );

Parameters
entry

The registry entry handle whose name to look up.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
location

The caller's buffer to receive the location string. Return Value A kern_return_t error code. Discussion Registry entries can given a location string in a particular plane, or globally. If the entry has had a location set in the specified plane that location string will be returned, otherwise the global location string is returned. If no global location string has been set, an error is returned. Availability Available in OS X v10.1 and later. Declared in
IOKitLib.h

IORegistryEntryGetName
Returns a C-string name assigned to a registry entry.

kern_return_t IORegistryEntryGetName( io_registry_entry_t entry, io_name_t name );

Parameters
entry

The registry entry handle whose name to look up.

name

The caller's buffer to receive the name.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

905

IOKitLib.h Reference Functions

Return Value A kern_return_t error code. Discussion Registry entries can be named in a particular plane, or globally. This function returns the entry's global name. The global name defaults to the entry's meta class name if it has not been named. Availability Available in OS X v10.0 and later.
Related Sample Code USBPrivateDataSample

Declared in
IOKitLib.h

IORegistryEntryGetNameInPlane
Returns a C-string name assigned to a registry entry, in a specified plane.

kern_return_t IORegistryEntryGetNameInPlane( io_registry_entry_t entry, const io_name_t plane, io_name_t name );

Parameters
entry

The registry entry handle whose name to look up.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
name

The caller's buffer to receive the name. Return Value A kern_return_t error code. Discussion Registry entries can be named in a particular plane, or globally. This function returns the entry's name in the specified plane or global name if it has not been named in that plane. The global name defaults to the entry's meta class name if it has not been named.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

906

IOKitLib.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IOKitLib.h

IORegistryEntryGetParentEntry
Returns the first parent of a registry entry in a plane.

kern_return_t IORegistryEntryGetParentEntry( io_registry_entry_t entry, const io_name_t plane, io_registry_entry_t *parent );

Parameters
entry

The registry entry whose parent to look up.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
parent

The first parent of the registry entry, on success. The parent must be released by the caller. Return Value A kern_return_t error code. Discussion This function will return the parent to which the registry entry was first attached in a plane. Availability Available in OS X v10.0 and later.
Related Sample Code GetPrimaryMACAddress GLUT SMARTQuery

Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

907

IOKitLib.h Reference Functions

IORegistryEntryGetParentIterator
Returns an iterator over an registry entry's parent entries in a plane.

kern_return_t IORegistryEntryGetParentIterator( io_registry_entry_t entry, const io_name_t plane, io_iterator_t *iterator );

Parameters
entry

The registry entry whose parents to iterate over.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
iterator

The created iterator over the parents of the entry, on success. The iterator must be released when the iteration is finished. Return Value A kern_return_t error. Discussion This method creates an iterator which will return each of a registry entry's parent entries in a specified plane. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryEntryGetPath
Create a path for a registry entry.

kern_return_t IORegistryEntryGetPath( io_registry_entry_t entry, const io_name_t plane, io_string_t path );

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

908

IOKitLib.h Reference Functions

Parameters
entry

The registry entry handle whose path to look up.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.
path

A char buffer allocated by the caller. Return Value IORegistryEntryGetPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path. Discussion The path for a registry entry is copied to the caller's buffer. The path describes the entry's attachment in a particular plane, which must be specified. The path begins with the plane name followed by a colon, and then followed by '/' separated path components for each of the entries between the root and the registry entry. An alias may also exist for the entry, and will be returned if available. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI

Declared in
IOKitLib.h

IORegistryEntryGetRegistryEntryID
Returns an ID for the registry entry that is global to all tasks.

kern_return_t IORegistryEntryGetRegistryEntryID( io_registry_entry_t entry, uint64_t *entryID );

Parameters
entry

The registry entry handle whose ID to look up.

entryID

The resulting ID.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

909

IOKitLib.h Reference Functions

Return Value A kern_return_t error code. Discussion The entry ID returned by IORegistryEntryGetRegistryEntryID can be used to identify a registry entry across all tasks. A registry entry may be looked up by its entryID by creating a matching dictionary with IORegistryEntryIDMatching() to be used with the IOKit matching functions. The ID is valid only until the machine reboots. Availability Available in OS X v10.6 and later. Declared in
IOKitLib.h

IORegistryEntryIDMatching
Create a matching dictionary that specifies an IOService match based on a registry entry ID.

CFMutableDictionaryRef IORegistryEntryIDMatching( uint64_t entryID );

Parameters
entryID

The registry entry ID to be found. Return Value The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. Discussion This function creates a matching dictionary that will match a registered, active IOService found with the given registry entry ID. The entry ID for a registry entry is returned by IORegistryEntryGetRegistryEntryID(). Availability Available in OS X v10.6 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

910

IOKitLib.h Reference Functions

IORegistryEntryInPlane
Determines if the registry entry is attached in a plane.

boolean_t IORegistryEntryInPlane( io_registry_entry_t entry, const io_name_t plane );

Parameters
entry

The registry entry.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane. Return Value If the entry has a parent in the plane, true is returned, otherwise false is returned. Discussion This method determines if the entry is attached in a plane to any other entry. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryEntrySearchCFProperty
Create a CF representation of a registry entry's property.

CFTypeRef IORegistryEntrySearchCFProperty( io_registry_entry_t entry, const io_name_t plane, CFStringRef key, CFAllocatorRef allocator, IOOptionBits options ) CF_RETURNS_RETAINED;

Parameters
entry

The registry entry at which to start the search.

plane

The name of an existing registry plane. Plane names are defined in IOKitKeys.h, eg. kIOServicePlane.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

911

IOKitLib.h Reference Functions

key

A CFString specifying the property name.

allocator

The CF allocator to use when creating the CF container.

options

kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard IORegistryEntryCreateCFProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children. Return Value A CF container is created and returned the caller on success. The caller should release with CFRelease. Discussion This function creates an instantaneous snapshot of a registry entry property, creating a CF container analogue in the caller's task. Not every object available in the kernel is represented as a CF container; currently OSDictionary, OSArray, OSSet, OSSymbol, OSString, OSData, OSNumber, OSBoolean are created as their CF counterparts. This function will search for a property, starting first with specified registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the same semantics as IORegistryEntryCreateCFProperty. The iteration keeps track of entries that have been recursed into previously to avoid loops. Availability Available in OS X v10.1 and later. Declared in
IOKitLib.h

IORegistryEntrySetCFProperties
Set CF container based properties in a registry entry.

kern_return_t IORegistryEntrySetCFProperties( io_registry_entry_t entry, CFTypeRef properties );

Parameters
entry

The registry entry whose properties to set.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

912

IOKitLib.h Reference Functions

properties

A CF container - commonly a CFDictionary but this is not enforced. The container should consist of objects which are understood by IOKit - these are currently : CFDictionary, CFArray, CFSet, CFString, CFData, CFNumber, CFBoolean, and are passed in the kernel as the corresponding OSDictionary etc. objects. Return Value A kern_return_t error code returned by the object. Discussion This is a generic method to pass a CF container of properties to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperties for connection based property setting. The properties are interpreted by the object. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI

Declared in
IOKitLib.h

IORegistryEntrySetCFProperty
Set a CF container based property in a registry entry.

kern_return_t IORegistryEntrySetCFProperty( io_registry_entry_t entry, CFStringRef propertyName, CFTypeRef property );

Parameters
entry

The registry entry whose property to set.

propertyName

The name of the property as a CFString.

property

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

913

IOKitLib.h Reference Functions

Return Value A kern_return_t error code returned by the object. Discussion This is a generic method to pass a CF container as a property to an object in the registry. Setting properties in a registry entry is not generally supported, it is more common to support IOConnectSetCFProperty for connection based property setting. The property is interpreted by the object. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryGetRootEntry
Return a handle to the registry root.

io_registry_entry_t IORegistryGetRootEntry( mach_port_t masterPort );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port. Return Value A handle to the IORegistryEntry root instance, to be released with IOObjectRelease by the caller, or MACH_PORT_NULL on failure. Discussion This method provides an accessor to the root of the registry for the machine. The root may be passed to a registry iterator when iterating a plane, and contains properties that describe the available planes, and diagnostic information for IOKit. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

914

IOKitLib.h Reference Functions

IORegistryIteratorEnterEntry
Recurse into the current entry in the registry iteration.

kern_return_t IORegistryIteratorEnterEntry( io_iterator_t iterator );

Return Value A kern_return_t error code. Discussion This method makes the current entry, ie. the last entry returned by IOIteratorNext, the root in a new level of recursion. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IORegistryIteratorExitEntry
Exits a level of recursion, restoring the current entry.

kern_return_t IORegistryIteratorExitEntry( io_iterator_t iterator );

Return Value kIOReturnSuccess if a level of recursion was undone, kIOReturnNoDevice if no recursive levels are left in the iteration. Discussion This method undoes an IORegistryIteratorEnterEntry, restoring the current entry. If there are no more levels of recursion to exit false is returned, otherwise true is returned. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

915

IOKitLib.h Reference Functions

IOServiceAddInterestNotification
Register for notification of state changes in an IOService.

kern_return_t IOServiceAddInterestNotification( IONotificationPortRef notifyPort, io_service_t service, const io_name_t interestType, IOServiceInterestCallback callback, void *refCon, io_object_t *notification );

Parameters
notifyPort

A IONotificationPortRef object that controls how messages will be sent when the notification is fired. See IONotificationPortCreate.
interestType

A notification type from IOKitKeys.h kIOGeneralInterest General state changes delivered via the IOService::message API. kIOBusyInterest Delivered when the IOService changes its busy state to or from zero. The message argument contains the new busy state causing the notification.
callback

A callback function called when the notification fires, with messageType and messageArgument for the state change.
refCon

A reference constant for the callbacks use.

notification

An object handle is returned on success, and should be released by the caller when the notification is to be destroyed. Return Value A kern_return_t error code. Discussion IOService objects deliver notifications of their state changes to their clients via the IOService::message API, and to other interested parties including callers of this function. Message type s are defined IOKit/IOMessage.h. Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

916

IOKitLib.h Reference Functions

Related Sample Code USBPrivateDataSample

Declared in
IOKitLib.h

IOServiceAddMatchingNotification
Look up registered IOService objects that match a matching dictionary, and install a notification request of new IOServices that match.

kern_return_t IOServiceAddMatchingNotification( IONotificationPortRef notifyPort, const io_name_t notificationType, CFDictionaryRef matching, IOServiceMatchingCallback callback, void *refCon, io_iterator_t *notification );

Parameters
notifyPort

A IONotificationPortRef object that controls how messages will be sent when the armed notification is fired. When the notification is delivered, the io_iterator_t representing the notification should be iterated through to pick up all outstanding objects. When the iteration is finished the notification is rearmed. See IONotificationPortCreate.
notificationType

A notification type from IOKitKeys.h kIOPublishNotification Delivered when an IOService is registered. kIOFirstPublishNotification Delivered when an IOService is registered, but only once per IOService instance. Some IOService's may be reregistered when their state is changed. kIOMatchedNotification Delivered when an IOService has had all matching drivers in the kernel probed and started. kIOFirstMatchNotification Delivered when an IOService has had all matching drivers in the kernel probed and started, but only once per IOService instance. Some IOService's may be reregistered when their state is changed. kIOTerminatedNotification Delivered after an IOService has been terminated.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

917

IOKitLib.h Reference Functions

matching

A callback function called when the notification fires.

refCon

A reference constant for the callbacks use.

notification

An iterator handle is returned on success, and should be released by the caller when the notification is to be destroyed. The notification is armed when the iterator is emptied by calls to IOIteratorNext - when no more objects are returned, the notification is armed. Note the notification is not armed when first created. Return Value A kern_return_t error code. Discussion This is the preferred method of finding IOService objects that may arrive at any time. The type of notification specifies the state change the caller is interested in, on IOService's that match the match dictionary. Notification types are identified by name, and are defined in IOKitKeys.h. The matching information used in the matching dictionary may vary depending on the class of service being looked up. Availability Available in OS X v10.0 and later.
Related Sample Code STUCAuthoringDeviceTool STUCOtherDeviceTool USBPrivateDataSample

Declared in
IOKitLib.h

IOServiceClose
Close a connection to an IOService and destroy the connect handle.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

918

IOKitLib.h Reference Functions

kern_return_t IOServiceClose( io_connect_t connect );

Parameters
connect

The connect handle created by IOServiceOpen. It will be destroyed by this function, and should not be released with IOObjectRelease. Return Value A kern_return_t error code. Discussion A connection created with the IOServiceOpen should be closed when the connection is no longer to be used with IOServiceClose. Availability Available in OS X v10.0 and later.
Related Sample Code SimpleUserClient

Declared in
IOKitLib.h

IOServiceGetBusyState
Returns the busyState of an IOService.

kern_return_t IOServiceGetBusyState( io_service_t service, uint32_t *busyState );

Parameters
service

The IOService whose busyState to return.

busyState

The busyState count is returned. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

919

IOKitLib.h Reference Functions

Discussion Many activities in IOService are asynchronous. When registration, matching, or termination is in progress on an IOService, its busyState is increased by one. Change in busyState to or from zero also changes the IOService's provider's busyState by one, which means that an IOService is marked busy when any of the above activities is ocurring on it or any of its clients. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOServiceGetMatchingService
Look up a registered IOService object that matches a matching dictionary.

io_service_t IOServiceGetMatchingService( mach_port_t masterPort, CFDictionaryRef matching );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
matching

A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching. Return Value The first service matched is returned on success. The service must be released by the caller. Discussion This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

920

IOKitLib.h Reference Functions

Availability Available in OS X v10.2 and later.

Related Sample Code HID Config Save HID Dumper HID Utilities VolumeToBSDNode

Declared in
IOKitLib.h

IOServiceGetMatchingServices
Look up registered IOService objects that match a matching dictionary.

kern_return_t IOServiceGetMatchingServices( mach_port_t masterPort, CFDictionaryRef matching, io_iterator_t *existing );

Parameters
masterPort

The master port obtained from IOMasterPort(). Pass kIOMasterPortDefault to look up the default master port.
matching

An iterator handle is returned on success, and should be released by the caller when the iteration is finished. Return Value A kern_return_t error code.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

921

IOKitLib.h Reference Functions

Discussion This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI GetPrimaryMACAddress GLUT SimpleUserClient SMARTQuery

Declared in
IOKitLib.h

IOServiceMatching
Create a matching dictionary that specifies an IOService class match.

CFMutableDictionaryRef IOServiceMatching( const char *name );

Parameters
name

The class name, as a const C-string. Class matching is successful on IOService's of this class or any subclass. Return Value The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. Discussion A very common matching criteria for IOService is based on its class. IOServiceMatching will create a matching dictionary that specifies any IOService of a class, or its subclasses. The class is specified by C-string name. Availability Available in OS X v10.0 and later.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

922

IOKitLib.h Reference Functions

Related Sample Code AppleSamplePCI Deva_Example GetPrimaryMACAddress GLUT SimpleUserClient

Declared in
IOKitLib.h

IOServiceMatchPropertyTable
Match an IOService objects with matching dictionary.

kern_return_t IOServiceMatchPropertyTable( io_service_t service, CFDictionaryRef matching, boolean_t *matches );

Parameters
service

The IOService object to match.

matching

A CF dictionary containing matching information. IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.
matches

The boolean result is returned. Return Value A kern_return_t error code. Discussion This function calls the matching method of an IOService object and returns the boolean result. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

923

IOKitLib.h Reference Functions

IOServiceNameMatching
Create a matching dictionary that specifies an IOService name match.

CFMutableDictionaryRef IOServiceNameMatching( const char *name );

Parameters
name

The IOService name, as a const C-string. Return Value The matching dictionary created, is returned on success, or zero on failure. The dictionary is commonly passed to IOServiceGetMatchingServices or IOServiceAddNotification which will consume a reference, otherwise it should be released with CFRelease by the caller. Discussion A common matching criteria for IOService is based on its name. IOServiceNameMatching will create a matching dictionary that specifies an IOService with a given name. Some IOServices created from the device tree will perform name matching on the standard compatible, name, model properties. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOServiceOpen
A request to create a connection to an IOService.

kern_return_t IOServiceOpen( io_service_t service, task_port_t owningTask, uint32_t type, io_connect_t *connect );

Parameters
service

The IOService object to open a connection to, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

924

IOKitLib.h Reference Functions

owningTask

The mach task requesting the connection.

type

A constant specifying the type of connection to be created, interpreted only by the IOService's family.
connect

An io_connect_t handle is returned on success, to be used with the IOConnectXXX APIs. It should be destroyed with IOServiceClose(). Return Value A return code generated by IOService::newUserClient. Discussion A non kernel client may request a connection be opened via the IOServiceOpen() library function, which will call IOService::newUserClient in the kernel. The rules & capabilities of user level clients are family dependent, the default IOService implementation returns kIOReturnUnsupported. Availability Available in OS X v10.0 and later.
Related Sample Code AppleSamplePCI SimpleUserClient

Declared in
IOKitLib.h

IOServiceRequestProbe
A request to rescan a bus for device changes.

kern_return_t IOServiceRequestProbe( io_service_t service, uint32_t options );

Parameters
service

The IOService object to request a rescan, usually obtained via the IOServiceGetMatchingServices or IOServiceAddNotification APIs.
options

An options mask, interpreted only by the IOService's family.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

925

IOKitLib.h Reference Functions

Return Value A return code generated by IOService::requestProbe. Discussion A non kernel client may request a bus or controller rescan for added or removed devices, if the bus family does automatically notice such changes. For example, SCSI bus controllers do not notice device changes. The implementation of this routine is family dependent, and the default IOService implementation returns kIOReturnUnsupported. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOServiceWaitQuiet
Wait for an IOService's busyState to be zero.

kern_return_t IOServiceWaitQuiet( io_service_t service, mach_timespec_t *waitTime );

Parameters
service

The IOService wait on.

waitTime

Specifies a maximum time to wait. Return Value Returns an error code if mach synchronization primitives fail, kIOReturnTimeout, or kIOReturnSuccess. Discussion Blocks the caller until an IOService is non busy, see IOServiceGetBusyState. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

926

IOKitLib.h Reference Callbacks

Callbacks
See the Overview for header-level documentation.

IOAsyncCallback
standard callback function for asynchronous I/O requests with lots of extra arguments beyond a refcon and result code.

typedef void ( *IOAsyncCallback)( void *refcon, IOReturn result, void **args, uint32_t numArgs);

Parameters
refcon

The refcon passed into the original I/O request

result

The result of the I/O operation

args

Array of extra arguments

numArgs

Number of extra arguments Availability Available in OS X v10.0 and later. Declared in

IOKitLib.h

IOAsyncCallback0
standard callback function for asynchronous I/O requests with no extra arguments beyond a refcon and result code.

typedef void ( *IOAsyncCallback0)(

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

927

IOKitLib.h Reference Callbacks

void *refcon, IOReturn result);

Parameters
refcon

The refcon passed into the original I/O request

result

The result of the I/O operation Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOAsyncCallback1
standard callback function for asynchronous I/O requests with one extra argument beyond a refcon and result code. This is often a count of the number of bytes transferred

typedef void ( IOAsyncCallback1)( void refcon, IOReturn result, void *arg0);

Parameters
refcon

The refcon passed into the original I/O request

result

The result of the I/O operation

arg0

Extra argument Availability Available in OS X v10.0 and later. Declared in

IOKitLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

928

IOKitLib.h Reference Callbacks

IOAsyncCallback2
standard callback function for asynchronous I/O requests with two extra arguments beyond a refcon and result code.

typedef void ( *IOAsyncCallback2)( void *refcon, IOReturn result, void *arg0, void *arg1);

Parameters
refcon

The refcon passed into the original I/O request

result

The result of the I/O operation

arg0

Extra argument
arg1

Extra argument Availability Available in OS X v10.0 and later. Declared in

IOKitLib.h

IOServiceInterestCallback
Callback function to be notified of changes in state of an IOService.

typedef void ( *IOServiceInterestCallback)( void *refcon, io_service_t service, uint32_t messageType, void *messageArgument );

Parameters
refcon

The refcon passed when the notification was installed.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

929

IOKitLib.h Reference Constants

service

The IOService whose state has changed.

messageType

A messageType enum, defined by IOKit/IOMessage.h or by the IOService's family.

messageArgument

An argument for the message, dependent on the messageType. If the message data is larger than sizeof(void*), then messageArgument contains a pointer to the message data; otherwise, messageArgument contains the message data. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

IOServiceMatchingCallback
Callback function to be notified of IOService publication.

typedef void ( IOServiceMatchingCallback)( void refcon, io_iterator_t iterator );

Parameters
refcon

The refcon passed when the notification was installed.

iterator

The notification iterator which now has new objects. Availability Available in OS X v10.0 and later. Declared in
IOKitLib.h

Constants
See the Overview for header-level documentation.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

930

IOKitLib.h Reference Constants

Global Constants

extern const mach_port_t kIOMasterPortDefault;

Constants
kIOMasterPortDefault

The default mach port used to initiate communication with IOKit. When specifying a master port to IOKit functions, the NULL argument indicates "use the default". This is a synonym for NULL, if you'd rather use a named constant. Available in OS X v10.2 and later. Declared in IOKitLib.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

931

IOKitServer.h User-Space Reference

Declared in

IOKitServer.h

Overview
Included Headers

<IOKit/IOTypes.h> <IOKit/IOKitKeys.h> <IOKit/OSMessageNotification.h> <mach/kmod.h>

Constants
See the Overview for header-level documentation.

IOCatalogueGetData

enum { kIOCatalogGetContents = 1, kIOCatalogGetModuleDemandList = 2, kIOCatalogGetCacheMissList = 3, kIOCatalogGetROMMkextList = 4 };

Constants
kIOCatalogGetContents

Returns a snapshot of the database to the caller. Available in OS X v10.0 and later. Declared in IOKitServer.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

932

IOKitServer.h User-Space Reference Constants

Discussion user-client flags

IOCatalogueReset

enum { kIOCatalogResetDefault = 1 };

Constants
kIOCatalogResetDefault

Removes all entries from IOCatalogue except those used for booting the system. Available in OS X v10.0 and later. Declared in IOKitServer.h. Discussion user-client flag

IOCatalogueSendData

enum { kIOCatalogAddDrivers = 1, kIOCatalogAddDriversNoMatch, kIOCatalogRemoveDrivers, kIOCatalogRemoveDriversNoMatch, kIOCatalogStartMatching, kIOCatalogRemoveKernelLinker, kIOCatalogKextdActive, kIOCatalogKextdFinishedLaunching, kIOCatalogResetDrivers, kIOCatalogResetDriversNoMatch };

Constants
kIOCatalogAddDrivers

Signals a call to the addDrivers function in IOCatalogue. Available in OS X v10.0 and later. Declared in IOKitServer.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

933

IOKitServer.h User-Space Reference Constants

kIOCatalogAddDriversNoMatch

Signals a call to the addDrivers function in IOCatalogue but does not start a matching thread. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogRemoveDrivers

Signals a call to the removeDrivers function in IOCatalogue. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogRemoveDriversNoMatch

Signals a call to the removedrivers function in IOCatalogue but does not start a matching thread. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogStartMatching

Signals the IOCatalogue to start an IOService matching thread. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogRemoveKernelLinker

Deprecated; does nothing. Available in OS X v10.0 and later. Declared in IOKitServer.h.

kIOCatalogKextdActive

Signals the kernel that kextd is running. Available in OS X v10.6 and later. Declared in IOKitServer.h.
kIOCatalogKextdFinishedLaunching

Signals the IOCatalogue that kextd has finished sending it information at startup. Available in OS X v10.5 and later. Declared in IOKitServer.h.
kIOCatalogResetDrivers

Resets the IOCatalogue with a new set of personalities. Available in OS X v10.7 and later. Declared in IOKitServer.h.
kIOCatalogResetDriversNoMatch

Resets the IOCatalogue with a new set of personalities but does not start a matching thread. Available in OS X v10.7 and later. Declared in IOKitServer.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

934

IOKitServer.h User-Space Reference Constants

Discussion user-client flags.

IOCatalogueTerminate

enum { kIOCatalogModuleUnload = 1, kIOCatalogModuleTerminate, kIOCatalogServiceTerminate };

Constants
kIOCatalogModuleUnload

Terminates all services which depend on a particular module and unloads the module. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogModuleTerminate

Terminates all services which depend on a particular module but does not unload the module. Available in OS X v10.0 and later. Declared in IOKitServer.h.
kIOCatalogServiceTerminate

Terminates a particular service by name. Available in OS X v10.0 and later. Declared in IOKitServer.h. Discussion user-client flags.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

935

IOMedia.h User-Space Reference

Declared in

IOMedia.h

Overview
This header contains the IOMedia class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOMediaClass "IOMedia" kIOMediaContentHintKey "Content Hint" kIOMediaContentKey "Content" kIOMediaContentMaskKey "Content Mask" kIOMediaEjectableKey "Ejectable" kIOMediaIconKey "IOMediaIcon" kIOMediaLeafKey "Leaf" kIOMediaOpenKey "Open" kIOMediaPreferredBlockSizeKey "Preferred Block Size" kIOMediaRemovableKey "Removable" kIOMediaSizeKey "Size" kIOMediaUUIDKey "UUID" kIOMediaWholeKey "Whole" kIOMediaWritableKey "Writable"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

936

IOMedia.h User-Space Reference Constants

Constants
kIOMediaClass

The name of the IOMedia class. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaContentHintKey

A property of IOMedia objects. The kIOMediaContentHintKey property has an OSString value and contains a hint of the media's contents. The hint is set at the time of the object's creation, should the creator have a clue as to what it may contain. The hint string does not change for the lifetime of the object and is formed in the likeness of Apple's "Apple_HFS" strings or in the likeness of a UUID. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaContentKey

A property of IOMedia objects. The kIOMediaContentKey property has an OSString value and contains a description of the media's contents. The description is the same as the hint at the time of the object's creation, but it is possible that the description has been overridden by a client (which has probed the media and identified the content correctly) of the media object. It is more accurate than the hint for this reason. The string is formed in the likeness of Apple's "Apple_HFS" strings or in the likeness of a UUID. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaContentMaskKey

A property of IOMedia clients. The kIOMediaContentMaskKey property has an OSString value and must exist in all IOMedia clients that drive new content (that is, produce new media objects). When the client matches against the provider media, the value of the client's kIOMediaContentMaskKey property is used to replace the provider's kIOMediaContentKey property. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaEjectableKey

A property of IOMedia objects. The kIOMediaEjectableKey property has an OSBoolean value and describes whether the media is ejectable from the drive mechanism under software control. Implies IOMediaRemovable is also true. Available in OS X v10.0 and later. Declared in IOMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

937

IOMedia.h User-Space Reference Constants

kIOMediaIconKey

A property of any object in the media stack. kIOMediaIconKey is a property of any object in the media stack that wishes to override the default icon shown for the media objects in the stack. It is usually defined in a provider object below the media object. It has an OSDictionary value, with properties identical to the kIOIconKey definition, that is, kCFBundleIdentifierKey and kIOBundleResourceFileKey. Available in OS X v10.2 and later. Declared in IOMedia.h.
kIOMediaLeafKey

A property of IOMedia objects. The kIOMediaLeafKey property has an OSBoolean value and describes whether the media is a leaf, that is, it is the deepest media object in this branch of the I/O Registry. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaOpenKey

A property of IOMedia objects. The kIOMediaOpenKey property has an OSBoolean value and describes whether a client presently has an open on this media. Available in OS X v10.5 and later. Declared in IOMedia.h.
kIOMediaPreferredBlockSizeKey

A property of IOMedia objects. The kIOMediaPreferredBlockSizeKey property has an OSNumber value and describes the media's natural block size in bytes. This information is useful to clients that want to optimize access to the media. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaRemovableKey

A property of IOMedia objects. The kIOMediaRemovableKey property has an OSBoolean value and describes whether the media is removable from the drive mechanism. Available in OS X v10.2 and later. Declared in IOMedia.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

938

IOMedia.h User-Space Reference Constants

kIOMediaSizeKey

A property of IOMedia objects. The kIOMediaSizeKey property has an OSNumber value and describes the total length of the media in bytes. Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaUUIDKey

A property of IOMedia objects. The kIOMediaUUIDKey property has an OSString value and contains a persistent Universal Unique Identifier for the media if such an identifier is available. Available in OS X v10.4 and later. Declared in IOMedia.h.
kIOMediaWholeKey

A property of IOMedia objects. The kIOMediaWholeKey property has an OSBoolean value and describes whether the media is whole, that is, it represents the whole disk (the physical disk, or a virtual replica thereof ). Available in OS X v10.0 and later. Declared in IOMedia.h.
kIOMediaWritableKey

A property of IOMedia objects. The kIOMediaWritableKey property has an OSBoolean value and describes whether the media is writable. Available in OS X v10.0 and later. Declared in IOMedia.h.

IOMediaAttributeMask

enum { kIOMediaAttributeEjectableMask = 0x00000001, kIOMediaAttributeRemovableMask = 0x00000002, kIOMediaAttributeReservedMask = 0xFFFFFFFC };

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

939

IOMedia.h User-Space Reference Constants

Constants
kIOMediaAttributeEjectableMask

Indicates whether the media is ejectable from the drive mechanism under software control. Implies kIOMediaAttributeRemovableMask. Available in OS X v10.4 and later. Declared in IOMedia.h.
kIOMediaAttributeRemovableMask

Indicates whether the media is removable from the drive mechanism. Available in OS X v10.4 and later. Declared in IOMedia.h. Discussion The IOMediaAttributeMask bit mask describes various attributes of the media object, such as its ejectability and its removability.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

940

IOMessage.h User-Space Reference

Declared in

IOMessage.h

Overview
Defines message type constants for several IOKit messaging API's.

Included Headers

Functions
See the Overview for header-level documentation.

iokit_vendor_specific_msg

#define iokit_vendor_specific_msg(message) (UInt32)(sys_iokit|sub_iokit_vendor_specific|message)

Discussion iokit_vendor_specific_msg passes messages in the sub_iokit_vendor_specific subsystem. It can be used to generate messages that are used for private communication between vendor specific code with the IOService::message() etc. APIs. Availability Available in OS X v10.4 and later. Declared in
IOMessage.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

941

IOMessage.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOMessageCanDevicePowerOff iokit_common_msg(0x200) kIOMessageCanSystemPowerOff iokit_common_msg(0x240) kIOMessageCanSystemSleep iokit_common_msg(0x270) kIOMessageDeviceHasPoweredOff iokit_common_msg(0x225) kIOMessageDeviceHasPoweredOn iokit_common_msg(0x230) kIOMessageDeviceWillNotPowerOff iokit_common_msg(0x220) kIOMessageDeviceWillPowerOff iokit_common_msg(0x210) kIOMessageDeviceWillPowerOn iokit_common_msg(0x215) kIOMessageSystemHasPoweredOn iokit_common_msg(0x300) kIOMessageSystemPagingOff iokit_common_msg(0x255) kIOMessageSystemWillNotPowerOff iokit_common_msg(0x260) kIOMessageSystemWillNotSleep iokit_common_msg(0x290) kIOMessageSystemWillPowerOff iokit_common_msg(0x250) kIOMessageSystemWillPowerOn iokit_common_msg(0x320) kIOMessageSystemWillRestart iokit_common_msg(0x310) kIOMessageSystemWillSleep iokit_common_msg(0x280)

Constants
kIOMessageCanDevicePowerOff

Delivered to kIOAppPowerStateInterest clients of devices that implement their own idle timeouts. This message type is almost never used. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageCanSystemPowerOff

Available in OS X v10.0 and later. Declared in IOMessage.h.

kIOMessageCanSystemSleep

Announces/Requests permission to proceed to system sleep. Delivered to in-kernel IOKit drivers via kIOGeneralInterest and kIOPriorityPowerStateInterest. Delivered to user clients of IORegisterForSystemPower. Available in OS X v10.0 and later. Declared in IOMessage.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

942

IOMessage.h User-Space Reference Constants

kIOMessageDeviceHasPoweredOff

IOService power mgt does not send kIOMessageDeviceHasPoweredOff. Available in OS X v10.7 and later. Declared in IOMessage.h.
kIOMessageDeviceHasPoweredOn

Indicates the device has just moved to a higher power state. Sent to IOKit interest notification clients of type kIOAppPowerStateInterest and kIOGeneralInterest. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageDeviceWillNotPowerOff

This IOKit interest notification is largely unused; it's not very interesting. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageDeviceWillPowerOff

Indicates the device is about to move to a lower power state. Sent to IOKit interest notification clients of type kIOAppPowerStateInterest and kIOGeneralInterest. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageDeviceWillPowerOn

IOService power mgt does not send kIOMessageDeviceWillPowerOn. Available in OS X v10.7 and later. Declared in IOMessage.h.
kIOMessageSystemHasPoweredOn

Announces that the system and its devices have woken up. Delivered to in-kernel IOKit drivers via kIOGeneralInterest and kIOPriorityPowerStateInterest. Delivered to user clients of IORegisterForSystemPower. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageSystemPagingOff

Indicates an imminent system shutdown, paging device now unavailable. Recipients have a limited amount of time to respond, otherwise the system will timeout and shutdown even without a response. Delivered to clients of registerPrioritySleepWakeInterest(). Never delivered to user space notification clients. Available in OS X v10.7 and later. Declared in IOMessage.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

943

IOMessage.h User-Space Reference Constants

kIOMessageSystemWillNotPowerOff

Available in OS X v10.0 and later. Declared in IOMessage.h.

kIOMessageSystemWillNotSleep

Announces that the system has retracted a previous attempt to sleep; it follows kIOMessageCanSystemSleep. Delivered to in-kernel IOKit drivers via kIOGeneralInterest and kIOPriorityPowerStateInterest. Delivered to user clients of IORegisterForSystemPower. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageSystemWillPowerOff

Indicates an imminent system shutdown. Recipients have a limited amount of time to respond, otherwise the system will timeout and shutdown even without a response. Delivered to in-kernel IOKit drivers via IOService::systemWillShutdown(), and to clients of registerPrioritySleepWakeInterest(). Never delivered to user space notification clients. Available in OS X v10.0 and later. Declared in IOMessage.h.
kIOMessageSystemWillPowerOn

Announces that the system is beginning to power the device tree; most devices are unavailable at this point.. Delivered to in-kernel IOKit drivers via kIOGeneralInterest and kIOPriorityPowerStateInterest. Delivered to user clients of IORegisterForSystemPower. Available in OS X v10.3 and later. Declared in IOMessage.h.
kIOMessageSystemWillRestart

Indicates an imminent system restart. Recipients have a limited amount of time to respond, otherwise the system will timeout and restart even without a response. Delivered to in-kernel IOKit drivers via IOService::systemWillShutdown(), and to clients of registerPrioritySleepWakeInterest(). Never delivered to user space notification clients. Available in OS X v10.1 and later. Declared in IOMessage.h.
kIOMessageSystemWillSleep

Announces that sleep is beginning. Delivered to in-kernel IOKit drivers via kIOGeneralInterest and kIOPriorityPowerStateInterest. Delivered to user clients of IORegisterForSystemPower. Available in OS X v10.0 and later. Declared in IOMessage.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

944

IONetworkController.h User-Space Reference

Declared in

IONetworkController.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOActiveMedium "IOActiveMedium" kIODefaultMedium "IODefaultMedium" kIOFeatures "IOFeatures" kIOLinkData "IOLinkData" kIOLinkSpeed "IOLinkSpeed" kIOLinkStatus "IOLinkStatus" kIOMACAddress "IOMACAddress" kIOMaxPacketSize "IOMaxPacketSize" kIOMediumDictionary "IOMediumDictionary" kIOMinPacketSize "IOMinPacketSize" kIOModel "IOModel" kIONetworkControllerClass "IONetworkController" kIONetworkFilterGroup "IONetworkFilterGroup" kIOPacketFilters "IOPacketFilters" kIORevision "IORevision" kIOSelectedMedium "IOSelectedMedium" kIOVendor "IOVendor"

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

945

IONetworkController.h User-Space Reference Constants

Constants
kIOActiveMedium

A property of IONetworkController objects. The kIOActiveMedium property is a property of IONetworkController objects. It has an OSSymbol value that describes the name of the active medium. This is the name of the medium where an active link has been established. This name can be used as a key into the medium dictionary to gather additional information about the active medium. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIODefaultMedium

A property of IONetworkController objects. The kIODefaultMedium property is a property of IONetworkController objects. It has an OSString value that describes the name of the default medium. This definition may change or disappear in the future. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOFeatures

A property of IONetworkController objects. The kIOFeatures property is a property of IONetworkController objects. It has an OSNumber value that describes generic features defined by IONetworkController that are supported by the network controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOLinkData

A property of IONetworkController objects. The kIOLinkData property is a property of IONetworkController objects. It has an OSData value that contains additional information describing the active link that was established. Its interpretation is not defined. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOLinkSpeed

A property of IONetworkController objects. The kIOLinkSpeed property is a property of IONetworkController objects. It has an OSNumber value that describes the speed of the link established over the active medium in bits per second. Available in OS X v10.0 and later. Declared in IONetworkController.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

946

IONetworkController.h User-Space Reference Constants

kIOLinkStatus

A property of IONetworkController objects. The kIOLinkStatus property is a property of IONetworkController objects. It has an OSNumber value that describes the current network link status. See IONetworkMedium for the definition of the link status bits. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOMACAddress

A property of IONetworkController objects. The kIOMACAddress property is a property of IONetworkController objects. It has an OSData value that describes the hardware MAC (media access controller) address, or station address, of the network controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOMaxPacketSize

A property of IONetworkController objects. The kIOMaxPacketSize property is a property of IONetworkController objects. It has an OSNumber value that describes the maximum packet size supported by the controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOMediumDictionary

A property of IONetworkController objects. The kIOMediumDictionary property is a property of IONetworkController objects. It has an OSDictionary value that is a container for the collection of IONetworkMedium objects that represent the media types supported by the network controller. Each entry in the dictionary is a key/value pair consisting of the medium name, and a dictionary value that contains the properties for that medium entry. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOMinPacketSize

A property of IONetworkController objects. The kIOMinPacketSize property is a property of IONetworkController objects. It has an OSNumber value that describes the minimum packet size supported by the controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

947

IONetworkController.h User-Space Reference Constants

kIOModel

A property of IONetworkController objects. The kIOModel property is a property of IONetworkController objects. It has an OSString value that describes the model of the network controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIONetworkControllerClass

The name of the IONetworkController class. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIONetworkFilterGroup

The name assigned to the standard network filter group. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOPacketFilters

A property of IONetworkController objects. The kIOPacketFilters property is a property of IONetworkController objects. It has an OSDictionary value that describes the entire set of packet filters supported by the controller. Each entry in the dictionary is a key/value pair consisting of the filter group name, and an OSNumber describing the set of supported filters for that group. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIORevision

A property of IONetworkController objects. The kIORevision property is a property of IONetworkController objects. It has an OSString value that describes the revision level of the network controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOSelectedMedium

A property of IONetworkController objects. The kIOSelectedMedium property is a property of IONetworkController objects. It has an OSSymbol value that describes the name of the current selected medium. This name can be used as a key into the medium dictionary to gather additional information about the selected medium. Available in OS X v10.0 and later. Declared in IONetworkController.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

948

IONetworkController.h User-Space Reference Constants

kIOVendor

A property of IONetworkController objects. The kIOVendor property is a property of IONetworkController objects. It has an OSString value that describes the vendor of the network controller. Available in OS X v10.0 and later. Declared in IONetworkController.h.

Network
Feature flags returned by the getFeatures() method.

enum { kIONetworkFeatureNoBSDWait = 0x01, kIONetworkFeatureHardwareVlan = 0x02, kIONetworkFeatureSoftwareVlan = 0x04, kIONetworkFeatureMultiPages = 0x08, kIONetworkFeatureTSOIPv4 = 0x10, kIONetworkFeatureTSOIPv6 = 0x20 };

Constants
kIONetworkFeatureNoBSDWait

Set this bit in the value returned by getFeatures() to disable the automatic wait for "IOBSD" resource by the IONetworkController::start() method. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIONetworkFeatureHardwareVlan

Set this bit in the value returned by getFeatures() to indicate the controller supports hardware stripping and stuffing of 802.1q vlan tags. If the controller supports this feature it must enable it when initializing so that all received packets delivered to higher layers have the tag stripped. The controller should use setVlanTag() to provide the tag information out of band. Available in OS X v10.3 and later. Declared in IONetworkController.h.
kIONetworkFeatureSoftwareVlan

Set this bit in the value returned by getFeatures() to indicate that the controller can support software based vlan by transmitting and receiving packets 4 bytes longer that normal. Available in OS X v10.3 and later. Declared in IONetworkController.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

949

IONetworkController.h User-Space Reference Constants

kIONetworkFeatureMultiPages

Set this bit if the driver is capable of handling packets coming down from the network stack that reside in virtually, but not in physically contiguous span of the external mbuf clusters. In this case, the data area of a packet in the external mbuf cluster might cross one or more physical pages that are disjoint, depending on the interface MTU and the packet size. Such a use of larger than system page size clusters by the network stack is done for better system efficiency. Drivers that utilize the IOMbufNaturalMemoryCursor with the getPhysicalSegmentsWithCoalesce interfaces and enumerate the list of vectors should set this flag for possible gain in performance during bulk data transfer. Available in OS X v10.5 and later. Declared in IONetworkController.h.
kIONetworkFeatureTSOIPv4

Set this bit to advertise support for TCP/IPv4 segmentation offload. Available in OS X v10.6 and later. Declared in IONetworkController.h.
kIONetworkFeatureTSOIPv6

Set this bit to advertise support for TCP/IPv6 segmentation offload. Available in OS X v10.6 and later. Declared in IONetworkController.h. Discussion Feature Flags

StandardPacketFilters
All standard packet filters.

enum { kIOPacketFilterUnicast = 0x1, kIOPacketFilterBroadcast = 0x2, kIOPacketFilterMulticast = 0x10, kIOPacketFilterMulticastAll = 0x20, kIOPacketFilterPromiscuous = 0x100, kIOPacketFilterPromiscuousAll = 0x200 };

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

950

IONetworkController.h User-Space Reference Constants

Constants
kIOPacketFilterUnicast

Reception of unicast packets. Available in OS X v10.0 and later. Declared in IONetworkController.h.

kIOPacketFilterBroadcast

Reception of broadcast packets. Available in OS X v10.0 and later. Declared in IONetworkController.h.

kIOPacketFilterMulticast

Reception of multicast packets addressed to a set of multicast addresses. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOPacketFilterMulticastAll

Reception of all multicast packets. Available in OS X v10.0 and later. Declared in IONetworkController.h.
kIOPacketFilterPromiscuous

Reception of all packets. Available in OS X v10.0 and later. Declared in IONetworkController.h.

kIOPacketFilterPromiscuousAll

Reception of all packets, including bad packets. Available in OS X v10.0 and later. Declared in IONetworkController.h. Discussion Each filter will allow the reception of certain class of packets depending on its destination MAC address.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

951

IONetworkData.h User-Space Reference

Declared in

IONetworkData.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define kIONetworkDataAccessTypes "Access Types" #define kIONetworkDataBasicAccessTypes \ (kIONetworkDataAccessTypeRead | kIONetworkDataAccessTypeSerialize) #define kIONetworkDataBytes "Data" #define kIONetworkDataSize "Size"

Constants
kIONetworkDataAccessTypes

A property of IONetworkData objects. The kIONetworkDataAccessTypes property is an OSNumber that describes the supported access types of an IONetworkData object. Available in OS X v10.0 and later. Declared in IONetworkData.h.
kIONetworkDataBasicAccessTypes

The default access types supported by an IONetworkData object. Allow read() and serialize(). Available in OS X v10.0 and later. Declared in IONetworkData.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

952

IONetworkData.h User-Space Reference Constants

kIONetworkDataBytes

A property of IONetworkData objects. The kIONetworkDataBytes property is an OSData that describes the data buffer of an IONetworkData object. This property is present only if kIONetworkDataAccessTypeSerialize access is supported. Available in OS X v10.0 and later. Declared in IONetworkData.h.
kIONetworkDataSize

A property of IONetworkData objects. The kIONetworkDataSize property is an OSNumber that describes the size of the data buffer of an IONetworkData object. Available in OS X v10.0 and later. Declared in IONetworkData.h.

NetworkDataAccessTypes
Constants that describe access types.

enum { kIONetworkDataAccessTypeRead = 0x01, kIONetworkDataAccessTypeWrite = 0x02, kIONetworkDataAccessTypeReset = 0x04, kIONetworkDataAccessTypeSerialize = 0x08, kIONetworkDataAccessTypeMask = 0xff };

Constants
kIONetworkDataAccessTypeRead

Read access. Available in OS X v10.0 and later. Declared in IONetworkData.h.

kIONetworkDataAccessTypeWrite

Write access. Available in OS X v10.0 and later. Declared in IONetworkData.h.

kIONetworkDataAccessTypeReset

Reset access. Available in OS X v10.0 and later. Declared in IONetworkData.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

953

IONetworkData.h User-Space Reference Constants

kIONetworkDataAccessTypeSerialize

Serialization access. Available in OS X v10.0 and later. Declared in IONetworkData.h.

NetworkDataBufferTypes
The types of data buffers that can be managed by an IONetworkData object.

enum { kIONetworkDataBufferTypeInternal = 0, kIONetworkDataBufferTypeExternal, kIONetworkDataBufferTypeNone };

Constants
kIONetworkDataBufferTypeInternal

An internal data buffer allocated by the init() method. Available in OS X v10.0 and later. Declared in IONetworkData.h.
kIONetworkDataBufferTypeExternal

An external (persistent) data buffer. Available in OS X v10.0 and later. Declared in IONetworkData.h.
kIONetworkDataBufferTypeNone

No data buffer. The only useful action perfomed by an IONetworkData object with this buffer type is to call the access notification handler. Available in OS X v10.0 and later. Declared in IONetworkData.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

954

IONetworkInterface.h User-Space Reference

Declared in

IONetworkInterface.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOBuiltin "IOBuiltin" kIOInterfaceExtraFlags "IOInterfaceExtraFlags" kIOInterfaceFlags "IOInterfaceFlags" kIOInterfaceNamePrefix "IOInterfaceNamePrefix" kIOInterfaceState "IOInterfaceState" kIOInterfaceType "IOInterfaceType" kIOInterfaceUnit "IOInterfaceUnit" kIOLocation "IOLocation" kIOMaxTransferUnit "IOMaxTransferUnit" kIOMediaAddressLength "IOMediaAddressLength" kIOMediaHeaderLength "IOMediaHeaderLength" kIONetworkData "IONetworkData" kIONetworkInterfaceClass "IONetworkInterface" kIOPrimaryInterface "IOPrimaryInterface"

Constants
kIOBuiltin

kIOBuiltin is a property of IONetworkInterface objects. It has an OSBoolean value. The kIOBuiltin property describes whether the interface is built-in. Available in OS X v10.3 and later. Declared in IONetworkInterface.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

955

IONetworkInterface.h User-Space Reference Constants

kIOInterfaceExtraFlags

A property of IONetworkInterface objects. The kIOInterfaceExtraFlags property has an OSNumber value that specifies the current value of the interface eflags. The eflag constants are defined in bsd/net/if.h. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOInterfaceFlags

A property of IONetworkInterface objects. The kIOInterfaceFlags property has an OSNumber value that specifies the current value of the interface flags. The flag constants are defined in bsd/net/if.h. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOInterfaceNamePrefix

A property of IONetworkInterface objects. The kIOInterfaceNamePrefix property has an OSString value that describes the string prefix for the BSD name assigned to the interface. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOInterfaceState

A property of IONetworkInterface objects. The kIOInterfaceState property has an OSNumber value that describes the current state of the interface object. This property is not exported to BSD via the ifnet structure. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOInterfaceType

A property of IONetworkInterface objects. The kIOInterfaceType property has an OSNumber value that specifies the type of network interface that this interface represents. The type constants are defined in bsd/net/if_types.h. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOInterfaceUnit

A property of IONetworkInterface objects. The kIOInterfaceUnit property has an OSNumber value that describes the unit number assigned to the interface object. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

956

IONetworkInterface.h User-Space Reference Constants

kIOLocation

kIOLocation is a property of IONetworkInterface objects. It has an OSString value. The kIOLocation property describes the physical location of built-in interfaces. Available in OS X v10.3 and later. Declared in IONetworkInterface.h.
kIOMaxTransferUnit

A property of IONetworkInterface objects. The kIOMaxTransferUnit property has an OSNumber value that specifies the maximum transfer unit for the interface in bytes. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOMediaAddressLength

A property of IONetworkInterface objects. The kIOMediaAddressLength property has an OSNumber value that specifies the size of the media address in bytes. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIOMediaHeaderLength

A property of IONetworkInterface objects. The kIOMediaHeaderLength property has an OSNumber value that specifies the size of the media header in bytes. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIONetworkData

A property of IONetworkInterface objects. The kIONetworkData property has an OSDictionary value and is a container for the set of IONetworkData objects managed by the interface. Each entry in the dictionary is a key/value pair consisting of the network data name, and an OSDictionary describing the contents of the network data. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIONetworkInterfaceClass

The name of the IONetworkInterface class. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

957

IONetworkInterface.h User-Space Reference Constants

kIOPrimaryInterface

A property of IONetworkInterface objects. The kIOInterfaceNamePrefix property has an OSBoolean value that describes whether the interface is the primary or the built-in network interface. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.

InterfaceObjectStates

enum { kIONetworkInterfaceRegisteredState = 0x1, kIONetworkInterfaceOpenedState = 0x2, kIONetworkInterfaceDisabledState = 0x4 };

Constants
kIONetworkInterfaceRegisteredState

The interface object has registered with the data link layer. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIONetworkInterfaceOpenedState

One or more clients have an open on the interface object. Available in OS X v10.0 and later. Declared in IONetworkInterface.h.
kIONetworkInterfaceDisabledState

The interface is temporarily unable to service its clients. This will occur when the network controller that is servicing the interface has entered a low power state that renders it unusable. Available in OS X v10.0 and later. Declared in IONetworkInterface.h. Discussion Constants used to encode the state of the interface object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

958

IONetworkLib.h Reference

Declared in

IONetworkLib.h

Overview
Included Headers

<IOKit/IOKitLib.h> <IOKit/network/IONetworkData.h> <IOKit/network/IONetworkMedium.h> <IOKit/network/IONetworkStats.h> <IOKit/network/IOEthernetStats.h> <IOKit/network/IONetworkUserClient.h>

Functions
See the Overview for header-level documentation.

IONetworkClose
Close the connection to an IONetworkInterface object.

IOReturn IONetworkClose( io_connect_t con);

Availability Available in OS X v10.0 and later. Declared in

IONetworkLib.h

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

959

IONetworkLib.h Reference Functions

IONetworkGetDataCapacity
Get the capacity (in bytes) of a network data object.

IOReturn IONetworkGetDataCapacity( io_connect_t conObject, IONDHandle dataHandle, UInt32 *capacityP);

Parameters
conObject

The connection object.

dataHandle

The handle of a network data object.

capacityP

Upon success, the capacity is written to this address. Return Value kIOReturnSuccess on success, or an error code otherwise. Availability Available in OS X v10.0 and later. Declared in
IONetworkLib.h

IONetworkGetDataHandle
Get the handle of a network data object with the given name.

IOReturn IONetworkGetDataHandle( io_connect_t conObject, const char dataName, IONDHandle dataHandleP);

Parameters
conObject

The connection object.

dataName

The name of the network data object.

2011-05-05 | 2011 Apple Inc. All Rights Reserved.

960

IONetworkLib.h Reference Functions

dataHandleP

Upon success, the handle is written to this address. Return Value kIOReturnSuccess on success, or an error code otherwise. Availability Available in OS X v10.0 and later. Declared in
IONetworkLib.h

IONetworkGetPacketFiltersMask
Get the packet filters for a given filter group.

IOReturn IONetworkGetPacketFiltersMask( io_connect_t connect, const io_name_t filterGroup, UInt32 *filtersMask, IOOptionBits options );

Parameters
connect

The connection object returned from IONetworkOpen().

filterGroup

The name of the packet filter group.

filtersMask

Pointer to the return value containing a mask of packet filters.

options

kIONetworkSupportedPacketFilters may be set to fetch the filters that are supported by the hardware. Return Value An IOReturn error code. Discussion A network controller may support a number of packets filters that can accept or reject a type of packet seen on the network. A filter group identifies a set of related filters, such as all filters that will allow a packet to pass upstream based on the destination address encoded within the packet. This function allows an user-space program to get the filtering performed by a given filter group.

961

IONetworkLib.h Reference Functions

Availability Available in OS X v10.1 and later. Declared in

IONetworkLib.h

IONetworkOpen
Open a connection to an IONetworkInterface object. An IONetworkUserClient object is created to manage the connection.

IOReturn IONetworkOpen( io_object_t obj, io_connect_t *con);

Availability Available in OS X v10.0 and later. Declared in

IONetworkLib.h

IONetworkReadData
Read the buffer of a network data object.

IOReturn IONetworkReadData( io_connect_t conObj, IONDHandle dataHandle, UInt8 *destBuf, UInt32 *inOutSizeP);

Parameters
conObj

The connection object.

dataHandle

The handle of a network data object.

destBuf

The buffer where the data read shall be written to.

962

IONetworkLib.h Reference Functions

inOutSizeP

Pointer to an integer that the caller must initialize to contain the size of the buffer. This function will overwrite it with the actual number of bytes written to the buffer. Return Value kIOReturnSuccess on success, or an error code otherwise. Availability Available in OS X v10.0 and later. Declared in
IONetworkLib.h

IONetworkResetData
Fill the buffer of a network data object with zeroes.

IOReturn IONetworkResetData( io_connect_t conObject, IONDHandle dataHandle);

Parameters
conObject

The connection object.

dataHandle

The handle of a network data object. Return Value kIOReturnSuccess on success, or an error code otherwise. Availability Available in OS X v10.0 and later. Declared in
IONetworkLib.h

IONetworkSetPacketFiltersMask
Set the packet filters for a given filter group.

IOReturn IONetworkSetPacketFiltersMask(

963

IONetworkLib.h Reference Functions

io_connect_t connect, const io_name_t filterGroup, UInt32 filtersMask, IOOptionBits options );

Parameters
connect

The connection object returned from IONetworkOpen().

filterGroup

The name of the packet filter group.

filtersMask

A mask of filters to set.

options

No options are currently defined. Return Value An IOReturn error code. Discussion A network controller may support a number of packets filters that can accept or reject a type of packet seen on the network. A filter group identifies a set of related filters, such as all filters that will allow a packet to pass upstream based on the destination address encoded within the packet. This function allows an user-space program to set the filtering performed by a given filter group. Availability Available in OS X v10.1 and later. Declared in
IONetworkLib.h

IONetworkWriteData
Write to the buffer of a network data object.

IOReturn IONetworkWriteData( io_connect_t conObj, IONDHandle dataHandle, UInt8 *srcBuf, UInt32 inSize);

964

IONetworkLib.h Reference Constants

Parameters
conObj

The connection object.

dataHandle

The handle of a network data object.

srcBuf

The data to write is taken from this buffer.

inSize

The size of the source buffer. Return Value kIOReturnSuccess on success, or an error code otherwise. Availability Available in OS X v10.0 and later. Declared in
IONetworkLib.h

Constants
See the Overview for header-level documentation.

IONetworkPacketFilterOptions

enum { kIONetworkSupportedPacketFilters = 0x0001 };

Constants
kIONetworkSupportedPacketFilters

Indicate the filters that are supported by the hardware. Available in OS X v10.1 and later. Declared in IONetworkLib.h.

965

IONetworkMedium.h User-Space Reference

Declared in

IONetworkMedium.h

Overview
Included Headers

Data Types
See the Overview for header-level documentation.

IOMediumType

typedef UInt32 IOMediumType;

Discussion A 32-bit value divided into fields which describes a single medium type. Availability Available in OS X v10.0 and later. Declared in
IONetworkMedium.h

Constants
See the Overview for header-level documentation.

966

IONetworkMedium.h User-Space Reference Constants

Defines

#define #define #define #define

kIOMediumFlags "Flags" kIOMediumIndex "Index" kIOMediumSpeed "Speed" kIOMediumType "Type"

Constants
kIOMediumFlags

A property of IONetworkMedium objects. The kIOMediumFlags property is an OSNumber object that describes a set of attributes assigned to the medium. Available in OS X v10.0 and later. Declared in IONetworkMedium.h.
kIOMediumIndex

A property of IONetworkMedium objects. The kIOMediumIndex property is an OSNumber object that describes an index assigned by the owner of the medium object. Its interpretation is driver specific. Available in OS X v10.0 and later. Declared in IONetworkMedium.h.
kIOMediumSpeed

A property of IONetworkMedium objects. The kIOMediumSpeed property is an OSNumber object that describes the maximum link speed supported by the medium in bits per second. Available in OS X v10.0 and later. Declared in IONetworkMedium.h.
kIOMediumType

A property of IONetworkMedium objects. The kIOMediumType property is an OSNumber object that describes the type of medium that this object represents. Available in OS X v10.0 and later. Declared in IONetworkMedium.h.

967

IONetworkStats.h User-Space Reference

Declared in

IONetworkStats.h

Overview
Generic network statistics.

Data Types
See the Overview for header-level documentation.

IONetworkStats

typedef struct { UInt32 inputPackets; UInt32 inputErrors; UInt32 outputPackets; UInt32 outputErrors; UInt32 collisions; } IONetworkStats;

Discussion Generic network statistics structure. Availability Available in OS X v10.0 and later. Declared in
IONetworkStats.h

968

IONetworkStats.h User-Space Reference Constants

IOOutputQueueStats

typedef struct { UInt32 capacity; UInt32 size; UInt32 peakSize; UInt32 dropCount; UInt32 outputCount; UInt32 retryCount; UInt32 stallCount; UInt32 reserved[4]; } IOOutputQueueStats;

Discussion Statistics recorded by IOOutputQueue objects. Availability Available in OS X v10.0 and later. Declared in
IONetworkStats.h

Constants
See the Overview for header-level documentation.

Defines

#define kIONetworkStatsKey "IONetworkStatsKey" #define kIOOutputQueueStatsKey "IOOutputQueueStatsKey"

Constants
kIONetworkStatsKey

Defines the name of an IONetworkData that contains an IONetworkStats. Available in OS X v10.0 and later. Declared in IONetworkStats.h.
kIOOutputQueueStatsKey

Defines the name of an IONetworkData that contains an IOOutputQueueStats. Available in OS X v10.0 and later. Declared in IONetworkStats.h.

969

IOPM.h User-Space Reference

Declared in

IOPM.h

Overview
Defines power management constants and keys used by both in-kernel and user space power management. IOPM.h defines a range of power management constants used in several in-kernel and user space APIs. Most significantly, the IOPMPowerFlags used to specify the fields of an IOPMPowerState struct are defined here. Most of the constants defined in IOPM.h are deprecated or for Apple internal use only, and are not elaborated on in headerdoc.

Included Headers

<IOKit/IOTypes.h> <IOKit/IOMessage.h> <IOKit/IOReturn.h>

Data Types
See the Overview for header-level documentation.

IOPMSystemCapabilityChangeParameters
A structure describing a system capability change.

struct IOPMSystemCapabilityChangeParameters { uint32_t notifyRef; uint32_t maxWaitForReply; uint32_t changeFlags; uint32_t __reserved1; uint32_t fromCapabilities;

970

IOPM.h User-Space Reference Constants

uint32_t toCapabilities; uint32_t __reserved2[4]; };

Fields
notifyRef

An identifier for this message notification. Clients with pending I/O can signal completion by calling allowPowerChange() with this value as the argument. Clients that are able to process the notification synchronously should ignore this field.
maxWaitForReply

A return value to the caller indicating the maximum time in microseconds to wait for the allowPowerChange() call. The default value is zero, which indicates the client processing has finished, and power management should not wait for an allowPowerChange() call.
changeFlags

Flags will be set to indicate whether the notification precedes the capability change (kIOPMSystemCapabilityWillChange), or after the capability change has occurred (kIOPMSystemCapabilityDidChange).
__reserved1

Set to zero.
fromCapabilities

The system capabilities at the start of the transition.

toCapabilities

The system capabilities at the end of the transition.

__reserved2

Set to zero. Discussion A system capability change is a system level transition from a set of system capabilities to a new set of system capabilities. Power management sends a kIOMessageSystemCapabilityChange message and provides this structure as the message data (by reference) to gIOPriorityPowerStateInterest clients when system capability changes.

Constants
See the Overview for header-level documentation.

971

IOPM.h User-Space Reference Constants

Defines

#define kIOPMMessageDarkWakeThermalEmergency \ iokit_family_msg(sub_iokit_powermanagement, 0x160) #define kIOPMMessageDriverAssertionsChanged \ iokit_family_msg(sub_iokit_powermanagement, 0x150)

Constants
kIOPMMessageDarkWakeThermalEmergency

kIOPMMessageDarkWakeThermalEmergency Sent when machine becomes unsustainably warm in DarkWake. Kernel PM might choose to put the machine back to sleep right after. Available in OS X v10.8 and later. Declared in IOPM.h.
kIOPMMessageDriverAssertionsChanged

kIOPMMessageDriverAssertionsChanged Sent when kernel PM driver assertions have changed. Available in OS X v10.7 and later. Declared in IOPM.h.

Global Variables

kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */

972

IOPM.h User-Space Reference Constants

kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */

973

IOPM.h User-Space Reference Constants

kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 }; kIOPMDriverAssertionCPUBit *= 0x01, /! kIOPMDriverAssertionUSBExternalDeviceBit */ kIOPMDriverAssertionUSBExternalDeviceBit *= 0x04, /! kIOPMDriverAssertionBluetoothHIDDevicePairedBit */ kIOPMDriverAssertionBluetoothHIDDevicePairedBit *= 0x08, /! kIOPMDriverAssertionExternalMediaMountedBit */ kIOPMDriverAssertionExternalMediaMountedBit *= 0x10, /! kIOPMDriverAssertionReservedBit5 */ kIOPMDriverAssertionReservedBit5 *= 0x20, /! kIOPMDriverAssertionPreventDisplaySleepBit */ kIOPMDriverAssertionPreventDisplaySleepBit = 0x40, kIOPMDriverAssertionReservedBit7 = 0x80 };

Constants
kIOPMDriverAssertionBluetoothHIDDevicePairedBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.
kIOPMDriverAssertionCPUBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.
kIOPMDriverAssertionExternalMediaMountedBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.
kIOPMDriverAssertionPreventDisplaySleepBit

kIOPMDriverAssertionPreventDisplaySleepBit When set, the display should remain powered on while the system's awake.

974

IOPM.h User-Space Reference Constants

kIOPMDriverAssertionPreventDisplaySleepBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.
kIOPMDriverAssertionReservedBit7

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.
kIOPMDriverAssertionUSBExternalDeviceBit

kIOPMDriverAssertionCPUBit When set, PM kernel will prefer to leave the CPU and core hardware running in "Dark Wake" state, instead of sleeping.

IOPMPowerFlags
Bits are used in defining capabilityFlags, inputPowerRequirements, and outputPowerCharacter in the IOPMPowerState structure.

enum { kIOPMPowerOn = 0x00000002, kIOPMDeviceUsable = 0x00008000, kIOPMLowPower = 0x00010000, kIOPMPreventIdleSleep = 0x00000040, kIOPMSleepCapability = 0x00000004, kIOPMRestartCapability = 0x00000080, kIOPMSleep = 0x00000001, kIOPMRestart = 0x00000080, kIOPMInitialDeviceState = 0x00000100 }; typedef unsigned long IOPMPowerFlags;

Constants
kIOPMPowerOn

Indicates the device is on, requires power, and provides power. Useful as a: Capability, InputPowerRequirement, OutputPowerCharacter Available in OS X v10.1 and later. Declared in IOPM.h.
kIOPMDeviceUsable

Indicates the device is usable in this state. Useful only as a Capability Available in OS X v10.1 and later. Declared in IOPM.h.

975

IOPM.h User-Space Reference Constants

kIOPMLowPower

Indicates device is in a low power state. May be bitwis-OR'd together with kIOPMDeviceUsable flag, to indicate the device is still usable. A device with a capability of kIOPMLowPower may: Require either 0 or kIOPMPowerOn from its power parent Offer either kIOPMLowPower, kIOPMPowerOn, or 0 (no power at all) to its power plane children. Useful only as a Capability, although USB drivers should consult USB family documentation for other valid circumstances to use the kIOPMLowPower bit. Available in OS X v10.5 and later. Declared in IOPM.h.
kIOPMPreventIdleSleep

In the capability field of a power state, disallows idle system sleep while the device is in that state. For example, displays and disks set this capability for their ON power state; since the system may not idle sleep while the display (and thus keyboard or mouse) or the disk is active. Useful only as a Capability. Available in OS X v10.1 and later. Declared in IOPM.h.
kIOPMSleepCapability

Used only by certain IOKit Families (USB). Not defined or used by generic Power Management. Read your family documentation to see if you should define a powerstate using these capabilities. Available in OS X v10.1 and later. Declared in IOPM.h.
kIOPMRestartCapability

976

IOPM.h User-Space Reference Constants

kIOPMInitialDeviceState

Indicates the initial power state for the device. If initialPowerStateForDomainState() returns a power state with this flag set in the capability field, then the initial power change is performed without calling the driver's setPowerState(). Available in OS X v10.7 and later. Declared in IOPM.h. Discussion These bits may be bitwise-OR'd together in the IOPMPowerState capabilityFlags field, the outputPowerCharacter field, and/or the inputPowerRequirement field. The comments clearly mark whether each flag should be used in the capabilityFlags field, outputPowerCharacter field, and inputPowerRequirement field, or all three. The value of capabilityFlags, inputPowerRequirement or outputPowerCharacter may be 0. Most drivers implement their 'OFF' state, used when asleep, by defininf each of the 3 fields as 0. The bits listed below are only the most common bits used to define a device's power states. Your device's IO family may require that your device specify other input or output power flags to interact properly. Consult family-specific documentation to determine if your IOPower plane parents or children require other power flags; they probably don't. See Also
IOPMPowerFlags (page 975)

IOPMSystemCapabilityChangeFlags

enum { kIOPMSystemCapabilityWillChange = 0x01, kIOPMSystemCapabilityDidChange = 0x02 };

Constants
kIOPMSystemCapabilityWillChange

Indicates the system capability will change. Available in OS X v10.7 and later. Declared in IOPM.h.

977

IOPM.h User-Space Reference Constants

kIOPMSystemCapabilityDidChange

Indicates the system capability has changed. Available in OS X v10.7 and later. Declared in IOPM.h.

978

IOPMKeys.h Reference

Declared in

IOPMKeys.h

Overview
IOPMKeys.h defines C strings for use accessing power management data. Note that all of these C strings must be converted to CFStrings before use. You can wrap them with the CFSTR() macro, or create a CFStringRef (that you must later CFRelease()) using CFStringCreateWithCString()

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define

kIOPMAutoPowerOn "poweron" kIOPMAutoRestart "restart" kIOPMAutoShutdown "shutdown" kIOPMAutoSleep "sleep" kIOPMAutoWake "wake" kIOPMAutoWakeOrPowerOn "wakepoweron" kIOPMPowerEventAppNameKey "scheduledby" kIOPMPowerEventTimeKey "time" kIOPMPowerEventTypeKey "eventtype"

Constants
kIOPMAutoPowerOn

Value for scheduled power on from off state. Available in OS X v10.3 and later. Declared in IOPMKeys.h.

979

IOPMKeys.h Reference Constants

kIOPMAutoRestart

Value for scheduled restart. Available in OS X v10.5 and later. Declared in IOPMKeys.h.
kIOPMAutoShutdown

Value for scheduled shutdown. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMAutoSleep

Value for scheduled sleep. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMAutoWake

Value for scheduled wake from sleep. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMAutoWakeOrPowerOn

Value for scheduled wake from sleep, or power on. The system will either wake OR power on, whichever is necessary. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMPowerEventAppNameKey

Key for the CFBundleIdentifier of the app that scheduled the power event. Value is a CFStringRef. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMPowerEventTimeKey

Key for the time of the scheduled power event. Value is a CFDateRef. Available in OS X v10.3 and later. Declared in IOPMKeys.h.
kIOPMPowerEventTypeKey

Key for the type of power event. Value is a CFStringRef, with the c-string value of one of the "kIOPMAuto" strings. Available in OS X v10.3 and later. Declared in IOPMKeys.h.

980

IOPMLib.h Reference

Declared in

IOPMLib.h

Overview
IOPMLib provides access to common power management facilities, like initiating system sleep, getting current idle timer values, registering for sleep/wake notifications, and preventing system sleep.

Included Headers

<CoreFoundation/CFArray.h> <IOKit/IOKitLib.h> <IOKit/pwr_mgt/IOPMLibDefs.h> <IOKit/pwr_mgt/IOPMKeys.h> <Availability.h>

Functions by Task
See the Overview for header-level documentation.

ScheduledEvents
IOPMCancelScheduledPowerEvent (page 998)

Cancel a previously scheduled power event.

IOPMCopyScheduledPowerEvents (page 1001)

List all scheduled system power events

IOPMSchedulePowerEvent (page 1003)

Schedule the machine to wake from sleep, power on, go to sleep, or shutdown.

981

IOPMLib.h Reference Functions by Task

Notifications
IOAllowPowerChange (page 984)

The caller acknowledges notification of a power state change on a device it has registered for notifications for via IORegisterForSystemPower or IORegisterApp.
IOCancelPowerChange (page 985)

The caller denies an idle system sleep power state change.

IODeregisterApp (page 986)

Disconnects the caller from an IOService after receiving power state change notifications from the IOService. (Caller must also release IORegisterApp's return io_connect_t and returned IONotificationPortRef for complete clean-up).
IODeregisterForSystemPower (page 987)

Disconnects the caller from the Root Power Domain IOService after receiving system power state change notifications. (Caller must also destroy the IONotificationPortRef returned from IORegisterForSystemPower.)
IORegisterApp (page 1006)

Connects the caller to an IOService for the purpose of receiving power state change notifications for the device controlled by the IOService.
IORegisterForSystemPower (page 1007)

Connects the caller to the Root Power Domain IOService for the purpose of receiving sleep & wake notifications for the system. Does not provide system shutdown and restart notifications.

IOSystemLoadAdvisory
IOCopySystemLoadAdvisoryDetailed (page 986)

Indicates how user activity, battery level, and thermal level each contribute to the overall "SystemLoadAdvisory" level. In the future, this combined level may represent new levels as well.
IOGetSystemLoadAdvisory (page 987)

Returns a hint about whether now would be a good time to perform time-insensitive work.

CPU Power & Thermal

IOPMCopyCPUPowerStatus (page 1001)

Copy status of all current CPU power levels.

IOPMGetThermalWarningLevel (page 1003)

Get thermal warning level of the system.

982

IOPMLib.h Reference Functions by Task

Assertions
IOPMAssertionCopyProperties (page 988)

Copies details about an IOPMAssertion

IOPMAssertionCreate (page 989)

Dynamically requests a system behavior from the power management system.

IOPMAssertionCreateWithDescription (page 989)

IOPMAssertionCreateWithName (page 991)

Dynamically requests a system behavior from the power management system.

IOPMAssertionCreateWithProperties (page 992)

Creates an IOPMAssertion with more flexibility than IOPMAssertionCreateWithDescription (page 989).

IOPMAssertionDeclareUserActivity (page 993)

Declares that the user is active on the system. This causes the display to power on and postpone display sleep up to the user's display sleep Energy Saver settings. If you prefer to hold the display awake for a longer period and you know how long you'd like to hold it, consider taking assertion kIOPMAssertionTypePreventUserIdleDisplaySleep using IOPMAssertionCreateWithDescription (page 989) API instead.
IOPMAssertionRelease (page 995)

Decrements the assertion's retain count.

IOPMAssertionRetain (page 996)

Increments the assertion's retain count.

IOPMAssertionSetProperty (page 996)

Sets a property in the assertion.

IOPMCopyAssertionsByProcess (page 999)

Returns a dictionary listing all assertions, grouped by their owning process.

IOPMCopyAssertionsStatus (page 999)

Returns a list of available assertions and their system-wide levels.

Miscellaneous
IOPMAssertionDictionaryKeys (page 994)

983

IOPMLib.h Reference Functions

IOPMAssertionTypes (page 997)

Use as AssertionType argument to IOPMAssertionCreate (page 989). The idle display will not sleep when enabled, and consequently the system will not idle sleep.
IOPMCopyBatteryInfo (page 1000)

Request raw battery data from the system.

IOPMFindPowerManagement (page 1002)

Finds the Root Power Domain IOService.

IOPMGetAggressiveness (page 1002)

Retrieves the current value of one of the aggressiveness factors in IOKit Power Management.
IOPMSetAggressiveness (page 1004)

Sets one of the aggressiveness factors in IOKit Power Management.

IOPMSleepEnabled (page 1005)

Tells whether the system supports full sleep, or just doze

IOPMSleepSystem (page 1005)

Request that the system initiate sleep.

Functions
IOAllowPowerChange
The caller acknowledges notification of a power state change on a device it has registered for notifications for via IORegisterForSystemPower or IORegisterApp.

IOReturn IOAllowPowerChange ( io_connect_t kernelPort, long notificationID ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
kernelPort

Port used to communicate to the kernel, from IORegisterApp or IORegisterForSystemPower.

notificationID

A copy of the notification ID which came as part of the power state change notification being acknowledged. Return Value Returns kIOReturnSuccess or an error condition if request failed.

984

IOPMLib.h Reference Functions

Discussion Must be used when handling kIOMessageCanSystemSleep and kIOMessageSystemWillSleep messages from IOPMrootDomain system power. The caller should not call IOAllowPowerChange in response to any messages except for these two. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IOCancelPowerChange
The caller denies an idle system sleep power state change.

IOReturn IOCancelPowerChange ( io_connect_t kernelPort, long notificationID ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
kernelPort

Port used to communicate to the kernel, from IORegisterApp or IORegisterForSystemPower.

notificationID

A copy of the notification ID which came as part of the power state change notification being acknowledged. Return Value Returns kIOReturnSuccess or an error condition if request failed. Discussion Should only called in response to kIOMessageCanSystemSleep messages from IOPMrootDomain. IOCancelPowerChange has no meaning for responding to kIOMessageSystemWillSleep (which is non-abortable) or any other messages. When an app responds to a kIOMessageCanSystemSleep message by calling IOCancelPowerChange, the app vetoes the idle sleep request. The system will stay awake. The idle timer will elapse again after a period of inactivity, and the system will send out the same kIOMessageCanSystemSleep message, and interested applications will respond gain. Availability Available in OS X v10.0 and later.

985

Applications may use this result to avoid degrading the user experience. If it is a "Bad" or "OK" time to perform work, applications should slow down and perform work less aggressively. There is no guarantee that the system will ever be in "Great" condition to perform work - all essential work must still be performed even in "Bad", or "OK" times. Completely optional work, such as updating caches, may be postponed indefinitely. Note: You may more efficiently read the SystemLoadAdvisory level using notify_get_state() instead of IOGetSystemLoadAdvisory. The results are identical. notify_get_state() requires that you pass the token argument received by registering for SystemLoadAdvisory notifications. Availability Available in OS X v10.6 and later. Declared in
IOPMLib.h

IOPMAssertionCopyProperties
Copies details about an IOPMAssertion

CFDictionaryRef IOPMAssertionCopyProperties( IOPMAssertionID theAssertion) __OSX_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_3_2);

Parameters
theAssertion

The assertion ID to copy info about. Return Value A dictionary describing the assertion with keys specified in See IOPMAssertionDictionaryKeys. It's the caller's responsibility to release this dictionary. Discussion Returns a dictionary describing an IOPMAssertion's specifications and current state. Availability Available in OS X v10.7 and later. Declared in
IOPMLib.h

988

IOPMLib.h Reference Functions

IOPMAssertionCreate
Dynamically requests a system behavior from the power management system.

IOReturn IOPMAssertionCreate( CFStringRef AssertionType, IOPMAssertionLevel AssertionLevel, IOPMAssertionID *AssertionID) __OSX_AVAILABLE_BUT_DEPRECATED ( __MAC_10_5,__MAC_10_6,__IPHONE_2_0, __IPHONE_2_1);

Parameters
AssertionType

The CFString assertion type to request from the PM system.

AssertionLevel

Pass kIOPMAssertionLevelOn or kIOPMAssertionLevelOff.

AssertionID

On success, a unique id will be returned in this parameter. Return Value Returns kIOReturnSuccess on success, any other return indicates PM could not successfully activate the specified assertion. Discussion No special privileges necessary to make this call - any process may activate a power assertion. Availability Available in OS X v10.5 and later. Deprecated in OS X v10.6. Declared in
IOPMLib.h

IOPMAssertionCreateWithDescription

IOReturn IOPMAssertionCreateWithDescription( CFStringRef AssertionType, CFStringRef Name, CFStringRef Details, CFStringRef HumanReadableReason, CFStringRef LocalizationBundlePath, CFTimeInterval Timeout,

989

IOPMLib.h Reference Functions

CFStringRef TimeoutAction, IOPMAssertionID *AssertionID) __OSX_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_4_3);

Parameters
AssertionType

An assertion type constant. Caller must specify this argument.

Name

A CFString value to correspond to key kIOPMAssertionNameKey. Caller must specify this argument.
Details

A CFString value to correspond to key kIOPMAssertionDetailsKey. Caller my pass NULL, but it helps power users and administrators identify the reasons for this assertion.
HumanReadableReason

A CFString value to correspond to key kIOPMAssertionHumanReadableReasonKey. Caller may pass NULL, but if it's specified OS X may display it to users to describe the active assertions on their system.
LocalizationBundlePath

A CFString value to correspond to key kIOPMAssertionLocalizationBundlePathKey. This bundle path should include a localization for the string HumanReadableReason Caller may pass NULL, but this argument is required if caller specifies HumanReadableReason
Timeout

Specifies a timeout for this assertion. Pass 0 for no timeout.

TimeoutAction

Specifies a timeout action. Caller my pass NULL. If a timeout is specified but a TimeoutAction is not, the default timeout action is kIOPMAssertionTimeoutActionTurnOff
AssertionID

(Output) On successful return, contains a unique reference to a PM assertion. Return Value kIOReturnSuccess, or another IOKit return code on error. Discussion Creates an IOPMAssertion. This is the preferred API to call to create an assertion. It allows the caller to specify the Name, Details, and HumanReadableReason at creation time. There are other keys that can further describe an assertion, but most developers don't need to use them. Use IOPMAssertionSetProperties or IOPMAssertionCreateWithProperties (page 992) if you need to specify properties that aren't available here. Availability Available in OS X v10.7 and later.

990

IOPMLib.h Reference Functions

Declared in
IOPMLib.h

IOPMAssertionCreateWithName
Dynamically requests a system behavior from the power management system.

IOReturn IOPMAssertionCreateWithName( CFStringRef AssertionType, IOPMAssertionLevel AssertionLevel, CFStringRef AssertionName, IOPMAssertionID *AssertionID) AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

Parameters
AssertionType

The CFString assertion type to request from the PM system.

AssertionLevel

Pass kIOPMAssertionLevelOn or kIOPMAssertionLevelOff.

AssertionName

A string that describes the name of the caller and the activity being handled by this assertion (e.g. "Mail Compacting Mailboxes"). Name may be no longer than 128 characters.
AssertionID

On success, a unique id will be returned in this parameter. Return Value Returns kIOReturnSuccess on success, any other return indicates PM could not successfully activate the specified assertion. Discussion No special privileges are necessary to make this call - any process may activate a power assertion. Caller must specify an AssertionName - NULL is not a valid input. Availability Available in OS X v10.6 and later. Declared in
IOPMLib.h

991

IOPMLib.h Reference Functions

IOPMAssertionCreateWithProperties
Creates an IOPMAssertion with more flexibility than IOPMAssertionCreateWithDescription (page 989).

IOReturn IOPMAssertionCreateWithProperties( CFDictionaryRef AssertionProperties, IOPMAssertionID *AssertionID) __OSX_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_3_2);

Parameters
AssertionProperties

Dictionary providing the properties of the assertion that need to be created.

AssertionID

(Output) On successful return, contains a unique reference to a PM assertion. Discussion Create a new PM assertion - the caller must specify the type of assertion, initial level, and its properties as IOPMAssertionDictionaryKeys keys in the AssertionProperties dictionary. The following keys are recommend and/or required to be specified in the AssertionProperties dictionary argument.

REQUIRED: kIOPMAssertionTypeKey define the assertion type. REQUIRED: kIOPMAssertionValueKey define an inital value. REQUIRED: kIOPMAssertionNameKey Caller must describe the name for the activity that requires the change in behavior provided by the assertion. OPTIONAL: kIOPMAssertionDetailsKey Caller may describe context-specific data about the assertion. OPTIONAL: kIOPMAssertionHumanReadableReasonKey Caller may describe the reason for creating the assertion in a localizable CFString. This should be a human readable phrase that describes the actions the calling process is taking while the assertion is held, like "Downloading TV episodes", or "Compiling Projects" OPTIONAL: kIOPMAssertionLocalizationBundlePathKey Caller may provide its bundle's path, where OS X can localize for GUI display the CFString specified by kIOPMAssertionHumanReadableReasonKey. OPTIONAL: kIOPMAssertionPlugInIDKey if the caller is a plugin with a different identity than the process it's loaded in. OPTIONAL: kIOPMAssertionFrameworkIDKey if the caller is a framework acting on behalf of a process. OPTIONAL: The caller may specify a timeout.

Availability Available in OS X v10.7 and later.

992

IOPMLib.h Reference Functions

Declared in
IOPMLib.h

IOPMAssertionDeclareUserActivity
Declares that the user is active on the system. This causes the display to power on and postpone display sleep up to the user's display sleep Energy Saver settings. If you prefer to hold the display awake for a longer period and you know how long you'd like to hold it, consider taking assertion kIOPMAssertionTypePreventUserIdleDisplaySleep using IOPMAssertionCreateWithDescription (page 989) API instead.

IOReturn IOPMAssertionDeclareUserActivity( CFStringRef AssertionName, IOPMUserActiveType userType, IOPMAssertionID *AssertionID) AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER; introduced in 10.7.3 */

/* This API is

Parameters
AssertionName

A string that describes the name of the caller and the activity being handled by this assertion (e.g. "Mail Compacting Mailboxes"). Name may be no longer than 128 characters.
userType

This parameter specifies if the active user is located locally in front of the system or connected to the system over the network. Various components of the system are maintained at different power levels depending on user location.
AssertionID

On Success, unique id will be returned in this parameter. Caller may call this function again with the unique id retured previously to report continous user activity. The unique id returned by this function may change on each call depending on how frequently this function call is repeated and the current display sleep timer value. If you make this call more than once, track the returned value for assertionID, and pass it in as an argument on each call. Return Value Returns kIOReturnSuccess on success, any other return indicates PM could not successfully activate the specified assertion. Discussion No special privileges are necessary to make this call - any process may call this API. Caller must specify an AssertionName - NULL is not a valid input.

993

IOPMLib.h Reference Functions

Availability Available in OS X v10.7 and later. Declared in

IOPMLib.h

IOPMAssertionDictionaryKeys

/*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */

kIOPMAssertionTimeoutKey CFSTR("TimeoutSeconds")

kIOPMAssertionTimeoutActionKey CFSTR("TimeoutAction")

kIOPMAssertionTimeoutActionLog CFSTR("TimeoutActionLog")

kIOPMAssertionTimeoutActionTurnOff CFSTR("TimeoutActionTurnOff")

kIOPMAssertionTimeoutActionRelease CFSTR("TimeoutActionRelease")

kIOPMAssertionRetainCountKey CFSTR("RetainCount")

kIOPMAssertionNameKey CFSTR("AssertName")

kIOPMAssertionDetailsKey CFSTR("Details")

kIOPMAssertionHumanReadableReasonKey CFSTR("HumanReadableReason")

kIOPMAssertionLocalizationBundlePathKey CFSTR("BundlePath")

kIOPMAssertionFrameworkIDKey CFSTR("FrameworkBundleID")

kIOPMAssertionPlugInIDKey CFSTR("PlugInBundleID")

994

IOPMLib.h Reference Functions

#define kIOPMAssertionTypeKey CFSTR("AssertType") /! / #define kIOPMAssertionLevelKey CFSTR("AssertLevel")

Discussion Keys into dictionaries describing assertions. See Also

kIOPMAssertionTimeoutKey kIOPMAssertionTimeoutActionKey kIOPMAssertionTimeoutActionLog kIOPMAssertionTimeoutActionTurnOff kIOPMAssertionTimeoutActionRelease kIOPMAssertionRetainCountKey kIOPMAssertionNameKey kIOPMAssertionDetailsKey kIOPMAssertionHumanReadableReasonKey kIOPMAssertionLocalizationBundlePathKey kIOPMAssertionFrameworkIDKey kIOPMAssertionPlugInIDKey kIOPMAssertionTypeKey kIOPMAssertionLevelKey

IOPMAssertionRelease
Decrements the assertion's retain count.

IOReturn IOPMAssertionRelease( IOPMAssertionID AssertionID) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
AssertionID

The assertion_id, returned from IOPMAssertionCreate, to cancel. Return Value Returns kIOReturnSuccess on success. Discussion If the retain count becomes zero, then this also frees and deactivates the assertion referred to by assertionID Calls to IOPMAssertionCreate (page 989) and IOPMAssertionRelease (page 995) must each be paired with calls to IOPMAssertionRelease.

995

IOPMLib.h Reference Functions

Availability Available in OS X v10.5 and later. Declared in

IOPMLib.h

IOPMAssertionRetain
Increments the assertion's retain count.

void IOPMAssertionRetain( IOPMAssertionID theAssertion) __OSX_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_3_2);

Parameters
theAssertion

The assertion ID to retain. Discussion Increments the retain count according to CoreFoundation style retain/release semantics. Retain count can be inspected in the assertion's info dictionary at key kIOPMAssertionRetainCountKey Availability Available in OS X v10.7 and later. Declared in
IOPMLib.h

IOPMAssertionSetProperty
Sets a property in the assertion.

IOReturn IOPMAssertionSetProperty( IOPMAssertionID theAssertion, CFStringRef theProperty, CFTypeRef theValue) __OSX_AVAILABLE_STARTING( __MAC_10_7, __IPHONE_3_2);

Parameters
theAssertion

The IOPMAssertionID (page 1009) of the assertion to modify.

996

IOPMLib.h Reference Functions

theProperty

The CFString key, from IOPMAssertionDictionaryKeys to modify.

theValue

The property to set. It must be a CFNumber or CFString, as specified by the property key named in whichProperty. Return Value Returns kIOReturnNotPriviliged if the caller doesn't have permission to modify this assertion. Returns kIOReturnNotFound if PM can't locate this assertion. Returns kIOReturnError upon an unidentified error. Returns kIOReturnSuccess otherwise. Discussion Only the process that created an assertion may change its properties. Availability Available in OS X v10.7 and later. Declared in
IOPMLib.h

IOPMAssertionTypes
Use as AssertionType argument to IOPMAssertionCreate (page 989). The idle display will not sleep when enabled, and consequently the system will not idle sleep.

/*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define

kIOPMAssertionTypePreventUserIdleSystemSleep CFSTR("PreventUserIdleSystemSleep")

kIOPMAssertionTypePreventUserIdleDisplaySleep CFSTR("PreventUserIdleDisplaySleep")

kIOPMAssertionTypePreventSystemSleep CFSTR("PreventSystemSleep")

kIOPMAssertionTypeNoIdleSleep CFSTR("NoIdleSleepAssertion")

kIOPMAssertionTypeNoDisplaySleep CFSTR("NoDisplaySleepAssertion")

997

IOPMLib.h Reference Functions

Discussion When asserted and set to level kIOPMAssertionLevelOn, the system will prefer to enter the Dark Wake state, or remain in Dark Wake if already there, rather than go to sleep. Assertions are just suggestions to the OS, and the OS can only honor them to the best of its ability. In the case of low power or a thermal emergency, the system may sleep anyway despite the assertion. An assertion must publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. See Also
kIOPMAssertionTypePreventUserIdleSystemSleep kIOPMAssertionTypePreventUserIdleDisplaySleep kIOPMAssertionTypePreventSystemSleep kIOPMAssertionTypeNoIdleSleep kIOPMAssertionTypeNoDisplaySleep

IOPMCancelScheduledPowerEvent
Cancel a previously scheduled power event.

IOReturn IOPMCancelScheduledPowerEvent( CFDateRef time_to_wake, CFStringRef my_id, CFStringRef type);

Parameters
time_to_wake

Cancel entry with this date and time.

my_id

Cancel entry with this name.

type

Type to cancel Return Value kIOReturnSuccess on success, otherwise on failure Discussion Arguments mirror those to IOPMSchedulePowerEvent. All arguments must match the original arguments from when the power on was scheduled. Must be called as root.

998

IOPMLib.h Reference Functions

Availability Available in OS X v10.3 and later. Declared in

IOPMLib.h

IOPMCopyAssertionsByProcess
Returns a dictionary listing all assertions, grouped by their owning process.

IOReturn IOPMCopyAssertionsByProcess( CFDictionaryRef *AssertionsByPID) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

Parameters
AssertionsByPID

On success, this returns a dictionary of assertions per process. At the top level, keys to the CFDictionary are pids stored as CFNumbers (kCFNumberIntType). The value associated with each CFNumber pid is a CFArray of active assertions. Each entry in the CFArray is an assertion represented as a CFDictionary. See the keys kIOPMAssertionTypeKey and kIOPMAssertionLevelKey. Caller must CFRelease() this dictionary when done. Return Value Returns kIOReturnSuccess on success. Discussion Notes: One process may have multiple assertions. Several processes may have asserted the same assertion to different levels. Availability Available in OS X v10.5 and later. Declared in
IOPMLib.h

IOPMCopyAssertionsStatus
Returns a list of available assertions and their system-wide levels.

IOReturn IOPMCopyAssertionsStatus( CFDictionaryRef *AssertionsStatus) AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;

999

IOPMLib.h Reference Functions

Parameters
AssertionsStatus

On success, this returns a CFDictionary of all assertions currently available. The keys in the dictionary are the assertion types, and the value of each is a CFNumber that represents the aggregate level for that assertion. Caller must CFRelease() this dictionary when done. Return Value Returns kIOReturnSuccess on success. Discussion The system-wide level is the maximum of all individual assertions' levels. Availability Available in OS X v10.5 and later. Declared in
IOPMLib.h

IOPMCopyBatteryInfo
Request raw battery data from the system.

IOReturn IOPMCopyBatteryInfo( mach_port_t masterPort, CFArrayRef *info ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
masterPort

The master port obtained from IOMasterPort(). Just pass MACH_PORT_NULL.

info

A CFArray of CFDictionaries containing raw battery data. Return Value Returns kIOReturnSuccess or an error condition if request failed. Discussion WARNING! IOPMCoyBatteryInfo is unsupported on ALL Intel CPU based systems. For PPC CPU based systems, it remains not recommended. For almost all purposes, developers should use the richer IOPowerSources API (with change notifications) instead of using IOPMCopyBatteryInfo. Keys to decipher IOPMCopyBatteryInfo's return CFArray exist in IOPM.h.

1000

IOPMLib.h Reference Functions

Availability Available in OS X v10.0 and later. Declared in

IOPMLib.h

IOPMCopyCPUPowerStatus
Copy status of all current CPU power levels.

IOReturn IOPMCopyCPUPowerStatus( CFDictionaryRef *cpuPowerStatus);

Parameters
cpuPowerStatus

Upon success, a pointer to a dictionary defining CPU power; otherwise NULL. Pointer will be populated with a newly created dictionary upon successful return. Caller must release dictionary. Return Value kIOReturnSuccess, or other error report. Returns kIOReturnNotFound if CPU PowerStatus has not been published. Discussion The returned dictionary may define some of these keys, as defined in IOPM.h: kIOPMCPUPowerLimitProcessorSpeedKey - kIOPMCPUPowerLimitProcessorCountKey kIOPMCPUPowerLimitSchedulerTimeKey Availability Available in OS X v10.7 and later. Declared in
IOPMLib.h

IOPMCopyScheduledPowerEvents
List all scheduled system power events

CFArrayRef IOPMCopyScheduledPowerEvents( void);

1001

IOPMLib.h Reference Functions

Return Value A CFArray of CFDictionaries of power events. The CFArray must be released by the caller. NULL if there are no scheduled events. Discussion Returns a CFArray of CFDictionaries of power events. Each CFDictionary contains keys for CFSTR(kIOPMPowerEventTimeKey), CFSTR(kIOPMPowerEventAppNameKey), and CFSTR(kIOPMPowerEventTypeKey). Availability Available in OS X v10.3 and later. Declared in
IOPMLib.h

IOPMFindPowerManagement
Finds the Root Power Domain IOService.

io_connect_t IOPMFindPowerManagement( mach_port_t master_device_port ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
master_device_port

Just pass in MACH_PORT_NULL for master device port. Return Value Returns a io_connect_t handle on the root domain. Must be released with IOServiceClose() when done. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IOPMGetAggressiveness
Retrieves the current value of one of the aggressiveness factors in IOKit Power Management.

IOReturn IOPMGetAggressiveness ( io_connect_t fb,

1002

IOPMLib.h Reference Functions

unsigned long type, unsigned long *aggressiveness ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
fb

Representation of the Root Power Domain from IOPMFindPowerManagement.

type

Specifies which aggressiveness factor is being retrieved.

aggressiveness

Points to where to store the retrieved value of the aggressiveness factor. Return Value Returns kIOReturnSuccess or an error condition if request failed. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IOPMGetThermalWarningLevel
Get thermal warning level of the system.

IOReturn IOPMGetThermalWarningLevel( uint32_t *thermalLevel);

Return Value kIOReturnSuccess, or other error report. Returns kIOReturnNotFound if thermal warning level has not been published. Availability Available in OS X v10.7 and later. Declared in
IOPMLib.h

IOPMSchedulePowerEvent
Schedule the machine to wake from sleep, power on, go to sleep, or shutdown.

1003

IOPMLib.h Reference Functions

IOReturn IOPMSchedulePowerEvent( CFDateRef time_to_wake, CFStringRef my_id, CFStringRef type);

Parameters
time_to_wake

Date and time that the system will power on/off.

my_id

A CFStringRef identifying the calling app by CFBundleIdentifier. May be NULL.

type

The type of power on you desire, either wake from sleep or power on. Choose from: CFSTR(kIOPMAutoWake) == wake machine, CFSTR(kIOPMAutoPowerOn) == power on machine, CFSTR(kIOPMAutoWakeOrPowerOn) == wake or power on, CFSTR(kIOPMAutoSleep) == sleep machine, CFSTR(kIOPMAutoShutdown) == power off machine, CFSTR(kIOPMAutoRestart) == restart the machine. Return Value kIOReturnSuccess on success, otherwise on failure Discussion This event will be added to the system's queue of power events and stored persistently on disk. The sleep and shutdown events present a graphical warning and allow a console user to cancel the event. Must be called as root. Availability Available in OS X v10.3 and later. Declared in
IOPMLib.h

IOPMSetAggressiveness
Sets one of the aggressiveness factors in IOKit Power Management.

IOReturn IOPMSetAggressiveness ( io_connect_t fb, unsigned long type, unsigned long aggressiveness ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

1004

IOPMLib.h Reference Functions

Parameters
fb

Representation of the Root Power Domain from IOPMFindPowerManagement.

type

Specifies which aggressiveness factor is being set.

aggressiveness

New value of the aggressiveness factor. Return Value Returns kIOReturnSuccess or an error condition if request failed. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IOPMSleepEnabled
Tells whether the system supports full sleep, or just doze

boolean_t IOPMSleepEnabled ( void )AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Return Value Returns true if the system supports sleep, false if some hardware prevents full sleep. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IOPMSleepSystem
Request that the system initiate sleep.

IOReturn IOPMSleepSystem ( io_connect_t fb )AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

1005

IOPMLib.h Reference Functions

Parameters
fb

Port used to communicate to the kernel, from IOPMFindPowerManagement. Return Value Returns kIOReturnSuccess or an error condition if request failed. Discussion For security purposes, caller must be root or the console user. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IORegisterApp
Connects the caller to an IOService for the purpose of receiving power state change notifications for the device controlled by the IOService.

io_connect_t IORegisterApp( void *refcon, io_service_t theDriver, IONotificationPortRef *thePortRef, IOServiceInterestCallback callback, io_object_t *notifier ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
refcon

Data returned on power state change notifications and not used by the kernel.
theDriver

Representation of the IOService, probably from IOServiceGetMatchingService.

thePortRef

Pointer to a port on which the caller will receive power state change notifications. The port is allocated by the calling application.
callback

A c-function which is called during the notification.

notifier

Pointer to a notifier which caller must keep and pass to subsequent call to IODeregisterApp.

1006

IOPMLib.h Reference Functions

Return Value Returns a io_connect_t session for the IOService or MACH_PORT_NULL if request failed. Caller must close return value via IOServiceClose() after calling IODeregisterApp on the notifier argument. Discussion IORegisterApp requires that the IOService of interest implement an IOUserClient. In addition, that IOUserClient must implement the allowPowerChange and cancelPowerChange methods defined in IOPMLibDefs.h. If you're interested in receiving power state notifications from a device without an IOUserClient, try using IOServiceAddInterestNotification with interest type gIOGeneralInterest instead. Availability Available in OS X v10.0 and later. Declared in
IOPMLib.h

IORegisterForSystemPower
Connects the caller to the Root Power Domain IOService for the purpose of receiving sleep & wake notifications for the system. Does not provide system shutdown and restart notifications.

io_connect_t IORegisterForSystemPower ( void *refcon, IONotificationPortRef *thePortRef, IOServiceInterestCallback callback, io_object_t *notifier ) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;

Parameters
refcon

Caller may provide data to receive s an argument to 'callback' on power state changes.
thePortRef

On return, thePortRef is a pointer to an IONotificationPortRef, which will deliver the power notifications. The port is allocated by this function and must be later released by the caller (after calling IODeregisterForSystemPower (page 987)). The caller should also enable IONotificationPortRef by calling IONotificationPortGetRunLoopSource (page 890), or IONotificationPortGetMachPort (page 889), or IONotificationPortSetDispatchQueue (page 891).
callback

A c-function which is called during the notification.

1007

IOPMLib.h Reference Functions

notifier

On success, returns a pointer to a unique notifier which caller must keep and pass to a subsequent call to IODeregisterForSystemPower. Return Value Returns a io_connect_t session for the IOPMrootDomain or MACH_PORT_NULL if request failed. Caller must close return value via IOServiceClose() after calling IODeregisterForSystemPower on the notifier argument. Discussion Provides sleep/wake notifications to applications. Requires that applications acknowledge some, but not all notifications. Register for sleep/wake notifications will deliver these messages over the sleep/wake lifecycle: - kIOMessageSystemWillSleep is delivered at the point the system is initiating a non-abortable sleep. Callers MUST acknowledge this event by calling IOAllowPowerChange (page 984). If a caller does not acknowledge the sleep notification, the sleep will continue anyway after a 30 second timeout (resulting in bad user experience). Delivered before any hardware is powered off. - kIOMessageSystemWillPowerOn is delivered at early wakeup time, before most hardware has been powered on. Be aware that any attempts to access disk, network, the display, etc. may result in errors or blocking your process until those resources become available. Caller must NOT acknowledge kIOMessageSystemWillPowerOn; the caller must simply return from its handler. - kIOMessageSystemHasPoweredOn is delivered at wakeup completion time, after all device drivers and hardware have handled the wakeup event. Expect this event 1-5 or more seconds after initiating system wakeup. Caller must NOT acknowledge kIOMessageSystemHasPoweredOn; the caller must simply return from its handler. - kIOMessageCanSystemSleep indicates the system is pondering an idle sleep, but gives apps the chance to veto that sleep attempt. Caller must acknowledge kIOMessageCanSystemSleep by calling IOAllowPowerChange (page 984) or IOCancelPowerChange (page 985). Calling IOAllowPowerChange will not veto the sleep; any app that calls IOCancelPowerChange will veto the idle sleep. A kIOMessageCanSystemSleep notification will be followed up to 30 seconds later by a kIOMessageSystemWillSleep message. or a kIOMessageSystemWillNotSleep message. - kIOMessageSystemWillNotSleep is delivered when some app client has vetoed an idle sleep request. kIOMessageSystemWillNotSleep may follow a kIOMessageCanSystemSleep notification, but will not otherwise be sent. Caller must NOT acknowledge kIOMessageSystemWillNotSleep; the caller must simply return from its handler. To deregister for sleep/wake notifications, the caller must make two calls, in this order: - Call IODeregisterForSystemPower with the 'notifier' argument returned here. - Then call IONotificationPortDestroy passing the 'thePortRef' argument returned here.

1008

IOPMLib.h Reference Data Types

Availability Available in OS X v10.0 and later. Declared in

IOPMLib.h

Data Types
See the Overview for header-level documentation.

IOPMAssertionID
Type for AssertionID arguments to IOPMAssertionCreateWithProperties (page 992) and
IOPMAssertionRelease (page 995)

typedef uint32_t IOPMAssertionID;

Availability Available in OS X v10.5 and later. Declared in

IOPMLib.h

IOPMAssertionLevel
Type for AssertionLevel argument to IOPMAssertionCreate

typedef uint32_t IOPMAssertionLevel;

Discussion Possible values for IOPMAssertionLevel are kIOPMAssertionLevelOff and kIOPMAssertionLevelOn Availability Available in OS X v10.5 and later. Declared in
IOPMLib.h

1009

IOPMLib.h Reference Constants

IOSystemLoadAdvisoryLevel
Return type for IOGetSystemLoadAdvisory

typedef int IOSystemLoadAdvisoryLevel;

Discussion Value is one of kIOSystemLoadAdvisoryLevelGreat, kIOSystemLoadAdvisoryLevelOK, or kIOSystemLoadAdvisoryLevelBad. Availability Available in OS X v10.6 and later. Declared in
IOPMLib.h

Constants
See the Overview for header-level documentation.

Defines

/*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */

kIOPMAssertionDetailsKey CFSTR("Details")

kIOPMAssertionFrameworkIDKey CFSTR("FrameworkBundleID")

kIOPMAssertionHumanReadableReasonKey CFSTR("HumanReadableReason")

kIOPMAssertionLevelKey CFSTR("AssertLevel")

kIOPMAssertionLocalizationBundlePathKey CFSTR("BundlePath")

kIOPMAssertionNameKey CFSTR("AssertName")

1010

IOPMLib.h Reference Constants

#define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define /*! */ #define #define #define #define #define #define #define #define

kIOPMAssertionPlugInIDKey CFSTR("PlugInBundleID")

kIOPMAssertionRetainCountKey CFSTR("RetainCount")

kIOPMAssertionTimeoutActionKey CFSTR("TimeoutAction")

kIOPMAssertionTimeoutActionLog CFSTR("TimeoutActionLog")

kIOPMAssertionTimeoutActionRelease CFSTR("TimeoutActionRelease")

kIOPMAssertionTimeoutActionTurnOff CFSTR("TimeoutActionTurnOff")

kIOPMAssertionTimeoutKey CFSTR("TimeoutSeconds")

kIOPMAssertionTypeKey CFSTR("AssertType")

kIOPMAssertionTypeNoDisplaySleep CFSTR("NoDisplaySleepAssertion")

kIOPMAssertionTypeNoIdleSleep CFSTR("NoIdleSleepAssertion")

kIOPMAssertionTypePreventSystemSleep CFSTR("PreventSystemSleep")

kIOPMAssertionTypePreventUserIdleDisplaySleep CFSTR("PreventUserIdleDisplaySleep")

kIOPMAssertionTypePreventUserIdleSystemSleep CFSTR("PreventUserIdleSystemSleep") kIOPMCPUPowerNotificationKey "com.apple.system.power.CPU" kIOPMThermalWarningNotificationKey "com.apple.system.power.thermal_warning" kIOSystemLoadAdvisoryBatteryLevelKey CFSTR("BatteryLevel") kIOSystemLoadAdvisoryCombinedLevelKey CFSTR("CombinedLevel") kIOSystemLoadAdvisoryNotifyName "com.apple.system.powermanagement.SystemLoadAdvisory" kIOSystemLoadAdvisoryThermalLevelKey CFSTR("ThermalLevel") kIOSystemLoadAdvisoryUserLevelKey CFSTR("UserLevel")

1011

IOPMLib.h Reference Constants

Constants
kIOPMAssertionDetailsKey

The CFDictionary key for assertion name. Setting this key is required when you're creating an assertion.
kIOPMAssertionNameKey describes the the activity the assertion is protecting. The creator should

specify a CFString value for this key in the dictionary passed to

IOPMAssertionCreateWithProperties (page 992)

The assertion name is separate from the assertion type's behavior - specify a CFString like "Checking mail" or "Compiling" that describes the task that this assertion protects. The CFString you associate with this key does not have to be localizable (OS X will not attempt to localize it.) Describe your assertion as thoroughly as possible. See these other keys that can you can also set to add explanation to an assertion: OPTIONAL kIOPMAssertionDetailsKey OPTIONAL kIOPMAssertionHumanReadableReasonKey OPTIONAL
kIOPMAssertionLocalizationBundlePathKey

Available in OS X v10.7 and later. Declared in IOPMLib.h.

kIOPMAssertionFrameworkIDKey

Specify if the assertion creator is a framework. If the code that creates the assertion resides in a framework or library, the caller should specify a CFBundleIdentifier, as a CFString, identifying that bundle here. This info helps developers and administrators determine the source of an assertion. This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.

1012

IOPMLib.h Reference Constants

kIOPMAssertionHumanReadableReasonKey

Optional key that provides a localizable string for OS X to display PM Assertions in the GUI. The caller should specify this string in IOPMAssertionCreateWithProperties (page 992). If present, OS X may display this string, localized to the user's language, to explain changes in system behavior caused by the assertion. If set, the caller must also specify a bundle path for the key kIOPMAssertionLocalizationBundlePathKey The bundle at that path should contain localization info for the specified string. This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Describe your assertion as thoroughly as possible. See these other keys that can you can set to add explanation to an assertion: REQUIRED kIOPMAssertionNameKey OPTIONAL
kIOPMAssertionDetailsKey

Available in OS X v10.7 and later. Declared in IOPMLib.h.

kIOPMAssertionLevelKey

The CFDictionary key for assertion level in an assertion info dictionary. The value for this key will be a CFNumber, kCFNumberIntType with value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. The level reflects the assertion's level set at creation, or adjusted via
IOPMAssertionSetLevel

Available in OS X v10.5 and later. Declared in IOPMLib.h.

kIOPMAssertionLocalizationBundlePathKey

Refers to a CFURL, as a CFString, identifying the path to the caller's bundle, which contains localization info. The bundle must contain localizations for kIOPMAssertionHumanReadableReasonKey This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.

1013

IOPMLib.h Reference Constants

kIOPMAssertionNameKey

specify a CFString value for this key in the dictionary passed to

IOPMAssertionCreateWithProperties (page 992)

Available in OS X v10.6 and later. Declared in IOPMLib.h.

kIOPMAssertionPlugInIDKey

Specify if the assertion creator is a plugin. If the code that creates the assertion resides in a plugin, the caller should specify a CFBundleIdentifier, as a CFString, identifying the plugin's bundle here. This info helps developers and administrators determine the source of an assertion. This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionRetainCountKey

A potential value for kIOPMAssertionTimeoutActionKey kIOPMAssertionRetainCountKey reflects the CoreFoundation-style retain count on this assertion. Creating or retaining an assertion increments its retain count. Release an assertion decrements its retain count. When the retain count decrements to zero, the OS will destroy the object. This key can be found in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.

1014

IOPMLib.h Reference Constants

kIOPMAssertionTimeoutActionKey

Specifies the action to take upon timeout expiration. Specifying the timeout action only has meaning if you also specify an kIOPMAssertionTimeoutKey If the caller does not specify a timeout action, the default action is
kIOPMAssertionTimeoutActionTurnOff

This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionTimeoutActionLog

A potential value for kIOPMAssertionTimeoutActionKey When this timeout action is specified, PM will log the timeout event but will not turn off or affect the setting of the assertion in any way. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionTimeoutActionRelease

A potential value for kIOPMAssertionTimeoutActionKey When a timeout expires with this action, Power Management will log the timeout event, and will release the assertion. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionTimeoutActionTurnOff

A potential value for kIOPMAssertionTimeoutActionKey When a timeout expires with this action, Power Management will log the timeout event, and will set the assertion's level to kIOPMAssertionLevelOff. Available in OS X v10.7 and later. Declared in IOPMLib.h.

1015

IOPMLib.h Reference Constants

kIOPMAssertionTimeoutKey

kIOPMAssertionTimeoutKey specifies an outer bound, in seconds, that this assertion should be asserted. If your application hangs, or is unable to complete its assertion task in a reasonable amount of time, specifying a timeout allows PM to disable your assertion so the system can resume normal activity. Once a timeout with the kIOPMAssertionTimeoutActionTurnOff assertion fires, the level will be set to kIOPMAssertionTimeoutActionTurnOff. The assertion may be re-armed by calling IOPMAssertionSetLevel. This key may be specified in the dictionary passed to IOPMAssertionCreateWithProperties (page 992). This key may be present in the dictionary returned from IOPMAssertionCopyProperties (page 988). Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionTypeKey

The CFDictionary key for assertion type in an assertion info dictionary. The value for this key will be a CFStringRef, with the value of the assertion type specified at creation time. Note that OS X may substitute a support assertion type string if the caller specifies a deprecated assertion type; in that case the value for this key could differ from the caller-provided assertion type. Available in OS X v10.5 and later. Declared in IOPMLib.h.
kIOPMAssertionTypeNoDisplaySleep

Use as AssertionType argument to IOPMAssertionCreate (page 989). The idle display will not sleep when enabled, and consequently the system will not idle sleep. When asserted and set to level kIOPMAssertionLevelOn, the system will prefer to enter the Dark Wake state, or remain in Dark Wake if already there, rather than go to sleep. Assertions are just suggestions to the OS, and the OS can only honor them to the best of its ability. In the case of low power or a thermal emergency, the system may sleep anyway despite the assertion. An assertion must publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. Available in OS X v10.5 and later. Declared in IOPMLib.h.

1016

IOPMLib.h Reference Constants

kIOPMAssertionTypeNoIdleSleep

Pass as the AssertionType argument to IOPMAssertionCreate (page 989). The system will not idle sleep when enabled (display may sleep). Note that the system may sleep for other reasons. When asserted and set to level kIOPMAssertionLevelOn, the system will prefer to enter the Dark Wake state, or remain in Dark Wake if already there, rather than go to sleep. Assertions are just suggestions to the OS, and the OS can only honor them to the best of its ability. In the case of low power or a thermal emergency, the system may sleep anyway despite the assertion. An assertion must publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. Available in OS X v10.5 and later. Declared in IOPMLib.h.
kIOPMAssertionTypePreventSystemSleep

Prevents the system from sleeping and allows the system to reside in Dark Wake for an arbitrary length of time. When asserted and set to level kIOPMAssertionLevelOn, the system will prefer to enter the Dark Wake state, or remain in Dark Wake if already there, rather than go to sleep. Assertions are just suggestions to the OS, and the OS can only honor them to the best of its ability. In the case of low power or a thermal emergency, the system may sleep anyway despite the assertion. An assertion must publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMAssertionTypePreventUserIdleDisplaySleep

Prevents the display from dimming automatically. When asserted and set to level kIOPMAssertionLevelOn, will prevent the display from turning off due to a period of idle user activity. Note that the display may still sleep from other reasons, like a user closing a portable's lid or the machine sleeping. If the display is already off, this assertion does not light up the display. If display needs to be turned on, then consider calling function IOPMAssertionDeclareUserActivity (page 993). While the display is prevented from dimming, the system cannot go into idle sleep. This assertion does not put the system into Dark Wake. A caller publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. Available in OS X v10.7 and later. Declared in IOPMLib.h.

1017

IOPMLib.h Reference Constants

kIOPMAssertionTypePreventUserIdleSystemSleep

Prevents the system from sleeping automatically due to a lack of user activity. When asserted and set to level kIOPMAssertionLevelOn, will prevent the system from sleeping due to a period of idle user activity. The display may dim and idle sleep while kIOPMAssertionTypePreventUserIdleSystemSleep is enabled, but the system may not idle sleep. The system may still sleep for lid close, Apple menu, low battery, or other sleep reasons. This assertion does not put the system into Dark Wake. A caller publish the AssertionType in its assertion properties dictionary. The AssertionType should be a key in the properties dictionary, with a value of a CFNumber containing the kCFNumberIntegerType value kIOPMAssertionLevelOff or kIOPMAssertionLevelOn. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMCPUPowerNotificationKey

Key to register for BSD style notifications on CPU power or thermal change. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOPMThermalWarningNotificationKey

Key to register for BSD style notifications on system thermal warnings. Available in OS X v10.7 and later. Declared in IOPMLib.h.
kIOSystemLoadAdvisoryBatteryLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed Indicates battery constraints on the current SystemLoadAdvisory level. Available in OS X v10.6 and later. Declared in IOPMLib.h.
kIOSystemLoadAdvisoryCombinedLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed Provides a combined level based on UserLevel, BatteryLevel, and ThermalLevels; the combined level is the minimum of these levels. In the future, this combined level may represent new levels as well. The combined level is identical to the value returned by IOGetSystemLoadAdvisory(). Available in OS X v10.6 and later. Declared in IOPMLib.h.

1018

IOPMLib.h Reference Constants

kIOSystemLoadAdvisoryNotifyName

The notification by this name fires when system "SystemLoadAdvisory" status changes. Pass this string as an argument to register via notify(3). You can query SystemLoadAdvisory state via notify_get_state() when this notification fires - this is more efficient than calling IOGetSystemLoadAdvisory(), and returns an identical combined SystemLoadAdvisory value. Available in OS X v10.6 and later. Declared in IOPMLib.h.
kIOSystemLoadAdvisoryThermalLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed Indicates thermal constraints on the current SystemLoadAdvisory level. Available in OS X v10.6 and later. Declared in IOPMLib.h.
kIOSystemLoadAdvisoryUserLevelKey

Key for dictionary returned by IOCopySystemLoadAdvisoryDetailed Indicates user activity constraints on the current SystemLoadAdvisory level. Available in OS X v10.6 and later. Declared in IOPMLib.h. See Also
IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionDictionaryKeys IOPMAssertionTypes IOPMAssertionTypes IOPMAssertionTypes IOPMAssertionTypes IOPMAssertionTypes

1019

IOPMLib.h Reference Constants

Assertion
Level for an enabled assertion, passed as an argument to IOPMAssertionCreate.

enum { /! / kIOPMAssertionLevelOff = 0, /! / kIOPMAssertionLevelOn = 255 };

Constants
kIOPMAssertionLevelOff

Available in OS X v10.5 and later. Declared in IOPMLib.h.

kIOPMAssertionLevelOn

Available in OS X v10.5 and later. Declared in IOPMLib.h. Discussion Levels

kIOPMNullAssertionID
This value represents a non-initialized assertion ID

enum { kIOPMNullAssertionID = 0 };

Constants
kIOPMNullAssertionID

This value represents a non-initialized assertion ID. Available in OS X v10.5 and later. Declared in IOPMLib.h.

1020

IOPSKeys.h Reference

Declared in

IOPSKeys.h

Overview
IOPSKeys.h defines C strings for use accessing power source data in IOPowerSource CFDictionaries, as returned by IOPSGetPowerSourceDescription (page 1041) Note that all of these C strings must be converted to CFStrings before use. You can wrap them with the CFSTR() macro, or create a CFStringRef (that you must later CFRelease()) using CFStringCreateWithCString().

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOPSACPowerValue "AC Power" kIOPSBatteryFailureModesKey "BatteryFailureModes" kIOPSBatteryHealthConditionKey "BatteryHealthCondition" kIOPSBatteryHealthKey "BatteryHealth" kIOPSBatteryPowerValue "Battery Power" kIOPSCheckBatteryValue "Check Battery" kIOPSCommandDelayedRemovePowerKey "Delayed Remove Power" kIOPSCommandEnableAudibleAlarmKey "Enable Audible Alarm" kIOPSCommandStartupDelayKey "Startup Delay" kIOPSCurrentCapacityKey "Current Capacity" kIOPSCurrentKey "Current" kIOPSDeadWarnLevelKey "Shutdown Level" kIOPSDesignCapacityKey "DesignCapacity" kIOPSDynamicStorePath "/IOKit/PowerSources" kIOPSFailureCellImbalance "Cell Imbalance" kIOPSFailureChargeFET "Charge FET" kIOPSFailureChargeOverCurrent "Charge Over-Current" kIOPSFailureChargeOverTemp "Charge Over-Temperature"

1021

IOPSKeys.h Reference Constants

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOPSFailureDataFlushFault "Data Flush Fault" kIOPSFailureDischargeFET "Discharge FET" kIOPSFailureDischargeOverCurrent "Discharge Over-Current" kIOPSFailureDischargeOverTemp "Discharge Over-Temperature" kIOPSFailureExternalInput "Externally Indicated Failure" kIOPSFailureFuseBlown "Fuse Blown" kIOPSFailureOpenThermistor "Open Thermistor" kIOPSFailurePeriodicAFEComms "Periodic AFE Comms" kIOPSFailurePermanentAFEComms "Permanent AFE Comms" kIOPSFailureSafetyOverVoltage "Safety Over-Voltage" kIOPSFairValue "Fair" kIOPSGoodValue "Good" kIOPSHardwareSerialNumberKey "Hardware Serial Number" kIOPSHealthConfidenceKey "HealthConfidence" kIOPSInternalBatteryType "InternalBattery" kIOPSInternalType "Internal" kIOPSIsChargedKey "Is Charged" kIOPSIsChargingKey "Is Charging" kIOPSIsFinishingChargeKey "Is Finishing Charge" kIOPSIsPresentKey "Is Present" kIOPSLowWarnLevelKey "Low Warn Level" kIOPSMaxCapacityKey "Max Capacity" kIOPSMaxErrKey "MaxErr" kIOPSNameKey "Name" kIOPSNetworkTransportType "Ethernet" kIOPSOffLineValue "Off Line" kIOPSPermanentFailureValue "Permanent Battery Failure" kIOPSPoorValue "Poor" kIOPSPowerAdapterCurrentKey "Current" kIOPSPowerAdapterFamilyKey "FamilyCode" kIOPSPowerAdapterIDKey "AdapterID" kIOPSPowerAdapterRevisionKey "AdapterRevision" kIOPSPowerAdapterSerialNumberKey "SerialNumber" kIOPSPowerAdapterSourceKey "Source" kIOPSPowerAdapterWattsKey "Watts" kIOPSPowerSourceIDKey "Power Source ID" kIOPSPowerSourceStateKey "Power Source State" kIOPSSerialTransportType "Serial" kIOPSTimeToEmptyKey "Time to Empty" kIOPSTimeToFullChargeKey "Time to Full Charge" kIOPSTransportTypeKey "Transport Type" kIOPSTypeKey "Type" kIOPSUPSManagementClaimed "/IOKit/UPSPowerManagementClaimed" kIOPSUPSType "UPS" kIOPSUSBTransportType "USB" kIOPSVendorDataKey "Vendor Specific Data" kIOPSVoltageKey "Voltage"

1022

IOPSKeys.h Reference Constants

Constants
kIOPSACPowerValue

Value for key kIOPSPowerSourceStateKey. Power source is connected to external or AC power, and is not draining the internal battery. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSBatteryFailureModesKey

Enumerates a battery's failures and error conditions. Various battery failures will be listed here. A battery may suffer from more than one type of failure simultaneously, so this key has a CFArray value. If BatteryFailureModesKey is not defined (or is set to an empty dictionary), then the battery has no detectable failures. Each entry in the array should be a short descriptive string describing the error.

Apple-defined power sources will publish this key if any battery errors exist. For power source creators: Providing this key is RECOMMENDED. Type CFArrayRef

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

kIOPSBatteryHealthConditionKey

kIOPSBatteryHealthConditionKey broadly describes the battery's health.

Apple-defined power sources will publish this key. Value is one of the "Battery Health Condition Values" strings described in this file. For power source creators: Providing this key is OPTIONAL - these keys have values only used by Apple power sources. Type CFStringRef

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

1023

IOPSKeys.h Reference Constants

kIOPSBatteryHealthKey

CFDictionary key for the current power source's "health" estimate.

Apple-defined battery power sources will publish this key. Use value kIOPSGoodValue to describe a well-performing power source, Use kIOPSFairValue to describe a functional power source with limited capacity And use kIOPSPoorValue to describe a power source that's not capable of Providing power. For power source creators: Providing this key is OPTIONAL. Type CFStringRef

Available in OS X v10.4 and later. Declared in IOPSKeys.h.

kIOPSBatteryPowerValue

Value for key kIOPSPowerSourceStateKey. Power source is currently using the internal battery. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSCheckBatteryValue

Value for key kIOPSBatteryHealthConditionKey This value indicates that the battery should be checked out by a licensed Mac repair service. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSCommandDelayedRemovePowerKey

Command to give a UPS when it should remove power from its AC plugs in a specified amount of time

The matching argument should be a CFNumber of kCFNumberIntType specifying when the UPS should remove power from its AC power ports.

Available in OS X v10.3 and later. Declared in IOPSKeys.h.

kIOPSCommandEnableAudibleAlarmKey

Command to give a UPS when it should either enable or disable the audible alarm.

The matching argument should be a CFBooleanRef where kCFBooleanTrue enables the alarm and kCFBooleanFalse diables the alarm

Available in OS X v10.3 and later. Declared in IOPSKeys.h.

1024

IOPSKeys.h Reference Constants

kIOPSCommandStartupDelayKey

Tell UPS how long it should wait for

The matching argument should be a CFNumber of kCFNumberIntType specifying when the UPS should remove power from its AC power ports.

Available in OS X v10.3 and later. Declared in IOPSKeys.h.

kIOPSCurrentCapacityKey

CFDictionary key for the current power source's capacity.

Apple-defined power sources will publish this key in units of percent. The power source's software may specify the units for this key. The units must be consistent for all capacities reported by this power source. The power source will usually define this number in units of percent, or mAh. Clients may derive a percentage of power source battery remaining by dividing "Current Capacity" by "Max Capacity" For power source creators: Providing this key is REQUIRED. Type CFNumber kCFNumberIntType (signed integer)

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSCurrentKey

CFDictionary key for the current power source's electrical current.

Apple-defined power sources will publish this key. For power source creators: Providing this key is RECOMMENDED. Type CFNumber kCFNumberIntType (signed integer) - units are mA

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSDeadWarnLevelKey

Key for the "Shutdown System" low power trigger-level. Default is 20%. Available in OS X v10.2 and later. Declared in IOPSKeys.h.

1025

IOPSKeys.h Reference Constants

kIOPSDesignCapacityKey

CFDictionary key for the current power source's design capacity

Apple-defined power sources might not publish this key. The power source's software may specify the units for this key. The units must be consistent for all capacities reported by this power source. For power source creators: Providing this key is RECOMMENDED. Type CFNumber kCFNumberIntType (signed integer)

Available in OS X v10.4 and later. Declared in IOPSKeys.h.

kIOPSDynamicStorePath

This is only used for internal bookkeeping, and should be ignored. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSFailureCellImbalance

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureChargeFET

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureChargeOverCurrent

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureChargeOverTemp

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureDataFlushFault

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.

1026

IOPSKeys.h Reference Constants

kIOPSFailureDischargeFET

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureDischargeOverCurrent

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureDischargeOverTemp

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureExternalInput

Value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureFuseBlown

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureOpenThermistor

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailurePeriodicAFEComms

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailurePermanentAFEComms

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSFailureSafetyOverVoltage

Potential value for key kIOPSBatteryFailureModesKey Available in OS X v10.6 and later. Declared in IOPSKeys.h.

1027

IOPSKeys.h Reference Constants

kIOPSFairValue

Value for key kIOPSBatteryHealthKey. Available in OS X v10.4 and later. Declared in IOPSKeys.h.
kIOPSGoodValue

Value for key kIOPSBatteryHealthKey. Available in OS X v10.4 and later. Declared in IOPSKeys.h.
kIOPSHardwareSerialNumberKey

A unique serial number that identifies the power source. For Apple-manufactured batteries, this is an alphanumeric string generated during the battery manufacturing process.

Apple-defined power sources will publish this key if the hardware provides the serial number. For power source creators: Providing this key is RECOMMENDED. Type CFStringRef

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

kIOPSHealthConfidenceKey

CFDictionary key for our confidence in the accuracy of our power source's "health" estimate.

Apple-defined power sources will no longer publish this key. Power source creators should not publish this key. For power source creators: This key is DEPRECATED, do not implement it. Type CFStringRef

Available in OS X v10.4 and later. Declared in IOPSKeys.h.

kIOPSInternalBatteryType

Represents a battery residing inside a Mac. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSInternalType

Value for key kIOPSTransportTypeKey. Indicates the power source is an internal battery. Available in OS X v10.2 and later. Declared in IOPSKeys.h.

1028

IOPSKeys.h Reference Constants

kIOPSIsChargedKey

CFDictionary key indicates whether the battery is charged. A battery must be plugged in to an external power source in order to be fully charged. Note that a battery may validly be plugged in, not charging, and <100% charge. e.g. A battery with capacity >= 95% and not charging, is defined as charged.

Apple-defined power sources will publish this key. For power source creators: Providing this key is REQUIRED. Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

kIOPSIsChargingKey

CFDictionary key for the current power source's charging state

Apple-defined power sources will publish this key. For power source creators: Providing this key is REQUIRED. Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSIsFinishingChargeKey

CFDictionary key indicates whether the battery is finishing off its charge. When this is true, the system UI should indicate that the battery is "Finishing Charge." Some batteries may continue charging after they report 100% capacity.

Apple-defined battery power sources will publish this key. For power source creators: Providing this key is RECOMMENDED. Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

1029

IOPSKeys.h Reference Constants

kIOPSIsPresentKey

CFDictionary key for the current power source's presence.

Apple-defined power sources will publish this key. For instance, a portable with the capacity for two batteries but with only one present would show two power source dictionaries, but kIOPSIsPresentKey would have the value kCFBooleanFalse in one of them. For power source creators: Providing this key is REQUIRED. Type CFBoolean - kCFBooleanTrue or kCFBooleanFalse

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSLowWarnLevelKey

Key for the "Warning" UPS low power trigger-level. Default is 50%. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSMaxCapacityKey

CFDictionary key for the current power source's maximum or "Full Charge Capacity"

Apple-defined power sources will publish this key in units of percent. The value is usually 100%. The power source's software may specify the units for this key. The units must be consistent for all capacities reported by this power source. For power source creators: Providing this key is REQUIRED. Type CFNumber kCFNumberIntType (signed integer)

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSMaxErrKey

CFDictionary key for the current power source's percentage error in capacity reporting. In internal batteries, this refers to the battery pack's estimated percentage error.

Apple-defined battery power sources will publish this key, but only if it's defined for the battery. For power source creators: Providing this key is OPTIONAL. Type CFNumberRef kCFNumberIntType, non-negative integer

Available in OS X v10.4 and later. Declared in IOPSKeys.h.

1030

IOPSKeys.h Reference Constants

kIOPSNameKey

CFDictionary key for the current power source's name.

Apple-defined power sources will publish this key. For power source creators: Providing this key is REQUIRED. Type CFStringRef

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSNetworkTransportType

Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a network connection (and it may be managing several computers). Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSOffLineValue

Value for key kIOPSPowerSourceStateKey. Power source is off-line or no longer connected. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSPermanentFailureValue

Value for key kIOPSBatteryHealthConditionKey Indicates the battery needs replacement. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPoorValue

Value for key kIOPSBatteryHealthKey. Available in OS X v10.4 and later. Declared in IOPSKeys.h.
kIOPSPowerAdapterCurrentKey

This key refers to the current of the external AC power adapter attached to a portable. The value associated with this key is a CFNumberRef kCFNumberIntType integer value, in units of mAmps. This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.7 and later. Declared in IOPSKeys.h.

1031

IOPSKeys.h Reference Constants

kIOPSPowerAdapterFamilyKey

The power adapter's family code. The value associated with this key is a CFNumberRef kCFNumberIntType integer value This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPowerAdapterIDKey

This key refers to the attached external AC power adapter's ID. The value associated with this key is a CFNumberRef kCFNumberIntType integer. This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPowerAdapterRevisionKey

The power adapter's revision. The value associated with this key is a CFNumberRef kCFNumberIntType integer value This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPowerAdapterSerialNumberKey

The power adapter's serial number. The value associated with this key is a CFNumberRef kCFNumberIntType integer value This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPowerAdapterSourceKey

This key refers to the source of the power. The value associated with this key is a CFNumberRef kCFNumberIntType integer value. This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.7 and later. Declared in IOPSKeys.h.

1032

IOPSKeys.h Reference Constants

kIOPSPowerAdapterWattsKey

This key refers to the wattage of the external AC power adapter attached to a portable. The value associated with this key is a CFNumberRef kCFNumberIntType integer value, in units of watts. This key may be present in the dictionary returned from IOPSCopyExternalPowerAdapterDetails (page 1039) This key might not be defined in the adapter details dictionary. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSPowerSourceIDKey

CFNumber key uniquely identifying a UPS attached to the system.

Apple UPS power sources will publish this key. Callers should not set this key; OS X power management will publish this key for UPS's. Type CFNumber, kCFNumberIntType, uniquely identifying an attached UPS.

Available in OS X v10.3 and later. Declared in IOPSKeys.h.

kIOPSPowerSourceStateKey

CFDictionary key for the current source of power.

Apple-defined power sources will publish this key. For power source creators: Providing this key is REQUIRED.
kIOPSBatteryPowerValue indicates power source is drawing internal power; kIOPSACPowerValue indicates power source is connected to an external power source.

Type CFString, value is kIOPSACPowerValue, kIOPSBatteryPowerValue, or kIOPSOffLineValue.

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSSerialTransportType

Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a serial connection. Available in OS X v10.2 and later. Declared in IOPSKeys.h.

1033

IOPSKeys.h Reference Constants

kIOPSTimeToEmptyKey

CFDictionary key for the current power source's time remaining until empty. Only valid if the power source is running off its own power. That's when the kIOPSPowerSourceStateKey has value kIOPSBatteryPowerValue and the value of kIOPSIsChargingKey is kCFBooleanFalse.

Apple-defined power sources will publish this key. For power source creators: Providing this key is RECOMMENDED. Type CFNumber kCFNumberIntType (signed integer), units are minutes A value of -1 indicates "Still Calculating the Time", otherwise estimated minutes left on the battery.

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSTimeToFullChargeKey

CFDictionary key for the current power source's time remaining until empty. Only valid if the value of kIOPSIsChargingKey is kCFBooleanTrue.

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

kIOPSTransportTypeKey

CFDictionary key for the current power source's data transport type (e.g. the means that the power source conveys power source data to the OS X machine).

Apple-defined power sources will publish this key. A value of kIOPSInternalType describes an internal power source.
kIOPSUSBTransportType, kIOPSNetworkTransportType, and kIOPSSerialTransportType

usually describe UPS's.

For power source creators: Providing this key is REQUIRED. Type CFStringRef. Valid transport types are kIOPSSerialTransportType, kIOPSUSBTransportType, kIOPSNetworkTransportType, kIOPSInternalType

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

1034

IOPSKeys.h Reference Constants

kIOPSTypeKey

CFDictionary key for the type of the power source

Apple-defined power sources will publish this key. For power source creators: Providing this key is REQUIRED. Type CFStringRef. Valid transport types are kIOPSUPSType or kIOPSInternalBatteryType.

Available in OS X v10.6 and later. Declared in IOPSKeys.h.

kIOPSUPSManagementClaimed

Claims UPS management for a third-party driver. kIOPSUPSManagementClaimed is obsolete. Do not use. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSUPSType

Represents an external attached UPS. Available in OS X v10.6 and later. Declared in IOPSKeys.h.
kIOPSUSBTransportType

Value for key kIOPSTransportTypeKey. Indicates the power source is a UPS attached over a USB connection. Available in OS X v10.2 and later. Declared in IOPSKeys.h.
kIOPSVendorDataKey

CFDictionary key for arbitrary vendor data.

Apple-defined power sources are not required to publish this key. For power source creators: Providing this key is OPTIONAL. CFDictionary; contents determined by the power source software. OS X will not look at this data.

Available in OS X v10.3 and later. Declared in IOPSKeys.h.

kIOPSVoltageKey

CFDictionary key for the current power source's electrical voltage.

Apple-defined power sources will publish this key. For power source creators: Providing this key is RECOMMENDED. Type CFNumber kCFNumberIntType (signed integer) - units are mV

Available in OS X v10.2 and later. Declared in IOPSKeys.h.

1035

IOPartitionScheme.h User-Space Reference

Declared in

IOPartitionScheme.h

Overview
This header contains the IOPartitionScheme class definition.

Constants
See the Overview for header-level documentation.

Defines

#define kIOMediaLiveKey "Live" #define kIOMediaPartitionIDKey "Partition ID" #define kIOPartitionSchemeClass "IOPartitionScheme"

Constants
kIOMediaLiveKey

A property of IOMedia objects. The kIOMediaLiveKey property has an OSBoolean value and is placed into an IOMedia instance created via the partition scheme. It describes whether the partition is live, that is, it is up-to-date with respect to the on-disk partition table. Available in OS X v10.5 and later. Declared in IOPartitionScheme.h.

1036

IOPartitionScheme.h User-Space Reference Constants

kIOMediaPartitionIDKey

A property of IOMedia objects. The kIOMediaPartitionIDKey property has an OSNumber value and is placed into an IOMedia instance created via the partition scheme. It is an ID that differentiates one partition from the other (within a given scheme). It is typically an index into the on-disk partition table. Available in OS X v10.0 and later. Declared in IOPartitionScheme.h.
kIOPartitionSchemeClass

The name of the IOPartitionScheme class. kIOPartitionSchemeClass is the name of the IOPartitionScheme class. Available in OS X v10.0 and later. Declared in IOPartitionScheme.h.

1037

IOPowerSources.h Reference

Declared in

IOPowerSources.h

Overview
IOPowerSources provides uniform access to the state of power sources attached to the system. You can receive a change notification when any power source data changes. "Power sources" currently include batteries and UPS devices. The header follows CF semantics in that it is the caller's responsibility to CFRelease() anything returned by a "Copy" function, and the caller should not CFRelease() anything returned by a "Get" function.

Included Headers

Functions by Task
See the Overview for header-level documentation.

Quick Power Source Info

IOPSGetTimeRemainingEstimate (page 1043)

Returns the estimated minutes remaining until all power sources (battery and/or UPS's) are empty, or returns kIOPSTimeRemainingUnlimited if attached to an unlimited power source.

Power Source Descriptions

IOPSCopyExternalPowerAdapterDetails (page 1039)

Returns a CFDictionary that describes the attached (AC) external power adapter (if any external power adapter is attached.

1038

IOPowerSources.h Reference Functions

IOPSCopyPowerSourcesInfo (page 1040)

Returns a blob of Power Source information in an opaque CFTypeRef.

IOPSCopyPowerSourcesList (page 1040)

Returns a CFArray of Power Source handles, each of type CFTypeRef.

IOPSGetPowerSourceDescription (page 1041)

Returns a CFDictionary with readable information about the specific power source.
IOPSGetProvidingPowerSourceType(CFTypeRef) (page 1042)

Indicates the power source the computer is currently drawing from.

IOPSGetProvidingPowerSourceType(CFTypeRef) (page 1043)

Indicates the power source the computer is currently drawing from.

IOPSNotificationCreateRunLoopSource (page 1044)

Returns a CFRunLoopSourceRef that notifies the caller when power source information changes.

Low Power Warnings

IOPSGetBatteryWarningLevel (page 1041)

Indicates whether the system is at a low battery warning level.

Functions
IOPSCopyExternalPowerAdapterDetails
Returns a CFDictionary that describes the attached (AC) external power adapter (if any external power adapter is attached.

CFDictionaryRef IOPSCopyExternalPowerAdapterDetails( void);

Return Value Returns a CFDictionary on success. Caller must release the returned dictionary. If no adapter is attached, or if there's an error, returns NULL. Discussion Use the kIOPSPowerAdapter... keys described in IOPSKeys.h to interpret the returned CFDictionary.

1039

IOPowerSources.h Reference Functions

Availability Available in OS X v10.6 and later. Declared in

IOPowerSources.h

IOPSCopyPowerSourcesInfo
Returns a blob of Power Source information in an opaque CFTypeRef.

CFTypeRef IOPSCopyPowerSourcesInfo( void);

Return Value NULL if errors were encountered, a CFTypeRef otherwise. Caller must CFRelease() the return value when done accessing it. Discussion Clients should not directly access data in the returned CFTypeRef - they should use the accessor functions IOPSCopyPowerSourcesList and IOPSGetPowerSourceDescription, instead. Availability Available in OS X v10.2 and later.
Related Sample Code Quartz Composer BatteryInfo

Declared in
IOPowerSources.h

IOPSCopyPowerSourcesList
Returns a CFArray of Power Source handles, each of type CFTypeRef.

CFArrayRef IOPSCopyPowerSourcesList( CFTypeRef blob);

Parameters
blob

Takes the CFTypeRef returned by IOPSCopyPowerSourcesInfo()

1040

IOPowerSources.h Reference Functions

Return Value Returns NULL if errors were encountered, otherwise a CFArray of CFTypeRefs. Caller must CFRelease() the returned CFArrayRef. Discussion The caller shouldn't directly access the CFTypeRefs, but should use IOPSGetPowerSourceDescription on each member of the CFArrayRef. Availability Available in OS X v10.2 and later.
Related Sample Code Quartz Composer BatteryInfo

Declared in
IOPowerSources.h

IOPSGetBatteryWarningLevel
Indicates whether the system is at a low battery warning level.

IOPSLowBatteryWarningLevel IOPSGetBatteryWarningLevel( void);

Discussion If your app runs in full screen mode and occludes OS X's battery monitor's low battery warnings, you should alert the user at least when the system is in kIOPSLowBatteryWarnFinal. Availability Available in OS X v10.6 and later. Declared in
IOPowerSources.h

IOPSGetPowerSourceDescription
Returns a CFDictionary with readable information about the specific power source.

CFDictionaryRef IOPSGetPowerSourceDescription( CFTypeRef blob, CFTypeRef ps);

1041

IOPowerSources.h Reference Functions

Parameters
blob

The CFTypeRef returned by IOPSCopyPowerSourcesInfo()

One of the CFTypeRefs in the CFArray returned by IOPSCopyPowerSourcesList() Return Value Returns NULL if an error was encountered, otherwise a CFDictionary. Caller should NOT release the returned CFDictionary - it will be released as part of the CFTypeRef returned by IOPSCopyPowerSourcesInfo(). Discussion See the C-strings defined in IOPSKeys.h for specific keys into the dictionary. Don't expect all keys to be present in any dictionary. Some power sources, for example, may not support the "Time Remaining To Empty" key and it will not be present in their dictionaries. Availability Available in OS X v10.2 and later.
Related Sample Code Quartz Composer BatteryInfo

Declared in
IOPowerSources.h

IOPSGetProvidingPowerSourceType(CFTypeRef )
Indicates the power source the computer is currently drawing from.

CFStringRef IOPSGetProvidingPowerSourceType( CFTypeRef snapshot);

Parameters
snapshot

The CFTypeRef returned by IOPSCopyPowerSourcesInfo(); caller may pass NULL. Return Value One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) Discussion Determines which power source is providing power.

1042

IOPowerSources.h Reference Functions

IOPSGetProvidingPowerSourceType(CFTypeRef )
Indicates the power source the computer is currently drawing from.

CFStringRef IOPSGetProvidingPowerSourceType( CFTypeRef snapshot);

Parameters
snapshot

The CFTypeRef returned by IOPSCopyPowerSourcesInfo() Return Value One of: CFSTR(kIOPMACPowerKey), CFSTR(kIOPMBatteryPowerKey), CFSTR(kIOPMUPSPowerKey) Discussion Determines which power source is providing power.

IOPSGetTimeRemainingEstimate
Returns the estimated minutes remaining until all power sources (battery and/or UPS's) are empty, or returns kIOPSTimeRemainingUnlimited if attached to an unlimited power source.

CFTimeInterval IOPSGetTimeRemainingEstimate( void);

Return Value Returns kIOPSTimeRemainingUnknown if the OS cannot determine the time remaining. Returns kIOPSTimeRemainingUnlimited if the system has an unlimited power source. Otherwise returns a positive number of type CFTimeInterval, indicating the time remaining in seconds until all power sources are depleted. Discussion If attached to an "Unlimited" power source, like AC power or any external source, the return value is
kIOPSTimeRemainingUnlimited

If the system is on "Limited" power, like a battery or UPS, but is still calculating the time remaining, which may take several seconds after each system power event (e.g. waking from sleep, or unplugging AC Power), the return value is kIOPSTimeRemainingUnknown Otherwise, if the system is on "Limited" power and the system has an accurate time remaining estimate, the system returns a CFTimeInterval estimate of the time remaining until the system is out of battery power.

1043

IOPowerSources.h Reference Functions

If you require more detailed battery information, use IOPSCopyPowerSourcesInfo (page 1040)> and IOPSGetPowerSourceDescription (page 1041)>. Availability Available in OS X v10.7 and later. Declared in
IOPowerSources.h

IOPSNotificationCreateRunLoopSource
Returns a CFRunLoopSourceRef that notifies the caller when power source information changes.

CFRunLoopSourceRef IOPSNotificationCreateRunLoopSource( IOPowerSourceCallbackType callback, void *context);

Parameters
callback

A function to be called whenever any power source is added, removed, or changes.

context

Any user-defined pointer, passed to the IOPowerSource callback. Return Value Returns NULL if an error was encountered, otherwise a CFRunLoopSource. Caller must release the CFRunLoopSource. Discussion Returns a CFRunLoopSourceRef for scheduling with your CFRunLoop. If your project does not use a CFRunLoop, you can alternatively receive notifications via mach port, dispatch, or signal, via notify.h using the name
kIOPSTimeRemainingNotificationKey

Availability Available in OS X v10.2 and later. Declared in

IOPowerSources.h

1044

IOPowerSources.h Reference Data Types

Data Types
See the Overview for header-level documentation.

IOPSLowBatteryWarningLevel
The battery can provide no more than 10 minutes of runtime.

typedef enum { /*! @constant kIOPSLowBatteryWarningNone */ kIOPSLowBatteryWarningNone = 1, /*! @constant kIOPSLowBatteryWarningEarly */ kIOPSLowBatteryWarningEarly = 2, /*! @constant kIOPSLowBatteryWarningFinal */ kIOPSLowBatteryWarningFinal = 3 } IOPSLowBatteryWarningLevel;

Constants
kIOPSLowBatteryWarningNone

Available in OS X v10.6 and later. Declared in IOPowerSources.h.

kIOPSLowBatteryWarningEarly

Available in OS X v10.6 and later. Declared in IOPowerSources.h.

kIOPSLowBatteryWarningFinal

Available in OS X v10.6 and later. Declared in IOPowerSources.h. Discussion OS X makes no guarantees that the system shall remain in Final Warning for 10 minutes. Batteries are frequently calibrated differently and may provide runtime for more, or less, than the estimated 10 minutes. Availability Available in OS X v10.6 and later. Declared in
IOPowerSources.h

1045

IOPowerSources.h Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define

kIOPSNotifyLowBattery "com.apple.system.powersources.lowbattery" kIOPSTimeRemainingNotificationKey "com.apple.system.powersources.timeremaining" kIOPSTimeRemainingUnknown ((CFTimeInterval)-1.0) kIOPSTimeRemainingUnlimited ((CFTimeInterval)-2.0)

Constants
kIOPSNotifyLowBattery

Notify(3) key. The system delivers notifications on this key when the battery time remaining drops into a warnable level. Available in OS X v10.6 and later. Declared in IOPowerSources.h.
kIOPSTimeRemainingNotificationKey

C-string key for a notification that fires when the power source(s) time remaining changes. Use notify(3) API to register for notifications. Available in OS X v10.7 and later. Declared in IOPowerSources.h.
kIOPSTimeRemainingUnknown

Possible return value from IOPSGetTimeRemainingEstimate (page 1043) Indicates the system is connected to a limited power source, but the system is still calculating a time remaining estimate. Check for a valid estimate again when the notification kIOPSPowerSourcesNotificationKey fires. Available in OS X v10.7 and later. Declared in IOPowerSources.h.
kIOPSTimeRemainingUnlimited

Possible return value from IOPSGetTimeRemainingEstimate (page 1043) Indicates the system is connected to an external power source, without a time limit. Available in OS X v10.7 and later. Declared in IOPowerSources.h.

1046

IOStorage.h User-Space Reference

Declared in

IOStorage.h

Overview
This header contains the IOStorage class definition.

Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define

kIOStorageCategory "IOStorage" /* (as IOMatchCategory) */ kIOStorageClass "IOStorage" kIOStorageFeatureForceUnitAccess "Force Unit Access" kIOStorageFeaturesKey "IOStorageFeatures" kIOStorageFeatureUnmap "Unmap"

1047

IOStorage.h User-Space Reference Constants

Constants
kIOStorageCategory

kIOStorageCategory is a value for IOService's kIOMatchCategoryKey property. The kIOStorageCategory value is the standard value for the IOService property kIOMatchCategoryKey ("IOMatchCategory") for all storage drivers. All storage objects that expect to drive new content (that is, produce new media objects) are expected to compete within the kIOStorageCategory namespace. See the IOService documentation for more information on match categories. Available in OS X v10.0 and later. Declared in IOStorage.h.
kIOStorageClass

The name of the IOStorage class. Available in OS X v10.0 and later. Declared in IOStorage.h.
kIOStorageFeatureForceUnitAccess

Describes the presence of the Force Unit Access feature. This property describes the ability of the storage stack to force a request to access the media. It is one of the feature entries listed under the top- level kIOStorageFeaturesKey property table. It has an OSBoolean value. Available in OS X v10.5 and later. Declared in IOStorage.h.
kIOStorageFeaturesKey

A property of any object in the storage stack. kIOStorageFeaturesKey is a property of any object in the storage stack that wishes to express support of additional features, such as Force Unit Access. It is typically defined in the device object below the block storage driver object. It has an OSDictionary value, where each entry describes one given feature. Available in OS X v10.5 and later. Declared in IOStorage.h.
kIOStorageFeatureUnmap

Describes the presence of the Unmap feature. This property describes the ability of the storage stack to delete unused data from the media. It is one of the feature entries listed under the top- level kIOStorageFeaturesKey property table. It has an OSBoolean value. Available in OS X v10.7 and later. Declared in IOStorage.h.

1048

IOStorageCardCharacteristics.h User-Space Reference

Declared in IOStorageCardCharacteristics.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOProperty64BitKey "64-bit" kIOPropertyApplicationIDKey "Application ID" kIOPropertyBaseFrequencyKey "Base Frequency" kIOPropertyBusVoltageKey "Bus Voltage" kIOPropertyBusWidthKey "Bus Width" kIOPropertyCardCharacteristicsKey "Card Characteristics" kIOPropertyCardPresentKey "Card Present" kIOPropertyCardTypeKey "Card Type" kIOPropertyCardTypeMMCKey "MMC" kIOPropertyCardTypeSDHCKey "SDHC" kIOPropertyCardTypeSDSCKey "SDSC" kIOPropertyCardTypeSDXCKey "SDXC" kIOPropertyClockDivisorKey "Clock Divisor" kIOPropertyManufacturerIDKey "Manufacturer ID" kIOPropertyManufacturingDateKey "Manufacturing Date" kIOPropertyProductSerialNumberKey "Serial Number" kIOPropertySlotKey "Slot" kIOPropertySpecificationVersionKey "Specification Version" kIOPropertySpeedClassKey "Speed Class"

1049

IOStorageCardCharacteristics.h User-Space Reference Constants

Constants
kIOProperty64BitKey

This key defines wether the device supports 64-bit. Requirement: Mandatory Example:

<dict> <key>64-bit</key> <true/> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyApplicationIDKey

This key is used to indicate the card application ID. Requirement: Optional Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> <key>Card Type</key> <string>SDHC</string> <key>Application ID</key> <data>ffff</data> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1050

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyBaseFrequencyKey

This key defines the current base frequency for the device. Requirement: Mandatory. Example:

<dict> <key>Base Frequency</key> <integer>50</integer> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyBusVoltageKey

This key defines the current bus voltage for the device in mV Requirement: Mandatory. Example:

<dict> <key>Bus Voltage</key> <integer>3300</integer> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyBusWidthKey

This key defines the current bus width for the device. Requirement: Mandatory. Example:

<dict> <key>Bus Width</key> <integer>4</integer> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1051

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyCardCharacteristicsKey

This key is used to define Card Characteristics for a particular piece of MMC/SD media and it has an associated dictionary which lists the card characteristics. Requirement: Mandatory Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyCardPresentKey

This key defines wether a MMC or SD card is physically present. Requirement: Mandatory Example:

<dict> <key>Card Present</key> <true/> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1052

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyCardTypeKey

This key is used to indicate the card type is MMC. Requirement: Optional. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyCardTypeMMCKey

This key is used to indicate the card type is MMC. Requirement: Optional. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1053

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyCardTypeSDHCKey

This key is used to indicate the card type is SDHC. Requirement: Optional. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyCardTypeSDSCKey

This key is used to indicate the card type is SDSC. Requirement: Optional. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1054

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyCardTypeSDXCKey

This key is used to indicate the card type is SDXC. Requirement: Optional. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyClockDivisorKey

This key defines the current clock divisor for the device. Requirement: Mandatory. Example:

<dict> <key>Clock Divisor</key> <integer>128</integer> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1055

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyManufacturerIDKey

This key is used to indicate the card manufacturer ID. Requirement: Optional Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> <key>Card Type</key> <string>SDHC</string> <key>Manufacturer ID</key> <data>03</data> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertyManufacturingDateKey

This key is used to indicate the card manufacturing date. Requirement: Mandatory. Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> <key>Card Type</key> <string>SDHC</string> <key>Manufacturing Date</key> <string>2009-12</string> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1056

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertyProductSerialNumberKey

This key is used to indicate the card serial number ID. Requirement: Mandatory Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> <key>Card Type</key> <string>SDHC</string> <key>Serial Number</key> <data>0045ff</data> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertySlotKey

This key is used to define the slot number for the device Requirement: Mandatory Example:

<dict> <key>Slot</key> <integer>1<integer> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1057

IOStorageCardCharacteristics.h User-Space Reference Constants

kIOPropertySpecificationVersionKey

This key is used to indicate the card specification version. Requirement: Mandatory. Example:

<dict> <key>Card Characteristics</key> <dict> <key>Product Name</key> <string>SD32G</string> <key>Product Revision Level</key> <string>1.0</string> <key>Card Type</key> <string>SDHC</string> <key>Specification Version</key> <string>3.0</string> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

kIOPropertySpeedClassKey

This key is used to indicate SD card speed class. Requirement: Mandatory. Example:

Available in OS X v10.7 and later. Declared in IOStorageCardCharacteristics.h.

1058

IOStorageDeviceCharacteristics.h User-Space Reference

Declared in IOStorageDeviceCharacteristics.h

Overview
Included Headers

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOPropertyBytesPerPhysicalSectorKey "Bytes per Physical Sector" kIOPropertyCylinderCountKey "Cylinder Count" kIOPropertyDeviceCharacteristicsKey "Device Characteristics" kIOPropertyHeadCountKey "Head Count" kIOPropertyLogicalBlockSizeKey "Logical Block Size" kIOPropertyMediumRotationRateKey "Rotation Rate" kIOPropertyMediumTypeKey "Medium Type" kIOPropertyMediumTypeRotationalKey "Rotational" kIOPropertyMediumTypeSolidStateKey "Solid State" kIOPropertyPhysicalBlockSizeKey "Physical Block Size" kIOPropertyProductNameKey "Product Name" kIOPropertyProductRevisionLevelKey "Product Revision Level" kIOPropertyProductSerialNumberKey "Serial Number" kIOPropertyRigidDiskGeometryKey "Rigid Disk Geometry" kIOPropertySectorCountPerTrackKey "Sector Count per Track" kIOPropertySupportedBDFeaturesKey "BD Features" kIOPropertySupportedCDFeaturesKey "CD Features" kIOPropertySupportedDVDFeaturesKey "DVD Features"

1059

IOStorageDeviceCharacteristics.h User-Space Reference Constants

#define kIOPropertyTargetDiskModeKey "Target Disk Mode" #define kIOPropertyVendorNameKey "Vendor Name"

Constants
kIOPropertyBytesPerPhysicalSectorKey

This key is used to define the number of heads for a particular medium. Requirement: Mandatory element of the Rigid Disk Geometry dictionary. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>Apple</string> <key>Product Name</key> <string>iPod</string> <key>Product Revision Level</key> <string>1.0</string> <key>Rigid Disk Geometry</key> <dict> <key>Sector Count per Track</key> <integer>12345</integer> <key>Head Count</key> <integer>12</integer> <key>Cylinder Count</key> <integer>12345</integer> <key>Bytes per Physical Sector</key> <integer>512</integer> </dict> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1060

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyCylinderCountKey

This key is used to define the number of heads for a particular medium. Requirement: Mandatory element of the Rigid Disk Geometry dictionary. Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1061

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyDeviceCharacteristicsKey

This key is used to define Device Characteristics for a particular device and it has an associated dictionary which lists the device characteristics. The device characteristics are Command Set specific and are listed in the header files for each command set. Requirement: Mandatory Example:

Available in OS X v10.1 and later. Declared in IOStorageDeviceCharacteristics.h.

1062

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyHeadCountKey

This key is used to define the number of heads for a particular medium. Requirement: Mandatory element of the Rigid Disk Geometry dictionary. Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1063

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyLogicalBlockSizeKey

This key is used to define the logical block size of a hard disk drive. Requirement: Mandatory for hard disk drives with logical block size other than 512 bytes or that does not match its physical block size. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>Apple</string> <key>Product Name</key> <string>iPod</string> <key>Product Revision Level</key> <string>1.0</string> <key>Physical Block Size</key> <integer>4096</integer> <key>Logical Block Size</key> <integer>512</integer> </dict> </dict>

Available in OS X v10.5 and later. Declared in IOStorageDeviceCharacteristics.h.

1064

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyMediumRotationRateKey

This key is used to indicate the medium rotation rate in RPM of the device. Requirement: Optional. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>AAPL</string> <key>Product Name</key> <string>FireWire Target</string> <key>Product Revision Level</key> <string>0000</string> <key>Rotation Rate</key> <integer>7200</integer> </dict> </dict>

Available in OS X v10.6 and later. Declared in IOStorageDeviceCharacteristics.h.

kIOPropertyMediumTypeKey

This key is used to indicate the medium type of the device. Requirement: Optional. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>AAPL</string> <key>Product Name</key> <string>FireWire Target</string> <key>Product Revision Level</key> <string>0000</string> <key>Medium Type</key> <string>Rotational</string> </dict> </dict>

Available in OS X v10.6 and later. Declared in IOStorageDeviceCharacteristics.h.

1065

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyMediumTypeRotationalKey

This key is used to indicate the medium type of the device is rotational. Requirement: Optional. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>AAPL</string> <key>Product Name</key> <string>FireWire Target</string> <key>Product Revision Level</key> <string>0000</string> <key>Medium Type</key> <string>Rotational</string> </dict> </dict>

Available in OS X v10.6 and later. Declared in IOStorageDeviceCharacteristics.h.

kIOPropertyMediumTypeSolidStateKey

This key is used to indicate the medium type of the device is solid state. Requirement: Optional. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>AAPL</string> <key>Product Name</key> <string>FireWire Target</string> <key>Product Revision Level</key> <string>0000</string> <key>Medium Type</key> <string>Solid State</string> </dict> </dict>

Available in OS X v10.6 and later. Declared in IOStorageDeviceCharacteristics.h.

1066

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalBlockSizeKey

This key is used to define the physical block size of a hard disk drive. Requirement: Mandatory for hard disk drives with physical block size other than 512 bytes. Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>Apple</string> <key>Product Name</key> <string>iPod</string> <key>Product Revision Level</key> <string>1.0</string> <key>Physical Block Size</key> <integer>4096</integer> <key>Logical Block Size</key> <integer>512</integer> </dict> </dict>

Available in OS X v10.5 and later. Declared in IOStorageDeviceCharacteristics.h.

kIOPropertyProductNameKey

This key is used to define the Product Name for a particular device and it has an associated string. Requirement: Mandatory Example:

Available in OS X v10.1 and later. Declared in IOStorageDeviceCharacteristics.h.

1067

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyProductRevisionLevelKey

This key is used to define the Product Revision Level for a particular device and it has an associated string. Requirement: Mandatory Example:

Available in OS X v10.1 and later. Declared in IOStorageDeviceCharacteristics.h.

kIOPropertyProductSerialNumberKey

This key is used to define the Product Serial Number for a particular device and it has an associated data. Requirement: Mandatory Example:

Available in OS X v10.4 and later. Declared in IOStorageCardCharacteristics.h.

1068

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyRigidDiskGeometryKey

This key is used to define a dictionary containing rigid disk geometry information. Requirement: Optional. If a device publishes this dictionary, it must publish all key/value pairs which are deemed Mandatory. Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1069

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertySectorCountPerTrackKey

This key is used to define the number of sectors per each track for a particular medium. Requirement: Mandatory element of the Rigid Disk Geometry dictionary. Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1070

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertySupportedBDFeaturesKey

This key is used to define the supported BD Features for a particular optical device and it has an associated bitfield. See <IOKit/scsi/IOSCSIMultimediaCommandsDevice.h> for definitions of the bits and associated bitmasks. Requirement: Mandatory for optical devices (Peripheral Device Type 05h). Example:

<dict> <key>Device Characteristics</key> <dict> <key>Vendor Name</key> <string>Apple</string> <key>Product Name</key> <string>SuperDrive</string> <key>Product Revision Level</key> <string>1.0</string> <key>CD Features</key> <integer>1663</integer> <key>DVD Features</key> <integer>103</integer> <key>BD Features</key> <integer>21</integer> </dict> </dict>

Available in OS X v10.5 and later. Declared in IOStorageDeviceCharacteristics.h.

1071

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertySupportedCDFeaturesKey

This key is used to define the supported CD Features for a particular optical device and it has an associated bitfield. See <IOKit/scsi/IOSCSIMultimediaCommandsDevice.h> for definitions of the bits and associated bitmasks. Requirement: Mandatory for optical devices (Peripheral Device Type 05h). Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1072

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertySupportedDVDFeaturesKey

This key is used to define the supported DVD Features for a particular optical device and it has an associated bitfield. See <IOKit/scsi/IOSCSIMultimediaCommandsDevice.h> for definitions of the bits and associated bitmasks. Requirement: Mandatory for optical devices (Peripheral Device Type 05h). Example:

Available in OS X v10.3 and later. Declared in IOStorageDeviceCharacteristics.h.

1073

IOStorageDeviceCharacteristics.h User-Space Reference Constants

kIOPropertyTargetDiskModeKey

This key is used to indicate the device is another computer in Target Disk Mode. Requirement: Optional. Example:

Available in OS X v10.6 and later. Declared in IOStorageDeviceCharacteristics.h.

kIOPropertyVendorNameKey

This key is used to define the Vendor Name for a particular device and it has an associated string. Requirement: Mandatory Example:

Available in OS X v10.1 and later. Declared in IOStorageDeviceCharacteristics.h.

1074

IOStorageProtocolCharacteristics.h User-Space Reference

Declared in IOStorageProtocolCharacteristics.h

Overview Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOPropertyExternalKey "External" kIOPropertyFibreChannelAddressIdentifierKey "Address Identifier" kIOPropertyFibreChannelALPAKey "AL_PA" kIOPropertyFibreChannelCableDescriptionCopperKey "Copper" kIOPropertyFibreChannelCableDescriptionFiberOpticKey "Fiber Optic" kIOPropertyFibreChannelCableDescriptionKey "Fibre Channel Cabling Type" kIOPropertyFibreChannelNodeWorldWideNameKey "Node World Wide Name" kIOPropertyFibreChannelPortWorldWideNameKey "Port World Wide Name" kIOPropertyInterconnectFileKey "File" kIOPropertyInterconnectRAMKey "RAM" kIOPropertyInternalExternalKey "Internal/External" kIOPropertyInternalKey "Internal" kIOPropertyPhysicalInterconnectLocationKey "Physical Interconnect Location" kIOPropertyPhysicalInterconnectTypeATA "ATA" kIOPropertyPhysicalInterconnectTypeATAPI "ATAPI" kIOPropertyPhysicalInterconnectTypeFibreChannel "Fibre Channel Interface" kIOPropertyPhysicalInterconnectTypeFireWire "FireWire" kIOPropertyPhysicalInterconnectTypeKey "Physical Interconnect" kIOPropertyPhysicalInterconnectTypeSCSIParallel "SCSI Parallel Interface" kIOPropertyPhysicalInterconnectTypeSecureDigital "Secure Digital" kIOPropertyPhysicalInterconnectTypeSerialATA "SATA" kIOPropertyPhysicalInterconnectTypeSerialAttachedSCSI "SAS" kIOPropertyPhysicalInterconnectTypeUSB "USB"

1075

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeVirtual "Virtual Interface" kIOPropertyPortDescriptionKey "Port Description" kIOPropertyPortSpeed10GigabitKey "10 Gigabit" kIOPropertyPortSpeed12GigabitKey "12 Gigabit" kIOPropertyPortSpeed16GigabitKey "16 Gigabit" kIOPropertyPortSpeed1_5GigabitKey "1.5 Gigabit" kIOPropertyPortSpeed1GigabitKey "1 Gigabit" kIOPropertyPortSpeed2GigabitKey "2 Gigabit" kIOPropertyPortSpeed3GigabitKey "3 Gigabit" kIOPropertyPortSpeed40GigabitKey "40 Gigabit" kIOPropertyPortSpeed4GigabitKey "4 Gigabit" kIOPropertyPortSpeed6GigabitKey "6 Gigabit" kIOPropertyPortSpeed8GigabitKey "8 Gigabit" kIOPropertyPortSpeedAutomatic10GigabitKey "Automatic (10 Gigabit)" kIOPropertyPortSpeedAutomatic1_5GigabitKey "Automatic (1.5 Gigabit)" kIOPropertyPortSpeedAutomatic1GigabitKey "Automatic (1 Gigabit)" kIOPropertyPortSpeedAutomatic2GigabitKey "Automatic (2 Gigabit)" kIOPropertyPortSpeedAutomatic3GigabitKey "Automatic (3 Gigabit)" kIOPropertyPortSpeedAutomatic4GigabitKey "Automatic (4 Gigabit)" kIOPropertyPortSpeedAutomatic6GigabitKey "Automatic (6 Gigabit)" kIOPropertyPortSpeedAutomatic8GigabitKey "Automatic (8 Gigabit)" kIOPropertyPortSpeedAutomaticKey "Automatic" kIOPropertyPortSpeedKey "Port Speed" kIOPropertyPortStatusKey "Port Status" kIOPropertyPortStatusLinkEstablishedKey "Link Established" kIOPropertyPortStatusLinkFailedKey "Link Failed" kIOPropertyPortStatusNoLinkEstablishedKey "No Link Established" kIOPropertyPortTopologyAutomaticKey "Automatic" kIOPropertyPortTopologyAutomaticNLPortKey "Automatic (NL_Port)" kIOPropertyPortTopologyAutomaticNPortKey "Automatic (N_Port)" kIOPropertyPortTopologyKey "Port Topology" kIOPropertyPortTopologyNLPortKey "NL_Port" kIOPropertyPortTopologyNPortKey "N_Port" kIOPropertyProtocolCharacteristicsKey "Protocol Characteristics" kIOPropertySASAddressKey "SAS Address" kIOPropertySCSIDomainIdentifierKey "SCSI Domain Identifier" kIOPropertySCSIInitiatorIdentifierKey "SCSI Initiator Identifier" kIOPropertySCSILogicalUnitNumberKey "SCSI Logical Unit Number" kIOPropertySCSIParallelSignalingTypeHVDKey "High Voltage Differential" kIOPropertySCSIParallelSignalingTypeKey "SCSI Parallel Signaling Type" kIOPropertySCSIParallelSignalingTypeLVDKey "Low Voltage Differential" kIOPropertySCSIParallelSignalingTypeSEKey "Single Ended" kIOPropertySCSIPortIdentifierKey "Unique SCSI Port Identifier" kIOPropertySCSIProtocolMultiInitKey "Multiple Initiators" kIOPropertySCSITargetIdentifierKey "SCSI Target Identifier"

1076

IOStorageProtocolCharacteristics.h User-Space Reference Constants

Constants
kIOPropertyExternalKey

This key defines the value of External for the key kIOPropertyPhysicalInterconnectLocationKey. If the device is connected to an external bus, this key should be set. Example:

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

1077

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelAddressIdentifierKey

This key is the 24-bit Address Identifier (S_ID or D_ID) as defined in the FC-FS specification. It contains the address identifier of the source or destination Nx_Port. Note: This value can change. It is not a static value. Requirement: Optional (only necessary for Fibre Channel Interface). Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Fibre Channel Interface</string> <key>Physical Interconnect Location</key> <string>External</string> <key>Address Identifier</key> <data>001122</data> </dict> </dict>

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>Address Identifier</key> <data>001122</data> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1078

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelALPAKey

This key is the 8-bit Arbitrated Loop Physical Address (AL_PA) value as defined in the FC-AL-2 specification. Note: This value can change. It is not a static value. Requirement: Optional (only necessary for Fibre Channel Interface). Example:

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>AL_PA</key> <data>04</data> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1079

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelCableDescriptionCopperKey

This key defines the value of Copper for the key kIOPropertyFibreChannelCableDescriptionKey. If the cabling is Copper, this key should be used. Requirement: Optional for Fibre Channel Interface interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Fibre Channel Cabling Type</key> <string>Copper</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyFibreChannelCableDescriptionFiberOpticKey

This key defines the value of Fiber Optic for the key kIOPropertyFibreChannelCableDescriptionKey. If the cabling is Fiber Optic, this key should be used. Requirement: Optional for Fibre Channel Interface interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Fibre Channel Cabling Type</key> <string>Fiber Optic</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1080

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelCableDescriptionKey

This key is associated with the cabling type used for this Fibre Channel port. Valid values include "Copper" and "Fiber Optic". Requirement: Optional for Fibre Channel Interface. Not defined for any other physical interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Fibre Channel Cabling Type</key> <string>Copper</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1081

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelNodeWorldWideNameKey

This key is the unique 64-bit World Wide Name for the device server node located at this port, or for the initiating host port. Requirement: Mandatory for Fibre Channel Interface. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Fibre Channel Interface</string> <key>Physical Interconnect Location</key> <string>External</string> <key>Node World Wide Name</key> <data>0011223344556677</data> </dict> </dict>

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>Node World Wide Name</key> <data>0011223344556677</data> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1082

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyFibreChannelPortWorldWideNameKey

This key is the unique 64-bit World Wide Name for the port. Requirement: Mandatory for Fibre Channel Interface. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Fibre Channel Interface</string> <key>Physical Interconnect Location</key> <string>External</string> <key>Port World Wide Name</key> <data>0011223344556677</data> </dict> </dict>

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>Port World Wide Name</key> <data>0011223344556677</data> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1083

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyInterconnectFileKey

This key defines the value of File for the key kIOPropertyPhysicalInterconnectLocationKey. If the device is a file that is being represented as a storage device, this key should be set. NOTE: This key should only be used when the Physical Interconnect is set to Virtual Interface. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Virtual Interface</string> <key>Physical Interconnect Location</key> <string>File</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyInterconnectRAMKey

This key defines the value of RAM for the key kIOPropertyPhysicalInterconnectLocationKey. If the device is system memory that is being represented as a storage device, this key should be set. NOTE: This key should only be used when the Physical Interconnect is set to Virtual Interface. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Virtual Interface</string> <key>Physical Interconnect Location</key> <string>RAM</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1084

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyInternalExternalKey

This key defines the value of Internal/External for the key kIOPropertyPhysicalInterconnectLocationKey. If the device is connected to a bus and it is indeterminate whether it is internal or external, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>SCSI Parallel Interface</string> <key>Physical Interconnect Location</key> <string>Internal/External</string> </dict> </dict>

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyInternalKey

This key defines the value of Internal for the key kIOPropertyPhysicalInterconnectLocationKey. If the device is connected to an internal bus, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>ATA</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

1085

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectLocationKey

This key is used to define the Physical Interconnect Location. Requirement: Mandatory. Example:

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeATA

This key defines the value of ATA for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to an ATA bus, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>ATA</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1086

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeATAPI

This key defines the value of ATAPI for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to an ATA bus and follows the ATAPI command specification, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>ATAPI</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeFibreChannel

This key defines the value of Fibre Channel Interface for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a Fibre Channel port, this key should be set. Example:

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1087

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeFireWire

This key defines the value of USB for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a FireWire port, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>FireWire</string> <key>Physical Interconnect Location</key> <string>External</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeKey

This key is used to define the Physical Interconnect to which a device is attached. Requirement: Mandatory. Example:

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

1088

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeSCSIParallel

This key defines the value of SCSI Parallel Interface for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a SCSI Parallel port, this key should be set. Example:

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeSecureDigital

This key defines the value of Secure Digital for the key kIOPropertyPhysicalInterconnectTypeSecureDigital. If the device is connected to a Secure Digital port and follows the Secure Digital specification, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Secure Digital</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageProtocolCharacteristics.h.

1089

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeSerialATA

This key defines the value of SATA for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a SATA bus, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>SATA</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeSerialAttachedSCSI

This key defines the value of SAS for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a SAS bus, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>SAS</string> <key>Physical Interconnect Location</key> <string>External</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1090

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPhysicalInterconnectTypeUSB

This key defines the value of USB for the key kIOPropertyPhysicalInterconnectTypeKey. If the device is connected to a USB port, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>USB</string> <key>Physical Interconnect Location</key> <string>External</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPhysicalInterconnectTypeVirtual

This key defines the value of Virtual Interface for the key kIOPropertyPhysicalInterconnectTypeVirtual. If the device is being made to look like a storage device, but is not such in actuality, such as a File or RAM, this key should be set. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Virtual Interface</string> <key>Physical Interconnect Location</key> <string>File</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1091

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortDescriptionKey

This key is associated with an human readable port description. Examples include "Channel A", "Port 1", etc. Requirement: Optional for all interconnects. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Description</key> <string>Channel A</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed10GigabitKey

This key defines the value of 10 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 10 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>10 Gigabit</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1092

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeed12GigabitKey

This key defines the value of 12 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 12 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>12 Gigabit</string> </dict> </dict>

Available in OS X v10.8 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed16GigabitKey

This key defines the value of 16 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 16 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>16 Gigabit</string> </dict> </dict>

Available in OS X v10.8 and later. Declared in IOStorageProtocolCharacteristics.h.

1093

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeed1_5GigabitKey

This key defines the value of 1.5 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 1.5 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>1.5 Gigabit</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed1GigabitKey

This key defines the value of 1 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 1 Gigabit per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>1 Gigabit</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1094

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeed2GigabitKey

This key defines the value of 2 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 2 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>2 Gigabit</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed3GigabitKey

This key defines the value of 3 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 3 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>3 Gigabit</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

1095

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeed40GigabitKey

This key defines the value of 40 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 40 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>40 Gigabit</string> </dict> </dict>

Available in OS X v10.8 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed4GigabitKey

This key defines the value of 4 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 4 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>4 Gigabit</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1096

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeed6GigabitKey

This key defines the value of 6 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 6 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>6 Gigabit</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeed8GigabitKey

This key defines the value of 8 Gigabit for the key kIOPropertyPortSpeedKey. If the speed of the port is 8 Gigabits per second and is not automatically determined (i.e. the user configured the port to be exactly this speed), this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>8 Gigabit</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

1097

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeedAutomatic10GigabitKey

This key defines the value of Automatic (10 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 10 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (10 Gigabit)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeedAutomatic1_5GigabitKey

This key defines the value of Automatic (1.5 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 1.5 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (1.5 Gigabit)</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

1098

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeedAutomatic1GigabitKey

This key defines the value of Automatic (1 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 1 Gigabit per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (1 Gigabit)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeedAutomatic2GigabitKey

This key defines the value of Automatic (2 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 2 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (2 Gigabit)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1099

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeedAutomatic3GigabitKey

This key defines the value of Automatic (3 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 3 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (3 Gigabit)</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeedAutomatic4GigabitKey

This key defines the value of Automatic (4 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 4 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (4 Gigabit)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1100

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeedAutomatic6GigabitKey

This key defines the value of Automatic (6 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 6 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (6 Gigabit)</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeedAutomatic8GigabitKey

This key defines the value of Automatic (8 Gigabit) for the key kIOPropertyPortSpeedKey. If the speed of the port is 8 Gigabits per second and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (8 Gigabit)</string> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

1101

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortSpeedAutomaticKey

This key defines the value of Automatic for the key kIOPropertyPortSpeedKey. If the speed of the port is automatically adjusted by the host/device and a definitive speed is not known, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortSpeedKey

This key is associated with the current port speed. The port speed can be any valid speed for the interconnect. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Speed</key> <string>Automatic (1 Gigabit)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1102

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortStatusKey

This key is associated with the current port status of the physical link. The port status is either "Link Established", "No Link Established", or "Link Failed". Note: This value can change when the port status changes. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Status</key> <string>Link Established</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortStatusLinkEstablishedKey

This key defines the value of Link Established for the key kIOPropertyPortStatusKey. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Status</key> <string>Link Established</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1103

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortStatusLinkFailedKey

This key defines the value of Link Failed for the key kIOPropertyPortStatusKey. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Status</key> <string>Link Failed</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortStatusNoLinkEstablishedKey

This key defines the value of No Link Established for the key kIOPropertyPortStatusKey. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Status</key> <string>No Link Established</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1104

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortTopologyAutomaticKey

This key defines the value of Automatic for the key kIOPropertyPortTopologyKey. If the topology of the port is automatically adjusted by the host/device and a definitive topology is not known, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>Automatic</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortTopologyAutomaticNLPortKey

This key defines the value of Automatic (NL_Port) for the key kIOPropertyPortTopologyKey. If the topology of the port is NL_Port and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>Automatic (NL_Port)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1105

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortTopologyAutomaticNPortKey

This key defines the value of Automatic (N_Port) for the key kIOPropertyPortTopologyKey. If the topology of the port is N_Port and is automatically determined by host software, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>Automatic (N_Port)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortTopologyKey

This key is associated with the current port topology. The port topology can be any valid topology for the interconnect. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>Automatic (N_Port)</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1106

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyPortTopologyNLPortKey

This key defines the value of NL_Port for the key kIOPropertyPortTopologyKey. If the topology of the port is an NL_Port, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>NL_Port</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertyPortTopologyNPortKey

This key defines the value of N_Port for the key kIOPropertyPortTopologyKey. If the topology of the port is an N_Port, this key should be used. Note: This value can change. It is not a static value. Requirement: Optional for any interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>Port Topology</key> <string>N_Port</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1107

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertyProtocolCharacteristicsKey

This key is used to define Protocol Characteristics for a particular protocol and it has an associated dictionary which lists the protocol characteristics. Requirement: Mandatory Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>ATAPI</string> <key>Physical Interconnect Location</key> <string>Internal</string> </dict> </dict>

Available in OS X v10.1 and later. Declared in IOStorageProtocolCharacteristics.h.

1108

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySASAddressKey

This key is the unique 64-bit SAS Address for the device server node located at this port, or for the initiating host port. Requirement: Mandatory for SAS. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>SAS</string> <key>Physical Interconnect Location</key> <string>External</string> <key>SAS Address</key> <data>0011223344556677</data> </dict> </dict>

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>SAS Address</key> <data>0011223344556677</data> </dict> </dict>

Available in OS X v10.4 and later. Declared in IOStorageProtocolCharacteristics.h.

1109

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSIDomainIdentifierKey

An identifier that will uniquely identify this SCSI Domain for the Physical Interconnect type. This identifier is only guaranteed to be unique for any given Physical Interconnect and is not guaranteed to be the same across restarts or shutdowns. Requirement: Mandatory for SCSI Parallel Interface and Fibre Channel Interface. Example:

Available in OS X v10.2 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertySCSIInitiatorIdentifierKey

An identifier that will uniquely identify this SCSI Initiator for the SCSI Domain. Requirement: Mandatory for SCSI Parallel Interface, SAS, and Fibre Channel Interface. Example:

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1110

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSILogicalUnitNumberKey

This key is the SCSI Logical Unit Number for the device server controlled by the driver. Requirement: Mandatory for SCSI Parallel Interface, SAS, and Fibre Channel Interface. Example:

Available in OS X v10.2 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertySCSIParallelSignalingTypeHVDKey

This key defines the value of High Voltage Differential for the key kIOPropertySCSIParallelSignalingTypeKey. If the signaling type of the port is High Voltage Differential, this key should be used. Requirement: Optional for SCSI Parallel Interface interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>SCSI Parallel Signaling Type</key> <string>High Voltage Differential</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1111

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSIParallelSignalingTypeKey

This key is associated with the signaling type used for this SCSI Parallel bus. Valid values include "High Voltage Differential", "Low Voltage Differential", and "Single Ended". Requirement: Optional for SCSI Parallel Interface. Not defined for any other physical interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>SCSI Parallel Signaling Type</key> <string>High Voltage Differential</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertySCSIParallelSignalingTypeLVDKey

This key defines the value of Low Voltage Differential for the key kIOPropertySCSIParallelSignalingTypeKey. If the signaling type of the port is Low Voltage Differential, this key should be used. Requirement: Optional for SCSI Parallel Interface interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>SCSI Parallel Signaling Type</key> <string>Low Voltage Differential</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1112

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSIParallelSignalingTypeSEKey

This key defines the value of Single Ended for the key kIOPropertySCSIParallelSignalingTypeKey. If the signaling type of the port is Single Ended, this key should be used. Requirement: Optional for SCSI Parallel Interface interconnect. Example:

<dict> <key>Controller Characteristics</key> <dict> <key>SCSI Parallel Signaling Type</key> <string>Single Ended</string> </dict> </dict>

Available in OS X v10.3 and later. Declared in IOStorageProtocolCharacteristics.h.

1113

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSIPortIdentifierKey

This key is the unique port identifier for the device server node located at this port, or for the initiating host port. The format for this data is allowed to be vendor-specific, as long as it is guaranteed to be unique. Length is arbitrary, to allow for itnerfaces with non-standard identifier rules. It is recommended to have this be a copy of an existing standard unique identifier for this port, should one already exist for your interface type Requirement: Mandatory. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Fibre Channel Interface</string> <key>Physical Interconnect Location</key> <string>External</string> <key>Node World Wide Name</key> <data>0011223344556677</data> <key>Unique SCSI Port Identifier</key> <data>0011223344556677</data> </dict> </dict>

Example2:

<dict> <key>Controller Characteristics</key> <dict> <key>Unique SCSI Port Identifier</key> <data>0011223344556677</data> </dict> </dict>

Available in OS X v10.7 and later. Declared in IOStorageProtocolCharacteristics.h.

1114

IOStorageProtocolCharacteristics.h User-Space Reference Constants

kIOPropertySCSIProtocolMultiInitKey

This protocol characteristics key is used to inform the system that the protocol supports having multiple devices that act as initiators. Requirement: Optional. Example:

<dict> <key>Protocol Characteristics</key> <dict> <key>Physical Interconnect</key> <string>Fibre Channel Interface</string> <key>Physical Interconnect Location</key> <string>External</string> <key>Multiple Initiators</key> <string>True</string> </dict> </dict>

Available in OS X v10.2 and later. Declared in IOStorageProtocolCharacteristics.h.

kIOPropertySCSITargetIdentifierKey

This is the SCSI Target Identifier for a given SCSI Target Device. Requirement: Mandatory for SCSI Parallel Interface and Fibre Channel Interface. Example:

Available in OS X v10.2 and later. Declared in IOStorageProtocolCharacteristics.h.

1115

IOStreamLib.h Reference

Declared in

IOStreamLib.h

Overview
IOCFPlugin library for using IOStream objects. The IOStream plugin provides a convenient set of functions for accessing and manipulating IOStream objects from user programs.

Included Headers

<sys/cdefs.h> <IOKit/IOKitLib.h> <IOKit/IOCFPlugIn.h> <CoreFoundation/CoreFoundation.h> <IOKit/stream/IOStreamShared.h>

Functions by Task
See the Overview for header-level documentation.

Run loop operations

AddToRunLoop (page 1119)

Add the CFRunLoopSource for the notification port to a run loop.

GetRunLoopSource (page 1125)

Gets a CFRunLoopSource for the CFMachPort used for notifications from the kernel that data is ready.
RemoveFromRunLoop (page 1126)

Remove the CFRunLoopSource for the notification port from a run loop.

1116

IOStreamLib.h Reference Functions by Task

Opening and closing streams

Close (page 1119)

Closes an IOStream.
Open (page 1126)

Open an IOStream from user space.

Notifications
SendInputNotification (page 1127)

Send a notification to the kernel side of the IOStream that data is available in the input queue.
SendInputSyncNotification (page 1127)

Notify the kernel side of the stream that input is ready by using a fast trap to call directly into the stream user client driver. This will transfer control to the kernel and continue executing on your same thread, rather than sending the notification to a separate thread.

Input and output

GetInputPort (page 1124)

Get the notification port for buffers moving in from user to kernel space.
GetInputQueue (page 1124)

Get the shared memory queue for buffers moving in from user to kernel space.
GetOutputPort (page 1124)

Get the notification port for buffers moving out from kernel to user space.
GetOutputQueue (page 1125)

Get the shared memory queue for buffers moving out from kernel to user space.
SetOutputCallback (page 1128)

Set the callback function to be called when a new buffer is available from the kernel.

Buffer operations on streams

DequeueOutputEntry (page 1119)

Get the next IOStreamBufferQueueEntry available from the output queue.

EnqueueInputBuffer (page 1120)

Send a buffer to the kernel side of the IOStream on the input queue.

1117

IOStreamLib.h Reference Functions by Task

EnqueueInputEntry (page 1121)

Buffer information
GetBufferCount (page 1121)

Gets the number of buffers in the stream.

GetBufferInfo (page 1121)

Gets information about a buffer in an IOStream.

Buffer convenience functions

GetControlBuffer (page 1122)

Get a pointer to the control area of an IOStreamBuffer.

GetControlBufferLength (page 1122)

Get the length of the control area of an IOStreamBuffer.

GetDataBuffer (page 1123)

Get a pointer to the data area of an IOStreamBuffer.

GetDataBufferLength (page 1123)

Get the length of the data area of an IOStreamBuffer.

GetMode (page 1124)

SetMode (page 1128)

StartStream (page 1128)

StopStream (page 1128)

SuspendStream (page 1128)

1118

IOStreamLib.h Reference Functions

EnqueueInputBuffer
Send a buffer to the kernel side of the IOStream on the input queue.

IOReturn ( *EnqueueInputBuffer)( IOStreamRef stream, IOStreamBufferID bufferID, IOByteCount dataOffset, IOByteCount dataLength, IOByteCount controlOffset, IOByteCount controlLength );

Parameters
stream

The IOStreamRef of the stream to operate on.

bufferID

The IOStreamBufferID of the buffer to place on the queue.

dataLength

The length of the valid data in the buffer. Return Value Returns kIOReturnSuccess if the buffer was successfully placed on the input queue.

1120

IOStreamLib.h Reference Functions

EnqueueInputEntry

IOReturn ( EnqueueInputEntry)( IOStreamRef stream, IOStreamBufferQueueEntry entry);

GetBufferCount
Gets the number of buffers in the stream.

IOItemCount ( *GetBufferCount)( IOStreamRef stream );

Parameters
stream

The IOStreamRef of the stream to operate on. Return Value Returns then number of buffers in the stream.

GetBufferInfo
Gets information about a buffer in an IOStream.

IOReturn ( *GetBufferInfo)( IOStreamRef stream, IOStreamBufferID bufferID, void **dataBufferAddressOut, IOByteCount *dataBufferSizeOut, void **controlBufferAddressOut, IOByteCount *controlBufferSizeOut );

Parameters
stream

The IOStreamRef of the stream to operate on.

1121

IOStreamLib.h Reference Functions

bufferID dataBufferAddressOut dataBufferSizeOut controlBufferAddressOut controlBufferSizeOut

Return Value Returns kIOReturnSuccess if the buffer ID was valid.

GetControlBuffer
Get a pointer to the control area of an IOStreamBuffer.

void ( GetControlBuffer)( IOStreamRef stream, IOStreamBufferID bufferID );

Parameters
stream

The IOStreamRef of the stream owning the buffer.

bufferID

The IOStreamBufferID of the buffer to operate on. Return Value A pointer to the control buffer area of the IOStreamBuffer, or NULL if it does not have a control buffer.

GetControlBufferLength
Get the length of the control area of an IOStreamBuffer.

IOByteCount ( *GetControlBufferLength)( IOStreamRef stream, IOStreamBufferID bufferID );

Parameters
stream

The IOStreamRef of the stream owning the buffer.

bufferID

The IOStreamBufferID of the buffer to operate on.

1122

IOStreamLib.h Reference Functions

Return Value The length in bytes of the control buffer, or 0 if there is no control buffer.

GetDataBuffer
Get a pointer to the data area of an IOStreamBuffer.

void ( GetDataBuffer)( IOStreamRef stream, IOStreamBufferID bufferID );

Parameters
stream

The IOStreamRef of the stream owning the buffer.

bufferID

The IOStreamBufferID of the buffer to operate on. Return Value A pointer to the data buffer area of the IOStreamBuffer, or NULL if it does not have a data buffer.

GetDataBufferLength
Get the length of the data area of an IOStreamBuffer.

IOByteCount ( *GetDataBufferLength)( IOStreamRef stream, IOStreamBufferID bufferID );

Parameters
stream

The IOStreamRef of the stream owning the buffer.

bufferID

The IOStreamBufferID of the buffer to operate on. Return Value The length in bytes of the data buffer, or 0 if there is no data buffer.

1123

IOStreamLib.h Reference Functions

RemoveFromRunLoop
Remove the CFRunLoopSource for the notification port from a run loop.

IOReturn ( *RemoveFromRunLoop)( IOStreamRef stream, CFRunLoopRef runLoop );

Parameters
stream

The IOStreamRef of the stream to operate on.

runLoop

The run loop from which to remove the notification source. Return Value Returns kIOReturnSuccess if the source was successfully removed from the run loop.

1126

IOStreamLib.h Reference Functions

SendInputNotification
Send a notification to the kernel side of the IOStream that data is available in the input queue.

IOReturn ( *SendInputNotification)( IOStreamRef stream, UInt32 token );

Parameters
stream

The IOStreamRef of the stream to operate on.

token

A value to pass to the stream's notification function. This is unused by IOStream but may be used by subclasses. Return Value Returns kIOReturnSuccess if the notification was successfully sent.

SendInputSyncNotification
Notify the kernel side of the stream that input is ready by using a fast trap to call directly into the stream user client driver. This will transfer control to the kernel and continue executing on your same thread, rather than sending the notification to a separate thread.

IOReturn ( *SendInputSyncNotification)( IOStreamRef stream, UInt32 token );

Parameters
stream

The IOStreamRef of the stream to operate on.

token

A value to pass to the stream's notification function. This is unused by IOStream but may be used by subclasses. Return Value Returns kIOReturnSuccess if the notification was successfully sent.

1127

IOStreamLib.h Reference Functions

SetMode

IOReturn ( *SetMode)( IOStreamRef stream, IOStreamMode mode );

SetOutputCallback
Set the callback function to be called when a new buffer is available from the kernel.

IOReturn ( SetOutputCallback)( IOStreamRef stream, IOStreamOutputCallback callback, void context );

Parameters
stream

The IOStreamRef of the stream to operate on. Pass NULL to remove the callback. Return Value Returns kIOReturnSuccess if the callback was successfully set or removed.

StartStream

IOReturn ( *StartStream)( IOStreamRef stream );

StopStream

IOReturn ( *StopStream)( IOStreamRef stream );

SuspendStream

IOReturn ( *SuspendStream)( IOStreamRef stream );

1128

IOStreamLib.h Reference Callbacks

Callbacks
See the Overview for header-level documentation.

IOStreamCallback

typedef void ( IOStreamOutputCallback) ( IOStreamRef stream, void context );

See Also
IOStreamOutputCallback (page 1129)

IOStreamOutputCallback

typedef void ( IOStreamOutputCallback) ( IOStreamRef stream, void context );

Availability Available in OS X v10.5 and later. See Also

IOStreamCallback

Declared in
IOStreamLib.h

Data Types
See the Overview for header-level documentation.

IOStreamRef

typedef struct IOStreamInterface_v1_t ** IOStreamRef;

Availability Available in OS X v10.5 and later.

1129

IOStreamLib.h Reference Data Types

Declared in
IOStreamLib.h

1130

IOStreamShared.h User-Space Reference

Declared in

IOStreamShared.h

Overview
IOStream definitions shared between kernel and user space.

Included Headers

Data Types
See the Overview for header-level documentation.

IOStreamBufferID

typedef UInt32 IOStreamBufferID;

Availability Available in OS X v10.5 and later. Declared in

IOStreamShared.h

IOStreamBufferQueue

struct IOStreamBufferQueue { UInt32 entryCount; volatile UInt32 headIndex;

1131

IOStreamShared.h User-Space Reference Data Types

volatile UInt32 tailIndex; UInt32 reserved; IOStreamBufferQueueEntry queue[0]; };

Fields
entryCount

The number of queue entries in the queue.

headIndex

The index of the next queue slot that will be filled in by the queue writer.
tailIndex

The index of the next queue slot that can be read by the queue reader.
reserved

Reserved for future use.

queue

The array of queue entries.

IOStreamBufferQueueEntry

struct IOStreamBufferQueueEntry { IOStreamBufferID bufferID; UInt32 dataOffset; UInt32 dataLength; UInt32 controlOffset; UInt32 controlLength; UInt32 reserved[3]; };

Fields
bufferID

The ID of the buffer passed in this queue entry.

dataLength

The length of the valid data in the buffer.

reserved

Reserved for future use.

1132

IOStreamShared.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

IOStream open options

enum { kIOStreamOptionOpenExclusive = 0x00010000, kIOStreamOptionOpenShared = 0x00020000 };

Mach port types

Port types used with IOConnectSetNotificationPort().

enum { kIOStreamPortTypeOutput, kIOStreamPortTypeInput };

Constants
kIOStreamPortTypeOutput

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamPortTypeInput

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

Memory mapping types

Memory types used with IOConnectMapMemory().

enum { kIOStreamMemoryTypeOutputQueue = 0x10000000, kIOStreamMemoryTypeInputQueue = 0x20000000, kIOStreamMemoryTypeBufferData = 0x30000000, kIOStreamMemoryTypeBufferControl = 0x40000000, kIOStreamBufferIDMask = 0x0FFFFFFF, kIOStreamMemoryTypeMask = 0xF0000000 };

1133

IOStreamShared.h User-Space Reference Constants

Constants
kIOStreamMemoryTypeOutputQueue

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMemoryTypeInputQueue

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMemoryTypeBufferData

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMemoryTypeBufferControl

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamBufferIDMask

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMemoryTypeMask

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

User client methods

Client method numbers used with IOConnectMethod...() functions.

enum { kIOStreamMethodOpen, kIOStreamMethodClose, kIOStreamMethodStart, kIOStreamMethodStop, kIOStreamMethodSuspend, kIOStreamMethodGetMode, kIOStreamMethodSetMode, kIOStreamMethodGetBufferCount };

Constants
kIOStreamMethodOpen

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

1134

IOStreamShared.h User-Space Reference Constants

kIOStreamMethodClose

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMethodStart

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMethodStop

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMethodSuspend

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMethodGetMode

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamMethodSetMode

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

User client traps

Client trap numbers used with IOConnectTrap..() functions.

enum { kIOStreamEnqueueInputTrap, kIOStreamEnqueueInputSyncTrap };

Constants
kIOStreamEnqueueInputTrap

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

kIOStreamEnqueueInputSyncTrap

Available in OS X v10.5 and later. Declared in IOStreamShared.h.

1135

IOTypes.h User-Space Reference

Declared in

IOTypes.h

Overview
Included Headers

<mach/message.h> <mach/vm_types.h> <IOKit/IOReturn.h> <stdbool.h> <libkern/OSTypes.h> <device/device_types.h>

Constants
See the Overview for header-level documentation.

Scale Factors

enum { kNanosecondScale = 1, kMicrosecondScale = 1000, kMillisecondScale = 1000 * 1000, kSecondScale = 1000 * 1000 * 1000, kTickScale = ( kSecondScale / 100) };

1136

IOTypes.h User-Space Reference Constants

Constants
kNanosecondScale

Scale factor for nanosecond based times. Available in OS X v10.0 and later. Declared in IOTypes.h.
kMicrosecondScale

Scale factor for microsecond based times. Available in OS X v10.0 and later. Declared in IOTypes.h.
kMillisecondScale

Scale factor for millisecond based times. Available in OS X v10.0 and later. Declared in IOTypes.h.
kTickScale

Scale factor for the standard (100Hz) tick. Available in OS X v10.4 and later. Declared in IOTypes.h.
kSecondScale

Scale factor for second based times. Available in OS X v10.0 and later. Declared in IOTypes.h. Discussion Used when a scale_factor parameter is required to define a unit of time.

1137

IOUPSPlugIn.h Reference

Declared in

IOUPSPlugIn.h

Overview
IOUPSPlugIn.h is the header that defines the software used by ioupsd in user-space to communicate with UPS devices. NOTE: Kernel extensions should have the following key/value pair in their personality in order to be recognized by ioupsd:

<key>UPSDevice<key> <true/>

To communicate with a UPS device, an instance of IOUPSPlugInInterface (a struct which is defined below) is created. The methods of IOUPSPlugInInterface allow ioupsd to communicate with the device. To obtain an IOUPSPlugInInterface for a UPS device, use the function IOCreatePlugInInterfaceForService() defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is always upper-case.) Quick usage reference:

'service' is a reference to the IOKit registry entry of the kernel object (usually of type IOHIDDevice) representing the device of interest. This reference can be obtained using the functions defined in IOKit/IOKitLib.h. 'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID) 'interfaceType' should be CFUUIDGetUUIDBytes(kIOUPSPlugInTypeID) when using IOUPSPlugIn

The interface returned by IOCreatePlugInInterfaceForService() should be deallocated using IODestroyPlugInInterface(). Do not call Release() on it.

1138

IOUPSPlugIn.h Reference Callbacks

Included Headers

Callbacks
See the Overview for header-level documentation.

IOUPSEventCallbackFunction

typedef void ( *IOUPSEventCallbackFunction) ( void *target, IOReturn result, void *refcon, void *sender, CFDictionaryRef event);

Parameters
target

void * pointer to your data, often a pointer to an object.

result

Completion result of desired operation.

refcon

void * pointer to more data.

sender

Interface instance sending the completion routine.

event

CFDictionaryRef containing event data. Discussion Type and arguments of callout C function that is used when a completion routine is called. This function pointer is set via setEventCallback and is called when an event is available from the UPS. Availability Available in OS X v10.3 and later. Declared in
IOUPSPlugIn.h

1139

IOUPSPlugIn.h Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define kIOUPSPlugInInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x63, 0xf8, 0xbf, 0xc4, 0x26, 0xa0, 0x11, 0xd8, \ 0x88, 0xb4, 0x0, 0xa, 0x95, 0x8a, 0x2c, 0x78) #define kIOUPSPlugInInterfaceID_v140 CFUUIDGetConstantUUIDWithBytes(NULL, \ 0xe6, 0xe, 0x7, 0x99, 0x9a, 0xa6, 0x49, 0xdf, \ 0xb5, 0x5b, 0xa5, 0xc9, 0x4b, 0xa0, 0x7a, 0x4a) #define kIOUPSPlugInTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \

1140

IOUPSPlugIn.h Reference Constants

0x40, 0xa5, 0x7a, 0x4e, 0x26, 0xa0, 0x11, 0xd8, \ 0x92, 0x95, 0x00, 0x0a, 0x95, 0x8a, 0x2c, 0x78)

Constants
kIOUPSPlugInInterfaceID

Interface ID for the IOUPSPlugInInterface. Corresponds to an available UPS device. Available in OS X v10.3 and later. Declared in IOUPSPlugIn.h.
kIOUPSPlugInInterfaceID_v140

Interface ID for the IOUPSPlugInInterface. Corresponds to an available UPS device. Available in OS X v10.4 and later. Declared in IOUPSPlugIn.h.
kIOUPSPlugInTypeID

Type ID for the IOUPSPlugInInterface. Corresponds to an available UPS device. Available in OS X v10.3 and later. Declared in IOUPSPlugIn.h.

1141

IOUSBLib.h Reference

Declared in

IOUSBLib.h

Overview
This documentation describes the details of the programming interface for accessing USB devices and USB interfaces from code running in user space. This documentation assumes that you have a basic understanding of the material contained in Accessing Hardware From Applications For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts in the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications . This documentation also assumes you have read Working With USB Device Interfaces . Please review that document before using this reference. All of the information described in this document is contained in the header file IOUSBLib.h found at /System/Library/Frameworks/IOKit.framework/Headers/usb/IOUSBLib.h.

Included Headers

<IOKit/usb/USB.h> <IOKit/IOKitLib.h> <CoreFoundation/CFRunLoop.h> <CoreFoundation/CFPlugIn.h> <CoreFoundation/CFPlugInCOM.h> <sys/cdefs.h>

Functions
See the Overview for header-level documentation.

1142

IOUSBLib.h Reference Functions

FindNextAltInterface

IOUSBDescriptorHeader * ( FindNextAltInterface)( void self, const void current, IOUSBFindInterfaceRequest request);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

current

interface descriptor to start searching from, NULL to start at alternate interface 0.

request

specifies what properties an interface must have to match. Return Value Pointer to a matching interface descriptor, or NULL if none match. Discussion return alternate interface descriptor satisfying the requirements specified in request, or NULL if there aren't any. discussion request is updated with the properties of the returned interface.

FindNextAssociatedDescriptor
Find the next descriptor of the requested type associated with the interface.

IOUSBDescriptorHeader * ( FindNextAssociatedDescriptor)( void self, const void *currentDescriptor, UInt8 descriptorType);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

currentDescriptor

Descriptor to start searching from, NULL to start from beginning of list.

descriptorType

Descriptor type to search for, or kUSBAnyDesc to return any descriptor type.

1143

IOUSBLib.h Reference Functions

Return Value Pointer to the descriptor, or NULL if no matching descriptors found. Discussion The interface does not have to be open to use this function.

GetBusFrameNumberWithTime
Gets a recent frame number of the bus to which the device is attached, along with a system time corresponding to the start of that frame

IOReturn ( GetBusFrameNumberWithTime)( void self, UInt64 frame, AbsoluteTime atTime);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

frame

Pointer to UInt64 to hold the frame number.

atTime

GetPipePropertiesV2
Gets the properties for a pipe, including the USB SuperSpeed endpoint companion properties.

IOReturn ( GetPipePropertiesV2)( void self, UInt8 pipeRef,

1144

IOUSBLib.h Reference Functions

UInt8 *direction, UInt8 *number, UInt8 *transferType, UInt16 *maxPacketSize, UInt8 *interval, UInt8 *maxBurst, UInt8 *mult, UInt16 *bytesPerInterval);

Parameters
self

Pointer to the IOUSBInterfaceInterface.

pipeRef

Index for the desired pipe (1 - GetNumEndpoints).

direction

Pointer to an UInt8 to get the direction of the pipe.

number

Pointer to an UInt8 to get the pipe number.

transferType

Pointer to an UInt8 to get the transfer type of the pipe.

maxPacketSize

Pointer to an UInt16 to get the maxPacketSize of the pipe.

interval

Pointer to an UInt8 to get the interval for polling the pipe for data (in milliseconds).
maxBurst

Pointer to an UInt8 to get the bMaxBurst value of the SuperSpeed Endpoint Companion descriptor
mult

Pointer to an UInt8 to get the mult value of the bmAttributes field of the SuperSpeed Endpoint Companion descriptor, valid only for an isochronous endpoint
bytesPerInterval

Pointer to an UInt16 to get the wBytesPerInterval value of the SuperSpeed Endpoint Companion descriptor, valid only for periodic endpoints Return Value Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, or kIOReturnNotOpen if the interface is not open for exclusive access.

1145

IOUSBLib.h Reference Constants

Discussion Once an interface is opened, all of the pipes in that interface get created by the kernel. The number of pipes can be retrieved by GetNumEndpoints. The client can then get the properties of any pipe using an index of 1 to GetNumEndpoints. Pipe 0 is the default control pipe in the device.

Constants
See the Overview for header-level documentation.

Defines

1162

IOUSBLib.h Reference Constants

kIOUSBDeviceUserClientTypeID

This UUID constant is used to obtain a device interface corresponding to an io_service_t corresponding to an IOUSBDevice in the kernel. Once you have obtained the device interface for the service, you must use the QueryInterface function to obtain the device interface for the user client itself. Example:

io_service_t IOCFPlugInInterface SInt32 IOReturn

usbDeviceRef; **iodev; score; err;

// obtained earlier // fetching this now // not used

err = IOCreatePlugInInterfaceForService(usbDeviceRef, kIOUSBDeviceUserClientTypeID, kIOCFPlugInInterfaceID, &iodev, &score);

Available in OS X v10.0 and later. Declared in IOUSBLib.h.

kIOUSBFactoryID

This UUID constant is used internally by the system, and should not have to be used by any driver code to access the device interfaces. Available in OS X v10.0 and later. Declared in IOUSBLib.h.

1163

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface is returned by all versions of the IOUSBFamily currently shipping. However, there are some functions which are available only in IOUSBFamily version 1.8.2 and above. Access to these functions, as well as to all of the functions contained in IOUSBInterfaceInterface, can be obtained by using one of the other UUIDs listed in this header. Example:

IOCFPluginInterface

**iodev;

// obtained earlier

IOUSBInterfaceInterface **intf; // fetching this now IOReturn err; err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID), (LPVoid)&intf);

Available in OS X v10.0 and later. Declared in IOUSBLib.h.

1164

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID182

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface182. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface182 is returned only by version 1.8.2 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.0.4. If your software is running on an earlier version of OS X, you will need to use the UUID kIOUSBInterfaceInterfaceID and you will not have access to some functions. Example:

IOCFPluginInterface

**iodev;

// obtained earlier

IOUSBInterfaceInterface182 **intf; IOReturn err;

// fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID182), (LPVoid)&intf);

Available in OS X v10.1 and later. Declared in IOUSBLib.h.

1165

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID183

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface183. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface183 is returned only by version 1.8.3 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.1. If your software is running on a version of OS X prior to 10.1 you will need to use the UUID kIOUSBInterfaceInterfaceID or kIOUSBInterfaceInterfaceID182 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface183 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID183), (LPVoid)&intf);

Available in OS X v10.1 and later. Declared in IOUSBLib.h.

1166

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID190

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface190. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface190 is returned only by version 1.9 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.2. If your software is running on a version of OS X prior to 10.2 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, or kIOUSBInterfaceInterfaceID183 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface190 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID190), (LPVoid)&intf);

Available in OS X v10.2 and later. Declared in IOUSBLib.h.

1167

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID192

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface192. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface192 is returned only by version 1.9.2 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.2.3. If your software is running on a version of OS X prior to 10.2.3 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, or kIOUSBInterfaceInterfaceID190 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface192 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID192), (LPVoid)&intf);

Available in OS X v10.2 and later. Declared in IOUSBLib.h.

1168

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID197

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface197. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface197 is returned only by version 1.9.7 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.2.5. If your software is running on a version of OS X prior to 10.2.5 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, or kIOUSBInterfaceInterfaceID192 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface197 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID197), (LPVoid)&intf);

Available in OS X v10.2 and later. Declared in IOUSBLib.h.

1169

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID220

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface197. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface220 is returned only by version 2.2.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.4. If your software is running on a version of OS X prior to 10.4 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, kIOUSBInterfaceInterfaceID192, or kIOUSBInterfaceInterfaceID197 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface220 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID220), (LPVoid)&intf);

Available in OS X v10.4 and later. Declared in IOUSBLib.h.

1170

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID245

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface245. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface245 is returned only by version 2.4.5 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.4.5. This version does not add any new functions. It is used to allow us to fix a leak in our termination without affecting any current drivers: In previous versions, we would not release a reference to the IOUSBDevice. For IOUSBInterfaceInterfaceID245 clients we will now release that reference. Example:

IOCFPluginInterface IOUSBInterfaceInterface245 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID245), (LPVoid)&intf);

Available in OS X v10.4 and later. Declared in IOUSBLib.h.

1171

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID300

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface300. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface300 is returned only by version 3.0.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.5. If your software is running on a version of OS X prior to 10.5 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, kIOUSBInterfaceInterfaceID192, kIOUSBInterfaceInterfaceID197, kIOUSBInterfaceInterfaceID220, or kIOUSBInterfaceInterfaceID245 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface300 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID300), (LPVoid)&intf);

Available in OS X v10.5 and later. Declared in IOUSBLib.h.

1172

IOUSBLib.h Reference Constants

kIOUSBInterfaceInterfaceID500

This UUID constant is used to obtain a device interface corresponding to an IOUSBInterface user client in the kernel. The type of this device interface is IOUSBInterfaceInterface500. This device interface is obtained after the device interface for the service itself has been obtained. Note: The IOUSBInterfaceInterface500 is returned only by version 5.0.0 or above of the IOUSBFamily. This version of IOUSBFamily shipped with OS X version 10.7.3. If your software is running on a version of OS X prior to 10.7.3 you will need to use the UUID kIOUSBInterfaceInterfaceID, kIOUSBInterfaceInterfaceID182, kIOUSBInterfaceInterfaceID183, kIOUSBInterfaceInterfaceID190, kIOUSBInterfaceInterfaceID192, kIOUSBInterfaceInterfaceID197, kIOUSBInterfaceInterfaceID220, kIOUSBInterfaceInterfaceID245, or kIOUSBInterfaceInterfaceID300 and you will not have access to some functions. Example:

IOCFPluginInterface IOUSBInterfaceInterface500 IOReturn

iodev; intf; err;

// obtained earlier // fetching this now

err = (*iodev)->QueryInterface(iodev, CFUUIDGetUUIDBytes(kIOUSBInterfaceInterfaceID500), (LPVoid)&intf);

Available in OS X v10.8 and later. Declared in IOUSBLib.h.

1173

IOUSBLib.h Reference Constants

kIOUSBInterfaceUserClientTypeID

This UUID constant is used to obtain a device interface corresponding to an io_service_t corresponding to an IOUSBInterface in the kernel. Once you have obtained the device interface for the service, you must use the QueryInterface function to obtain the device interface for the user client itself. Example:

io_service_t

usbInterfaceRef; // obtained earlier // fetching this now // not used

IOCFPlugInInterface **iodev; SInt32 IOReturn score; err;

err = IOCreatePlugInInterfaceForService(usbInterfaceRef, kIOUSBInterfaceUserClientTypeID, kIOCFPlugInInterfaceID, &iodev, &score);

Available in OS X v10.0 and later. Declared in IOUSBLib.h.

1174

IOVideoDeviceLib.h User-Space Reference

Declared in

IOVideoDeviceLib.h

Overview
Included Headers

<CoreFoundation/CoreFoundation.h> <IOKit/IOKitLib.h> <IOKit/IOCFPlugIn.h> <IOKit/stream/IOStreamLib.h> <IOKit/stream/IOStreamShared.h> <IOKit/video/IOVideoDeviceShared.h> <IOKit/video/IOVideoTypes.h>

Functions
See the Overview for header-level documentation.

AddToRunLoop
Add the CFRunLoopSource for the notification port to a run loop.

IOReturn ( *AddToRunLoop)( IOVideoDeviceRef device, CFRunLoopRef runLoop);

GetRunLoopSource
Gets a CFRunLoopSource for the CFMachPort used for notifications from the kernel that data is ready.

CFRunLoopSourceRef ( *GetRunLoopSource)( IOVideoDeviceRef device);

Parameters
device

The IOVideoDeviceRef of the stream to operate on. Return Value The CFRunLoopSourceRef for the run loop source, or NULL if there was an error creating the source.

1178

IOVideoDeviceLib.h User-Space Reference Functions

runLoop

The run loop from which to remove the notification source. Return Value Returns kIOReturnSuccess if the source was successfully removed from the run loop.

SetControlValue

IOReturn ( *SetControlValue)( IOVideoDeviceRef device, UInt32 controlID, UInt32 value, UInt32 *newValue);

Parameters
device controlID newValue

Return Value Returns kIOReturnSuccess if the call was successfully. Availability Available in OS X v10.0 and later. Not available to 64-bit applications. Declared in
Controls.h

SetNotificationCallback
Set the callback function to be called when certain device state changes happen.

IOReturn ( SetNotificationCallback)( IOVideoDeviceRef device, IOVideoDeviceNotificationCallback callback, void context);

1179

IOVideoDeviceLib.h User-Space Reference Callbacks

Parameters
device

The IOVideoDeviceRef of the device to operate on. Pass NULL to remove the callback. Return Value Returns kIOReturnSuccess if the callback was successfully set or removed.

SetStreamFormat

IOReturn ( SetStreamFormat)( IOVideoDeviceRef device, UInt32 streamID, IOVideoStreamDescription streamFormat);

Parameters
device streamID streamFormat

Return Value Returns kIOReturnSuccess if the call was successfully.

Callbacks
See the Overview for header-level documentation.

IOVideoDeviceNotificationCallback

typedef void ( IOVideoDeviceNotificationCallback)( IOVideoDeviceRef device, void context, void *message);

Availability Available in OS X v10.7 and later. Declared in

IOVideoDeviceLib.h

1180

IOVideoDeviceLib.h User-Space Reference Data Types

IOVideoDeviceOutputCallback

typedef void ( IOVideoDeviceOutputCallback)( IOVideoDeviceRef stream, void context);

Availability Available in OS X v10.7 and later. Declared in

IOVideoDeviceLib.h

Data Types
See the Overview for header-level documentation.

IOVideoDeviceInterface_v1_t
Forward declaration of IOVideoDeviceInterface_v1_t.

typedef struct IOVideoDeviceInterface_v1_t IOVideoDeviceInterface_v1_t;

Availability Available in OS X v10.7 and later. Declared in

IOVideoDeviceLib.h

IOVideoDeviceRef

typedef IOVideoDeviceInterface_v1_t** IOVideoDeviceRef;

Availability Available in OS X v10.7 and later. Declared in

IOVideoDeviceLib.h

1181

IOVideoDeviceLib.h User-Space Reference Constants

Constants
See the Overview for header-level documentation.

Defines

#define kIOVideoDeviceInterfaceID_v1 CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault, 0x0D, 0xE0, 0x80, 0xE3, 0x51, 0x06, 0x4D, 0x16, 0xB7, 0x0C, 0xB3, 0x21, 0x6F, 0x13, 0xCD, 0xB9) #define kIOVideoDeviceLibTypeID CFUUIDGetConstantUUIDWithBytes(kCFAllocatorDefault, 0x53, 0x39, 0x63, 0x3C, 0xF9, 0x03, 0x42, 0x12, 0x9C, 0x90, 0x9B, 0x18, 0xAF, 0x01, 0x86, 0x2D)

1182

IOVideoDeviceLib.h User-Space Reference Constants

Constants
kIOVideoDeviceInterfaceID_v1

This is the UUID of version 1 of the plug-in interface (080E3-5106-4D16-B70C-B3216F13CDB9A). Available in OS X v10.7 and later. Declared in IOVideoDeviceLib.h.
kIOVideoDeviceLibTypeID

This is the UUID of the plug-in type (5339633C-F903-4212-9C90-9B18AF01862D). Available in OS X v10.7 and later. Declared in IOVideoDeviceLib.h.

1183

IOVideoDeviceShared.h User-Space Reference

Declared in

IOVideoDeviceShared.h

Overview
IOVideoDevice definitions shared between kernel and user space.

Included Headers

Constants
See the Overview for header-level documentation.

Mach
Port types used with IOConnectSetNotificationPort().

enum { kIOVideoDevicePortTypeNotification, kIOVideoDevicePortTypeOutput, kIOVideoDevicePortTypeInput };

Constants
kIOVideoDevicePortTypeNotification

Available in OS X v10.7 and later. Declared in IOVideoDeviceShared.h.

1184

IOVideoDeviceShared.h User-Space Reference Constants

kIOVideoDevicePortTypeOutput

Available in OS X v10.7 and later. Declared in IOVideoDeviceShared.h.

kIOVideoDevicePortTypeInput

Available in OS X v10.7 and later. Declared in IOVideoDeviceShared.h. Discussion port types

1185

IOVideoDeviceUserClient.h User-Space Reference

Declared in

IOVideoDeviceUserClient.h

Overview
Included Headers

<IOKit/IOUserClient.h> <IOKit/stream/IOStreamShared.h> <IOKit/video/IOVideoTypes.h>

Constants
See the Overview for header-level documentation.

User
Client method numbers used with IOConnectMethod...() functions.

enum { kIOVideoDeviceMethodOpen = 0, kIOVideoDeviceMethodClose, kIOVideoDeviceMethodGetMode, kIOVideoDeviceMethodSetMode, kIOVideoDeviceMethodSetControlValue, kIOVideoDeviceMethodOpenStream, kIOVideoDeviceMethodCloseStream, kIOVideoDeviceMethodSetStreamFormat, kIOVideoDeviceMethodStartStream, kIOVideoDeviceMethodStopStream, kIOVideoDeviceMethodSuspendStream, kIOVideoDeviceMethodCount };

1186

IOVideoDeviceUserClient.h User-Space Reference Constants

Constants
kIOVideoDeviceMethodOpen

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodClose

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodGetMode

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodSetControlValue

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodOpenStream

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodCloseStream

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodSetStreamFormat

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodStartStream

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodStopStream

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h.

kIOVideoDeviceMethodSuspendStream

Available in OS X v10.7 and later. Declared in IOVideoDeviceUserClient.h. Discussion client methods

1187

IOVideoTypes.h User-Space Reference

Declared in

IOVideoTypes.h

Overview
Included Headers

Data Types
See the Overview for header-level documentation.

IOVideoDeviceNotification
This structure contains an individual notification from the driver.

struct IOVideoDeviceNotification { UInt32 mObjectID; UInt32 mNotificationID; UInt32 mNotificationArgument1; UInt32 mNotificationArgument2; UInt64 mNotificationArgument3; UInt64 mNotificationArgument4; };

Fields
mObjectID

The ID of the object to which the notification pertains.

mNotificationID

A UInt32 that identifies the kind of the notification.

1188

IOVideoTypes.h User-Space Reference Data Types

mNotificationArgument1

A UInt32 whose usage depends on the the specific kind of notification.

mNotificationArgument2

A UInt32 whose usage depends on the the specific kind of notification.

mNotificationArgument3

A UInt64 whose usage depends on the the specific kind of notification.

mNotificationArgument4

A UInt64 whose usage depends on the the specific kind of notification. See Also
IOVideoNotification

IOVideoDeviceNotificationMessage
This structure describes a notification from the driver. Note that the message can contain multiple notifications.

struct IOVideoDeviceNotificationMessage { mach_msg_header_t mMessageHeader; UInt32 mClientData; UInt32 mNumberNotifications; IOVideoDeviceNotification mNotifications[1]; };

Fields
mMessageHeader

The mach message header.

mClientData

The client data that was registered with the mach port.
mNumberNotifications

The number of IOVideoNotifications in the mNotifications array.

mNotifications

A variable length array of IOVideoNotification structures that carry the actual notification data. The number of elements in this array is denoted by mNumberNotifications, but can also be inferred from the message size in the mach message header.

IOVideoNotification
This structure contains an individual notification from the driver.

1189

IOVideoTypes.h User-Space Reference Constants

Fields
mObjectID

The ID of the object to which the notification pertains.

mNotificationID

A UInt32 that identifies the kind of the notification.

mNotificationArgument1

A UInt32 whose usage depends on the the specific kind of notification.

mNotificationArgument2

A UInt32 whose usage depends on the the specific kind of notification.

mNotificationArgument3

A UInt64 whose usage depends on the the specific kind of notification.

mNotificationArgument4

A UInt64 whose usage depends on the the specific kind of notification. See Also
IOVideoDeviceNotification (page 1189)

Constants
See the Overview for header-level documentation.

Control
Various constants related to controls.

enum { kIOVideoControlScopeGlobal = 'glob', kIOVideoControlScopeInput = 'inpt', kIOVideoControlScopeOutput = 'outp', kIOVideoControlScopePlayThrough = 'ptru',

1190

IOVideoTypes.h User-Space Reference Constants

kIOVideoControlElementMaster = 0 };

Constants
kIOVideoControlScopeGlobal

The scope for controls that apply to the device as a whole. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlScopeInput

The scope for controls that apply to the input section of the device. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlScopeOutput

The scope for controls that apply to the output section of the device. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlScopePlayThrough

The scope for controls that apply to the play through section of the device. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlElementMaster

The element value for controls that apply to the master element or to the entire scope. Note that other elements are numbered consecutively starting from 1. Available in OS X v10.7 and later. Declared in IOVideoTypes.h. Discussion Constants

Control
The class IDs that identify the various control base classes.

enum { kIOVideoControlBaseClassIDBoolean = 'togl', kIOVideoControlBaseClassIDSelector = 'slct', kIOVideoControlBaseClassIDFeature = 'ftct' };

1191

IOVideoTypes.h User-Space Reference Constants

Constants
kIOVideoControlBaseClassIDBoolean

The class ID that identifies the boolean control class which is a subclass of the base control class. Boolean controls manipulate on/off switches in the hardware. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlBaseClassIDSelector

The class ID that identifies the selector control class which is a subclass of the base control class. Selector controls manipulate controls that have multiple, but discreet values. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoControlBaseClassIDFeature

The class ID that identifies the feature control class which is a subclass of the base control class. Feature controls manipulate various features that might be present on a device, such as hue, saturation, zoom, etc. Available in OS X v10.7 and later. Declared in IOVideoTypes.h. Discussion Base Class IDs

IOVideoBooleanControl
The four char codes that identify the various standard subclasses of IOVideoBooleanControl.

enum { kIOVideoBooleanControlClassIDJack = 'jack', kIOVideoBooleanControlClassIDDirection = 'dire' };

Constants
kIOVideoBooleanControlClassIDJack

A IOVideoBooleanControl where a true value means something is plugged into that element. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.

1192

IOVideoTypes.h User-Space Reference Constants

kIOVideoBooleanControlClassIDDirection

A IOVideoBooleanControl where a true value means the element is operating in input mode, and false means the element is operating in output mode. This control is only needed for devices which can do input and output, but not at the same time. Available in OS X v10.7 and later. Declared in IOVideoTypes.h. Discussion Subclass IDs

IOVideoFeatureControl Subclass IDs

The four char codes that identify the various standard subclasses of IOVideoFeatureControl.

enum { kIOVideoFeatureControlClassIDBlackLevel = 'bklv', kIOVideoFeatureControlClassIDWhiteLevel = 'whlv', kIOVideoFeatureControlClassIDHue = 'hue ', kIOVideoFeatureControlClassIDSaturation = 'satu', kIOVideoFeatureControlClassIDContrast = 'ctst', kIOVideoFeatureControlClassIDSharpness = 'shrp', kIOVideoFeatureControlClassIDBrightness = 'brit', kIOVideoFeatureControlClassIDGain = 'gain', kIOVideoFeatureControlClassIDIris = 'iris', kIOVideoFeatureControlClassIDShutter = 'shtr', kIOVideoFeatureControlClassIDExposure = 'xpsr', kIOVideoFeatureControlClassIDWhiteBalanceU = 'whbu', kIOVideoFeatureControlClassIDWhiteBalanceV = 'whbv', kIOVideoFeatureControlClassIDGamma = 'gmma', kIOVideoFeatureControlClassIDTemperature = 'temp', kIOVideoFeatureControlClassIDZoom = 'zoom', kIOVideoFeatureControlClassIDFocus = 'fcus', kIOVideoFeatureControlClassIDPan = 'pan ', kIOVideoFeatureControlClassIDTilt = 'tilt', kIOVideoFeatureControlClassIDOpticalFilter = 'opft', kIOVideoFeatureControlClassIDBacklightCompensation = 'bklt', kIOVideoFeatureControlClassIDPowerLineFrequency = 'pwfq' };

1193

IOVideoTypes.h User-Space Reference Constants

Constants
kIOVideoFeatureControlClassIDBlackLevel

A IOVideoFeatureControl that controls the black level offset. The units for the control's absolute value are percetage (%). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDWhiteLevel

A IOVideoFeatureControl that controls the white level offset. The units for the control's absolute value are percentage (%). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDHue

A IOVideoFeatureControl that controls the hue offset. Positive values mean counterclockwise, negative values means clockwise on a vector scope. The units for the control's absolute value are degrees (\xB0). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDSaturation

A IOVideoFeatureControl that controls color intensity. For example, at high saturation levels, red appears to be red; at low saturation, red appears as pink. The unit for the control's absolute value is a percentage (%). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDContrast

A IOVideoFeatureControl that controls a the distance bewtween the whitest whites and blackest blacks. The units for the control's absolute value are percentage (%). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDSharpness

A IOVideoFeatureControl that controls the sharpness of the picture. The units for the control's absolute value are undefined. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDBrightness

A IOVideoFeatureControl that controls the intensity of the video level. The units for the control's absolute value are percetage (%). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.

1194

IOVideoTypes.h User-Space Reference Constants

kIOVideoFeatureControlClassIDGain

A IOVideoFeatureControl that controls the amplification of the signal. The units for the control's absolute value are decibels (dB). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDIris

A IOVideoFeatureControl that controls a mechanical lens iris. The units for the control's absolute value are an F number (F). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDShutter

A IOVideoFeatureControl that controls the integration time of the incoming light. The units for the control's absolute value are seconds (s). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDExposure

A IOVideoFeatureControl that controls a the total amount of light accumulated. The units for the control's absolute value are exposure value (EV). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDWhiteBalanceU

A IOVideoFeatureControl that controls the adjustment of the white color of the picture. The units for the control's absolute value are kelvin (K). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDWhiteBalanceV

A IOVideoFeatureControl that controls a adjustment of the white color of the picture. The units for the control's absolute value are kelvin (K). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDGamma

A IOVideoFeatureControl that defines the function between incoming light level and output picture level. The units for the control's absolute value are undefined. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.

1195

IOVideoTypes.h User-Space Reference Constants

kIOVideoFeatureControlClassIDTemperature

A IOVideoFeatureControl that controls the temperature inside of the device and/or controlling temperature. The units for the control's absolute value are undefined. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDZoom

A IOVideoFeatureControl that controls the zoom. The units for the control's absolute value are power where 1 is the wide end. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDFocus

A IOVideoFeatureControl that controls a focus mechanism. The units for the control's absolute value are meters (m). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDPan

A IOVideoFeatureControl that controls a panning mechanism. Positive values mean clockwise, negative values means counterclockwise. The units for the control's absolute value are degrees (\xB0). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDTilt

A IOVideoFeatureControl that controls a tilt mechanism. Positive values mean updwards, negative values means downwards. The units for the control's absolute value are degrees (\xB0). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDOpticalFilter

A IOVideoFeatureControl that controls chagning the optical filter of camera lens function. The units for the control's absolute value are are undefined. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoFeatureControlClassIDBacklightCompensation

A IOVideoFeatureControl that controls the amount of backlight compensation to apply. A low number indicates the least amount of backlight compensation. The units for the control's absolute value are are undefined. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.

1196

IOVideoTypes.h User-Space Reference Constants

kIOVideoFeatureControlClassIDPowerLineFrequency

A IOVideoFeatureControl to specify the power line frequency to properly implement anti-flicker processing. The units for the contorl's absolute value are hertz (Hz). Available in OS X v10.7 and later. Declared in IOVideoTypes.h.

IOVideoSelectorControl
The four char codes that identify the various standard subclasses of IOVideoSelectorControl.

enum { kIOVideoSelectorControlClassIDDataSource = 'dsrc', kIOVideoSelectorControlClassIDDataDestination = 'dest' };

Constants
kIOVideoSelectorControlClassIDDataSource

A IOVideoSelectorControl that identifies where the data for the element is coming from. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoSelectorControlClassIDDataDestination

A IOVideoSelectorControl that identifies where the data for the element is going. Available in OS X v10.7 and later. Declared in IOVideoTypes.h. Discussion Subclass IDs

Notification IDs
The four char codes used to identify the kind of the notification.

enum { kIOVideoDeviceNotificationID_ControlValueChanged = 'cval', kIOVideoDeviceNotificationID_ControlRangeChanged = 'crng' };

1197

IOVideoTypes.h User-Space Reference Constants

Constants
kIOVideoDeviceNotificationID_ControlValueChanged

Indicates that the value of the control with the given ID has changed. The first argument is the new value. Available in OS X v10.7 and later. Declared in IOVideoTypes.h.
kIOVideoDeviceNotificationID_ControlRangeChanged

Indicates that the range of the control with the given ID has changed. Available in OS X v10.7 and later. Declared in IOVideoTypes.h. Discussion All device-level notifications will have an object ID of 0.

1198

KextManager.h Reference

Declared in

KextManager.h

Overview
The KextManager API provides a simple interface for applications to load kernel extensions (kexts) via RPC to kextd, and to look up the URLs for kexts by bundle identifier.

Included Headers

<CoreFoundation/CoreFoundation.h> <libkern/OSReturn.h> <sys/cdefs.h>

Functions
See the Overview for header-level documentation.

KextManagerCopyLoadedKextInfo
Returns information about loaded kexts in a dictionary.

CFDictionaryRef KextManagerCopyLoadedKextInfo( CFArrayRef kextIdentifiers, CFArrayRef infoKeys)AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER;

Parameters
kextIdentifiers

An array of kext identifiers to read from the kernel. Pass NULL to read info for all loaded kexts.
infoKeys

An array of info keys to read from the kernel. Pass NULL to read all information.

1199

KextManager.h Reference Functions

Return Value A dictionary, keyed by bundle identifier, of dictionaries containing information about loaded kexts. Discussion The information keys returned by this function are listed below. Some are taken directly from the kext's information property list, and some are generated at run time. Never assume a given key will be present for a kext.

CFBundleIdentifier - CFString CFBundleVersion - CFString (note: version strings may be canonicalized but their numeric values will

be the same; "1.2.0" may become "1.2", for example)

OSBundleCompatibleVersion - CFString OSBundleIsInterface - CFBoolean OSKernelResource - CFBoolean OSBundleCPUType - CFNumber OSBundleCPUSubtype - CFNumber OSBundlePath - CFString (this is merely a hint stored in the kernel; the kext is not guaranteed to be at

this path)

OSBundleExecutablePath - CFString (the absolute path to the executable within the kext bundle; a

hint as above)

OSBundleUUID - CFData (the UUID of the kext executable, if it has one) OSBundleStarted - CFBoolean (true if the kext is running) OSBundlePrelinked - CFBoolean (true if the kext is loaded from a prelinked kernel) OSBundleLoadTag - CFNumber (the "Index" given by kextstat) OSBundleLoadAddress - CFNumber OSBundleLoadSize - CFNumber OSBundleWiredSize - CFNumber OSBundleDependencies - CFArray of load tags identifying immediate link dependencies OSBundleRetainCount - CFNumber (the OSObject retain count of the kext itself ) OSBundleClasses - CFArray of CFDictionary containing info on C++ classes defined by the kext: OSMetaClassName - CFString OSMetaClassSuperclassName - CFString, absent for root classes

1200

KextManager.h Reference Functions

OSMetaClassTrackingCount - CFNumber giving the instance count of the class itself, plus 1 for each

direct subclass with any instances Availability Available in OS X v10.7 and later. Declared in
KextManager.h

KextManagerCreateURLForBundleIdentifier
Create a URL locating a kext with a given bundle identifier.

CFURLRef KextManagerCreateURLForBundleIdentifier( CFAllocatorRef allocator, CFStringRef kextIdentifier)AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER;

Parameters
allocator

The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the current default allocator.
kextIdentifier

The bundle identifier to look up. Return Value A CFURLRef locating a kext with the requested bundle identifier. Returns NULL if the kext cannot be found, or on error. Discussion Kexts are looked up first by whether they are loaded, second by version. Specifically, if kextIdentifier identifies a kext that is currently loaded, the returned URL will locate that kext if it's still present on disk. If the requested kext is not loaded, or if its bundle is not at the location it was originally loaded from, the returned URL will locate the latest version of the desired kext, if one can be found within the system extensions folder. If no version of the kext can be found, NULL is returned. Availability Available in OS X v10.2 and later. Declared in
KextManager.h

1201

KextManager.h Reference Functions

KextManagerLoadKextWithIdentifier
Request the kext loading system to load a kext with a given bundle identifier.

OSReturn KextManagerLoadKextWithIdentifier( CFStringRef kextIdentifier, CFArrayRef dependencyKextAndFolderURLs)AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

Parameters
kextIdentifier

The bundle identifier of the kext to look up and load.

dependencyKextAndFolderURLs

An array of additional URLs, of individual kexts and of folders that may contain kexts. Return Value
kOSReturnSuccess if the kext is successfully loaded (or is already loaded), otherwise returns on error.

Discussion
kextIdentifier is looked up in the system extensions folder and among any kexts from dependencyKextAndFolderURLs. Any non-kext URLs in dependencyKextAndFolderURLs are scanned

at the top level for kexts and plugins of kexts. Either the calling process must have an effective user id of 0 (superuser), or the kext being loaded and all its dependencies must reside in /System and have an OSBundleAllowUserLoad property of true. Availability Available in OS X v10.6 and later. Declared in
KextManager.h

KextManagerLoadKextWithURL
Request the kext loading system to load a kext with a given URL.

OSReturn KextManagerLoadKextWithURL( CFURLRef kextURL, CFArrayRef dependencyKextAndFolderURLs)AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER;

1202

KextManager.h Reference Functions

Parameters
kextURL

The URL of the kext to load.

dependencyKextAndFolderURLs

Discussion Any non-kext URLs in dependencyKextAndFolderURLs are scanned at the top level for kexts and plugins of kexts. Either the calling process must have an effective user id of 0 (superuser), or the kext being loaded and all its dependencies must reside in /System and have an OSBundleAllowUserLoad property of true. Availability Available in OS X v10.6 and later. Declared in
KextManager.h

KextManagerUnloadKextWithIdentifier
Request the kernel to unload a kext with a given bundle identifier.

OSReturn KextManagerUnloadKextWithIdentifier( CFStringRef kextIdentifier)AVAILABLE_MAC_OS_X_VERSION_10_7_AND_LATER;

Parameters
kextIdentifier

The bundle identifier of the kext to unload. Return Value

kOSReturnSuccess if the kext is found and successfully unloaded, otherwise returns on error. See /usr/include/libkern/OSKextLib.h for error codes.

Discussion The calling process must have an effective user id of 0 (superuser). Availability Available in OS X v10.7 and later.

1203

KextManager.h Reference Functions

Declared in
KextManager.h

1204

SCSICmds_INQUIRY_Definitions.h User-Space Reference

Declared in SCSICmds_INQUIRY_Definitions.h

Overview
This file contains all definitions for the data returned from the INQUIRY (0x12) command.

Included Headers

Data Types
See the Overview for header-level documentation.

SCSICmd_INQUIRY_Page00_Header

typedef struct SCSICmd_INQUIRY_Page00_Header { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 PAGE_CODE; // Must be equal to 00h UInt8 RESERVED; // reserved field UInt8 PAGE_LENGTH; // n-3 bytes } SCSICmd_INQUIRY_Page00_Header;

Discussion INQUIRY Page 00h Header. Availability Available in OS X v10.2 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

1205

SCSICmds_INQUIRY_Definitions.h User-Space Reference Data Types

SCSICmd_INQUIRY_Page80_Header

typedef struct SCSICmd_INQUIRY_Page80_Header { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 PAGE_CODE; // Must be equal to 80h UInt8 RESERVED; // reserved field UInt8 PAGE_LENGTH; // n-3 bytes UInt8 PRODUCT_SERIAL_NUMBER; // 4-n } SCSICmd_INQUIRY_Page80_Header;

Discussion INQUIRY Page 80h Header. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_Header

typedef struct SCSICmd_INQUIRY_Page83_Header { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 PAGE_CODE; // Must be equal to 83h UInt8 RESERVED; // reserved field UInt8 PAGE_LENGTH; // n-3 bytes } SCSICmd_INQUIRY_Page83_Header;

Discussion INQUIRY Page 83h Header. Availability Available in OS X v10.2 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_Header_SPC_16

typedef struct SCSICmd_INQUIRY_Page83_Header_SPC_16 { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type.

1206

SCSICmds_INQUIRY_Definitions.h User-Space Reference Data Types

UInt8 PAGE_CODE; // Must be equal to 83h UInt16 PAGE_LENGTH; // n-3 bytes } SCSICmd_INQUIRY_Page83_Header_SPC_16;

Discussion INQUIRY Page 83h Header used with the 16 byte INQUIRY command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_Identification_Descriptor

typedef struct SCSICmd_INQUIRY_Page83_Identification_Descriptor { UInt8 CODE_SET; // 7-4 = Protocol Identifier. 3-0 = Code Set UInt8 IDENTIFIER_TYPE; // 7 = PIV 5-4 = ASSOCIATION 3-0 = Identifier UInt8 RESERVED; UInt8 IDENTIFIER_LENGTH; UInt8 IDENTIFIER; } SCSICmd_INQUIRY_Page83_Identification_Descriptor;

Discussion INQUIRY Page 83h Identification Descriptor. Availability Available in OS X v10.2 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_LogicalUnitGroup_Identifier

typedef struct SCSICmd_INQUIRY_Page83_LogicalUnitGroup_Identifier { UInt16 RESERVED; UInt16 LOGICAL_UNIT_GROUP; } SCSICmd_INQUIRY_Page83_LogicalUnitGroup_Identifier;

Discussion INQUIRY Page 83h Logical Unit Group Identifier.

1207

SCSICmds_INQUIRY_Definitions.h User-Space Reference Data Types

Availability Available in OS X v10.7 and later. Declared in

SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_RelativeTargetPort_Identifier

typedef struct SCSICmd_INQUIRY_Page83_RelativeTargetPort_Identifier { UInt16 OBSOLETE; UInt16 RELATIVE_TARGET_PORT_IDENTIFIER; } SCSICmd_INQUIRY_Page83_RelativeTargetPort_Identifier;

Discussion INQUIRY Page 83h Relative Target Port Identifier. Availability Available in OS X v10.7 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_Page83_TargetPortGroup_Identifier

typedef struct SCSICmd_INQUIRY_Page83_TargetPortGroup_Identifier { UInt16 RESERVED; UInt16 TARGET_PORT_GROUP; } SCSICmd_INQUIRY_Page83_TargetPortGroup_Identifier;

Discussion INQUIRY Page 83h Target Port Group Identifier. Availability Available in OS X v10.7 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

1208

SCSICmds_INQUIRY_Definitions.h User-Space Reference Data Types

SCSICmd_INQUIRY_Page89_Data

typedef struct SCSICmd_INQUIRY_Page89_Data { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 PAGE_CODE; // Must be equal to 89h UInt16 PAGE_LENGTH; // Must be equal to 238h UInt32 Reserved; UInt8 SAT_VENDOR_IDENTIFICATION[ kINQUIRY_VENDOR_IDENTIFICATION_Length]; UInt8 SAT_PRODUCT_IDENTIFICATION[ kINQUIRY_PRODUCT_IDENTIFICATION_Length]; UInt8 SAT_PRODUCT_REVISION_LEVEL[ kINQUIRY_PRODUCT_REVISION_LEVEL_Length]; UInt8 ATA_DEVICE_SIGNATURE[20]; UInt8 COMMAND_CODE; UInt8 Reserved2[3]; UInt8 IDENTIFY_DATA[512]; } SCSICmd_INQUIRY_Page89_Data;

Discussion INQUIRY Page 89h data as defined in the SAT 1.0 specification. This section contians all structures and definitions used by the INQUIRY command in response to a request for page 89h - ATA information VPD Page. Availability Available in OS X v10.4 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_PageB1_Data

typedef struct SCSICmd_INQUIRY_PageB1_Data { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 PAGE_CODE; // Must be equal to B1h UInt8 Reserved; UInt8 PAGE_LENGTH; // Must be equal to 3Ch UInt16 MEDIUM_ROTATION_RATE; UInt8 Reserved2[58]; } SCSICmd_INQUIRY_PageB1_Data;

Discussion INQUIRY Page B1h data as defined in the SBC specification. This section contians all structures and definitions used by the INQUIRY command in response to a request for page B1h - Block Device Characteristics VPD Page.

1209

SCSICmds_INQUIRY_Definitions.h User-Space Reference Data Types

Availability Available in OS X v10.7 and later. Declared in

SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_StandardData

typedef struct SCSICmd_INQUIRY_StandardData { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type. UInt8 RMB; // 7 = removable UInt8 VERSION; // 7/6 = ISO/IEC, 5-3 = ECMA, 2-0 = ANSI. UInt8 RESPONSE_DATA_FORMAT; // 7 = AERC, 6 = Obsolete, 5 = NormACA, 4 = HiSup 3-0 = Response data format. (SPC-3 obsoletes AERC) // If ANSI Version = 0, this is ATAPI and bits 7-4 = ATAPI version. UInt8 ADDITIONAL_LENGTH; // Number of additional bytes available in inquiry data UInt8 SCCSReserved; // SCC-2 device flag and reserved fields (SPC-3 adds PROTECT 3PC TPGS, and ACC) UInt8 flags1; // First byte of support flags (See SPC-3 section 6.4.2) UInt8 flags2; // Second byte of support flags (Byte 7) (See SPC-3 section 6.4.2) char VENDOR_IDENTIFICATION[ kINQUIRY_VENDOR_IDENTIFICATION_Length]; char PRODUCT_IDENTIFICATION[ kINQUIRY_PRODUCT_IDENTIFICATION_Length]; char PRODUCT_REVISION_LEVEL[ kINQUIRY_PRODUCT_REVISION_LEVEL_Length]; } SCSICmd_INQUIRY_StandardData;

Discussion This structure defines the format of the required standard data that is returned for the INQUIRY command. This is the data that is required to be returned from all devices. Availability Available in OS X v10.0 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

SCSICmd_INQUIRY_StandardDataAll

typedef struct SCSICmd_INQUIRY_StandardDataAll { UInt8 PERIPHERAL_DEVICE_TYPE; // 7-5 = Qualifier. 4-0 = Device type.

1210

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

UInt8 RMB; // 7 = removable UInt8 VERSION; // 7/6 = ISO/IEC, 5-3 = ECMA, 2-0 = ANSI. UInt8 RESPONSE_DATA_FORMAT; // 7 = AERC, 6 = Obsolete, 5 = NormACA, 4 = HiSup 3-0 = Response data format. // If ANSI Version = 0, this is ATAPI and bits 7-4 = ATAPI version. UInt8 ADDITIONAL_LENGTH; // Number of additional bytes available in inquiry data UInt8 SCCSReserved; // SCC-2 device flag and reserved fields UInt8 flags1; // First byte of support flags (Byte 6) UInt8 flags2; // Second byte of support flags (Byte 7) char VENDOR_IDENTIFICATION[ kINQUIRY_VENDOR_IDENTIFICATION_Length]; char PRODUCT_IDENTIFICATION[ kINQUIRY_PRODUCT_IDENTIFICATION_Length]; char PRODUCT_REVISION_LEVEL[ kINQUIRY_PRODUCT_REVISION_LEVEL_Length]; // Following is the optional data that may be returned by a device. UInt8 VendorSpecific1[20]; UInt8 flags3; // Third byte of support flags, mainly SPI-3 (Byte 56) UInt8 Reserved1; UInt16 VERSION_DESCRIPTOR[8]; UInt8 Reserved2[22]; UInt8 VendorSpecific2[160]; } SCSICmd_INQUIRY_StandardDataAll;

Discussion This structure defines the all of the fields that can be returned in repsonse to the INQUIRy request for the standard data. There is no requirement as to how much of the additional data must be returned by a device. Availability Available in OS X v10.2 and later. Declared in
SCSICmds_INQUIRY_Definitions.h

Constants
See the Overview for header-level documentation.

Defines

#define #define #define #define

kINQUIRY_VERSION_DESCRIPTOR_MaxCount 8 kIOPropertyHiSup "Hierarchical LUN Support" kIOPropertySATProductIdentification "SAT Product Identification" kIOPropertySATProductRevisonLevel "SAT Product Revision Level"

1211

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

#define #define #define #define #define #define #define #define #define #define #define #define #define #define

kIOPropertySATVendorIdentification "SAT Vendor Identification" kIOPropertySCSIINQUIRYDeviceIdAssociation "Association" kIOPropertySCSIINQUIRYDeviceIdCodeSet "Code Set" kIOPropertySCSIINQUIRYDeviceIdentification "INQUIRY Device Identification" kIOPropertySCSIINQUIRYDeviceIdentifier "Identifier" kIOPropertySCSIINQUIRYDeviceIdType "Identifier Type" kIOPropertySCSIINQUIRYUnitSerialNumber "INQUIRY Unit Serial Number" kIOPropertySCSIPeripheralDeviceType "Peripheral Device Type" kIOPropertySCSIPeripheralDeviceTypeSize 8 kIOPropertySCSIProductIdentification "Product Identification" kIOPropertySCSIProductRevisionLevel "Product Revision Level" kIOPropertySCSIVendorIdentification "Vendor Identification" kIOPropertyTPGSInfo "TPGS Information" kIOPropertyTPGSInfoSize 8

Constants
kINQUIRY_VERSION_DESCRIPTOR_MaxCount

Maximum number of INQUIRY version descriptors supported. Available in OS X v10.4 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertyHiSup

Hierarchical LUN Support as reported in the INQUIRY data. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySATProductIdentification

Product Identification of the SATL. Available in OS X v10.4 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySATProductRevisonLevel

Product Revision Level of the SATL. Available in OS X v10.4 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySATVendorIdentification

Vendor Identification of the SATL. Available in OS X v10.4 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIINQUIRYDeviceIdAssociation

Association key. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1212

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kIOPropertySCSIINQUIRYDeviceIdCodeSet

Code Set type key. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIINQUIRYDeviceIdentification

Device Identification key. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kIOPropertySCSIINQUIRYDeviceIdentifier

Identifier key (data or string). Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIINQUIRYDeviceIdType

Identifier Type key. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kIOPropertySCSIINQUIRYUnitSerialNumber

Key that describes the INQUIRY Unit Serial Number in the IORegistry. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIPeripheralDeviceType

SCSI Peripheral Device Type as reported in the INQUIRY data. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIPeripheralDeviceTypeSize

Size of the kIOPropertySCSIPeripheralDeviceType key. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIProductIdentification

Product ID as reported in the INQUIRY data. Additional space characters (0x20) are truncated. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertySCSIProductRevisionLevel

Product Revision Level as reported in the INQUIRY data. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1213

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kIOPropertySCSIVendorIdentification

Vendor ID as reported in the INQUIRY data. Additional space characters (0x20) are truncated. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertyTPGSInfo

TPGS Info as reported in the INQUIRY data. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kIOPropertyTPGSInfoSize

Size of the kIOPropertyTPGSInfo key. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

Byte 56 features field definitions

enum { // Byte offset kINQUIRY_Byte56_Offset = 56, // Bit definitions kINQUIRY_Byte56_IUS_Bit = 0, kINQUIRY_Byte56_QAS_Bit = 1, // Bits 2 and 3 are the CLOCKING bits // All other bits are reserved kINQUIRY_Byte56_IUS_Mask = ( 1 << kINQUIRY_Byte56_IUS_Bit), kINQUIRY_Byte56_QAS_Mask = ( 1 << kINQUIRY_Byte56_QAS_Bit), kINQUIRY_Byte56_CLOCKING_Mask = 0x0C, // Definitions for the CLOCKING bits kINQUIRY_Byte56_CLOCKING_ONLY_ST = 0x00, kINQUIRY_Byte56_CLOCKING_ONLY_DT = 0x04, // kINQUIRY_Byte56_CLOCKING_RESERVED kINQUIRY_Byte56_CLOCKING_ST_AND_DT = 0x0C };

= 0x08,

Constants
kINQUIRY_Byte56_IUS_Bit

IUS bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1214

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte56_QAS_Bit

QAS bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte56_IUS_Mask

Mask to use to test the IUS bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte56_QAS_Mask

Mask to use to test the QAS bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte56_CLOCKING_Mask

Mask to use to test CLOCKING bits. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte56_CLOCKING_ONLY_ST

Single-transition clocking only. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte56_CLOCKING_ONLY_DT

Double-transition clocking only. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte56_CLOCKING_ST_AND_DT

Single-transition and double-transition clocking. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for bits/masks in the INQUIRY Byte 56 field. Inquiry Byte 56 features (for devices that report an ANSI VERSION of kINQUIRY_ANSI_VERSION_SCSI_SPC_Compliant or later). These are SPI-3 Specific.

flags1 field definitions

enum {

1215

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

// Byte offset kINQUIRY_Byte6_Offset = 6, // Bit definitions kINQUIRY_Byte6_ADDR16_Bit = 0, // SPI Specific // Bit 1 is Obsolete // Bit 2 is Obsolete kINQUIRY_Byte6_MCHNGR_Bit = 3, kINQUIRY_Byte6_MULTIP_Bit = 4, kINQUIRY_Byte6_VS_Bit = 5, kINQUIRY_Byte6_ENCSERV_Bit = 6, kINQUIRY_Byte6_BQUE_Bit = 7, // Masks kINQUIRY_Byte6_ADDR16_Mask = ( 1 << kINQUIRY_Byte6_ADDR16_Bit), // SPI Specific // Bit 1 is Obsolete // Bit 2 is Obsolete kINQUIRY_Byte6_MCHNGR_Mask = ( 1 << kINQUIRY_Byte6_MCHNGR_Bit), kINQUIRY_Byte6_MULTIP_Mask = ( 1 << kINQUIRY_Byte6_MULTIP_Bit), kINQUIRY_Byte6_VS_Mask = ( 1 << kINQUIRY_Byte6_VS_Bit), kINQUIRY_Byte6_ENCSERV_Mask = ( 1 << kINQUIRY_Byte6_ENCSERV_Bit), kINQUIRY_Byte6_BQUE_Mask = ( 1 << kINQUIRY_Byte6_BQUE_Bit) };

Constants
kINQUIRY_Byte6_ADDR16_Bit

ADDR16 bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte6_MCHNGR_Bit

MCHNGR bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte6_MULTIP_Bit

MULTIP bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1216

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte6_VS_Bit

VS bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte6_ENCSERV_Bit

ENCSERV bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte6_BQUE_Bit

BQUE bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte6_ADDR16_Mask

Mask to use to test the ADDR16 bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte6_MCHNGR_Mask

Mask to use to test the MCHNGR bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte6_MULTIP_Mask

Mask to use to test the MULTIP bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte6_VS_Mask

Mask to use to test the VS bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte6_ENCSERV_Mask

Mask to use to test the ENCSERV bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte6_BQUE_Mask

Mask to use to test the BQUE bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1217

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Discussion Definitions for bits/masks in the INQUIRY flags1 field.

flags2 field definitions

enum { // Byte offset kINQUIRY_Byte7_Offset = 7, // Bit definitions kINQUIRY_Byte7_VS_Bit = 0, kINQUIRY_Byte7_CMDQUE_Bit = 1, kINQUIRY_Byte7_TRANDIS_Bit = 2, // SPI Specific kINQUIRY_Byte7_LINKED_Bit = 3, kINQUIRY_Byte7_SYNC_Bit = 4, // SPI Specific kINQUIRY_Byte7_WBUS16_Bit = 5, // SPI Specific // Bit 6 is Obsolete kINQUIRY_Byte7_RELADR_Bit = 7, // Masks kINQUIRY_Byte7_VS_Mask = ( 1 << kINQUIRY_Byte7_VS_Bit), kINQUIRY_Byte7_CMDQUE_Mask = ( 1 << kINQUIRY_Byte7_CMDQUE_Bit), kINQUIRY_Byte7_TRANDIS_Mask = ( 1 << kINQUIRY_Byte7_TRANDIS_Bit),// SPI Specific kINQUIRY_Byte7_LINKED_Mask = ( 1 << kINQUIRY_Byte7_LINKED_Bit), kINQUIRY_Byte7_SYNC_Mask = ( 1 << kINQUIRY_Byte7_SYNC_Bit), // SPI Specific kINQUIRY_Byte7_WBUS16_Mask = ( 1 << kINQUIRY_Byte7_WBUS16_Bit), // SPI Specific // Bit 6 is Obsolete kINQUIRY_Byte7_RELADR_Mask = ( 1 << kINQUIRY_Byte7_RELADR_Bit) };

Constants
kINQUIRY_Byte7_VS_Bit

VS bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1218

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte7_CMDQUE_Bit

CMDQUE bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_TRANDIS_Bit

TRANDIS bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_LINKED_Bit

LINKED bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_SYNC_Bit

SYNC bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_WBUS16_Bit

WBUS16 bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_RELADR_Bit

RELADR bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte7_VS_Mask

Mask to use to test the VS bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte7_CMDQUE_Mask

Mask to use to test the CMDQUE bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte7_TRANDIS_Mask

Mask to use to test the TRANDIS bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1219

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte7_LINKED_Mask

Mask to use to test the LINKED bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte7_SYNC_Mask

Mask to use to test the SYNC bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte7_WBUS16_Mask

Mask to use to test the WBUS16 bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte7_RELADR_Mask

Mask to use to test the RELADR bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for bits/masks in the INQUIRY flags2 field.

INQUIRY field sizes

enum { kINQUIRY_VENDOR_IDENTIFICATION_Length = 8, kINQUIRY_PRODUCT_IDENTIFICATION_Length = 16, kINQUIRY_PRODUCT_REVISION_LEVEL_Length = 4 };

Constants
kINQUIRY_VENDOR_IDENTIFICATION_Length

Size of VENDOR_IDENTIFICATION field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PRODUCT_IDENTIFICATION_Length

Size of PRODUCT_IDENTIFICATION field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1220

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_PRODUCT_REVISION_LEVEL_Length

Size of PRODUCT_REVISION_LEVEL field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Sizes for some of the inquiry data fields.

INQUIRY Page 83h Association

enum { // SPC-3 - Association is changed to be specific to // Logical Units kINQUIRY_Page83_AssociationLogicalUnit = 0x00, // Backwards compatibility for SPC-2 kINQUIRY_Page83_AssociationDevice = kINQUIRY_Page83_AssociationLogicalUnit, // Association is related to a Target Port kINQUIRY_Page83_AssociationTargetPort = 0x10, // SPC-3 - Added as specific association to // a Target device. kINQUIRY_Page83_AssociationTargetDevice = 0x20, kINQUIRY_Page83_AssociationMask = 0x30, kINQUIRY_Page83_AssociationShift = 4 };

Constants
kINQUIRY_Page83_AssociationLogicalUnit

Association of the identifier is with the logical unit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_AssociationDevice

Association of the identifier is with the device (same as logical unit in SPC-2). Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_AssociationTargetPort

Association of the identifier is with the target port. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1221

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Page83_AssociationTargetDevice

Association of the identifier is with the target device (i.e. all ports). Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_AssociationMask

Mask to use to determine association. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for the Association field.

INQUIRY Page 83h Code Set

enum { kINQUIRY_Page83_CodeSetReserved = 0x0, kINQUIRY_Page83_CodeSetBinaryData = 0x1, kINQUIRY_Page83_CodeSetASCIIData = 0x2, kINQUIRY_Page83_CodeSetUTF8Data = 0x3, // 0x4 - 0xF reserved kINQUIRY_Page83_CodeSetMask = 0xF };

Constants
kINQUIRY_Page83_CodeSetBinaryData

The identifier contains binary data. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_CodeSetASCIIData

The identifier contains ASCII data. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_CodeSetUTF8Data

The identifier contains UTF-8 data. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1222

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Discussion Definitions for the Code Set field.

INQUIRY Page 83h Identifier Type

enum { kINQUIRY_Page83_IdentifierTypeVendorSpecific = 0, kINQUIRY_Page83_IdentifierTypeVendorID = 1, kINQUIRY_Page83_IdentifierTypeIEEE_EUI64 = 2, kINQUIRY_Page83_IdentifierTypeNAAIdentifier = 3, kINQUIRY_Page83_IdentifierTypeRelativePortIdentifier = 4, kINQUIRY_Page83_IdentifierTypeTargetPortGroup = 5, kINQUIRY_Page83_IdentifierTypeLogicalUnitGroup = 6, kINQUIRY_Page83_IdentifierTypeMD5LogicalUnitIdentifier = 7, kINQUIRY_Page83_IdentifierTypeSCSINameString = 8, // 0x9 - 0xF Reserved kINQUIRY_Page83_IdentifierTypeMask = 0xF, kINQUIRY_Page83_ProtocolIdentifierValidBit = 7, kINQUIRY_Page83_ProtocolIdentifierValidMask = ( 1 << kINQUIRY_Page83_ProtocolIdentifierValidBit) };

Constants
kINQUIRY_Page83_IdentifierTypeVendorSpecific

Vendor Specific Identifier Type. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeVendorID

Vendor Specific Identifier Type. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeIEEE_EUI64

EUI-64 Identifier Type. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Page83_IdentifierTypeNAAIdentifier

NAA Identifier Type. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1223

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Page83_IdentifierTypeRelativePortIdentifier

Relative Target Port Identifier Type. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeTargetPortGroup

Target Port Group Identifier Type. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeLogicalUnitGroup

Logical Unit Group Identifier Type. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeMD5LogicalUnitIdentifier

MD5 Logical Unit Identifier Type. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeSCSINameString

SCSI Name String Identifier Type. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_IdentifierTypeMask

Mask to use to determine association. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Page83_ProtocolIdentifierValidBit

PIV Bit definition. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Page83_ProtocolIdentifierValidMask

Mask to use to determine if PIV is set. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for the Identifier Type field.

1224

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

INQUIRY Page Codes

enum { kINQUIRY_Page00_PageCode kINQUIRY_Page80_PageCode kINQUIRY_Page83_PageCode kINQUIRY_Page89_PageCode kINQUIRY_PageB1_PageCode };

= = = = =

0x00, 0x80, 0x83, 0x89, 0xB1

Constants
kINQUIRY_Page00_PageCode

Page Code 00h. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Page80_PageCode

Page Code 80h. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Page83_PageCode

Page Code 83h. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Page89_PageCode

Page Code 89h. Available in OS X v10.4 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion INQUIRY Page Codes to be used when EVPD is set in the INQUIRY command.

kINQUIRY_VERSION_DESCRIPTOR_SAT

enum { kINQUIRY_VERSION_DESCRIPTOR_SAT = 0x1EA0 };

Discussion SAT specification version descriptor.

1225

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Payload sizes

enum { kINQUIRY_StandardDataHeaderSize = 5, kINQUIRY_MaximumDataSize = 255 };

Constants
kINQUIRY_StandardDataHeaderSize

INQUIRY data header size. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_MaximumDataSize

Maximum size for INQUIRY data. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for sizes related to the INQUIRY data.

Peripheral Device types

enum { kINQUIRY_PERIPHERAL_TYPE_DirectAccessSBCDevice = 0x00, kINQUIRY_PERIPHERAL_TYPE_SequentialAccessSSCDevice = 0x01, kINQUIRY_PERIPHERAL_TYPE_PrinterSSCDevice = 0x02, kINQUIRY_PERIPHERAL_TYPE_ProcessorSPCDevice = 0x03, kINQUIRY_PERIPHERAL_TYPE_WriteOnceSBCDevice = 0x04, kINQUIRY_PERIPHERAL_TYPE_CDROM_MMCDevice = 0x05, kINQUIRY_PERIPHERAL_TYPE_ScannerSCSI2Device = 0x06, kINQUIRY_PERIPHERAL_TYPE_OpticalMemorySBCDevice = 0x07, kINQUIRY_PERIPHERAL_TYPE_MediumChangerSMCDevice = 0x08, kINQUIRY_PERIPHERAL_TYPE_CommunicationsSSCDevice = 0x09, /* 0x0A - 0x0B ASC IT8 Graphic Arts Prepress Devices */ kINQUIRY_PERIPHERAL_TYPE_StorageArrayControllerSCC2Device = 0x0C, kINQUIRY_PERIPHERAL_TYPE_EnclosureServicesSESDevice = 0x0D, kINQUIRY_PERIPHERAL_TYPE_SimplifiedDirectAccessRBCDevice = 0x0E, kINQUIRY_PERIPHERAL_TYPE_OpticalCardReaderOCRWDevice = 0x0F, /* 0x10 - 0x1E Reserved Device Types */ kINQUIRY_PERIPHERAL_TYPE_ObjectBasedStorageDevice = 0x11, kINQUIRY_PERIPHERAL_TYPE_AutomationDriveInterface = 0x12, kINQUIRY_PERIPHERAL_TYPE_WellKnownLogicalUnit = 0x1E,

1226

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_PERIPHERAL_TYPE_UnknownOrNoDeviceType = 0x1F, kINQUIRY_PERIPHERAL_TYPE_Mask = 0x1F };

Constants
kINQUIRY_PERIPHERAL_TYPE_DirectAccessSBCDevice

SBC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_SequentialAccessSSCDevice

Sequential Access (Tape) SSC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_TYPE_PrinterSSCDevice

SSC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_ProcessorSPCDevice

SPC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_WriteOnceSBCDevice

SBC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_CDROM_MMCDevice

MMC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_ScannerSCSI2Device

SCSI2 Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_OpticalMemorySBCDevice

SBC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1227

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_PERIPHERAL_TYPE_MediumChangerSMCDevice

SMC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_CommunicationsSSCDevice

Comms SSC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_StorageArrayControllerSCC2Device

SCC2 Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_EnclosureServicesSESDevice

SES Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_SimplifiedDirectAccessRBCDevice

RBC Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_OpticalCardReaderOCRWDevice

OCRW Device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_ObjectBasedStorageDevice

OSD device. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_AutomationDriveInterface

Automation Drive Interface device. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_TYPE_WellKnownLogicalUnit

Well known logical unit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1228

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_PERIPHERAL_TYPE_UnknownOrNoDeviceType

Unknown or no device. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_TYPE_Mask

Mask to use for PERIPHERAL_DEVICE_TYPE field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Inquiry Peripheral Device type definitions

Peripheral Qualifier

enum { kINQUIRY_PERIPHERAL_QUALIFIER_Connected = 0x00, kINQUIRY_PERIPHERAL_QUALIFIER_SupportedButNotConnected = 0x20, kINQUIRY_PERIPHERAL_QUALIFIER_NotSupported = 0x60, kINQUIRY_PERIPHERAL_QUALIFIER_Mask = 0xE0 };

Constants
kINQUIRY_PERIPHERAL_QUALIFIER_Connected

Peripheral Device is connected. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_PERIPHERAL_QUALIFIER_SupportedButNotConnected

Peripheral Device is supported, but not connected. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_QUALIFIER_NotSupported

Peripheral Device is not supported. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_QUALIFIER_Mask

Mask to use for PERIPHERAL_DEVICE_TYPE field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1229

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Discussion Inquiry Peripheral Qualifier definitions

Protocol Identifier values

enum { kSCSIProtocolIdentifier_FibreChannel = 0, kSCSIProtocolIdentifier_ParallelSCSI = 1, kSCSIProtocolIdentifier_SSA = 2, kSCSIProtocolIdentifier_FireWire = 3, kSCSIProtocolIdentifier_RDMA = 4, kSCSIProtocolIdentifier_iSCSI = 5, kSCSIProtocolIdentifier_SAS = 6, kSCSIProtocolIdentifier_ADT = 7, kSCSIProtocolIdentifier_ATAPI = 8, // 0x9-xE Reserved kSCSIProtocolIdentifier_None = 0xF };

Constants
kSCSIProtocolIdentifier_FibreChannel

FibreChannel Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_ParallelSCSI

Parallel SCSI Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kSCSIProtocolIdentifier_SSA

SSA Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_FireWire

FireWire (IEEE-1394) Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1230

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kSCSIProtocolIdentifier_RDMA

RDMA Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_iSCSI

iSCSI Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_SAS

SAS Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_ADT

ADT Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_ATAPI

ATAPI Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kSCSIProtocolIdentifier_None

No Protocol Identifier. Available in OS X v10.5 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for the protocol identifier values.

Removable Bit field definitions

enum { kINQUIRY_PERIPHERAL_RMB_MediumFixed = 0x00, kINQUIRY_PERIPHERAL_RMB_MediumRemovable = 0x80, kINQUIRY_PERIPHERAL_RMB_BitMask = 0x80 };

1231

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Constants
kINQUIRY_PERIPHERAL_RMB_MediumFixed

Medium type is fixed disk. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_RMB_MediumRemovable

Medium type is removable disk. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_PERIPHERAL_RMB_BitMask

Mask to use for RMB field. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Inquiry Removable Bit field definitions

Response Data Format field definitions

enum { // Bit definitions // Bits 0-3: RESPONSE DATA FORMAT kINQUIRY_Byte3_HISUP_Bit = 4, kINQUIRY_Byte3_NORMACA_Bit = 5, // Bit 6 is Obsolete kINQUIRY_Byte3_AERC_Bit = 7, // Masks kINQUIRY_RESPONSE_DATA_FORMAT_Mask = 0x0F, // Bits 0-3 kINQUIRY_Byte3_HISUP_Mask = ( 1 << kINQUIRY_Byte3_HISUP_Bit), kINQUIRY_Byte3_NORMACA_Mask = ( 1 << kINQUIRY_Byte3_NORMACA_Bit), // Bit 6 is Obsolete kINQUIRY_Byte3_AERC_Mask = ( 1 << kINQUIRY_Byte3_AERC_Bit) };

1232

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Constants
kINQUIRY_Byte3_HISUP_Bit

HISUP bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte3_NORMACA_Bit

NORMACA bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte3_AERC_Bit

AERC bit definition. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_RESPONSE_DATA_FORMAT_Mask

Mask for valid bits for RESPONSE_DATA_FORMAT. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte3_HISUP_Mask

Mask to use to test the HISUP bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte3_NORMACA_Mask

Mask to use to test the NORMACA bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte3_AERC_Mask

Mask to use to test the AERC bit. Available in OS X v10.2 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for bits/masks in the INQUIRY RESPONSE_DATA_FORMAT field.

SCCS field definitions

enum { // Bit definitions

1233

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte5_SCCS_Bit = 7, kINQUIRY_Byte5_ACC_Bit = 6, kINQUIRY_Byte5_ExplicitTPGS_Bit = 5, kINQUIRY_Byte5_ImplicitTPGS_Bit = 4, kINQUIRY_Byte5_3PC_Bit = 3, // Bits 1-2: Reserved kINQUIRY_Byte5_PROTECT_Bit = 0, // Masks kINQUIRY_Byte5_SCCS_Mask = ( 1 << kINQUIRY_Byte5_SCCS_Bit), kINQUIRY_Byte5_ACC_Mask = ( 1 << kINQUIRY_Byte5_ACC_Bit), kINQUIRY_Byte5_ExplicitTPGS_Mask = ( 1 << kINQUIRY_Byte5_ExplicitTPGS_Bit), kINQUIRY_Byte5_ImplicitTPGS_Mask = ( 1 << kINQUIRY_Byte5_ImplicitTPGS_Bit), kINQUIRY_Byte5_3PC_Mask = ( 1 << kINQUIRY_Byte5_3PC_Bit), // Bits 1-2: Reserved kINQUIRY_Byte5_PROTECT_Mask = ( 1 << kINQUIRY_Byte5_PROTECT_Bit) };

Constants
kINQUIRY_Byte5_SCCS_Bit

SCCS bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte5_ACC_Bit

ACC bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte5_ExplicitTPGS_Bit

Explicit TPGS bit definition. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_ImplicitTPGS_Bit

Implicit TPGS bit definition. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1234

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_Byte5_3PC_Bit

3PC bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte5_PROTECT_Bit

PROTECT bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

kINQUIRY_Byte5_SCCS_Mask

Mask to use to test the SCCS bit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_ACC_Mask

Mask to use to test the ACC bit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_ExplicitTPGS_Mask

Mask to use for the Explicit TPGS bits. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_ImplicitTPGS_Mask

Mask to use for the Implicit TPGS bits. Available in OS X v10.7 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_3PC_Mask

Mask to use to test the 3PC bit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_Byte5_PROTECT_Mask

Mask to use to test the PROTECT bit. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for bits/masks in the INQUIRY SCCSReserved field.

1235

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

Version field definitions

enum { kINQUIRY_ISO_IEC_VERSION_Mask = 0xC0, kINQUIRY_ECMA_VERSION_Mask = 0x38, kINQUIRY_ANSI_VERSION_NoClaimedConformance = 0x00, kINQUIRY_ANSI_VERSION_SCSI_1_Compliant = 0x01, kINQUIRY_ANSI_VERSION_SCSI_2_Compliant = 0x02, kINQUIRY_ANSI_VERSION_SCSI_SPC_Compliant = 0x03, kINQUIRY_ANSI_VERSION_SCSI_SPC_2_Compliant = 0x04, kINQUIRY_ANSI_VERSION_SCSI_SPC_3_Compliant = 0x05, kINQUIRY_ANSI_VERSION_Mask = 0x07 };

Constants
kINQUIRY_ISO_IEC_VERSION_Mask

Mask for valid bits for ISO/IEC Version. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ECMA_VERSION_Mask

Mask for valid bits for ECMA Version. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_NoClaimedConformance

No ANSI conformance claimed by the device server. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_SCSI_1_Compliant

SCSI-1 conformance claimed by the device server. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_SCSI_2_Compliant

SCSI-2 conformance claimed by the device server. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_SCSI_SPC_Compliant

SPC conformance claimed by the device server. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.

1236

SCSICmds_INQUIRY_Definitions.h User-Space Reference Constants

kINQUIRY_ANSI_VERSION_SCSI_SPC_2_Compliant

SPC-2 conformance claimed by the device server. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_SCSI_SPC_3_Compliant

SPC-3 conformance claimed by the device server. Available in OS X v10.3 and later. Declared in SCSICmds_INQUIRY_Definitions.h.
kINQUIRY_ANSI_VERSION_Mask

Mask for valid bits for ANSI Version. Available in OS X v10.0 and later. Declared in SCSICmds_INQUIRY_Definitions.h. Discussion Definitions for bits/masks in the INQUIRY Version field.

1237

SCSICmds_MODE_Definitions.h User-Space Reference

Declared in SCSICmds_MODE_Definitions.h

Overview
This file contains all definitions for the data returned from the MODE_SENSE_6 and MODE_SENSE_10 commands.

Included Headers

Data Types
See the Overview for header-level documentation.

DASDModeParameterBlockDescriptor

typedef struct DASDModeParameterBlockDescriptor { UInt32 NUMBER_OF_BLOCKS; UInt8 DENSITY_CODE; UInt8 BLOCK_LENGTH[3]; } DASDModeParameterBlockDescriptor;

Discussion Direct Access Storage Device mode parameter block descriptor. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

1238

SCSICmds_MODE_Definitions.h User-Space Reference Data Types

LongLBAModeParameterBlockDescriptor

typedef struct LongLBAModeParameterBlockDescriptor { UInt64 NUMBER_OF_BLOCKS; UInt8 DENSITY_CODE; UInt8 RESERVED[3]; UInt32 BLOCK_LENGTH; } LongLBAModeParameterBlockDescriptor;

Discussion Long LBA mode parameter block descriptor. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

ModePageFormatHeader

typedef struct ModePageFormatHeader { UInt8 PS_PAGE_CODE; UInt8 PAGE_LENGTH; } ModePageFormatHeader;

Discussion Mode Page format header. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

ModeParameterBlockDescriptor

typedef struct ModeParameterBlockDescriptor { UInt8 DENSITY_CODE; UInt8 NUMBER_OF_BLOCKS[3]; UInt8 RESERVED; UInt8 BLOCK_LENGTH[3]; } ModeParameterBlockDescriptor;

1239

SCSICmds_MODE_Definitions.h User-Space Reference Data Types

Discussion General mode parameter block descriptor. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SBCModePageCaching

typedef struct SBCModePageCaching { ModePageFormatHeader header; UInt8 flags; UInt8 DEMAND_READ_WRITE_RETENTION_PRIORITY; UInt16 DISABLE_PREFETCH_TRANSFER_LENGTH; UInt16 MINIMUM_PREFETCH; UInt16 MAXIMUM_PREFETCH; UInt16 MAXIMUM_PREFETCH_CEILING; UInt8 flags2; UInt8 NUMBER_OF_CACHE_SEGMENTS; UInt16 CACHE_SEGMENT_SIZE; UInt8 RESERVED; UInt8 NON_CACHE_SEGMENT_SIZE[3]; } SBCModePageCaching;

Discussion Caching Mode Page (PAGE CODE 0x08) format. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SBCModePageFlexibleDisk

typedef struct SBCModePageFlexibleDisk { ModePageFormatHeader header; UInt16 TRANSFER_RATE; UInt8 NUMBER_OF_HEADS; UInt8 SECTORS_PER_TRACK;

1240

SCSICmds_MODE_Definitions.h User-Space Reference Data Types

UInt16 DATA_BYTES_PER_SECTOR; UInt16 NUMBER_OF_CYLINDERS; UInt16 STARTING_CYLINDER_WRITE_PRECOMPENSATION; UInt16 STARTING_CYLINDER_REDUCED_WRITE_CURRENT; UInt16 DEVICE_STEP_RATE; UInt8 DEVICE_STEP_PULSE_WIDTH; UInt16 HEAD_SETTLE_DELAY; UInt8 MOTOR_ON_DELAY; UInt8 MOTOR_OFF_DELAY; UInt8 TRDY_SSN_MO; UInt8 SPC; UInt8 WRITE_COMPENSATION; UInt8 HEAD_LOAD_DELAY; UInt8 HEAD_UNLOAD_DELAY; UInt8 PIN_34_PIN_2; UInt8 PIN_4_PIN_1; UInt16 MEDIUM_ROTATION_RATE; UInt8 RESERVED[2]; } SBCModePageFlexibleDisk;

Discussion Flexible Disk Mode Page (PAGE CODE 0x05) format. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SBCModePageFormatDevice

typedef struct SBCModePageFormatDevice { ModePageFormatHeader header; UInt16 TRACKS_PER_ZONE; UInt16 ALTERNATE_SECTORS_PER_ZONE; UInt16 ALTERNATE_TRACKS_PER_ZONE; UInt16 ALTERNATE_TRACKS_PER_LOGICAL_UNIT; UInt16 SECTORS_PER_TRACK; UInt16 DATA_BYTES_PER_PHYSICAL_SECTOR; UInt16 INTERLEAVE; UInt16 TRACK_SKEW_FACTOR; UInt16 CYLINDER_SKEW_FACTOR; UInt8 SSEC_HSEC_RMB_SURF; UInt8 RESERVED[3]; } SBCModePageFormatDevice;

1241

SCSICmds_MODE_Definitions.h User-Space Reference Data Types

Discussion Format Device Mode Page (PAGE CODE 0x03) format. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SBCModePageRigidDiskGeometry

typedef struct SBCModePageRigidDiskGeometry { ModePageFormatHeader header; UInt8 NUMBER_OF_CYLINDERS[3]; UInt8 NUMBER_OF_HEADS; UInt8 STARTING_CYLINDER_WRITE_PRECOMPENSATION[3]; UInt8 STARTING_CYLINDER_REDUCED_WRITE_CURRENT[3]; UInt16 DEVICE_STEP_RATE; UInt8 LANDING_ZONE_CYLINDER[3]; UInt8 RPL; UInt8 ROTATIONAL_OFFSET; UInt8 RESERVED; UInt16 MEDIUM_ROTATION_RATE; UInt8 RESERVED1[2]; } SBCModePageRigidDiskGeometry;

Discussion Rigid Disk Geometry Mode Page (PAGE CODE 0x04) format. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SPCModePagePowerCondition

typedef struct SPCModePagePowerCondition { ModePageFormatHeader header; UInt8 RESERVED; UInt8 IDLE_STANDBY; UInt32 IDLE_CONDITION_TIMER;

1242

SCSICmds_MODE_Definitions.h User-Space Reference Data Types

UInt32 STANDBY_CONDITION_TIMER; } SPCModePagePowerCondition;

Discussion Power Conditions Mode Page (PAGE CODE 0x1A) format. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SPCModeParameterHeader10

typedef struct SPCModeParameterHeader10 { UInt16 MODE_DATA_LENGTH; UInt8 MEDIUM_TYPE; UInt8 DEVICE_SPECIFIC_PARAMETER; UInt8 LONGLBA; UInt8 RESERVED; UInt16 BLOCK_DESCRIPTOR_LENGTH; } SPCModeParameterHeader10;

Discussion Mode Parameter Header for the MODE_SENSE_10 command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

SPCModeParameterHeader6

typedef struct SPCModeParameterHeader6 { UInt8 MODE_DATA_LENGTH; UInt8 MEDIUM_TYPE; UInt8 DEVICE_SPECIFIC_PARAMETER; UInt8 BLOCK_DESCRIPTOR_LENGTH; } SPCModeParameterHeader6;

1243

SCSICmds_MODE_Definitions.h User-Space Reference Constants

Discussion Mode Parameter Header for the MODE_SENSE_6 command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_MODE_Definitions.h

Constants
See the Overview for header-level documentation.

Caching flags bitfields

enum { kSBCModePageCaching_RCD_Bit = 0, kSBCModePageCaching_MF_Bit = 1, kSBCModePageCaching_WCE_Bit = 2, kSBCModePageCaching_SIZE_Bit = 3, kSBCModePageCaching_DISC_Bit = 4, kSBCModePageCaching_CAP_Bit = 5, kSBCModePageCaching_ABPF_Bit = 6, kSBCModePageCaching_IC_Bit = 7, kSBCModePageCaching_RCD_Mask = ( 1 << kSBCModePageCaching_RCD_Bit), kSBCModePageCaching_MF_Mask = ( 1 << kSBCModePageCaching_MF_Bit), kSBCModePageCaching_WCE_Mask = ( 1 << kSBCModePageCaching_WCE_Bit), kSBCModePageCaching_SIZE_Mask = ( 1 << kSBCModePageCaching_SIZE_Bit), kSBCModePageCaching_DISC_Mask = ( 1 << kSBCModePageCaching_DISC_Bit), kSBCModePageCaching_CAP_Mask = ( 1 << kSBCModePageCaching_CAP_Bit), kSBCModePageCaching_ABPF_Mask = ( 1 << kSBCModePageCaching_ABPF_Bit), kSBCModePageCaching_IC_Mask = ( 1 << kSBCModePageCaching_IC_Bit) };

1244

SCSICmds_MODE_Definitions.h User-Space Reference Constants

Constants
kSBCModePageCaching_RCD_Bit

RCD Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_MF_Bit

MF Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_WCE_Bit

WCE Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_SIZE_Bit

SIZE Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_DISC_Bit

DISC Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_CAP_Bit

CAP Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_ABPF_Bit

ABPF Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_IC_Bit

IC Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_RCD_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

1245

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kSBCModePageCaching_MF_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_WCE_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_SIZE_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_DISC_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_CAP_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_ABPF_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_IC_Mask

Mask for use with flags field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Caching flags field.

Caching flags2 bitfields

enum { // Bits 0:2 Reserved

1246

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kSBCModePageCaching_VS1_Bit = 3, kSBCModePageCaching_VS2_Bit = 4, kSBCModePageCaching_DRA_Bit = 5, kSBCModePageCaching_LBCSS_Bit = 6, kSBCModePageCaching_FSW_Bit = 7, kSBCModePageCaching_VS1_Mask = ( 1 << kSBCModePageCaching_VS1_Bit), kSBCModePageCaching_VS2_Mask = ( 1 << kSBCModePageCaching_VS2_Bit), kSBCModePageCaching_DRA_Mask = ( 1 << kSBCModePageCaching_DRA_Bit), kSBCModePageCaching_LBCSS_Mask = ( 1 << kSBCModePageCaching_LBCSS_Bit), kSBCModePageCaching_FSW_Mask = ( 1 << kSBCModePageCaching_FSW_Bit) };

Constants
kSBCModePageCaching_VS1_Bit

VS1 Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_VS2_Bit

VS2 Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_DRA_Bit

DRA Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_LBCSS_Bit

LBCSS Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageCaching_FSW_Bit

FSW Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

1247

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kSBCModePageCaching_VS1_Mask

Mask for use with flags2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_VS2_Mask

Mask for use with flags2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_DRA_Mask

Mask for use with flags2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_LBCSS_Mask

Mask for use with flags2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCaching_FSW_Mask

Mask for use with flags2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Caching flags2 field.

Demand Read/Write Retention masks

enum { kSBCModePageCaching_DEMAND_WRITE_Mask = 0x00FF, kSBCModePageCaching_DEMAND_READ_Mask = 0xFF00 };

Constants
kSBCModePageCaching_DEMAND_WRITE_Mask

Mask for the DEMAND_READ_WRITE_RETENTION_PRIORITY field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

1248

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kSBCModePageCaching_DEMAND_READ_Mask

Mask for the DEMAND_READ_WRITE_RETENTION_PRIORITY field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Demand Read/Write Retention masks.

Device Specific Parameter Bitfield definitions

enum { kModeSenseSBCDeviceSpecific_DPOFUABit = 4, kModeSenseSBCDeviceSpecific_WriteProtectBit = 7, kModeSenseSBCDeviceSpecific_DPOFUAMask = ( 1 << kModeSenseSBCDeviceSpecific_DPOFUABit), kModeSenseSBCDeviceSpecific_WriteProtectMask = ( 1 << kModeSenseSBCDeviceSpecific_WriteProtectBit) };

Constants
kModeSenseSBCDeviceSpecific_DPOFUABit

Bit to indicate DPO and FUA bits are accepted by the device server. Available in OS X v10.6 and later. Declared in SCSICmds_MODE_Definitions.h.
kModeSenseSBCDeviceSpecific_WriteProtectBit

Bit to indicate medium is write protected. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kModeSenseSBCDeviceSpecific_DPOFUAMask

Mask to test for kModeSenseSBCDeviceSpecific_DPOFUABit. Available in OS X v10.6 and later. Declared in SCSICmds_MODE_Definitions.h.
kModeSenseSBCDeviceSpecific_WriteProtectMask

Mask to test for kModeSenseSBCDeviceSpecific_WriteProtectBit. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion SBC definitions for Device Specific Parameter in the Mode Sense Header Block.

1249

SCSICmds_MODE_Definitions.h User-Space Reference Constants

Long LBA Bitfield definitions

enum { kModeSenseParameterHeader10_LongLBABit = 0, kModeSenseParameterHeader10_LongLBAMask = ( 1 << kModeSenseParameterHeader10_LongLBABit), };

Constants
kModeSenseParameterHeader10_LongLBABit

Bit to indicate Long LBA block descriptors follow. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kModeSenseParameterHeader10_LongLBAMask

Mask to test for kModeSenseParameterHeader10_LongLBABit. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Long LBA Bitfield definitions for Mode Parameter Header for MODE_SENSE_10 command.

Mode Page Format bit definitions

enum { kModePageFormat_PS_Bit = 7, kModePageFormat_PAGE_CODE_Mask = 0x3F, kModePageFormat_PS_Mask = ( 1 << kModePageFormat_PS_Bit) };

Constants
kModePageFormat_PS_Bit

Bit to indicate Parameters Saveable. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kModePageFormat_PAGE_CODE_Mask

Mask to obtain the PAGE_CODE from the PS_PAGE_CODE field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

1250

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kModePageFormat_PS_Mask

Mask to test for kModePageFormat_PS_Bit. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Mode Page Format bit definitions.

PIN_34_PIN_2 bitfields

enum { kSBCModePageFlexibleDisk_PIN_2_Mask = 0x0F, kSBCModePageFlexibleDisk_PIN_34_Mask = 0xF0 };

Constants
kSBCModePageFlexibleDisk_PIN_2_Mask

Mask for use with PIN_34_PIN_2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageFlexibleDisk_PIN_34_Mask

Mask for use with PIN_34_PIN_2 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Flexible Disk PIN_34_PIN_2 field.

PIN_4_PIN_1 bitfields

enum { kSBCModePageFlexibleDisk_PIN_1_Mask = 0x0F, kSBCModePageFlexibleDisk_PIN_4_Mask = 0xF0 };

1251

SCSICmds_MODE_Definitions.h User-Space Reference Constants

Constants
kSBCModePageFlexibleDisk_PIN_1_Mask

Mask for use with PIN_4_PIN_1 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageFlexibleDisk_PIN_4_Mask

Mask for use with PIN_4_PIN_1 field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Flexible Disk PIN_4_PIN_1 field.

Rigid Disk Geometry bitfields

enum { kSBCModePageRigidDiskGeometry_RPL_Mask = 0x03 };

Constants
kSBCModePageRigidDiskGeometry_RPL_Mask

Mask for use with the RPL field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field masks for Rigid Disk Geometry structure fields.

SBC Mode Pages

enum { kSBCModePageFormatDeviceCode = 0x03, kSBCModePageRigidDiskGeometryCode = 0x04, kSBCModePageFlexibleDiskCode = 0x05, kSBCModePageCachingCode = 0x08 };

1252

SCSICmds_MODE_Definitions.h User-Space Reference Constants

Constants
kSBCModePageFormatDeviceCode

Format Device Mode Page value. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageRigidDiskGeometryCode

Rigid Disk Geometry Page value. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageFlexibleDiskCode

Flexible Disk Page value. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageCachingCode

Caching Page value. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion SBC Mode Page definitions.

SPC bitfields

enum { kSBCModePageFlexibleDisk_SPC_Mask = 0x0F };

Constants
kSBCModePageFlexibleDisk_SPC_Mask

Mask for use with SPC field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Flexible Disk SPC field.

1253

SCSICmds_MODE_Definitions.h User-Space Reference Constants

SPC Mode Pages

enum { kSPCModePagePowerConditionCode = 0x1A, kSPCModePageAllPagesCode = 0x3F };

Constants
kSPCModePagePowerConditionCode

Power Conditions Mode Page value. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSPCModePageAllPagesCode

All Mode Pages value. Available in OS X v10.5 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion SPC Mode Page definitions.

TRDY_SSN_MO bitfields

enum { // Bits 0:4 Reserved kSBCModePageFlexibleDisk_MO_Bit = 5, kSBCModePageFlexibleDisk_SSN_Bit = 6, kSBCModePageFlexibleDisk_TRDY_Bit = 7, kSBCModePageFlexibleDisk_MO_Mask = ( 1 << kSBCModePageFlexibleDisk_MO_Bit), kSBCModePageFlexibleDisk_SSN_Mask = ( 1 << kSBCModePageFlexibleDisk_SSN_Bit), kSBCModePageFlexibleDisk_TRDY_Mask = ( 1 << kSBCModePageFlexibleDisk_TRDY_Bit) };

Constants
kSBCModePageFlexibleDisk_MO_Bit

MO Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

1254

SCSICmds_MODE_Definitions.h User-Space Reference Constants

kSBCModePageFlexibleDisk_SSN_Bit

SSN Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageFlexibleDisk_TRDY_Bit

TRDY Bit definition. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.

kSBCModePageFlexibleDisk_MO_Mask

Mask for use with TRDY_SSN_MO field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageFlexibleDisk_SSN_Mask

Mask for use with TRDY_SSN_MO field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h.
kSBCModePageFlexibleDisk_TRDY_Mask

Mask for use with TRDY_SSN_MO field. Available in OS X v10.3 and later. Declared in SCSICmds_MODE_Definitions.h. Discussion Bit field definitions and masks for Flexible Disk TRDY_SSN_MO field.

1255

SCSICmds_READ_CAPACITY_Definitions.h User-Space Reference

Declared in SCSICmds_READ_CAPACITY_Definitions.h

Overview
This file contains all definitions for the data returned from the READ CAPACITY 10 (0x25) and READ CAPACITY 16 (0x9E) commands.

Included Headers

Data Types
See the Overview for header-level documentation.

SCSI_Capacity_Data

typedef struct SCSI_Capacity_Data { UInt32 RETURNED_LOGICAL_BLOCK_ADDRESS; UInt32 BLOCK_LENGTH_IN_BYTES; } SCSI_Capacity_Data;

Discussion Capacity return structure for READ CAPACITY 10 command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_READ_CAPACITY_Definitions.h

1256

SCSICmds_READ_CAPACITY_Definitions.h User-Space Reference Constants

SCSI_Capacity_Data_Long

typedef struct SCSI_Capacity_Data_Long { UInt64 RETURNED_LOGICAL_BLOCK_ADDRESS; UInt32 BLOCK_LENGTH_IN_BYTES; UInt8 RTO_EN_PROT_EN; UInt8 Reserved[19]; } SCSI_Capacity_Data_Long;

Discussion Capacity return structure for READ CAPACITY 16 command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_READ_CAPACITY_Definitions.h

Constants
See the Overview for header-level documentation.

Defines

#define kREPORT_CAPACITY_16_MaximumLBA 0xFFFFFFFFFFFFFFFFULL #define kREPORT_CAPACITY_MaximumLBA 0xFFFFFFFFUL

Constants
kREPORT_CAPACITY_16_MaximumLBA

Maximum LBA supported via READ CAPACITY 16 command. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.
kREPORT_CAPACITY_MaximumLBA

Maximum LBA supported via READ CAPACITY 10 command. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.

1257

SCSICmds_READ_CAPACITY_Definitions.h User-Space Reference Constants

PROTECTION INFORMATION definitions

enum { kREAD_CAPACITY_PROT_Enabled = 0x01, kREAD_CAPACITY_PROT_Disabled = 0x00, kREAD_CAPACITY_PROT_Mask = 0x01 };

Constants
kREAD_CAPACITY_PROT_Enabled

Protection Information enabled. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.

kREAD_CAPACITY_PROT_Disabled

Protection Information disabled. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.

kREAD_CAPACITY_PROT_Mask

Mask to use when checking the RTO_EN_PROT_EN field. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h. Discussion Values for the PROTECTION INFORMATION (PROT_EN) bit in the READ CAPACITY Long Data structure.

READ CAPACITY Payload Sizes

enum { kREPORT_CAPACITY_DataSize = 8, kREPORT_CAPACITY_16_DataSize = 32 };

Constants
kREPORT_CAPACITY_DataSize

Data size for a READ_CAPACITY command. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.

1258

SCSICmds_READ_CAPACITY_Definitions.h User-Space Reference Constants

kREPORT_CAPACITY_16_DataSize

Data size for a READ_CAPACITY_16 command. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h. Discussion Sizes of the payload for the READ CAPACITY 10 and READ CAPACITY 16 commands.

RTO_EN definitions

enum { kREAD_CAPACITY_RTO_Enabled = 0x02, kREAD_CAPACITY_RTO_Disabled = 0x00, kREAD_CAPACITY_RTO_Mask = 0x02 };

Constants
kREAD_CAPACITY_RTO_Enabled

Reference Tag Own enabled. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.
kREAD_CAPACITY_RTO_Disabled

Reference Tag Own disabled. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h.
kREAD_CAPACITY_RTO_Mask

Mask to use when checking the RTO_EN_PROT_EN field. Available in OS X v10.3 and later. Declared in SCSICmds_READ_CAPACITY_Definitions.h. Discussion Values for the REFERENCE TAG OWN (RTO_EN) bit in the READ CAPACITY Long Data structure.

1259

SCSICmds_REPORT_LUNS_Definitions.h User-Space Reference

Declared in SCSICmds_REPORT_LUNS_Definitions.h

Overview
This file contains all definitions for the data returned from the REPORT_LUNS (0xA0) command.

Included Headers

Data Types
See the Overview for header-level documentation.

REPORT_LUNS_LOGICAL_UNIT_ADDRESSING

typedef struct REPORT_LUNS_LOGICAL_UNIT_ADDRESSING { #ifdef __LITTLE_ENDIAN__ UInt16 LUN : 5; UInt16 BUS_NUMBER : 3; UInt16 TARGET : 6; UInt16 reserved2 : 1; UInt16 reserved : 1; #else /* !__LITTLE_ENDIAN__ */ UInt16 reserved : 1; UInt16 reserved2 : 1; UInt16 TARGET : 6; UInt16 BUS_NUMBER : 3; UInt16 LUN : 5; #endif /* !__LITTLE_ENDIAN__ */ } REPORT_LUNS_LOGICAL_UNIT_ADDRESSING;

1260

SCSICmds_REPORT_LUNS_Definitions.h User-Space Reference Data Types

Discussion This structure represents a LUN Addressing scheme. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_REPORT_LUNS_Definitions.h

REPORT_LUNS_PERIPHERAL_DEVICE_ADDRESSING

typedef struct REPORT_LUNS_PERIPHERAL_DEVICE_ADDRESSING { #ifdef __LITTLE_ENDIAN__ UInt16 TARGET_LUN : 8; UInt16 BUS_IDENTIFIER : 6; UInt16 reserved2 : 1; UInt16 reserved : 1; #else /* !__LITTLE_ENDIAN__ */ UInt16 reserved : 1; UInt16 reserved2 : 1; UInt16 BUS_IDENTIFIER : 6; UInt16 TARGET_LUN : 8; #endif /* !__LITTLE_ENDIAN__ */ } REPORT_LUNS_PERIPHERAL_DEVICE_ADDRESSING;

Discussion This structure represents a Peripheral Device Addressing scheme. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_REPORT_LUNS_Definitions.h

SCSICmd_REPORT_LUNS_LUN_ENTRY

typedef struct SCSICmd_REPORT_LUNS_LUN_ENTRY { UInt16 FIRST_LEVEL_ADDRESSING; UInt16 SECOND_LEVEL_ADDRESSING; UInt16 THIRD_LEVEL_ADDRESSING; UInt16 FOURTH_LEVEL_ADDRESSING; } SCSICmd_REPORT_LUNS_LUN_ENTRY;

1261

SCSICmds_REPORT_LUNS_Definitions.h User-Space Reference Constants

Discussion This structure represents a single LUN entry in a LUN list returned via the REPORT_LUNS command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_REPORT_LUNS_Definitions.h

SCSICmd_REPORT_LUNS_Header

typedef struct SCSICmd_REPORT_LUNS_Header { UInt32 LUN_LIST_LENGTH; // LUN list length in bytes. UInt32 RESERVED; SCSICmd_REPORT_LUNS_LUN_ENTRY LUN[1]; // Variable length list. Must have at least LUN 0 if } SCSICmd_REPORT_LUNS_Header; // Target supports REPORT_LUNS command.

Discussion This structure defines the format of the data that is returned for the REPORT_LUNS command. Availability Available in OS X v10.3 and later. Declared in
SCSICmds_REPORT_LUNS_Definitions.h

Constants
See the Overview for header-level documentation.

Defines

#define kREPORT_LUNS_HeaderSize 8

1262

SCSICmds_REPORT_LUNS_Definitions.h User-Space Reference Constants

Constants
kREPORT_LUNS_HeaderSize

Size of the REPORT_LUNS header as defined in the SPC-3 specification. Available in OS X v10.3 and later. Declared in SCSICmds_REPORT_LUNS_Definitions.h.

REPORT_LUNS addressing methods.

enum { kREPORT_LUNS_ADDRESS_METHOD_PERIPHERAL_DEVICE = 0, kREPORT_LUNS_ADDRESS_METHOD_FLAT_SPACE = 1, kREPORT_LUNS_ADDRESS_DEVICE_TYPE_SPECIFIC = kREPORT_LUNS_ADDRESS_METHOD_FLAT_SPACE, kREPORT_LUNS_ADDRESS_METHOD_LOGICAL_UNIT = 2, // Reserved [3] kREPORT_LUNS_ADDRESS_METHOD_OFFSET = 14 };

Constants
kREPORT_LUNS_ADDRESS_METHOD_PERIPHERAL_DEVICE

Peripheral Device Addressing Method. Available in OS X v10.3 and later. Declared in SCSICmds_REPORT_LUNS_Definitions.h.
kREPORT_LUNS_ADDRESS_DEVICE_TYPE_SPECIFIC

Device Type Specific Addressing Method. Available in OS X v10.3 and later. Declared in SCSICmds_REPORT_LUNS_Definitions.h.
kREPORT_LUNS_ADDRESS_METHOD_LOGICAL_UNIT

Logical Unit Specific Addressing Method. Available in OS X v10.3 and later. Declared in SCSICmds_REPORT_LUNS_Definitions.h.
kREPORT_LUNS_ADDRESS_METHOD_OFFSET

Offset to the address method data. Available in OS X v10.3 and later. Declared in SCSICmds_REPORT_LUNS_Definitions.h. Discussion REPORT_LUNS addressing methods described in SAM-2 documents.

1263

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference

Declared in SCSICmds_REQUEST_SENSE_Defs.h

Overview
This file contains all definitions for the data returned from the REQUEST SENSE (0x03) command and from auto sense on protocols that support it.

Included Headers

Data Types
See the Overview for header-level documentation.

SCSI_Sense_Data

typedef struct SCSI_Sense_Data { UInt8 VALID_RESPONSE_CODE; // 7 = Valid. 6-0 = Response Code. UInt8 SEGMENT_NUMBER; // Segment number UInt8 SENSE_KEY; // 7 = FILEMARK, 6 = EOM, 5 = ILI, 3-0 = SENSE KEY. UInt8 INFORMATION_1; // INFORMATION. UInt8 INFORMATION_2; // INFORMATION. UInt8 INFORMATION_3; // INFORMATION. UInt8 INFORMATION_4; // INFORMATION. UInt8 ADDITIONAL_SENSE_LENGTH; // Number of additional bytes available in sense data UInt8 COMMAND_SPECIFIC_INFORMATION_1; // Command Specific Information UInt8 COMMAND_SPECIFIC_INFORMATION_2; // Command Specific Information UInt8 COMMAND_SPECIFIC_INFORMATION_3; // Command Specific Information UInt8 COMMAND_SPECIFIC_INFORMATION_4; // Command Specific Information UInt8 ADDITIONAL_SENSE_CODE; // Additional Sense Code UInt8 ADDITIONAL_SENSE_CODE_QUALIFIER; // Additional Sense Code Qualifier

1264

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

UInt8 FIELD_REPLACEABLE_UNIT_CODE; // Field Replaceable Unit Code UInt8 SKSV_SENSE_KEY_SPECIFIC_MSB; // 7 = Sense Key Specific Valid bit, 6-0 Sense Key Specific MSB UInt8 SENSE_KEY_SPECIFIC_MID; // Sense Key Specific Middle UInt8 SENSE_KEY_SPECIFIC_LSB; // Sense Key Specific LSB } SCSI_Sense_Data;

Discussion The basic SCSI Request Sense data structure. Availability Available in OS X v10.0 and later. Declared in
SCSICmds_REQUEST_SENSE_Defs.h

Constants
See the Overview for header-level documentation.

EOM bit field definitions

enum { kSENSE_EOM_Set = 0x40, kSENSE_EOM_Not_Set = 0x00, kSENSE_EOM_Mask = 0x40 };

Constants
kSENSE_EOM_Set

End Of Medium bit is set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_EOM_Not_Set

End Of Medium bit is not set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_EOM_Mask

Mask to use when checking the SENSE_KEY field for the EOM bit. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.

1265

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

Discussion Masks and values to determine the End Of Medium bit field.

FILEMARK bit field definitions

enum { kSENSE_FILEMARK_Set = 0x80, kSENSE_FILEMARK_Not_Set = 0x00, kSENSE_FILEMARK_Mask = 0x80 };

Constants
kSENSE_FILEMARK_Set

Filemark bit is set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.

kSENSE_FILEMARK_Not_Set

Filemark bit is not set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_FILEMARK_Mask

Mask to use when checking the SENSE_KEY field for the FILEMARK bit. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h. Discussion Masks and values to determine the FileMark bit field.

ILI bit field definitions

enum { kSENSE_ILI_Set = 0x20, kSENSE_ILI_Not_Set = 0x00, kSENSE_ILI_Mask = 0x20 };

1266

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

Constants
kSENSE_ILI_Set

Incorrect Length Indicator bit is set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_ILI_Not_Set

Incorrect Length Indicator bit is not set. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_ILI_Mask

Mask to use when checking the SENSE_KEY field for the ILI bit. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h. Discussion Masks and values to determine the Incorrect Length Indicator bit field.

kSenseDefaultSize

enum { kSenseDefaultSize = 18 };

Discussion The default size for SCSI Request Sense data.

Sense Key definitions

enum { kSENSE_KEY_NO_SENSE = 0x00, kSENSE_KEY_RECOVERED_ERROR = 0x01, kSENSE_KEY_NOT_READY = 0x02, kSENSE_KEY_MEDIUM_ERROR = 0x03, kSENSE_KEY_HARDWARE_ERROR = 0x04, kSENSE_KEY_ILLEGAL_REQUEST = 0x05, kSENSE_KEY_UNIT_ATTENTION = 0x06, kSENSE_KEY_DATA_PROTECT = 0x07, kSENSE_KEY_BLANK_CHECK = 0x08, kSENSE_KEY_VENDOR_SPECIFIC = 0x09,

1267

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

kSENSE_KEY_COPY_ABORTED = 0x0A, kSENSE_KEY_ABORTED_COMMAND = 0x0B, /* SENSE KEY x0C is obsoleted */ kSENSE_KEY_VOLUME_OVERFLOW = 0x0D, kSENSE_KEY_MISCOMPARE = 0x0E, /* SENSE KEY x0F is reserved */ kSENSE_KEY_Mask = 0x0F };

Constants
kSENSE_KEY_NO_SENSE

No sense data is present. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.

kSENSE_KEY_RECOVERED_ERROR

A recovered error has occurred. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_NOT_READY

Device server is not ready. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_MEDIUM_ERROR

Device server detected a medium error. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_HARDWARE_ERROR

Device server detected a hardware error. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_ILLEGAL_REQUEST

Device server detected an illegal request. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_UNIT_ATTENTION

Device server indicates a unit attention condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.

1268

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

kSENSE_KEY_DATA_PROTECT

Device server indicates a data protect condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_BLANK_CHECK

Device server indicates a blank check condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_VENDOR_SPECIFIC

Device server indicates a vendor specific condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_COPY_ABORTED

Device server indicates a copy aborted condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_ABORTED_COMMAND

Device server indicates an aborted command condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_VOLUME_OVERFLOW

Device server indicates a volume overflow condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_MISCOMPARE

Device server indicates a miscompare condition. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_KEY_Mask

Mask to use when checking the SENSE_KEY field for the SENSE_KEY value. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h. Discussion Masks and values to determine the SENSE_KEY.

1269

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

Sense Response Codes

enum { kSENSE_RESPONSE_CODE_Current_Errors = 0x70, kSENSE_RESPONSE_CODE_Deferred_Errors = 0x71, kSENSE_RESPONSE_CODE_Mask = 0x7F };

Constants
kSENSE_RESPONSE_CODE_Current_Errors

Response code indicating current errors are reported. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_RESPONSE_CODE_Deferred_Errors

Response code indicating deferred errors are reported. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_RESPONSE_CODE_Mask

Mask to use when checking the VALID_RESPONSE_CODE field. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h. Discussion Masks and values to determine the Response Code.

Sense Valid

enum { kSENSE_DATA_VALID = 0x80, kSENSE_NOT_DATA_VALID = 0x00, kSENSE_DATA_VALID_Mask = 0x80 };

Constants
kSENSE_DATA_VALID

Sense data is valid. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.

1270

SCSICmds_REQUEST_SENSE_Defs.h User-Space Reference Constants

kSENSE_NOT_DATA_VALID

Sense data is not valid. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h.
kSENSE_DATA_VALID_Mask

Validity mask to use when checking the VALID_RESPONSE_CODE field. Available in OS X v10.0 and later. Declared in SCSICmds_REQUEST_SENSE_Defs.h. Discussion Masks to use to determine if sense data is valid or not.

1271

SCSICommandDefinitions.h User-Space Reference

Declared in

SCSICommandDefinitions.h

Overview
This file contains all the definitions for types and constants that are used by the command set classes for building CDBs. The field type definitions are used for the parameters passed to a method that builds and sends any SCSI defined command to clearly identify the type of value expected for a parameter. The command methods will then use the appropriate mask to verify that the value passed into a parameter is of the specified type. Currently only types and masks are defined for 8 bytes and smaller fields. If a command is defined that uses a larger field, these should be expanded to include those sizes.

Included Headers

Data Types
See the Overview for header-level documentation.

SCSICmdField10Bit

typedef UInt16 SCSICmdField10Bit;

Availability Available in OS X v10.0 and later.

1272

SCSICommandDefinitions.h User-Space Reference Data Types

Declared in
SCSICommandDefinitions.h

SCSICmdField11Bit

typedef UInt16 SCSICmdField11Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField12Bit

typedef UInt16 SCSICmdField12Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField13Bit

typedef UInt16 SCSICmdField13Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField14Bit

typedef UInt16 SCSICmdField14Bit;

1274

SCSICommandDefinitions.h User-Space Reference Data Types

1275

SCSICommandDefinitions.h User-Space Reference Data Types

SCSICmdField21Bit

typedef UInt32 SCSICmdField21Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField22Bit

typedef UInt32 SCSICmdField22Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField23Bit

typedef UInt32 SCSICmdField23Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField25Bit

typedef UInt32 SCSICmdField25Bit;

Availability Available in OS X v10.0 and later.

1276

SCSICommandDefinitions.h User-Space Reference Data Types

Declared in
SCSICommandDefinitions.h

SCSICmdField26Bit

typedef UInt32 SCSICmdField26Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField27Bit

typedef UInt32 SCSICmdField27Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField28Bit

typedef UInt32 SCSICmdField28Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField29Bit

typedef UInt32 SCSICmdField29Bit;

1278

SCSICommandDefinitions.h User-Space Reference Data Types

1279

SCSICommandDefinitions.h User-Space Reference Data Types

SCSICmdField36Bit

typedef UInt64 SCSICmdField36Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField37Bit

typedef UInt64 SCSICmdField37Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField38Bit

typedef UInt64 SCSICmdField38Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField39Bit

typedef UInt64 SCSICmdField39Bit;

Availability Available in OS X v10.3 and later.

1280

SCSICommandDefinitions.h User-Space Reference Data Types

Declared in
SCSICommandDefinitions.h

SCSICmdField3Bit

typedef UInt8 SCSICmdField3Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField3Byte

typedef UInt32 SCSICmdField3Byte;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField41Bit

typedef UInt64 SCSICmdField41Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField42Bit

typedef UInt64 SCSICmdField42Bit;

1282

SCSICommandDefinitions.h User-Space Reference Data Types

1283

SCSICommandDefinitions.h User-Space Reference Data Types

SCSICmdField4Byte

typedef UInt32 SCSICmdField4Byte;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField50Bit

typedef UInt64 SCSICmdField50Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField51Bit

typedef UInt64 SCSICmdField51Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField52Bit

typedef UInt64 SCSICmdField52Bit;

Availability Available in OS X v10.3 and later.

1284

SCSICommandDefinitions.h User-Space Reference Data Types

Declared in
SCSICommandDefinitions.h

SCSICmdField53Bit

typedef UInt64 SCSICmdField53Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField54Bit

typedef UInt64 SCSICmdField54Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField55Bit

typedef UInt64 SCSICmdField55Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField57Bit

typedef UInt64 SCSICmdField57Bit;

1286

SCSICommandDefinitions.h User-Space Reference Data Types

1287

SCSICommandDefinitions.h User-Space Reference Data Types

SCSICmdField63Bit

typedef UInt64 SCSICmdField63Bit;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField6Bit

typedef UInt8 SCSICmdField6Bit;

Availability Available in OS X v10.0 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField6Byte

typedef UInt64 SCSICmdField6Byte;

Availability Available in OS X v10.3 and later. Declared in

SCSICommandDefinitions.h

SCSICmdField7Bit

typedef UInt8 SCSICmdField7Bit;

Availability Available in OS X v10.0 and later.

Constants
kSCSICmdFieldMask10Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask11Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask12Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask13Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask14Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask15Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask17Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1291

SCSICommandDefinitions.h User-Space Reference Constants

kSCSICmdFieldMask18Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask19Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask1Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask20Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask21Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask22Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask23Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask25Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask26Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask27Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask28Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask29Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1292

SCSICommandDefinitions.h User-Space Reference Constants

kSCSICmdFieldMask2Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask2Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask30Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask31Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask33Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask34Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask35Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask36Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask37Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask38Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask39Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask3Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1293

SCSICommandDefinitions.h User-Space Reference Constants

kSCSICmdFieldMask3Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask41Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask42Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask43Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask44Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask45Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask46Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask47Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask49Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask4Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask4Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask50Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1294

SCSICommandDefinitions.h User-Space Reference Constants

kSCSICmdFieldMask51Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask52Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask53Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask54Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask55Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask57Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask58Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask59Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask5Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask5Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask60Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask61Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1295

SCSICommandDefinitions.h User-Space Reference Constants

kSCSICmdFieldMask62Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask63Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask6Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask6Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask7Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask7Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask8Byte

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

kSCSICmdFieldMask9Bit

Available in OS X v10.3 and later. Declared in SCSICommandDefinitions.h.

1296

SCSITask.h User-Space Reference

Declared in

SCSITask.h

Overview
SCSITask typedefs and constants used inside the kernel and user space. Note that the SCSITaskIdentifier is an opaque object and that directly casting the SCSITaskIdentifier to any other type is discouraged. The SCSITask implementation changes when necessary to accomodate architectural changes, performance improvements, and bug fixes. Device and protocol layer drivers that need to access information contained in a SCSITask should use the appropriate accessor methods in IOSCSIPrimaryCommandsDevice.h or IOSCSIProtocolServices.h

Included Headers

<IOKit/IOTypes.h> <CoreFoundation/CoreFoundation.h> <libkern/c++/OSObject.h>

Callbacks
See the Overview for header-level documentation.

SCSITaskCompletion

typedef void ( *SCSITaskCompletion )( SCSITaskIdentifier completedTask );

Discussion This is the typedef for completion routines that work with SCSITaskIdentifiers.

1297

SCSITask.h User-Space Reference Data Types

Availability Available in OS X v10.7 through OS X v10.7. Declared in

SCSITask.h

Data Types
See the Overview for header-level documentation.

SCSIDeviceIdentifier
64-bit number to represent a SCSI Device.

typedef UInt64 SCSIDeviceIdentifier;

Discussion If the identifier can either be that of an initiator or a target, SCSIDeviceIdentifier should be used. Availability Available in OS X v10.2 and later. Declared in
SCSITask.h

SCSIInitiatorIdentifier
64-bit number to represent a SCSI Initiator Device.

typedef SCSIDeviceIdentifier SCSIInitiatorIdentifier;

Discussion If the identifier is for an initiator only and not a target, then SCSIInitiatorIdentifier should be used. Availability Available in OS X v10.2 and later. Declared in
SCSITask.h

1298

SCSITask.h User-Space Reference Data Types

SCSIServiceResponse
Attributes for task service response.

typedef enum SCSIServiceResponse { /*! */ kSCSIServiceResponse_Request_In_Process = 0, /*! */ kSCSIServiceResponse_SERVICE_DELIVERY_OR_TARGET_FAILURE = 1, /*! */ kSCSIServiceResponse_TASK_COMPLETE = 2, /*! */ kSCSIServiceResponse_LINK_COMMAND_COMPLETE = 3, /*! */ kSCSIServiceResponse_FUNCTION_COMPLETE = 4, /*! */ kSCSIServiceResponse_FUNCTION_REJECTED = 5 } SCSIServiceResponse;

Constants
kSCSIServiceResponse_Request_In_Process

Not defined in SAM specification, but is a service response used for asynchronous commands that are not yet completed. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSIServiceResponse_SERVICE_DELIVERY_OR_TARGET_FAILURE

The service request failed because of a delivery or target failure. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSIServiceResponse_TASK_COMPLETE

The task completed. Available in OS X v10.0 and later. Declared in SCSITask.h.

kSCSIServiceResponse_LINK_COMMAND_COMPLETE

The linked command completed. Available in OS X v10.0 and later. Declared in SCSITask.h.

1299

SCSITask.h User-Space Reference Data Types

kSCSIServiceResponse_FUNCTION_COMPLETE

The task management function completed. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSIServiceResponse_FUNCTION_REJECTED

The task management function was rejected. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion The Service Response represents the execution status of a service request made to a Protocol Services Driver. The Service Response can only be modified by the SCSI Protocol Layer. The SCSI Application Layer can only read the state. Availability Available in OS X v10.0 and later. Declared in
SCSITask.h

SCSITaggedTaskIdentifier
64-bit number to represent a unique task identifier.

typedef UInt64 SCSITaggedTaskIdentifier;

Discussion The Tagged Task Identifier is used when a Task has a Task Attribute other than SIMPLE. The SCSI Application Layer client that controls the Logical Unit for which a Task is intended is required to guarantee that the Task Tag Identifier is unique. Zero cannot be used a a Tag value as this is used to when a Tagged Task Identifier value is needed for a Task with a SIMPLE attribute. Availability Available in OS X v10.2 and later. Declared in
SCSITask.h

1300

SCSITask.h User-Space Reference Data Types

SCSITargetIdentifier
64-bit number to represent a SCSI Target Device.

typedef SCSIDeviceIdentifier SCSITargetIdentifier;

Discussion If the identifier is for a target only and not an initiator, then SCSITargetIdentifier should be used. Availability Available in OS X v10.2 and later. Declared in
SCSITask.h

SCSITaskAttribute
Attributes for task delivery.

typedef enum SCSITaskAttribute { kSCSITask_SIMPLE = 0, kSCSITask_ORDERED = 1, kSCSITask_HEAD_OF_QUEUE = 2, kSCSITask_ACA = 3 } SCSITaskAttribute;

Constants
kSCSITask_SIMPLE

The task has a simple attribute. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITask_ORDERED

The task has an ordered attribute. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITask_HEAD_OF_QUEUE

The task has a head-of-queue attribute. Available in OS X v10.0 and later. Declared in SCSITask.h.

1301

SCSITask.h User-Space Reference Data Types

kSCSITask_ACA

The task has an auto-contingent-allegiance attribute. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion The Task Attribute defines how this task should be managed when determing order for queueing and submission to the appropriate device server. The Task Attribute is set by the SCSI Application Layer and cannot be modified by the SCSI Protocol Layer. Availability Available in OS X v10.0 and later. Declared in
SCSITask.h

SCSITaskIdentifier

typedef OSObject * SCSITaskIdentifier;

Discussion This is an opaque object that represents a task. This is used so that drivers for both the SCSI Protocol Layer and the SCSI Application Layer cannot modify the SCSITask object directly but must instead use the inherited methods to do so. This allows the implementation of SCSITask to change without directly impacting device and protocol layer drivers. In addition, it prevents changing of properties that are not allowed to be changed by a given layer. Availability Available in OS X v10.7 through OS X v10.7. Declared in
SCSITask.h

SCSITaskMode

typedef enum SCSITaskMode { kSCSITaskMode_CommandExecution = 1, kSCSITaskMode_Autosense = 2 } SCSITaskMode;

1302

SCSITask.h User-Space Reference Data Types

Discussion The SCSI Task mode is used by the SCSI Protocol Layer to indicate what mode the task is executing. Availability Available in OS X v10.7 through OS X v10.7. Declared in
SCSITask.h

SCSITaskState
Attributes for task state.

typedef enum SCSITaskState { kSCSITaskState_NEW_TASK = 0, kSCSITaskState_ENABLED = 1, kSCSITaskState_BLOCKED = 2, kSCSITaskState_DORMANT = 3, kSCSITaskState_ENDED = 4 } SCSITaskState;

Constants
kSCSITaskState_NEW_TASK

The task state is new task. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskState_ENABLED

The task is enabled and queued. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskState_BLOCKED

The task is blocked. Available in OS X v10.0 and later. Declared in SCSITask.h.

kSCSITaskState_DORMANT

The task is dormant. Available in OS X v10.0 and later. Declared in SCSITask.h.

1303

SCSITask.h User-Space Reference Data Types

kSCSITaskState_ENDED

The task is complete. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion The Task State represents the current state of the task. The state is set to NEW_TASK when the task is created. The SCSI Protocol Layer will then adjust the state as the task is queued and during execution. The SCSI Application Layer can examine the state to monitor the progress of a task. The Task State can only be modified by the SCSI Protocol Layer. The SCSI Application Layer can only read the state. Availability Available in OS X v10.0 and later. Declared in
SCSITask.h

SCSITaskStatus
Attributes for task status.

typedef enum SCSITaskStatus { /*! */ kSCSITaskStatus_GOOD = 0x00, /*! */ kSCSITaskStatus_CHECK_CONDITION = 0x02, /*! */ kSCSITaskStatus_CONDITION_MET = 0x04, /*! */ kSCSITaskStatus_BUSY = 0x08, /*! */ kSCSITaskStatus_INTERMEDIATE = 0x10, /*! */ kSCSITaskStatus_INTERMEDIATE_CONDITION_MET = 0x14, /*! */ kSCSITaskStatus_RESERVATION_CONFLICT = 0x18,

1304

SCSITask.h User-Space Reference Data Types

/*! */ kSCSITaskStatus_TASK_SET_FULL = 0x28, /*! */ kSCSITaskStatus_ACA_ACTIVE = 0x30, /*! */ kSCSITaskStatus_TaskTimeoutOccurred = 0x01, /*! */ kSCSITaskStatus_ProtocolTimeoutOccurred = 0x02, /*! */ kSCSITaskStatus_DeviceNotResponding = 0x03, /*! */ kSCSITaskStatus_DeviceNotPresent = 0x04, /*! */ kSCSITaskStatus_DeliveryFailure = 0x05, /*! */ kSCSITaskStatus_No_Status = 0xFF } SCSITaskStatus;

Constants
kSCSITaskStatus_GOOD

The task completed with a status of GOOD. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_CHECK_CONDITION

The task completed with a status of CHECK_CONDITION. Additional information about the condition should be available in the sense data. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_CONDITION_MET

The task completed with a status of CONDITION_MET. Available in OS X v10.0 and later. Declared in SCSITask.h.

1305

SCSITask.h User-Space Reference Data Types

kSCSITaskStatus_BUSY

The task completed with a status of BUSY. The device server might need time to process a request and a delay may be required. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_INTERMEDIATE

The task completed with a status of INTERMEDIATE. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_INTERMEDIATE_CONDITION_MET

The task completed with a status of INTERMEDIATE_CONDITION_MET. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_RESERVATION_CONFLICT

The task completed with a status of RESERVATION_CONFLICT. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_TASK_SET_FULL

The task completed with a status of TASK_SET_FULL. The device server may need to complete a task before the initiator sends another. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_ACA_ACTIVE

The task completed with a status of ACA_ACTIVE. The device server may need the initiator to clear the Auto-Contingent Allegiance condition before it will respond to new commands. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSITaskStatus_TaskTimeoutOccurred

If a task is aborted by the SCSI Protocol Layer due to it exceeding the timeout value specified by the task, the task status shall be set to kSCSITaskStatus_TaskTimeoutOccurred. Available in OS X v10.3 and later. Declared in SCSITask.h.

1306

SCSITask.h User-Space Reference Data Types

kSCSITaskStatus_ProtocolTimeoutOccurred

If a task is aborted by the SCSI Protocol Layer due to it exceeding a timeout value specified by the support for the protocol or a related specification, the task status shall be set to kSCSITaskStatus_ProtocolTimeoutOccurred. Available in OS X v10.3 and later. Declared in SCSITask.h.
kSCSITaskStatus_DeviceNotResponding

If a task is unable to be delivered due to a failure of the device not accepting the task or the device acknowledging the attempt to send it the device the task status shall be set to kSCSITaskStatus_DeviceNotResponding. This will allow the SCSI Application driver to perform the necessary steps to try to recover the device. This shall only be reported after the SCSI Protocol Layer driver has attempted all protocol specific attempts to recover the device. Available in OS X v10.3 and later. Declared in SCSITask.h.
kSCSITaskStatus_DeviceNotPresent

If the task is unable to be delivered because the device has been detached, the task status shall be set to kSCSITaskStatus_DeviceNotPresent. This will allow the SCSI Application Layer to halt the sending of tasks to the device and, if supported, perform any device failover or system cleanup. Available in OS X v10.3 and later. Declared in SCSITask.h.
kSCSITaskStatus_DeliveryFailure

If the task is unable to be delivered to the device due to a failure in the SCSI Protocol Layer, such as a bus reset or communications error, but the device is is known to be functioning properly, the task status shall be set to kSCSITaskStatus_DeliveryFailure. This can also be reported if the task could not be delivered due to a protocol error that has since been corrected. Available in OS X v10.3 and later. Declared in SCSITask.h.
kSCSITaskStatus_No_Status

This status is not defined by the SCSI specifications, but is here to provide a status that can be returned in cases where there is not status available from the device or protocol, for example, when the service response is neither TASK_COMPLETED nor LINK_COMMAND_COMPLETE or when the service response is SERVICE_DELIVERY_OR_TARGET_FAILURE and the reason for failure could not be determined. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion The Task Status represents the completion status of the task which provides the SCSI Application Layer with additional information about how to procede in handling a completed task.

1307

SCSITask.h User-Space Reference Constants

The SCSI Architecture Model specification only defines task status values for when a task completes with a service response of either TASK_COMPLETED or LINK_COMMAND_COMPLETE. Since additional information will aid in error recovery when a task fails to be completed by a device due to a service response of kSCSIServiceResponse_SERVICE_DELIVERY_OR_TARGET_FAILURE, additional values have been defined that can be returned by the SCSI Protocol Layer to inform the SCSI Application Layer of the cause of the delivery failure. The Task Status can only be modified by the SCSI Protocol Layer. The SCSI Application Layer can only read the status Availability Available in OS X v10.0 and later. Declared in
SCSITask.h

Constants
See the Overview for header-level documentation.

Command Descriptor Block Size

enum { /*! */ kSCSICDBSize_Maximum = 16, /*! */ kSCSICDBSize_6Byte = 6, /*! */ kSCSICDBSize_10Byte = 10, /*! */ kSCSICDBSize_12Byte = 12, /*! */ kSCSICDBSize_16Byte = 16 };

1308

SCSITask.h User-Space Reference Constants

Constants
kSCSICDBSize_Maximum

This is the largest size a Command Descriptor Block can be as specified in SPC-2. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSICDBSize_6Byte

Use this for a 6-byte CDB. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSICDBSize_10Byte

Use this for a 10-byte CDB. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSICDBSize_12Byte

Use this for a 12-byte CDB. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSICDBSize_16Byte

Use this for a 16-byte CDB. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion Command Descriptor Block Size constants.

Data Transfer Direction

enum { /*! */ kSCSIDataTransfer_NoDataTransfer = 0x00, /*! */ kSCSIDataTransfer_FromInitiatorToTarget = 0x01, /*! */ kSCSIDataTransfer_FromTargetToInitiator = 0x02 };

1309

SCSITask.h User-Space Reference Constants

Constants
kSCSIDataTransfer_NoDataTransfer

Use this for tasks that transfer no data. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSIDataTransfer_FromInitiatorToTarget

Use this for tasks that transfer data from the initiator to the target. Available in OS X v10.0 and later. Declared in SCSITask.h.
kSCSIDataTransfer_FromTargetToInitiator

Use this for tasks that transfer data from the target to the initiator. Available in OS X v10.0 and later. Declared in SCSITask.h. Discussion DataTransferDirection constants.

Untagged Task Identifier

enum { kSCSIUntaggedTaskIdentifier = 0 };

Constants
kSCSIUntaggedTaskIdentifier

This value means the task is untagged. Available in OS X v10.2 and later. Declared in SCSITask.h. Discussion The Untagged Task Identifier is used to indicate no unique tag is associated with the Task.

1310

SCSITaskLib.h Reference

Declared in

SCSITaskLib.h

Overview
SCSITaskLib implements non-kernel task access to specific IOKit object types, namely any SCSI Peripheral Device for which there isn't an in-kernel driver and for authoring devices such as CD-R/W and DVD-R/W drives.

Included Headers

<IOKit/scsi/SCSITask.h> <IOKit/scsi/SCSICommandDefinitions.h> <IOKit/scsi/SCSICmds_INQUIRY_Definitions.h> <IOKit/scsi/SCSICmds_REQUEST_SENSE_Defs.h> <CoreFoundation/CFPlugIn.h> <CoreFoundation/CFPlugInCOM.h> <IOKit/IOReturn.h> <IOKit/IOTypes.h> <IOKit/IOCFPlugIn.h>

Callbacks
See the Overview for header-level documentation.

SCSITaskCallbackFunction
Asynchronous callback routine definition.

typedef void ( *SCSITaskCallbackFunction ) ( SCSIServiceResponse serviceResponse,

1311

SCSITaskLib.h Reference Constants

SCSITaskStatus taskStatus, UInt64 bytesTransferred, void *refCon );

Parameters
serviceResponse

An SCSIServiceResponse returned by the protocol transport.

taskStatus

An SCSITaskStatus to indicate the task's status

bytesTransferred

A total byte count of bytes transferred.

refCon

The refCon passed when the task was executed. Discussion Asynchronous callback routine definition. Any function which is used as a callback routine for SCSITasks must conform to this function definition. Availability Available in OS X v10.1 and later. Declared in
SCSITaskLib.h

Constants
See the Overview for header-level documentation.

Defines

#define kIOMMCDeviceInterfaceID \ CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x1F, 0x65, 0x11, 0x06, 0x23, 0xCC, 0x11,

1312

SCSITaskLib.h Reference Constants

0xD5, \ 0xBB, 0xDB, 0x00, 0x30, 0x65, 0x70, 0x48, 0x66) #define kIOMMCDeviceUserClientTypeID \ CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x97, 0xAB, 0xCF, 0x2C, 0x23, 0xCC, 0x11, 0xD5, \ 0xA0, 0xE8, 0x00, 0x30, 0x65, 0x70, 0x48, 0x66) #define kIOPropertySCSITaskAuthoringDevice "SCSITaskAuthoringDevice" #define kIOPropertySCSITaskDeviceCategory "SCSITaskDeviceCategory" #define kIOPropertySCSITaskUserClientDevice "SCSITaskUserClientDevice" #define kIOPropertySCSITaskUserClientInstanceGUID "SCSITaskUserClient GUID" #define kIOSCSITaskDeviceInterfaceID \ CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x1B, 0xBC, 0x41, 0x32, 0x08, 0xA5, 0x11, 0xD5, \ 0x90, 0xED, 0x00,

1313

SCSITaskLib.h Reference Constants

0x30, 0x65, 0x7D, 0x05, 0x2A) #define kIOSCSITaskDeviceUserClientTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x7D, 0x66, 0x67, 0x8E, 0x08, 0xA2, 0x11, 0xD5, \ 0xA1, 0xB8, 0x00, 0x30, 0x65, 0x7D, 0x05, 0x2A) #define kIOSCSITaskInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x0B, 0x85, 0xB6, 0x3C, 0x46, 0x2E, 0x11, 0xD5, \ 0xA9, 0xD6, 0x00, 0x30, 0x65, 0x70, 0x48, 0x66) #define kIOSCSITaskLibFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 0x63, 0x32, 0x6D, 0x72,

1314

SCSITaskLib.h Reference Constants

0x08, 0xA2, 0x11, 0xD5, \ 0x86, 0x5F, 0x00, 0x30, 0x65, 0x7D, 0x05, 0x2A)

Constants
kIOMMCDeviceInterfaceID

InterfaceID for MMCDeviceInterface. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

kIOMMCDeviceUserClientTypeID

Factory ID for creating an MMC Device User Client. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.
kIOPropertySCSITaskAuthoringDevice

IORegistry property for the SCSI Task User Client. This property identifies an SCSITask enabled device capable of authoring. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.
kIOPropertySCSITaskDeviceCategory

IORegistry property for the SCSITaskUserClient. This category identifies which type of device and interface to the device is used in conjunction with the SCSITaskUserClient. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.
kIOPropertySCSITaskUserClientDevice

IORegistry property for the SCSI Task User Client. This property identifies an SCSITask enabled device. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

1315

SCSITaskLib.h Reference Constants

kIOPropertySCSITaskUserClientInstanceGUID

IORegistry property for the SCSITaskUserClient GUID. This GUID helps uniquely identify and track SCSITask enabled devices Available in OS X v10.1 and later. Declared in SCSITaskLib.h.
kIOSCSITaskDeviceInterfaceID

InterfaceID for SCSITaskDeviceInterface. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

kIOSCSITaskDeviceUserClientTypeID

Factory ID for creating an SCSITask Device User Client. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.
kIOSCSITaskInterfaceID

InterfaceID for SCSITaskInterface. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

kIOSCSITaskLibFactoryID

UUID for the SCSITaskLib Factory. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

MMCDeviceTrayState
Used to identify the state of an MMCDevice's tray (if applicable).

enum { kMMCDeviceTrayClosed = 0, kMMCDeviceTrayOpen = 1, kMMCDeviceTrayMask = 0x1 };

Constants
kMMCDeviceTrayClosed

This value means the tray is closed. Available in OS X v10.1 and later. Declared in SCSITaskLib.h.

1316

SCSITaskLib.h Reference Constants

kMMCDeviceTrayOpen

This value means the tray is open. Available in OS X v10.1 and later. Declared in SCSITaskLib.h. Discussion Used to identify the state of an MMCDevice's tray (if applicable).

1317

USB.h User-Space Reference

Declared in

USB.h

Overview
Included Headers

<libkern/OSByteOrder.h> <IOKit/IOMemoryDescriptor.h> <libkern/OSByteOrder.h> <IOKit/IOTypes.h>

Functions by Task
See the Overview for header-level documentation.

UNKNOWN OBJECT
iokit_usb_err (page 1319)

iokit_usb_msg (page 1319)

Miscellaneous
EncodeRequest (page 1319)

USBmakebmRequestType (page 1320)

1318

USB.h User-Space Reference Functions

Functions
EncodeRequest

#define EncodeRequest(request, direction, type, recipient) \ (((UInt16)request << 8) + \ ((UInt16)recipient + \ ((UInt16)type << kUSBRqTypeShift) + \ ((UInt16)direction << kUSBRqDirnShift)))

Discussion Macro that encodes the bRequest and bRequestType fields of a IOUSBDevRequest into a single value. It is useful when one needs to know what type of request the IOUSBDevRequest encodes and simplifies comparisons. Availability Available in OS X v10.0 and later. Declared in
USB.h

iokit_usb_err

#define iokit_usb_err(return) (sys_iokit|sub_iokit_usb|return)

Discussion Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Availability Available in OS X v10.0 and later. See Also
IOUSBFamily error codes

Declared in
USB.h

iokit_usb_msg

#define iokit_usb_msg(message) (UInt32)(sys_iokit|sub_iokit_usb|message)

1319

USB.h User-Space Reference Callbacks

Discussion Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Availability Available in OS X v10.1 and later. See Also
IOUSBFamily message codes

Declared in
USB.h

USBmakebmRequestType

#define USBmakebmRequestType(direction, type, recipient) \ (((direction & kUSBRqDirnMask) << kUSBRqDirnShift) | \ ((type & kUSBRqTypeMask) << kUSBRqTypeShift) | \ (recipient & kUSBRqRecipientMask))

Discussion Macro to encode the bRequest field of a Device Request. It is used when constructing an IOUSBDevRequest. Availability Available in OS X v10.0 and later.
Related Sample Code Deva_Example

Declared in
USB.h

Callbacks
See the Overview for header-level documentation.

IOUSBCompletionAction

typedef void ( IOUSBCompletionAction)( void target, void *parameter,

1320

USB.h User-Space Reference Callbacks

IOReturn status, UInt32 bufferSizeRemaining);

Parameters
target

The target specified in the IOUSBCompletion struct.

parameter

The parameter specified in the IOUSBCompletion struct.

status

Completion status.
bufferSizeRemaining

Bytes left to be transferred. Discussion Function called when USB I/O completes. Availability Available in OS X v10.0 and later. Declared in
USB.h

IOUSBCompletionActionWithTimeStamp

typedef void ( *IOUSBCompletionActionWithTimeStamp)( void *target, void *parameter, IOReturn status, UInt32 bufferSizeRemaining, AbsoluteTime timeStamp);

Parameters
target

The target specified in the IOUSBCompletion struct.

parameter

The parameter specified in the IOUSBCompletion struct.

status

Completion status.
bufferSizeRemaining

Bytes left to be transferred.

1321

USB.h User-Space Reference Callbacks

timeStamp

Time at which the transaction was processed. Discussion Function called when USB I/O completes. Availability Available in OS X v10.3 and later. Declared in
USB.h

IOUSBIsocCompletionAction

typedef void ( *IOUSBIsocCompletionAction)( void *target, void *parameter, IOReturn status, IOUSBIsocFrame *pFrames);

Parameters
target

The target specified in the IOUSBIsocCompletionn struct.

parameter

The parameter specified in the IOUSBIsocCompletion struct.

status

Completion status.
pFrames

Pointer to the frame list containing the status for each frame transferred. Discussion Function called when Isochronous USB I/O completes. Availability Available in OS X v10.0 and later. Declared in
USB.h

1322

USB.h User-Space Reference Data Types

IOUSBLowLatencyIsocCompletionAction

typedef void ( *IOUSBLowLatencyIsocCompletionAction)( void *target, void *parameter, IOReturn status, IOUSBLowLatencyIsocFrame *pFrames);

Parameters
target

The target specified in the IOUSBLowLatencyIsocCompletion struct.

parameter

The parameter specified in the IOUSBLowLatencyIsocCompletion struct.

status

Completion status.
pFrames

Pointer to the low latency frame list containing the status for each frame transferred. Discussion Function called when Low Latency Isochronous USB I/O completes. Availability Available in OS X v10.2 and later. Declared in
USB.h

Data Types
See the Overview for header-level documentation.

IOUSBBOSDescriptor

typedef struct IOUSBBOSDescriptor IOUSBBOSDescriptor;

Discussion BOS Descriptor for a USB Device. . Availability Available in OS X v10.8 and later.

1323

USB.h User-Space Reference Data Types

1324

USB.h User-Space Reference Data Types

IOUSBConfigurationDescHeader

typedef struct IOUSBConfigurationDescHeader IOUSBConfigurationDescHeader;

Discussion Header of a IOUSBConfigurationDescriptor. Used to get the total length of the descriptor. Availability Available in OS X v10.1 and later. See Also
IOUSBConfigurationDescHeader (page 1342)

Declared in
USB.h

IOUSBConfigurationDescriptor

typedef struct IOUSBConfigurationDescriptor IOUSBConfigurationDescriptor;

Discussion Standard USB Configuration Descriptor. It is variable length, so this only specifies the known fields. We use the wTotalLength field to read the whole descriptor. See the USB Specification at http://www.usb.org. Availability Available in OS X v10.0 and later. See Also
IOUSBConfigurationDescriptor (page 1343)

Declared in
USB.h

IOUSBDescriptorHeader

typedef struct IOUSBDescriptorHeader IOUSBDescriptorHeader;

Discussion Standard header used for all USB descriptors. Used to read the length of a descriptor so that we can allocate storage for the whole descriptor later on.

1325

1326

USB.h User-Space Reference Data Types

USB.h User-Space Reference Data Types

Availability Available in OS X v10.0 and later. Declared in

USB.h

IOUSBDevRequestDesc

typedef struct { UInt8 bmRequestType; UInt8 bRequest; UInt16 wValue; UInt16 wIndex; UInt16 wLength; IOMemoryDescriptor *pData; UInt32 wLenDone; } IOUSBDevRequestDesc;

Discussion Parameter block for control requests, using a memory descriptor for the data to be transferred. Only available in the kernel. Availability Available in OS X v10.7 through OS X v10.7. Declared in
USB.h

IOUSBDevRequestTO

typedef struct { UInt8 bmRequestType; UInt8 bRequest; UInt16 wValue; UInt16 wIndex; UInt16 wLength; void *pData; UInt32 wLenDone; UInt32 noDataTimeout; UInt32 completionTimeout; } IOUSBDevRequestTO;

1329

USB.h User-Space Reference Data Types

Discussion Parameter block for control requests with timeouts, using a simple pointer for the data to be transferred. Same as a IOUSBDevRequest except for the two extra timeout fields. Availability Available in OS X v10.1 and later. Declared in
USB.h

IOUSBDFUDescriptor

typedef struct IOUSBDFUDescriptor IOUSBDFUDescriptor;

Discussion USB Device Firmware Update Descriptor. See the USB Device Firmware Update Specification at http://www.usb.org. Availability Available in OS X v10.2 and later. See Also
IOUSBDFUDescriptor (page 1346)

Declared in
USB.h

IOUSBEndpointDescriptor

typedef struct IOUSBEndpointDescriptor IOUSBEndpointDescriptor;

Discussion Descriptor for a USB Endpoint. See the USB Specification at http://www.usb.org. Availability Available in OS X v10.0 and later. See Also
IOUSBEndpointDescriptor (page 1346)

1330

USB.h User-Space Reference Data Types

Declared in
USB.h

IOUSBFindEndpointRequest

typedef struct { UInt8 type; UInt8 direction; UInt16 maxPacketSize; UInt8 interval; } IOUSBFindEndpointRequest;

Discussion Struct used to find endpoints of an interface type and direction are used to match endpoints, type, direction, maxPacketSize and interval are updated with the properties of the found endpoint. Availability Available in OS X v10.0 and later. Declared in
USB.h

IOUSBFindInterfaceRequest

typedef struct { UInt16 bInterfaceClass; // requested class UInt16 bInterfaceSubClass; // requested subclass UInt16 bInterfaceProtocol; // requested protocol UInt16 bAlternateSetting; // requested alt setting } IOUSBFindInterfaceRequest;

Discussion Structure used with FindNextInterface. Availability Available in OS X v10.0 and later. Declared in
USB.h

1331

USB.h User-Space Reference Data Types

IOUSBGetFrameStruct

typedef struct { UInt64 frame; AbsoluteTime timeStamp; } IOUSBGetFrameStruct;

Discussion Structure used from user space to return the frame number and a timestamp on when the frame register was read. Availability Available in OS X v10.0 and later. Declared in
USB.h

IOUSBHIDDescriptor

typedef struct IOUSBHIDDescriptor IOUSBHIDDescriptor;

Discussion USB HID Descriptor. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment. Availability Available in OS X v10.0 and later. See Also
IOUSBHIDDescriptor (page 1347)

Declared in
USB.h

IOUSBHIDReportDesc

typedef struct IOUSBHIDReportDesc IOUSBHIDReportDesc;

1332

USB.h User-Space Reference Data Types

Discussion USB HID Report Descriptor header. See the USB HID Specification at http://www.usb.org. (This structure should have used the #pragma pack(1) compiler directive to get byte alignment. Availability Available in OS X v10.0 and later. See Also
IOUSBHIDReportDesc (page 1347)

Declared in
USB.h

IOUSBInterfaceAssociationDescriptor

typedef struct IOUSBInterfaceAssociationDescriptor IOUSBInterfaceAssociationDescriptor;

Discussion USB Inerface Association Descriptor. ECN to the USB 2.0 Spec. See the USB Specification at http://www.usb.org. Availability Available in OS X v10.3 and later. See Also
IOUSBInterfaceAssociationDescriptor (page 1348)

Declared in
USB.h

IOUSBInterfaceDescriptor

typedef struct IOUSBInterfaceDescriptor IOUSBInterfaceDescriptor;

Discussion Descriptor for a USB Interface. See the USB Specification at http://www.usb.org. Availability Available in OS X v10.0 and later. See Also
IOUSBInterfaceDescriptor (page 1348)

1333

USB.h User-Space Reference Data Types

Declared in
USB.h

IOUSBIsocCompletion

typedef struct IOUSBIsocCompletion { void *target; IOUSBIsocCompletionAction action; void *parameter; } IOUSBIsocCompletion;

Discussion Struct specifying action to perform when an Isochronous USB I/O completes. Availability Available in OS X v10.0 and later. Declared in
USB.h

IOUSBIsocFrame

typedef struct IOUSBIsocFrame { IOReturn frStatus; UInt16 frReqCount; UInt16 frActCount; } IOUSBIsocFrame;

Discussion Structure used to encode information about each isoc frame. Availability Available in OS X v10.0 and later. Declared in
USB.h

1334

USB.h User-Space Reference Data Types

IOUSBLowLatencyIsocCompletion

typedef struct IOUSBLowLatencyIsocCompletion { void *target; IOUSBLowLatencyIsocCompletionAction action; void *parameter; } IOUSBLowLatencyIsocCompletion;

Discussion Struct specifying action to perform when an Low Latency Isochronous USB I/O completes. Availability Available in OS X v10.2 and later. Declared in
USB.h

IOUSBLowLatencyIsocFrame

typedef struct IOUSBLowLatencyIsocFrame IOUSBLowLatencyIsocFrame;

Discussion Structure used to encode information about each isoc frame that is processed at hardware interrupt time (low latency). Availability Available in OS X v10.2 and later. See Also
IOUSBLowLatencyIsocFrame (page 1349)

Declared in
USB.h

IOUSBSuperSpeedEndpointCompanionDescriptor

typedef struct IOUSBSuperSpeedEndpointCompanionDescriptor IOUSBSuperSpeedEndpointCompanionDescriptor;

Discussion Descriptor for a SuperSpeed USB Endpoint Cpmpanion. See the USB Specification at http://www.usb.org.

1335

USB.h User-Space Reference Data Types

Availability Available in OS X v10.8 and later. See Also

IOUSBSuperSpeedEndpointCompanionDescriptor (page 1349)

Declared in
USB.h

USBDeviceInformationBits

typedef enum { kUSBInformationDeviceIsCaptiveBit = 0, kUSBInformationDeviceIsAttachedToRootHubBit = 1, kUSBInformationDeviceIsInternalBit = 2, kUSBInformationDeviceIsConnectedBit = 3, kUSBInformationDeviceIsEnabledBit = 4, kUSBInformationDeviceIsSuspendedBit = 5, kUSBInformationDeviceIsInResetBit = 6, kUSBInformationDeviceOvercurrentBit = 7, kUSBInformationDevicePortIsInTestModeBit = 8, kUSBInformationDeviceIsRootHub = 9, kUSBInformationRootHubisBuiltIn = 10, kUSBInformationDeviceIsRemote = 11, kUSBInformationDeviceIsAttachedToEnclosure = 12, kUSBInformationDeviceIsCaptiveMask = ( 1 << kUSBInformationDeviceIsCaptiveBit), kUSBInformationDeviceIsAttachedToRootHubMask = ( 1 << kUSBInformationDeviceIsAttachedToRootHubBit), kUSBInformationDeviceIsInternalMask = ( 1 << kUSBInformationDeviceIsInternalBit), kUSBInformationDeviceIsConnectedMask = ( 1 << kUSBInformationDeviceIsConnectedBit), kUSBInformationDeviceIsEnabledMask = ( 1 << kUSBInformationDeviceIsEnabledBit), kUSBInformationDeviceIsSuspendedMask = ( 1 << kUSBInformationDeviceIsSuspendedBit), kUSBInformationDeviceIsInResetMask = ( 1 << kUSBInformationDeviceIsInResetBit), kUSBInformationDeviceOvercurrentMask = ( 1 << kUSBInformationDeviceOvercurrentBit), kUSBInformationDevicePortIsInTestModeMask = ( 1 << kUSBInformationDevicePortIsInTestModeBit), kUSBInformationDeviceIsRootHubMask = ( 1 << kUSBInformationDeviceIsRootHub),

1336

USB.h User-Space Reference Data Types

kUSBInformationRootHubisBuiltInMask = ( 1 << kUSBInformationRootHubisBuiltIn), kUSBInformationDeviceIsRemoteMask = ( 1 << kUSBInformationDeviceIsRemote), kUSBInformationDeviceIsAttachedToEnclosureMask = ( 1 << kUSBInformationDeviceIsAttachedToEnclosure) } USBDeviceInformationBits;

Constants
kUSBInformationDeviceIsCaptiveBit

The USB device is directly attached to its hub and cannot be removed. Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsAttachedToRootHubBit

The USB device is directly attached to the root hub Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsInternalBit

The USB device is internal to the computer (all the hubs it attaches to are captive) Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsConnectedBit

The USB device is connected to its hub Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsEnabledBit

The hub port to which the USB device is attached is enabled Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsSuspendedBit

The hub port to which the USB device is attached is suspended Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsInResetBit

The hub port to which the USB device is attached is being reset Available in OS X v10.6 and later. Declared in USB.h.

1337

USB.h User-Space Reference Data Types

kUSBInformationDeviceOvercurrentBit

The USB device generated an overcurrent Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDevicePortIsInTestModeBit

The hub port to which the USB device is attached is in test mode Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsRootHub

The device is actually the root hub simulation Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationRootHubisBuiltIn

If this is a root hub simulation and it's built into the machine, this bit is set. If it's on an expansion card, it will be cleared Available in OS X v10.6 and later. Declared in USB.h.
kUSBInformationDeviceIsRemote

This device is "attached" to the controller through a remote connection Available in OS X v10.7 and later. Declared in USB.h.
kUSBInformationDeviceIsAttachedToEnclosure

The hub port to which the USB device is connected has a USB connector on the CPU enclosure Available in OS X v10.8 and later. Declared in USB.h. Discussion GetUSBDeviceInformation will return a unit32_t value with bits set indicating that a particular state is present in the USB device. These bits are described here Availability Available in OS X v10.6 and later. Declared in
USB.h

1338

USB.h User-Space Reference Data Types

USBLowLatencyBufferType

typedef enum { kUSBLowLatencyWriteBuffer = 0, kUSBLowLatencyReadBuffer = 1, kUSBLowLatencyFrameListBuffer = 2 } USBLowLatencyBufferType;

Constants
kUSBLowLatencyWriteBuffer

The buffer will be used to write data out to a device. Available in OS X v10.2 and later. Declared in USB.h.
kUSBLowLatencyReadBuffer

The buffer will be used to read data from a device. Available in OS X v10.2 and later. Declared in USB.h.
kUSBLowLatencyFrameListBuffer

The buffer will be used for a low latency isoch frame list. Available in OS X v10.2 and later. Declared in USB.h. Discussion Used to specify what kind of buffer to create when calling LowLatencyCreateBuffer(). Availability Available in OS X v10.2 and later. Declared in
USB.h

USBPowerRequestTypes

typedef enum { kUSBPowerDuringSleep = 0, kUSBPowerDuringWake = 1, kUSBPowerRequestWakeRelease = 2, kUSBPowerRequestSleepRelease = 3, kUSBPowerRequestWakeReallocate = 4, kUSBPowerRequestSleepReallocate = 5,

1339

USB.h User-Space Reference Data Types

kUSBPowerDuringWakeRevokable = 6 } USBPowerRequestTypes;

Constants
kUSBPowerDuringSleep

The power is to be used during sleep. Available in OS X v10.6 and later. Declared in USB.h.
kUSBPowerDuringWake

The power is to be used while the system is awake (i.e not sleeping) Available in OS X v10.6 and later. Declared in USB.h.
kUSBPowerRequestWakeRelease

When used with ReturnExtraPower(), it will send a message to all devices to return any extra wake power if possible. Available in OS X v10.7 and later. Declared in USB.h.
kUSBPowerRequestSleepRelease

When used with ReturnExtraPower(), it will send a message to all devices to return any sleep power if possible. Available in OS X v10.7 and later. Declared in USB.h.
kUSBPowerRequestWakeReallocate

When used with ReturnExtraPower(), it will send a message to all devices indicating that they can ask for more wake power, as some device has released it. Available in OS X v10.7 and later. Declared in USB.h.
kUSBPowerRequestSleepReallocate

When used with ReturnExtraPower(), it will send a message to all devices indicating that they can ask for more sleep power, as some device has released it. Available in OS X v10.7 and later. Declared in USB.h.

1340

USB.h User-Space Reference Data Types

kUSBPowerDuringWakeRevokable

The power is to be used while the system is awake (i.e not sleeping), but can be taken away (via the kUSBPowerRequestWakeRelease message). The system can then allocate that extra power to another device. Available in OS X v10.8 and later. Declared in USB.h. Discussion Used to specify what kind of power will be reserved using the IOUSBDevice RequestExtraPower and ReturnExtraPower APIs. Availability Available in OS X v10.6 and later. Declared in
USB.h

USBReEnumerateOptions

typedef enum { kUSBAddExtraResetTimeBit = 31, kUSBAddExtraResetTimeMask = ( 1 << kUSBAddExtraResetTimeBit) } USBReEnumerateOptions;

Constants
kUSBAddExtraResetTimeBit

Setting this bit will cause the Hub driver to wait 100ms before addressing the device after the reset following the re-enumeration. Available in OS X v10.3 and later. Declared in USB.h. Discussion Options used when calling ReEnumerateDevice. Availability Available in OS X v10.3 and later. Declared in
USB.h

1341

USB.h User-Space Reference Data Types

USBStatus

typedef UInt16 USBStatus;

Discussion Type used to get a DeviceStatus as a single quantity. Availability Available in OS X v10.0 and later. Declared in
USB.h

IOUSBBOSDescriptor

struct IOUSBBOSDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt16 wTotalLength; UInt8 bNumDeviceCaps; };

Discussion BOS Descriptor for a USB Device. . See Also

IOUSBBOSDescriptor (page 1323)

IOUSBConfigurationDescHeader

struct IOUSBConfigurationDescHeader { UInt8 bLength; UInt8 bDescriptorType; UInt16 wTotalLength; };

Discussion Header of a IOUSBConfigurationDescriptor. Used to get the total length of the descriptor. See Also
IOUSBConfigurationDescHeader (page 1325)

1342

USB.h User-Space Reference Data Types

IOUSBConfigurationDescriptor

struct IOUSBConfigurationDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt16 wTotalLength; UInt8 bNumInterfaces; UInt8 bConfigurationValue; UInt8 iConfiguration; UInt8 bmAttributes; UInt8 MaxPower; };

IOUSBDescriptorHeader

struct IOUSBDescriptorHeader { UInt8 bLength; UInt8 bDescriptorType; };

Discussion Standard header used for all USB descriptors. Used to read the length of a descriptor so that we can allocate storage for the whole descriptor later on. See Also
IOUSBDescriptorHeader (page 1325)

IOUSBDeviceCapabilityContainerID

struct IOUSBDeviceCapabilityContainerID { UInt8 bLength; UInt8 bDescriptorType; UInt8 bDevCapabilityType; UInt8 bReservedID;

1343

USB.h User-Space Reference Data Types

UInt8 containerID[16]; };

Discussion Device Capability Container ID See Also

IOUSBDeviceCapabilityContainerID (page 1326)

IOUSBDeviceCapabilityDescriptorHeader

struct IOUSBDeviceCapabilityDescriptorHeader { UInt8 bLength; UInt8 bDescriptorType; UInt8 bDevCapabilityType; UInt8 bNumDeviceCaps; };

Discussion Header for a Device Capability Descriptor for a USB Device. . See Also
IOUSBDeviceCapabilityDescriptorHeader (page 1326)

IOUSBDeviceCapabilitySuperSpeedUSB

struct IOUSBDeviceCapabilitySuperSpeedUSB { UInt8 bLength; UInt8 bDescriptorType; UInt8 bDevCapabilityType; UInt8 bmAttributes; UInt16 wSpeedsSupported; UInt8 bFunctionalitySupport; UInt8 bU1DevExitLat; UInt16 wU2DevExitLat; };

Discussion Device Capability SuperSpeed USB See Also

IOUSBDeviceCapabilitySuperSpeedUSB (page 1327)

1344

USB.h User-Space Reference Data Types

IOUSBDeviceCapabilityUSB2Extension

struct IOUSBDeviceCapabilityUSB2Extension { UInt8 bLength; UInt8 bDescriptorType; UInt8 bDevCapabilityType; UInt32 bmAttributes; };

Discussion Device Capability USB 2.0 Extension See Also

IOUSBDeviceCapabilityUSB2Extension (page 1327)

IOUSBDeviceDescriptor

struct IOUSBDeviceDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt16 bcdUSB; UInt8 bDeviceClass; UInt8 bDeviceSubClass; UInt8 bDeviceProtocol; UInt8 bMaxPacketSize0; UInt16 idVendor; UInt16 idProduct; UInt16 bcdDevice; UInt8 iManufacturer; UInt8 iProduct; UInt8 iSerialNumber; UInt8 bNumConfigurations; };

Discussion Descriptor for a USB Device. See the USB Specification at http://www.usb.org. See Also
IOUSBDeviceDescriptor (page 1327)

1345

USB.h User-Space Reference Data Types

IOUSBDeviceQualifierDescriptor

struct IOUSBDeviceQualifierDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt16 bcdUSB; UInt8 bDeviceClass; UInt8 bDeviceSubClass; UInt8 bDeviceProtocol; UInt8 bMaxPacketSize0; UInt8 bNumConfigurations; UInt8 bReserved; };

Discussion USB Device Qualifier Descriptor. See the USB Specification at http://www.usb.org. See Also
IOUSBDeviceQualifierDescriptor (page 1328)

IOUSBDFUDescriptor

struct IOUSBDFUDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt8 bmAttributes; UInt16 wDetachTimeout; UInt16 wTransferSize; };

Discussion USB Device Firmware Update Descriptor. See the USB Device Firmware Update Specification at http://www.usb.org. See Also
IOUSBDFUDescriptor (page 1330)

IOUSBEndpointDescriptor

struct IOUSBEndpointDescriptor { UInt8 bLength;

1346

USB.h User-Space Reference Data Types

UInt8 bDescriptorType; UInt8 bEndpointAddress; UInt8 bmAttributes; UInt16 wMaxPacketSize; UInt8 bInterval; };

Discussion Descriptor for a USB Endpoint. See the USB Specification at http://www.usb.org. See Also
IOUSBEndpointDescriptor (page 1330)

IOUSBHIDDescriptor

struct IOUSBHIDDescriptor { UInt8 descLen; UInt8 descType; UInt16 descVersNum; UInt8 hidCountryCode; UInt8 hidNumDescriptors; UInt8 hidDescriptorType; UInt8 hidDescriptorLengthLo; UInt8 hidDescriptorLengthHi; };

IOUSBHIDReportDesc

struct IOUSBHIDReportDesc { UInt8 hidDescriptorType; UInt8 hidDescriptorLengthLo; UInt8 hidDescriptorLengthHi; };

1347

USB.h User-Space Reference Data Types

IOUSBInterfaceAssociationDescriptor

struct IOUSBInterfaceAssociationDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt8 bFirstInterface; UInt8 bInterfaceCount; UInt8 bFunctionClass; UInt8 bFunctionSubClass; UInt8 bFunctionProtocol; UInt8 iFunction; };

Discussion USB Inerface Association Descriptor. ECN to the USB 2.0 Spec. See the USB Specification at http://www.usb.org. See Also
IOUSBInterfaceAssociationDescriptor (page 1333)

IOUSBInterfaceDescriptor

struct IOUSBInterfaceDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt8 bInterfaceNumber; UInt8 bAlternateSetting; UInt8 bNumEndpoints; UInt8 bInterfaceClass; UInt8 bInterfaceSubClass; UInt8 bInterfaceProtocol; UInt8 iInterface; };

Discussion Descriptor for a USB Interface. See the USB Specification at http://www.usb.org.

1348

USB.h User-Space Reference Data Types

See Also
IOUSBInterfaceDescriptor (page 1333)

IOUSBLowLatencyIsocFrame

struct IOUSBLowLatencyIsocFrame { IOReturn frStatus; UInt16 frReqCount; UInt16 frActCount; AbsoluteTime frTimeStamp; };

Fields
frStatus

Returns status associated with the frame.

frReqCount

Input specifiying how many bytes to read or write.

frActCount

Actual # of bytes transferred.

frTimeStamp

Time stamp that indicates time when frame was procesed. Discussion Structure used to encode information about each isoc frame that is processed at hardware interrupt time (low latency). See Also
IOUSBLowLatencyIsocFrame (page 1335)

IOUSBSuperSpeedEndpointCompanionDescriptor

struct IOUSBSuperSpeedEndpointCompanionDescriptor { UInt8 bLength; UInt8 bDescriptorType; UInt8 bMaxBurst; UInt8 bmAttributes; UInt16 wBytesPerInterval; };

1349

USB.h User-Space Reference Constants

Discussion Descriptor for a SuperSpeed USB Endpoint Cpmpanion. See the USB Specification at http://www.usb.org. See Also
IOUSBSuperSpeedEndpointCompanionDescriptor (page 1335)

Constants
See the Overview for header-level documentation.

Endian conversion definitions

Public Interfaces to the USB implementation in OS X.

#define #define #define #define

HostToUSBLong HostToUSBWord USBToHostLong USBToHostWord

OSSwapHostToLittleInt32 OSSwapHostToLittleInt16 OSSwapLittleToHostInt32 OSSwapLittleToHostInt16

Constants
HostToUSBLong

The USB API's use a convention of specifying parameters in the host order. The USB spec specifies that multi-byte items should be formatted in little endian order. The following macros allow one to translate multi-byte values from Host order to USB order and vice versa. There are separate macros for in-kernel use and for user space use. Available in OS X v10.0 and later. Declared in USB.h.
HostToUSBWord

1350

USB.h User-Space Reference Constants

USBToHostLong

IOUSBFamily error codes

#define kIOUSBClearPipeStallNotRecursive // 0xe0004048 IOUSBPipe::ClearPipeStall should not be called recursively #define kIOUSBConfigNotFound // 0xe0004056 Configuration Not found #define kIOUSBDeviceCountExceeded // 0xe0004045 The device cannot be enumerated because the controller cannot support more devices #define kIOUSBDeviceNotHighSpeed // 0xe0004049 Name is deprecated, see below #define kIOUSBDevicePortWasNotSuspended // 0xe0004047 Port was not suspended #define kIOUSBDeviceTransferredToCompanion // 0xe0004049 The device has been tranferred to another controller for enumeration #define kIOUSBEndpointCountExceeded // 0xe0004046 The endpoint was not created because the controller cannot support more endpoints #define kIOUSBEndpointNotFound // 0xe0004057 Endpoint Not found #define kIOUSBHighSpeedSplitError // 0xe000404b Error to hub on high speed bus trying to do split transaction #define kIOUSBInterfaceNotFound // 0xe000404e Interface ref not recognized #define kIOUSBLowLatencyBufferNotPreviouslyAllocated // 0xe000404d Attempted to use user land low latency isoc calls w/out calling PrepareBuffer (on the data buffer) first #define kIOUSBLowLatencyFrameListNotPreviouslyAllocated // 0xe000404c Attempted to use user land low latency isoc calls w/out calling PrepareBuffer (on the frame list) first

1351

USB.h User-Space Reference Constants

#define kIOUSBNoAsyncPortErr // 0xe000405f no async port #define kIOUSBNotEnoughPipesErr // 0xe000405e not enough pipes in interface #define kIOUSBNotEnoughPowerErr // 0xe000405d not enough power for selected configuration #define kIOUSBPipeStalled // 0xe000404f Pipe has stalled, error needs to be cleared #define kIOUSBStreamsNotSupported // 0xe0004044 The request cannot be completed because the XHCI controller does not support streams #define kIOUSBSyncRequestOnWLThread // 0xe000404a A synchronous USB request was made on the workloop thread (from a callback?). Only async requests are permitted in that case #define kIOUSBTooManyPipesErr // 0xe0004060 Too many pipes #define kIOUSBTransactionReturned // 0xe0004050 The transaction has been returned to the caller #define kIOUSBTransactionTimeout // 0xe0004051 Transaction timed out #define kIOUSBUnknownPipeErr // 0xe0004061 Pipe ref not recognized

Constants
kIOUSBClearPipeStallNotRecursive

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.7 and later. Declared in USB.h.
kIOUSBConfigNotFound

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.0 and later. Declared in USB.h.
kIOUSBDeviceCountExceeded

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.8 and later. Declared in USB.h.
kIOUSBDeviceNotHighSpeed

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.4 and later. Declared in USB.h.

1352

USB.h User-Space Reference Constants

kIOUSBDevicePortWasNotSuspended

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.6 and later. Declared in USB.h.
kIOUSBDeviceTransferredToCompanion

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.3 and later. Declared in USB.h.
kIOUSBInterfaceNotFound

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.2 and later. Declared in USB.h.

1353

USB.h User-Space Reference Constants

kIOUSBLowLatencyFrameListNotPreviouslyAllocated

1354

USB.h User-Space Reference Constants

kIOUSBTooManyPipesErr

Errors specific to the IOUSBFamily. Note that the iokit_usb_err(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.1 and later. Declared in USB.h.
kIOUSBTransactionTimeout

IOUSBFamily hardware error codes

#define kIOUSBBitstufErr // 0xe0004002 Pipe stall, bitstuffing #define kIOUSBBufferOverrunErr // 0xe000400c Buffer Overrun (Host hardware failure on data out, PCI busy?) #define kIOUSBBufferUnderrunErr // 0xe000400d Buffer Underrun (Host hardware failure on data out, PCI busy?) #define kIOUSBCRCErr // 0xe0004001 Pipe stall, bad CRC #define kIOUSBDataToggleErr // 0xe0004003 Pipe stall, Bad data toggle #define kIOUSBLinkErr // 0xe0004010 #define kIOUSBNotSent1Err // 0xe000400e Transaction not sent #define kIOUSBNotSent2Err // 0xe000400f Transaction not sent #define kIOUSBPIDCheckErr // 0xe0004006 Pipe stall, PID CRC error

1355

USB.h User-Space Reference Constants

#define kIOUSBReserved1Err // 0xe000400a Reserved #define kIOUSBReserved2Err // 0xe000400b Reserved #define kIOUSBWrongPIDErr // 0xe0004007 Pipe stall, Bad or wrong PID

Constants
kIOUSBBitstufErr

These errors are returned by the OHCI controller. The # in parenthesis (xx) corresponds to the OHCI Completion Code. For the following Completion codes, we return a generic IOKit error instead of a USB specific error.
Completion Code Error Returned 9 kIOReturnUnderrun data than max packet size 8 kIOReturnOverrun more data than buffer 5 kIOReturnNotResponding 4 kIOUSBPipeStalled Description (Data Underrun) EP returned less (Data Overrun) Packet too large or Device Not responding Endpoint returned a STALL PID

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBBufferOverrunErr

Available in OS X v10.1 and later. Declared in USB.h.

1356

USB.h User-Space Reference Constants

kIOUSBBufferUnderrunErr

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBCRCErr

Available in OS X v10.1 and later. Declared in USB.h.

1357

USB.h User-Space Reference Constants

kIOUSBDataToggleErr

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBLinkErr

Available in OS X v10.1 and later. Declared in USB.h.

1358

USB.h User-Space Reference Constants

kIOUSBNotSent1Err

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBNotSent2Err

Available in OS X v10.1 and later. Declared in USB.h.

1359

USB.h User-Space Reference Constants

kIOUSBPIDCheckErr

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBReserved1Err

Available in OS X v10.1 and later. Declared in USB.h.

1360

USB.h User-Space Reference Constants

kIOUSBReserved2Err

Available in OS X v10.1 and later. Declared in USB.h.

kIOUSBWrongPIDErr

Available in OS X v10.1 and later. Declared in USB.h.

IOUSBFamily message codes

#define kIOUSBMessageCompositeDriverReconfigured // 0xe0004011 Message from the composite driver indicating that it has finished re-configuring the device after a reset #define kIOUSBMessageController // 0xe0004015 Generic message sent from controller user client to controllers #define kIOUSBMessageDeviceCountExceeded // 0xe000401a Message sent by a hub when a device cannot be enumerated because the USB controller ran out of resources #define kIOUSBMessageEndpointCountExceeded // 0xe0004019 Message sent to a device when endpoints cannot be created because the USB controller ran out of resources #define kIOUSBMessageExpressCardCantWake // 0xe0004010 Message from a driver to a bus that

1361

USB.h User-Space Reference Constants

an express card will disconnect on sleep and thus shouldn't wake #define kIOUSBMessageFromThirdParty // 0xe000400e Message sent from a third party. Uses IOUSBThirdPartyParam to encode the sender's ID #define kIOUSBMessageHubIsDeviceConnected // 0xe0004004 Message sent to a hub to inquire whether a particular port has a device connected or not #define kIOUSBMessageHubIsPortEnabled // 0xe0004005 Message sent to a hub to inquire whether a particular port is enabled or not #define kIOUSBMessageHubPortClearTT // 0xe000400c Message sent to a hub to clear the transaction translator #define kIOUSBMessageHubPortDeviceDisconnected // 0xe000401b Message sent by a built-in hub when a device was disconnected #define kIOUSBMessageHubReEnumeratePort // 0xe0004006 Message sent to a hub to reenumerate the device attached to a particular port #define kIOUSBMessageHubResetPort // 0xe0004001 Message sent to a hub to reset a particular port #define kIOUSBMessageHubResumePort // 0xe0004003 Message sent to a hub to resume a particular port #define kIOUSBMessageHubSetPortRecoveryTime // 0xe0004012 Message sent to a hub to set the # of ms required when resuming a particular port #define kIOUSBMessageHubSuspendPort // 0xe0004002 Message sent to a hub to suspend a particular port #define kIOUSBMessageNotEnoughPower // 0xe0004014 Message sent to the clients of the device's hub parent, when a device causes an low power notice to be displayed. The message argument contains the locationID of the device #define kIOUSBMessageOvercurrentCondition // 0xe0004013 Message sent to the clients of the device's hub parent, when a device causes an overcurrent condition. The message argument contains the locationID of the device #define kIOUSBMessagePortHasBeenReset // 0xe000400a Message sent to a device indicating that the port it is attached to has been reset #define kIOUSBMessagePortHasBeenResumed // 0xe000400b Message sent to a device indicating that the port it is attached to has been resumed #define kIOUSBMessagePortHasBeenSuspended // 0xe000400d Message sent to a device indicating that the port it is attached to has been suspended #define kIOUSBMessagePortWasNotSuspended // 0xe000400f Message indicating that the hub driver received a resume request for a port that was not suspended #define kIOUSBMessageReallocateExtraCurrent // 0xe0004018 Message to ask any clients using extra current to attempt to allocate it some more #define kIOUSBMessageReleaseExtraCurrent // 0xe0004017 Message to ask any clients using extra current to release it if possible #define kIOUSBMessageRootHubWakeEvent // 0xe0004016 Message from the HC Wakeup code indicating that a Root Hub port has a wake event

1362

USB.h User-Space Reference Constants

Constants
kIOUSBMessageCompositeDriverReconfigured

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.4 and later. Declared in USB.h.
kIOUSBMessageController

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.7 and later. Declared in USB.h.
kIOUSBMessageDeviceCountExceeded

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.8 and later. Declared in USB.h.
kIOUSBMessageEndpointCountExceeded

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.3 and later. Declared in USB.h.
kIOUSBMessageHubIsDeviceConnected

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.1 and later. Declared in USB.h.

1363

USB.h User-Space Reference Constants

kIOUSBMessageHubIsPortEnabled

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.5 and later. Declared in USB.h.

1364

USB.h User-Space Reference Constants

kIOUSBMessageHubSuspendPort

Messages specific to the IOUSBFamily. Note that the iokit_usb_msg(x) translates to 0xe0004xxx, where xxx is the value in parenthesis as a hex number. Available in OS X v10.6 and later. Declared in USB.h.
kIOUSBMessageOvercurrentCondition

1365

USB.h User-Space Reference Constants

kIOUSBMessageReallocateExtraCurrent

Property Definitions

#define #define #define #define #define #define #define #define #define #define #define #define #define #define #define

kConfigurationDescriptorOverride "ConfigurationDescriptorOverride" kOverrideIfAtLocationID "OverrideIfAtLocationID" kUSBControllerNeedsContiguousMemoryForIsoch "Need contiguous memory for isoch" kUSBDevicePropertyAddress "USB Address" kUSBDevicePropertyBusPowerAvailable "Bus Power Available" kUSBDevicePropertyLocationID "locationID" kUSBDevicePropertySpeed "Device Speed" kUSBDeviceResumeRecoveryTime "kUSBDeviceResumeRecoveryTime" kUSBExpressCardCantWake "ExpressCardCantWake" kUSBHubDontAllowLowPower "kUSBHubDontAllowLowPower" kUSBOutOfSpecMPSOK "Out of spec MPS OK" kUSBPreferredConfiguration "Preferred Configuration" kUSBProductIDMask "idProductMask" kUSBProductIdsArrayName "idProductArray" kUSBSuspendPort "kSuspendPort"

Constants
kConfigurationDescriptorOverride

Useful property names in USB land. Available in OS X v10.7 and later. Declared in USB.h.

1366

USB.h User-Space Reference Constants

kOverrideIfAtLocationID

Useful property names in USB land. Available in OS X v10.7 and later. Declared in USB.h.
kUSBControllerNeedsContiguousMemoryForIsoch

Useful property names in USB land. Available in OS X v10.4 and later. Declared in USB.h.
kUSBDevicePropertyAddress

Useful property names in USB land. Available in OS X v10.0 and later. Declared in USB.h.
kUSBDevicePropertyBusPowerAvailable

Useful property names in USB land. Available in OS X v10.0 and later. Declared in USB.h.
kUSBDevicePropertyLocationID

Useful property names in USB land. Available in OS X v10.0 and later. Declared in USB.h.
kUSBDevicePropertySpeed

Useful property names in USB land. Available in OS X v10.0 and later. Declared in USB.h.
kUSBDeviceResumeRecoveryTime

Useful property names in USB land. Available in OS X v10.5 and later. Declared in USB.h.
kUSBExpressCardCantWake

Useful property names in USB land. Available in OS X v10.4 and later. Declared in USB.h.
kUSBHubDontAllowLowPower

Useful property names in USB land. Available in OS X v10.5 and later. Declared in USB.h.

1367

USB.h User-Space Reference Constants

kUSBOutOfSpecMPSOK

Useful property names in USB land. Available in OS X v10.6 and later. Declared in USB.h.
kUSBPreferredConfiguration

Useful property names in USB land. Available in OS X v10.4 and later. Declared in USB.h.
kUSBProductIDMask

Useful property names in USB land. Available in OS X v10.4 and later. Declared in USB.h.
kUSBProductIdsArrayName

Useful property names in USB land. Available in OS X v10.7 and later. Declared in USB.h.
kUSBSuspendPort

Useful property names in USB land. Available in OS X v10.4 and later. Declared in USB.h.

Miscellaneous Defines

#define kCallInterfaceOpenWithGate "kCallInterfaceOpenWithGate"

Constants
kCallInterfaceOpenWithGate

If the USB Device has this property, drivers for any of its interfaces will have their handleOpen method called while holding the workloop gate. Available in OS X v10.3 and later. Declared in USB.h.

1368

USB.h User-Space Reference Constants

bRequest Shifts and Masks

enum { kUSBRqDirnShift = 7, kUSBRqDirnMask = 1, kUSBRqTypeShift = 5, kUSBRqTypeMask = 3, kUSBRqRecipientMask = 0X1F };

Discussion These are used to create the macro to encode the bRequest filed of a Device Request

Default timeout values

enum { kUSBDefaultControlNoDataTimeoutMS = 5000, kUSBDefaultControlCompletionTimeoutMS = 0 };

Discussion default values used for data and completion timeouts.

IOUSBFamilyIOOptionBit

enum { kIOUSBInterfaceOpenAlt = 0x00010000, kIOUSBInterfaceOpenAlternateInterfaceBit = 16, kUSBOptionBitOpenExclusivelyBit = 17, kIOUSBInterfaceOpenAlternateInterfaceMask = ( 1 << kIOUSBInterfaceOpenAlternateInterfaceBit), kUSBOptionBitOpenExclusivelyMask = ( 1 << kUSBOptionBitOpenExclusivelyBit) };

Constants
kIOUSBInterfaceOpenAlt

Open the alternate interface specified when creating the interface. Available in OS X v10.7 through OS X v10.7. Declared in USB.h.

1369

USB.h User-Space Reference Constants

kUSBOptionBitOpenExclusivelyBit

Used in open()'ing the IOUSBDevice or IOUSBInterface by the corresponding user client. Only 1 user client can have exclusive access to those objects Available in OS X v10.7 through OS X v10.7. Declared in USB.h. Discussion Options used exclusively by the USB Family when calling calling IOService APIs, such as open() and close().

kIOUSBFindInterfaceDontCare

enum { kIOUSBFindInterfaceDontCare = 0xFFFF };

Discussion Constant that can be used for the fields of IOUSBFindInterfaceRequest to specify that they should not be matched.

kIOUSBVendorIDAppleComputer

enum { kIOUSBVendorIDAppleComputer = 0x05AC };

Discussion USB Vendor ID for Apple Computer, Inc.

kUSBMaxIsocFrameReqCount

enum { kUSBMaxFSIsocEndpointReqCount = 1023, // max size (bytes) of any one Isoc frame for 1 FS endpoint kUSBMaxHSIsocEndpointReqCount = 3072, // max size (bytes) of any one Isoc frame for 1 HS endpoint kUSBMaxHSIsocFrameCount = 7168 // max size (bytes) of all Isoc transfers in a HS frame };

1370

USB.h User-Space Reference Constants

Discussion Maximum size in bytes allowed for one Isochronous frame

MicrosecondsInFrame

enum { kUSBFullSpeedMicrosecondsInFrame = 1000, kUSBHighSpeedMicrosecondsInFrame = 125 };

Constants
kUSBFullSpeedMicrosecondsInFrame

The device is attached to a bus running at full speed (1 ms / frame). Available in OS X v10.2 and later. Declared in USB.h.
kUSBHighSpeedMicrosecondsInFrame

The device is attached to a bus running at high speed (125 microseconds / frame). Available in OS X v10.2 and later. Declared in USB.h. Discussion Returns the number of microseconds in a USB frame.

Miscellaneous Constants

enum { kUSBDeviceIDShift = 7, kUSBMaxDevices = 128, kUSBMaxDevice = kUSBMaxDevices-1, kUSBDeviceIDMask = 0x7f, kUSBPipeIDMask = 0xf, kUSBMaxPipes = 32, // In and Out pipes can have same pipe number. kUSBInterfaceIDShift = 8, kUSBMaxInterfaces = 1 << kUSBInterfaceIDShift, kUSBInterfaceIDMask = kUSBMaxInterfaces-1, kUSBEndPtShift = 7, kUSBDeviceMask = ( ( 1 << kUSBEndPtShift) -1), kUSBNoPipeIdx = -1, // Constants for streams

1371

USB.h User-Space Reference Constants

kUSBStream0 = 0, kUSBMaxStream = 65533, kUSBPRimeStream = 0xfffe, kUSBNoStream = 0xffff, kUSBAllStreams = 0xffffffff };

Standard Device Requests

enum { kClearDeviceFeature = ( ( ( UInt16)kUSBRqClearFeature << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) + ( UInt16) kUSBOut << kUSBRqDirnShift))), kClearInterfaceFeature = ( ( ( UInt16)kUSBRqClearFeature << 8) + ( ( UInt16) kUSBInterface + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) + ( UInt16) kUSBOut << kUSBRqDirnShift))), kClearEndpointFeature = ( ( ( UInt16)kUSBRqClearFeature << 8) + ( ( UInt16) kUSBEndpoint + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) + ( UInt16) kUSBOut << kUSBRqDirnShift))), kGetConfiguration = ( ( ( UInt16)kUSBRqGetConfig << 8) + ( ( UInt16) kUSBDevice + (

1372

USB.h User-Space Reference Constants

( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kGetDescriptor = ( ( ( UInt16)kUSBRqGetDescriptor << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kGetInterface = ( ( ( UInt16)kUSBRqGetInterface << 8) + ( ( UInt16) kUSBInterface + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kGetDeviceStatus = ( ( ( UInt16)kUSBRqGetStatus << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kGetInterfaceStatus = ( ( ( UInt16)kUSBRqGetStatus << 8) + ( ( UInt16) kUSBInterface + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kGetEndpointStatus = ( ( ( UInt16)kUSBRqGetStatus << 8) + ( (

1373

USB.h User-Space Reference Constants

UInt16) kUSBEndpoint + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), kSetAddress = ( ( ( UInt16)kUSBRqSetAddress << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetConfiguration = ( ( ( UInt16)kUSBRqSetConfig << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetDescriptor = ( ( ( UInt16)kUSBRqSetDescriptor << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetDeviceFeature = ( ( ( UInt16)kUSBRqSetFeature << 8) + ( ( UInt16) kUSBDevice + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetInterfaceFeature = ( ( ( UInt16)kUSBRqSetFeature << 8) + (

1374

USB.h User-Space Reference Constants

( UInt16) kUSBInterface + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetEndpointFeature = ( ( ( UInt16)kUSBRqSetFeature << 8) + ( ( UInt16) kUSBEndpoint + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSetInterface = ( ( ( UInt16)kUSBRqSetInterface << 8) + ( ( UInt16) kUSBInterface + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBOut << kUSBRqDirnShift))), kSyncFrame = ( ( ( UInt16)kUSBRqSyncFrame << 8) + ( ( UInt16) kUSBEndpoint + ( ( UInt16) kUSBStandard << kUSBRqTypeShift) ( UInt16) kUSBIn << kUSBRqDirnShift))), };

Discussion Encoding of the standard device requests.

bmRequestType bRequest 00000000B 00000001B 00000010B CLEAR_FEATURE

wValue Feature Feature Feature

wIndex Zero Interface Endpoint

wLength Data Zero Zero Zero None (device) None (Interface) None (Endpoint)

1375

USB.h User-Space Reference Constants

10000000B 10000000B 10000001B

GET_CONFIGURATION Zero GET_DESCRIPTOR GET_INTERFACE Type Zero

Zero LangID Interface

One Length One

Configuration Descriptor Alternate

10000000B 10000001B 10000010B

GET_STATUS

Zero Zero Zero

Zero Interface Endpoint

Two Two Two

status (device) status (Interface) status (Endpoint)

00000000B 00000000B 00000000B

SET_ADDRESS

Address

Zero

Zero Zero Length

None None Descriptor

SET_CONFIGURATION Configuration Zero SET_DESCRIPTOR Type LangID

00000000B 00000001B 00000010B

SET_FEATURE

Feature Feature Feature

Zero Interface Endpoint

Zero Zero Zero

None (device) None (Interface) None (Endpoint)

00000001B 10000010B

SET_INTERFACE SYNCH_FRAME

Alternate Zero

Interface Endpoint

Zero Two

None Frame Number

USBDeviceSpeed

enum { kUSBDeviceSpeedLow = 0, kUSBDeviceSpeedFull = 1, kUSBDeviceSpeedHigh = 2, kUSBDeviceSpeedSuper = 3 };

Constants
kUSBDeviceSpeedLow

The device is a low speed device. Available in OS X v10.0 and later. Declared in USB.h.

1376

USB.h User-Space Reference Constants

kUSBDeviceSpeedFull

The device is a full speed device. Available in OS X v10.0 and later. Declared in USB.h.
kUSBDeviceSpeedHigh

The device is a high speed device. Available in OS X v10.2 and later. Declared in USB.h.
kUSBDeviceSpeedSuper

The device is a SuperSpeed device Available in OS X v10.8 and later. Declared in USB.h. Discussion Returns the speed of a particular USB device.

1377

USBSpec.h User-Space Reference

Declared in

USBSpec.h

Overview Constants
See the Overview for header-level documentation.

USB Descriptor and IORegistry constants

Constants and definitions of parameters that are used in communcating with USB devices and interfaces.

#define kUSB1284DeviceID "1284 Device ID" #define kUSBAlternateSetting "bAlternateSetting" #define kUSBConfigurationValue "bConfigurationValue" #define kUSBDeviceClass "bDeviceClass" #define kUSBDeviceMaxPacketSize "bMaxPacketSize0" #define kUSBDeviceNumConfigs "bNumConfigurations" #define kUSBDeviceProtocol "bDeviceProtocol" #define kUSBDeviceReleaseNumber "bcdDevice" #define kUSBDeviceSubClass "bDeviceSubClass" #define kUSBInterfaceClass "bInterfaceClass" #define kUSBInterfaceNumber "bInterfaceNumber" #define kUSBInterfaceProtocol "bInterfaceProtocol" #define kUSBInterfaceStringIndex "iInterface" #define kUSBInterfaceSubClass "bInterfaceSubClass" #define kUSBManufacturerStringIndex "iManufacturer" #define kUSBNumEndpoints "bNumEndpoints" #define kUSBProductID "idProduct" // good name #define kUSBProductName "idProduct" /* good name \ */ // bad name - keep for backward compatibility #define kUSBProductString "USB Product Name" #define kUSBProductStringIndex "iProduct"

1378

USBSpec.h User-Space Reference Constants

#define kUSBSerialNumberString "USB Serial Number" #define kUSBSerialNumberStringIndex "iSerialNumber" #define kUSBVendorID "idVendor" // good name #define kUSBVendorName "idVendor" /* good name \ */ // bad name - keep for backward compatibility #define kUSBVendorString "USB Vendor Name"

Constants
kUSB1284DeviceID

IORegistry key for the 1284 Device ID of a printer Available in OS X v10.6 and later. Declared in USBSpec.h.
kUSBAlternateSetting

The field in the USB Configuration Descriptor corresponding to the number of configurations Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBConfigurationValue

The field in the USB Interface Descriptor corresponding to the configuration Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBDeviceClass

The field in the USB Device Descriptor corresponding to the device class Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBDeviceMaxPacketSize

The field in the USB Device Descriptor corresponding to the maximum packet size for endpoint 0 Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBDeviceNumConfigs

The field in the USB Configuration Descriptor corresponding to the number of configurations Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBDeviceProtocol

The field in the USB Device Descriptor corresponding to the device protocol Available in OS X v10.0 and later. Declared in USBSpec.h.

1379

USBSpec.h User-Space Reference Constants

kUSBDeviceReleaseNumber

The field in the USB Device Descriptor corresponding to the device release version Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBDeviceSubClass

The field in the USB Device Descriptor corresponding to the device sub class Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBInterfaceClass

The field in the USB Interface Descriptor corresponding to the interface class Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBInterfaceNumber

The field in the USB Configuration Descriptor corresponding to the number of configurations Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBInterfaceProtocol

The field in the USB Interface Descriptor corresponding to the interface protocol Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBInterfaceStringIndex

The field in the USB Interface Descriptor corresponding to the index for the interface name's string Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBInterfaceSubClass

The field in the USB Interface Descriptor corresponding to the interface sub class Available in OS X v10.0 and later. Declared in USBSpec.h.
kUSBManufacturerStringIndex

The field in the USB Device Descriptor corresponding to the index for the manufacturer's string Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBNumEndpoints

The field in the USB Configuration Descriptor corresponding to the number of configurations Available in OS X v10.0 and later. Declared in USBSpec.h.

1380

USBSpec.h User-Space Reference Constants

kUSBProductID

The field in the USB Device Descriptor corresponding to the device USB Product ID Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBProductName

Deprecated. Use kUSBProductID Available in OS X v10.0 and later. Declared in USBSpec.h.

kUSBProductString

IORegistry key for the device's USB Product string Available in OS X v10.6 and later. Declared in USBSpec.h.
kUSBProductStringIndex

The field in the USB Device Descriptor corresponding to the index for the product name's string Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBSerialNumberString

IORegistry key for the device's USB serial number string Available in OS X v10.6 and later. Declared in USBSpec.h.
kUSBSerialNumberStringIndex

The field in the USB Device Descriptor corresponding to the index for the serial number's string Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBVendorID

The field in the USB Device Descriptor corresponding to the device USB Vendor ID Available in OS X v10.1 and later. Declared in USBSpec.h.
kUSBVendorName

Deprecated. Use kUSBVendorID Available in OS X v10.0 and later. Declared in USBSpec.h.

kUSBVendorString

IORegistry key for the device's USB manufacturer string Available in OS X v10.6 and later. Declared in USBSpec.h.

1381

USBSpec.h User-Space Reference Constants

Apple USB Vendor ID

enum { kAppleVendorID = 0x05AC };

Discussion Apple's vendor ID, assigned by the USB-IF

Device Capability Types

enum { kUSBDeviceCapabilityWirelessUSB = 1, kUSBDeviceCapabilityUSB20Extension = 2, kUSBDeviceCapabilitySuperSpeedUSB = 3, kUSBDeviceCapabilityContainerID = 4 };

Discussion Used with decoding the Device Capability descriptor

Device Class Codes

enum { kUSBCompositeClass = 0, kUSBCommClass = 2, // Deprecated kUSBCommunicationClass = 2, kUSBHubClass = 9, kUSBDataClass = 10, kUSBPersonalHealthcareClass = 15, kUSBDiagnosticClass = 220, kUSBWirelessControllerClass = 224, kUSBMiscellaneousClass = 239, kUSBApplicationSpecificClass = 254, kUSBVendorSpecificClass = 255 };

Discussion Constants for USB Device classes (bDeviceClass).

1382

USBSpec.h User-Space Reference Constants

Device Request

enum { kUSBRqGetStatus = 0, kUSBRqClearFeature = 1, kUSBRqGetState = 2, kUSBRqSetFeature = 3, kUSBRqReserved2 = 4, kUSBRqSetAddress = 5, kUSBRqGetDescriptor = 6, kUSBRqSetDescriptor = 7, kUSBRqGetConfig = 8, kUSBRqSetConfig = 9, kUSBRqGetInterface = 10, kUSBRqSetInterface = 11, kUSBRqSyncFrame = 12, kUSBSetSel = 48, kUSBSetIsochDelay = 49 };

Discussion Specifies values for the bRequest field of a Device Request.

Device Request Recipient

enum { kUSBDevice = 0, kUSBInterface = 1, kUSBEndpoint = 2, kUSBOther = 3 };

Discussion This recipient is encoded in the bmRequestType field of a Device Request. It specifies the type of recipient for a request: the device, the interface, or an endpoint.

Device Request Type

enum { kUSBStandard = 0, kUSBClass = 1,

1383

USBSpec.h User-Space Reference Constants

kUSBVendor = 2 };

Discussion This type is encoded in the bmRequestType field of a Device Request. It specifies the type of request: standard, class or vendor specific.

DFU Class Attributes

enum { kUSBDFUAttributesMask = 0x07, kUSBDFUCanDownloadBit = 0, kUSBDFUCanUploadBit = 1, kUSBDFUManifestationTolerantBit = 2 };

Endpoint Descriptor bits

enum { kUSBbEndpointAddressMask = 0x0f, kUSBbEndpointDirectionBit = 7, kUSBbEndpointDirectionMask = ( 1 << kUSBbEndpointDirectionBit ), kUSBEndpointDirectionOut = 0x00, kUSBEndpointDirectionIn = 0x80, kUSBEndpointbmAttributesTransferTypeMask = 0x03, kUSBEndpointbmAttributesSynchronizationTypeMask = 0x0c, kUSBEndpointbmAttributesSynchronizationTypeShift = 2, kUSBEndpointbmAttributesUsageTypeMask = 0x30, kUSBEndpointbmAttributesUsageTypeShift = 4 };

Discussion Bit definitions for endpoint descriptor fields

Endpoint direction

enum { kUSBOut = 0, kUSBIn = 1,

1384

USBSpec.h User-Space Reference Constants

kUSBNone = 2, kUSBAnyDirn = 3 };

Discussion Used in IOUSBFindEndpointRequest's direction field

Endpoint type

enum { kUSBControl = 0, kUSBIsoc = 1, kUSBBulk = 2, kUSBInterrupt = 3, kUSBAnyType = 0xFF };

Discussion Used in IOUSBFindEndpointRequest's type field

Feature Selectors

enum { kUSBFeatureEndpointStall = 0, // Endpoint kUSBFeatureDeviceRemoteWakeup = 1, // Device kUSBFeatureTestMode = 2, // Device kUSBFeatureFunctionSuspend = 0, // Interface kUSBFeatureU1Enable = 48, // Device kUSBFeatureU2Enable = 49, // Device kUSBFeatureLTMEnable = 50 // Device };

Discussion Used with SET/CLEAR_FEATURE requests.

HID Protocol

enum { kHIDBootProtocolValue = 0, kHIDReportProtocolValue = 1 };

1385

USBSpec.h User-Space Reference Constants

Discussion Used in the SET_PROTOCOL device request

HID report types

enum { kHIDRtInputReport = 1, kHIDRtOutputReport = 2, kHIDRtFeatureReport = 3 };

Discussion Constants for the three kinds of HID reports.

HID requests

enum { kHIDRqGetReport = 1, kHIDRqGetIdle = 2, kHIDRqGetProtocol = 3, kHIDRqSetReport = 9, kHIDRqSetIdle = 10, kHIDRqSetProtocol = 11 };

Discussion Constants for HID requests.

Interface Class

enum { kUSBAudioClass = 1, // Deprecated kUSBAudioInterfaceClass = 1, kUSBCommunicationControlInterfaceClass = 2, kUSBCommunicationDataInterfaceClass = 10, kUSBHIDClass = 3, kUSBHIDInterfaceClass = 3, kUSBPhysicalInterfaceClass = 5, kUSBImageInterfaceClass = 6, kUSBPrintingClass = 7, // Deprecated

1386

USBSpec.h User-Space Reference Constants

kUSBPrintingInterfaceClass = 7, kUSBMassStorageClass = 8, // Deprecated kUSBMassStorageInterfaceClass = 8, kUSBChipSmartCardInterfaceClass = 11, kUSBContentSecurityInterfaceClass = 13, kUSBVideoInterfaceClass = 14, kUSBPersonalHealthcareInterfaceClass = 15, kUSBDiagnosticDeviceInterfaceClass = 220, kUSBWirelessControllerInterfaceClass = 224, kUSBApplicationSpecificInterfaceClass = 254, kUSBVendorSpecificInterfaceClass = 255 };

Discussion Constants for Interface classes (bInterfaceClass).

Interface Protocol

enum { // For kUSBHubClass kHubSuperSpeedProtocol = 3, // For kUSBHIDInterfaceClass // kHIDNoInterfaceProtocol = 0, kHIDKeyboardInterfaceProtocol = 1, kHIDMouseInterfaceProtocol = 2, kUSBVendorSpecificProtocol = 0xff, // For kUSBDiagnosticDeviceInterfaceClass // kUSB2ComplianceDeviceProtocol = 0x01, // For kUSBWirelessControllerInterfaceClass // kUSBBluetoothProgrammingInterfaceProtocol = 0x01, // For kUSBMiscellaneousClass // KUSBInterfaceAssociationDescriptorProtocol = 0x01, // For Mass Storage // kMSCProtocolControlBulkInterrupt = 0x00, kMSCProtocolControlBulk = 0x01, kMSCProtocolBulkOnly = 0x50, kMSCProtocolUSBAttachedSCSI = 0x62 };

Discussion Reported in the bInterfaceProtocol field of the Interface Descriptor.

1387

USBSpec.h User-Space Reference Constants

Interface SubClass

enum { kUSBCompositeSubClass = 0, kUSBHubSubClass = 0, // For the kUSBAudioInterfaceClass // kUSBAudioControlSubClass = 0x01, kUSBAudioStreamingSubClass = 0x02, kUSBMIDIStreamingSubClass = 0x03, // For the kUSBApplicationSpecificInterfaceClass // kUSBDFUSubClass = 0x01, kUSBIrDABridgeSubClass = 0x02, kUSBTestMeasurementSubClass = 0x03, // For the kUSBMassStorageInterfaceClass // kUSBMassStorageRBCSubClass = 0x01, kUSBMassStorageATAPISubClass = 0x02, kUSBMassStorageQIC157SubClass = 0x03, kUSBMassStorageUFISubClass = 0x04, kUSBMassStorageSFF8070iSubClass = 0x05, kUSBMassStorageSCSISubClass = 0x06, // For the kUSBHIDInterfaceClass // kUSBHIDBootInterfaceSubClass = 0x01, // For the kUSBCommunicationDataInterfaceClass // kUSBCommDirectLineSubClass = 0x01, kUSBCommAbstractSubClass = 0x02, kUSBCommTelephoneSubClass = 0x03, kUSBCommMultiChannelSubClass = 0x04, kUSBCommCAPISubClass = 0x05, kUSBCommEthernetNetworkingSubClass = 0x06, kUSBATMNetworkingSubClass = 0x07, // For the kUSBDiagnosticDeviceInterfaceClass // kUSBReprogrammableDiagnosticSubClass = 0x01, // For the kUSBWirelessControllerInterfaceClass // kUSBRFControllerSubClass = 0x01, // For the kUSBMiscellaneousClass // kUSBCommonClassSubClass = 0x02, // For the kUSBVideoInterfaceClass // kUSBVideoControlSubClass = 0x01,

1388

USBSpec.h User-Space Reference Constants

kUSBVideoStreamingSubClass = 0x02, kUSBVideoInterfaceCollectionSubClass = 0x03 };

Discussion Constants for USB Interface SubClasses (bInterfaceSubClass).

Printer Class Requests

enum { kUSPrintingClassGetDeviceID = 0, kUSPrintingClassGePortStatus = 1, kUSPrintingClassSoftReset = 2 };

Discussion The bRequest parameter for Printing Class Sepcific Requests

USB Descriptors

enum { kUSBAnyDesc = 0, // Wildcard for searches kUSBDeviceDesc = 1, kUSBConfDesc = 2, kUSBStringDesc = 3, kUSBInterfaceDesc = 4, kUSBEndpointDesc = 5, kUSBDeviceQualifierDesc = 6, kUSBOtherSpeedConfDesc = 7, kUSBInterfacePowerDesc = 8, kUSBOnTheGoDesc = 9, kUSDebugDesc = 10, kUSBInterfaceAssociationDesc = 11, kUSBBOSDescriptor = 15, kUSBDeviceCapability = 16, kUSBSuperSpeedEndpointCompanion = 48, kUSB3HUBDesc = 0x2A, kUSBHIDDesc = 0x21, kUSBReportDesc = 0x22, kUSBPhysicalDesc = 0x23, kUSBHUBDesc = 0x29, };

1389

USBSpec.h User-Space Reference Constants

Discussion Specifies values for diffent descriptor types.

USB Device Capability Type constants

enum { kUSB20ExtensionLPMSupported = 1, // Bit 1 of bmAttributes of USB 2.0 Extension Device Capability kUSBSuperSpeedLTMCapable = 1, // Bit 1 of bmAttributes of SuperSpeed USB Device Capability kUSBSuperSpeedSupportsLS supports low speed kUSBSuperSpeedSupportsFS supports full speed kUSBSuperSpeedSupportsHS supports high speed kUSBSuperSpeedSupportsSS supports 5 Gbps }; = 0, // Value of wSpeedSupported indicating that the device = 1, // Value of wSpeedSupported indicating that the device = 2, // Value of wSpeedSupported indicating that the device = 3, // Value of wSpeedSupported indicating that the device

Discussion Bit definitions and constants for different values of USB Device Capability types

USB Power constants

enum { kUSB100mAAvailable = 50, kUSB500mAAvailable = 250, kUSB100mA = 50, kUSBAtrBusPowered = 0x80, kUSBAtrSelfPowered = 0x40, kUSBAtrRemoteWakeup = 0x20, kUSB2MaxPowerPerPort = kUSB500mAAvailable * 2, kUSB150mAAvailable = 75, kUSB900mAAvailable = 450, kUSB150mA = 75, kUSB3MaxPowerPerPort = kUSB900mAAvailable * 2 };

Discussion Constants relating to USB Power.

1390

USBSpec.h User-Space Reference Constants

USB Release constants

enum { kUSBRel10 kUSBRel11 kUSBRel20 kUSBRel30 };

= = = =

0x0100, 0x0110, 0x0200, 0x0300

Discussion Constants relating to USB releases as found in the bcdUSB field of the Device Descriptor.

1391

Apple Inc. 2011 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Aperture, FireWire, iPod, Logic, Mac, Mac OS, Numbers, OS X, Pages, Quartz, SuperDrive, and Tiger are trademarks of Apple Inc., registered in the U.S. and other countries. .Mac is a service mark of Apple Inc., registered in the U.S. and other countries. CDB is a trademark of Third Eye Software, Inc. Intel and Intel Core are registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. SPEC is a registered trademark of the Standard Performance Evaluation Corporation (SPEC).
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

(Ebook PDF) Starting Out With Java: From Control Structures Through Data Structures 4th Edition Download
100% (1)
(Ebook PDF) Starting Out With Java: From Control Structures Through Data Structures 4th Edition Download
51 pages
Apple Manual
No ratings yet
Apple Manual
83 pages
Apple Manual
No ratings yet
Apple Manual
220 pages
Writing PCIDrivers
No ratings yet
Writing PCIDrivers
34 pages
Serial Port Complete
100% (2)
Serial Port Complete
400 pages
MachO Topics
No ratings yet
MachO Topics
50 pages
PowerFactory Api PDF
No ratings yet
PowerFactory Api PDF
64 pages
Objective C Tutorial
100% (4)
Objective C Tutorial
80 pages
RAghaVA C Programs
100% (1)
RAghaVA C Programs
73 pages
OOps in Selenium Framework
No ratings yet
OOps in Selenium Framework
4 pages
Cs304 Grand Mega Quiz by Junaid
No ratings yet
Cs304 Grand Mega Quiz by Junaid
14 pages
Programming 622 C CA Test One Questions Answers
No ratings yet
Programming 622 C CA Test One Questions Answers
51 pages
Assemly Language 02: To Pay More Attention To Gain Better Result
No ratings yet
Assemly Language 02: To Pay More Attention To Gain Better Result
24 pages
Final Cut Pro X Exam Preparation Guide
100% (1)
Final Cut Pro X Exam Preparation Guide
26 pages
Learning Cocoa With Objective-C PDF
100% (2)
Learning Cocoa With Objective-C PDF
461 pages
Week 03 Assignment
No ratings yet
Week 03 Assignment
8 pages
Air2 Concorde144 Concorde Factsheet
100% (1)
Air2 Concorde144 Concorde Factsheet
1 page
18CS653 Module 3
No ratings yet
18CS653 Module 3
76 pages
MFi Accessory Firmware Specification R46 - NoRestriction
No ratings yet
MFi Accessory Firmware Specification R46 - NoRestriction
598 pages
Asynchronous Programming in Kotlin
No ratings yet
Asynchronous Programming in Kotlin
125 pages
Mastering C23
No ratings yet
Mastering C23
569 pages
Cisco CCIE 400-101 Study Guide
No ratings yet
Cisco CCIE 400-101 Study Guide
304 pages
OpenGL ICD Development
No ratings yet
OpenGL ICD Development
10 pages
Python Interview Questions Core Python
No ratings yet
Python Interview Questions Core Python
4 pages
F
No ratings yet
F
139 pages
Jntuk 2-1 Oopt C++ - Unit-1
No ratings yet
Jntuk 2-1 Oopt C++ - Unit-1
16 pages
Drawing With Quartz 2 D
100% (1)
Drawing With Quartz 2 D
221 pages
Pascal (Programming Language) : Jump To Navigationjump To Search
No ratings yet
Pascal (Programming Language) : Jump To Navigationjump To Search
16 pages
BCA-II Sem-IV CPP Journal 2024-25
No ratings yet
BCA-II Sem-IV CPP Journal 2024-25
16 pages
Topics: Passing Objects As Parameters
No ratings yet
Topics: Passing Objects As Parameters
19 pages
Concorde144fedex Parts
No ratings yet
Concorde144fedex Parts
7 pages
Python Dictionary: Accessing The Dictionary Values
No ratings yet
Python Dictionary: Accessing The Dictionary Values
4 pages
Java Oop
No ratings yet
Java Oop
4 pages
Snake and Ladder
No ratings yet
Snake and Ladder
4 pages
Apple Lisa: Sales Marketing Binder (February 1984)
0% (1)
Apple Lisa: Sales Marketing Binder (February 1984)
288 pages
UML Book
100% (1)
UML Book
314 pages
Core Java 1
No ratings yet
Core Java 1
13 pages
Apple Manual
No ratings yet
Apple Manual
95 pages
Concorde144ba Landor Parts
No ratings yet
Concorde144ba Landor Parts
7 pages
Reprint Bogen/sheet 16-B
No ratings yet
Reprint Bogen/sheet 16-B
1 page
Reprint Bogen/sheet 16-A
No ratings yet
Reprint Bogen/sheet 16-A
1 page
Assignment 04 Solution: Marks: 5
No ratings yet
Assignment 04 Solution: Marks: 5
6 pages
CoreMotion Reference PDF
No ratings yet
CoreMotion Reference PDF
77 pages
2019 Summer Model Answer Paper (Msbte Study Resources) 1
No ratings yet
2019 Summer Model Answer Paper (Msbte Study Resources) 1
23 pages
Strategic Report For Apple Computer Inc.: Elia Mrak-Blumberg Anna Renery Tycen Bundgaard April 2006
No ratings yet
Strategic Report For Apple Computer Inc.: Elia Mrak-Blumberg Anna Renery Tycen Bundgaard April 2006
43 pages
Day - 5 C-Programming
No ratings yet
Day - 5 C-Programming
17 pages
Concorde144af Parts PDF
No ratings yet
Concorde144af Parts PDF
7 pages
Memory Guide
No ratings yet
Memory Guide
317 pages
Assignment 1: Qualification BTEC Level 5 HND Diploma in Computing Unit Number and Title Submission Date
No ratings yet
Assignment 1: Qualification BTEC Level 5 HND Diploma in Computing Unit Number and Title Submission Date
27 pages
Tutorial 2 - Encapsulation, Inheritance, Polymorphism
No ratings yet
Tutorial 2 - Encapsulation, Inheritance, Polymorphism
3 pages
C-Operators, Associativity and Precedence: A Group Report Submitted To: MR Sachin Dave
No ratings yet
C-Operators, Associativity and Precedence: A Group Report Submitted To: MR Sachin Dave
8 pages
12 Xii CS
No ratings yet
12 Xii CS
4 pages
Libiio
No ratings yet
Libiio
44 pages
Mid Java PDF
No ratings yet
Mid Java PDF
14 pages
TED (21) 4281 QP
No ratings yet
TED (21) 4281 QP
2 pages
f2806x DRL Ug
No ratings yet
f2806x DRL Ug
72 pages
Xcode Quick Start Guide
No ratings yet
Xcode Quick Start Guide
54 pages
Macosxinternals Singh 1 PDF
No ratings yet
Macosxinternals Singh 1 PDF
146 pages
ELEX 2125 - Lab 10
No ratings yet
ELEX 2125 - Lab 10
9 pages
CoreBluetooth Concepts
No ratings yet
CoreBluetooth Concepts
56 pages
Concorde144aircan Parts
No ratings yet
Concorde144aircan Parts
7 pages
Air2 Concorde144 - Concorde Factsheet PDF
No ratings yet
Air2 Concorde144 - Concorde Factsheet PDF
1 page
Apple Lisa 1 - Papercraft Design: October 19, 2019
No ratings yet
Apple Lisa 1 - Papercraft Design: October 19, 2019
7 pages
Learning Pascal: Tutorial Lessons
No ratings yet
Learning Pascal: Tutorial Lessons
43 pages
Non Metal Finished
No ratings yet
Non Metal Finished
5 pages
Balu Sir (I Phone) PDF
No ratings yet
Balu Sir (I Phone) PDF
322 pages
The Objective-C Runtime Reference
No ratings yet
The Objective-C Runtime Reference
68 pages
IEEE 1394-1995 High Performance Serial Bus
No ratings yet
IEEE 1394-1995 High Performance Serial Bus
53 pages
Scroll View Reference
No ratings yet
Scroll View Reference
40 pages
Whats New in OSX
No ratings yet
Whats New in OSX
103 pages
Cocoa Fundamentals
No ratings yet
Cocoa Fundamentals
238 pages
Macintosh Quadra 900/950/ AWS 95: Service Source
No ratings yet
Macintosh Quadra 900/950/ AWS 95: Service Source
117 pages
Unix para Mac
No ratings yet
Unix para Mac
356 pages
CFBundles
No ratings yet
CFBundles
53 pages
Assembly
No ratings yet
Assembly
6 pages
OSX Technology Overview
No ratings yet
OSX Technology Overview
183 pages
Mac Mini Early Late 2006
No ratings yet
Mac Mini Early Late 2006
146 pages
Ipod Notes Feature Guide
No ratings yet
Ipod Notes Feature Guide
54 pages
Realm. Building Modern Swift Apps With Realm Database (2nd Edition) - 2019 (Todorov M.)
No ratings yet
Realm. Building Modern Swift Apps With Realm Database (2nd Edition) - 2019 (Todorov M.)
301 pages
OSX Support Essential 10.11
No ratings yet
OSX Support Essential 10.11
40 pages
Apple Powerbook 190, 5300
No ratings yet
Apple Powerbook 190, 5300
186 pages
Uikit Function Reference
No ratings yet
Uikit Function Reference
44 pages
Xcode Release Notes
No ratings yet
Xcode Release Notes
142 pages
Object-Oriented Programming With Objective-C
No ratings yet
Object-Oriented Programming With Objective-C
40 pages
Os Eclipse Iphone CDT PDF
No ratings yet
Os Eclipse Iphone CDT PDF
34 pages
IOKit Lib
No ratings yet
IOKit Lib
30 pages
HTML language complete
From Everand
HTML language complete
Hiyesh Ratee
No ratings yet
Iphone Development, A Tutorial.: Jonathan Mohlenhoff
No ratings yet
Iphone Development, A Tutorial.: Jonathan Mohlenhoff
61 pages
Twido Programming Guide
No ratings yet
Twido Programming Guide
604 pages
Chapter-6 IO Interfaces
No ratings yet
Chapter-6 IO Interfaces
49 pages
I Phone App Programming Guide - Guiders
No ratings yet
I Phone App Programming Guide - Guiders
153 pages
IOKit Keys
No ratings yet
IOKit Keys
3 pages
Drawing With Quartz 2 D
No ratings yet
Drawing With Quartz 2 D
229 pages
CoreText Framework Ref
No ratings yet
CoreText Framework Ref
178 pages
Quartz Composer User Guide
No ratings yet
Quartz Composer User Guide
72 pages
Programming The GPIO in Spear Board
No ratings yet
Programming The GPIO in Spear Board
62 pages
CFLocales
No ratings yet
CFLocales
18 pages
Mastering The Spritekit Framework: Develop Professional Games With This New Ios 7 Framework
From Everand
Mastering The Spritekit Framework: Develop Professional Games With This New Ios 7 Framework
Peter van de Put
No ratings yet
Beginning C# 6 Programming with Visual Studio 2015
From Everand
Beginning C# 6 Programming with Visual Studio 2015
Benjamin Perkins
No ratings yet