IOHDDriveNub



Member Functions

doAsyncReadWrite

Abstract: Start an asynchronous read or write operation.
public:

virtual IOReturn doAsyncReadWrite(IOMemoryDescriptor *buffer, UInt32 block,UInt32 nblks, gdCompletionFunction action, IOService *target,void *param) = 0;

Parameters

NameDescription
bufferAn IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
blockThe starting block number of the data transfer.
nblksThe integral number of blocks to be transferred.
actionThe C function called upon completion of the data transfer.
targetThe C++ class "this" pointer, passed as an argument to "action."
paramThis value is passed as an argument to "action." It is not validated or modified.

doEjectMedia

Abstract: Eject the media.
public:

virtual IOReturn doEjectMedia(void) = 0;


doFormatMedia

Abstract: Format the media to the specified byte capacity.
public:

virtual IOReturn doFormatMedia(UInt64 byteCapacity) = 0;

The specified byte capacity must be one supported by the device. Supported capacities can be obtained by calling doGetFormatCapacities.

Parameters

NameDescription
byteCapacityThe byte capacity to which the device is to be formatted, if possible.

doGetFormatCapacities

Abstract: Return the allowable formatting byte capacities.
public:

virtual UInt32 doGetFormatCapacities(UInt64 * capacities, UInt32 capacitiesMaxCount) const = 0;

This function returns the supported byte capacities for the device.

Parameters

NameDescription
capacitiesPointer for returning the list of capacities.
capacitiesMaxCountThe number of capacity values returned in "capacities."

doLockUnlockMedia

Abstract: Lock or unlock the (removable) media in the drive.
public:

virtual IOReturn doLockUnlockMedia(bool doLock) = 0;

This method should only be called if the media is known to be removable.

Parameters

NameDescription
doLockTrue to lock the media, False to unlock.

doSyncReadWrite

Abstract: Perform a synchronous read or write operation.
public:

virtual IOReturn doSyncReadWrite(IOMemoryDescriptor *buffer, UInt32 block,UInt32 nblks) = 0;

Parameters

NameDescription
bufferAn IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
blockThe starting block number of the data transfer.
nblksThe integral number of blocks to be transferred.

doSynchronizeCache

Abstract: Force data blocks in the drive's buffer to be flushed to the media.
public:

virtual IOReturn doSynchronizeCache(void) = 0;

This method should only be called if the media is writable.


executeCdb

Abstract: Issue the client's cdb as a pass-through.
public:

virtual IOReturn executeCdb(struct cdbParams *params) = 0;

This method is provided to allow developers to issue arbitrary commands to the device (via the Transport Driver). Expected uses would include vendor-specific commands to effect password-protection, or for other vendor features.

This method may not be supported by all Transport Drivers. For example, ATA devices do not have a CDB concept; those Transport Drivers will return kIOReturnUnsupported.

Parameters

NameDescription
paramsSee IOHDTypes.h for the layout of this data structure.

getAdditionalDeviceInfoString

Abstract: Return additional informational string for the device.
public:

virtual char * getAdditionalDeviceInfoString(void) = 0;

Result: A pointer to a static character string.

getProductString

Abstract: Return Product Name string for the device.
public:

virtual char * getProductString(void) = 0;

Result: A pointer to a static character string.

getRevisionString

Abstract: Return Product Revision string for the device.
public:

virtual char * getRevisionString(void) = 0;

Result: A pointer to a static character string.

getVendorString

Abstract: Return Vendor Name string for the device.
public:

virtual char * getVendorString(void) = 0;

Result: A pointer to a static character string.

init

public:

virtual bool init(OSDictionary * properties);

This function is overridden so that IOHDDriveNub can set a property, used by IOHDDrive for matching. Since the concrete subclass of IOHDDriveNub can be of any class type, the property is used for matching.

This function is usually not overridden by developers.


reportBlockSize

Abstract: Report the block size for the device, in bytes.
public:

virtual IOReturn reportBlockSize(UInt64 *blockSize) = 0;

Parameters

NameDescription
blockSizePointer to returned block size value.

reportEjectability

Abstract: Report if the media is ejectable under software control.
public:

virtual IOReturn reportEjectability(bool *isEjectable) = 0;

This method should only be called if the media is known to be removable.

Parameters

NameDescription
isEjectablePointer to returned result. True indicates the media is ejectable, False indicates the media cannot be ejected under software control.

reportLockability

Abstract: Report if the media is lockable under software control.
public:

virtual IOReturn reportLockability(bool *isLockable) = 0;

This method should only be called if the media is known to be removable.

Parameters

NameDescription
isLockablePointer to returned result. True indicates the media can be locked in place; False indicates the media cannot be locked by software.

reportMaxReadTransfer

Abstract: Report the maximum allowed byte transfer for read operations.
public:

virtual IOReturn reportMaxReadTransfer(UInt64 blockSize,UInt64 *max) = 0;

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer.

Parameters

NameDescription
blockSizeThe block size desired for the transfer.
maxPointer to returned result.

reportMaxValidBlock

Abstract: Report the highest valid block for the device.
public:

virtual IOReturn reportMaxValidBlock(UInt64 *maxBlock) = 0;

Parameters

NameDescription
maxBlockPointer to returned result

reportMaxWriteTransfer

Abstract: Report the maximum allowed byte transfer for write operations.
public:

virtual IOReturn reportMaxWriteTransfer(UInt64 blockSize,UInt64 *max) = 0;

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer.

Parameters

NameDescription
blockSizeThe block size desired for the transfer.
maxPointer to returned result.

reportMediaState

Abstract: Report the device's media state.
public:

virtual IOReturn reportMediaState(bool *mediaPresent,bool *changedState) = 0;

This method reports whether we have media in the drive or not, and whether the state has changed from the previously reported state.

A result of kIOReturnSuccess is always returned if the test for media is successful, regardless of media presence. The mediaPresent result should be used to determine whether media is present or not. A return other than kIOReturnSuccess indicates that the Transport Driver was unable to interrogate the device. In this error case, the outputs mediaState and changedState will *not* be stored.

Parameters

NameDescription
mediaPresentPointer to returned media state. True indicates media is present in the device; False indicates no media is present.
changedStatePointer to returned result. True indicates a change of state since prior calls, False indicates that the state has not changed.

reportPollRequirements

Abstract: Report if it's necessary to poll for media insertion, and if polling is expensive.
public:

virtual IOReturn reportPollRequirements(bool *pollRequired, bool *pollIsExpensive) = 0;

This method reports whether the device must be polled to detect media insertion, and whether a poll is expensive to perform.

The term "expensive" typically implies a device that must be spun-up to detect media, as on a PC floppy. Most devices can detect media inexpensively.

Parameters

NameDescription
pollRequiredPointer to returned result. True indicates that polling is required; False indicates that polling is not required to detect media.
pollIsExpensivePointer to returned result. True indicates that the polling operation is expensive; False indicates that the polling operation is cheap.

reportRemovability

Abstract: Report whether the media is removable or not.
public:

virtual IOReturn reportRemovability(bool *isRemovable) = 0;

This method reports whether the media is removable, but it does not provide detailed information regarding software eject or lock/unlock capability.

Parameters

NameDescription
isRemovablePointer to returned result. True indicates that the media is removable; False indicates the media is not removable.

reportWriteProtection

Abstract: Report whether the media is write-protected or not.
public:

virtual IOReturn reportWriteProtection(bool *isWriteProtected) = 0;

Parameters

NameDescription
isWriteProtectedPointer to returned result. True indicates that the media is write-protected (it cannot be written); False indicates that the media is not write-protected (it is permissible to write).

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)