|
ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference
|
IOBlockStorageDevice |
| Inherits from: | |
| Declared In: |
A generic block storage device abstraction.
The IOBlockStorageDevice class exports the generic block storage protocol, independent of the physical connection protocol (e.g. SCSI, ATA, USB), forwarding all requests to its provider (the Transport Driver). Though the nub does no actual processing of requests, it is necessary in a C++ environment. The Transport Driver can be of any type, as long as it inherits from IOService. Because Transport Drivers needn't derive from a type known to IOBlockStorageDriver, it isn't possible for IOBlockStorageDriver to include the appropriate header file to allow direct communication with the Transport Driver. Thus we achieve polymorphism by having the Transport Driver instantiate a subclass of IOBlockStorageDevice. A typical implementation for a concrete subclass of IOBlockStorageDevice simply relays all methods to its provider (the Transport Driver), which implements the protocol- and device-specific behavior.
All pure-virtual functions must be implemented by the Transport Driver, which is responsible for instantiating the Nub.
Starts an asynchronous read or write operation.
Starts an asynchronous read or write operation.
Ejects the media.
Formats the media to the specified byte capacity.
Returns the allowable formatting byte capacities.
Locks or unlock the (removable) media in the drive.
Forces data blocks in the hardware's buffer to be flushed to the media.
Returns additional informational string for the device.
Returns Product Name string for the device.
Returns Product Revision string for the device.
Returns Vendor Name string for the device.
Reports the current write cache state of the device.
Allows IOBlockStorageDevice to set a property (not usually overridden by developers).
Reports the block size for the device, in bytes.
Reports if the media is ejectable under software control.
Reports if the media is lockable under software control.
Reports the maximum allowed byte transfer for read operations.
Reports the highest valid block for the device.
Reports the maximum allowed byte transfer for write operations.
Reports the device's media state.
Reports if it's necessary to poll for media insertion, and if polling is expensive.
Reports whether the media is removable or not.
Reports whether the media is write-protected or not.
Sets the write cache state of the device.
doAsyncReadWrite(IOMemoryDescriptor *, UInt32, UInt32, IOStorageCompletion) |
Starts an asynchronous read or write operation.
public
virtual IOReturn doAsyncReadWrite( IOMemoryDescriptor *buffer, UInt32 block, UInt32 nblks, IOStorageCompletion completion) = 0;
bufferAn IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsibility for releasing the descriptor rests with the caller.
blockThe starting block number of the data transfer.
nblksThe integral number of blocks to be transferred.
completionThe completion routine to call once the data transfer is complete.
doAsyncReadWrite(IOMemoryDescriptor *, UInt64, UInt64, IOStorageCompletion) |
Starts an asynchronous read or write operation.
public
virtual IOReturn doAsyncReadWrite( IOMemoryDescriptor *buffer, UInt64 block, UInt64 nblks, IOStorageCompletion completion);
bufferAn IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsibility for releasing the descriptor rests with the caller.
blockThe starting block number of the data transfer.
nblksThe integral number of blocks to be transferred.
completionThe completion routine to call once the data transfer is complete.
doEjectMedia |
Ejects the media.
public
virtual IOReturn doEjectMedia( void) = 0;
doFormatMedia |
Formats the media to the specified byte capacity.
public
virtual IOReturn doFormatMedia( UInt64 byteCapacity) = 0;
byteCapacityThe byte capacity to which the device is to be formatted, if possible.
The specified byte capacity must be one supported by the device. Supported capacities can be obtained by calling doGetFormatCapacities.
doGetFormatCapacities |
Returns the allowable formatting byte capacities.
public
virtual UInt32 doGetFormatCapacities( UInt64 *capacities, UInt32 capacitiesMaxCount) const = 0;
capacitiesPointer for returning the list of capacities.
capacitiesMaxCountThe number of capacity values returned in "capacities," or if no buffer is given, the total number of capacity values available.
This function returns the supported byte capacities for the device.
doLockUnlockMedia |
Locks or unlock the (removable) media in the drive.
public
virtual IOReturn doLockUnlockMedia( bool doLock) = 0;
doLockTrue to lock the media, False to unlock.
This method should only be called if the media is known to be removable.
doSynchronizeCache |
Forces data blocks in the hardware'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.
getAdditionalDeviceInfoString |
Returns additional informational string for the device.
public
virtual char * getAdditionalDeviceInfoString( void) = 0;
A pointer to a static character string.
getProductString |
Returns Product Name string for the device.
public
virtual char * getProductString( void) = 0;
A pointer to a static character string.
getRevisionString |
Returns Product Revision string for the device.
public
virtual char * getRevisionString( void) = 0;
A pointer to a static character string.
getVendorString |
Returns Vendor Name string for the device.
public
virtual char * getVendorString( void) = 0;
A pointer to a static character string.
getWriteCacheState |
Reports the current write cache state of the device.
public
virtual IOReturn getWriteCacheState( bool *enabled);
enabledPointer to returned result. True indicates the write cache is enabled; False indicates the write cache is disabled.
Reports the current write cache state of the device. The write cache state is not guaranteed to persist across reboots and detaches.
init |
Allows IOBlockStorageDevice to set a property (not usually overridden by developers).
public
virtual bool init( OSDictionary *properties);
This function is overridden so that IOBlockStorageDevice can set a property, used by IOBlockStorageDriver for matching. Since the concrete subclass of IOBlockStorageDevice can be of any class type, the property is used for matching.
This function is usually not overridden by developers.
reportBlockSize |
Reports the block size for the device, in bytes.
public
virtual IOReturn reportBlockSize( UInt64 *blockSize) = 0;
blockSizePointer to returned block size value.
reportEjectability |
Reports if the media is ejectable under software control.
public
virtual IOReturn reportEjectability( bool *isEjectable) = 0;
isEjectablePointer to returned result. True indicates the media is ejectable, False indicates the media cannot be ejected under software control.
This method should only be called if the media is known to be removable.
reportLockability |
Reports if the media is lockable under software control.
public
virtual IOReturn reportLockability( bool *isLockable) = 0;
isLockablePointer to returned result. True indicates the media can be locked in place; False indicates the media cannot be locked by software.
This method should only be called if the media is known to be removable.
reportMaxReadTransfer |
Reports the maximum allowed byte transfer for read operations.
public
virtual IOReturn reportMaxReadTransfer ( UInt64 blockSize, UInt64 *max) = 0;
blockSizeThe block size desired for the transfer.
maxPointer to returned result.
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.
reportMaxValidBlock |
Reports the highest valid block for the device.
public
virtual IOReturn reportMaxValidBlock( UInt64 *maxBlock) = 0;
maxBlockPointer to returned result
reportMaxWriteTransfer |
Reports the maximum allowed byte transfer for write operations.
public
virtual IOReturn reportMaxWriteTransfer( UInt64 blockSize, UInt64 *max) = 0;
blockSizeThe block size desired for the transfer.
maxPointer to returned result.
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.
reportMediaState |
Reports the device's media state.
public
virtual IOReturn reportMediaState( bool *mediaPresent, bool *changedState) = 0;
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.
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 mediaPresent and changedState will *not* be stored.
reportPollRequirements |
Reports if it's necessary to poll for media insertion, and if polling is expensive.
public
virtual IOReturn reportPollRequirements( bool *pollRequired, bool *pollIsExpensive) = 0;
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.
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.
reportRemovability |
Reports whether the media is removable or not.
public
virtual IOReturn reportRemovability( bool *isRemovable) = 0;
isRemovablePointer to returned result. True indicates that the media is removable; False indicates the media is not removable.
This method reports whether the media is removable, but it does not provide detailed information regarding software eject or lock/unlock capability.
reportWriteProtection |
Reports whether the media is write-protected or not.
public
virtual IOReturn reportWriteProtection( bool *isWriteProtected) = 0;
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).
setWriteCacheState |
Sets the write cache state of the device.
public
virtual IOReturn setWriteCacheState( bool enabled);
enabledTrue to enable the write cache; False to disable the write cache.
Sets the write cache state of the device. The write cache state is not guaranteed to persist across reboots and detaches.
|
Last Updated: 2009-02-23