Mac Developer Library

Developer

IOBlockStorageDevice Class Reference

Options
Deployment Target:

On This Page
Language:

IOBlockStorageDevice

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Start an asynchronous read or write operation.

    Declaration

    C++

    #ifdef __LP64__ virtual IOReturn doAsyncReadWrite( IOMemoryDescriptor *buffer, UInt64 block, UInt64 nblks, IOStorageAttributes *attributes, IOStorageCompletion *completion) = 0; #else /* !__LP64__ */ virtual IOReturn doAsyncReadWrite( IOMemoryDescriptor *buffer, UInt64 block, UInt64 nblks, IOStorageAttributes *attributes, IOStorageCompletion *completion); #endif /* !__LP64__ */

    Parameters

    buffer

    An IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsibility for releasing the descriptor rests with the caller.

    block

    The starting block number of the data transfer.

    nblks

    The integral number of blocks to be transferred.

    attributes

    Attributes of the data transfer. See IOStorageAttributes.

    completion

    The completion routine to call once the data transfer is complete.

  • Eject the media.

    Declaration

    C++

    virtual IOReturn doEjectMedia( void) = 0;

  • Format the media to the specified byte capacity.

    Declaration

    C++

    virtual IOReturn doFormatMedia( UInt64byteCapacity) = 0;

    Parameters

    byteCapacity

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

    Discussion

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

  • Return the allowable formatting byte capacities.

    Declaration

    C++

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

    Parameters

    capacities

    Pointer for returning the list of capacities.

    capacitiesMaxCount

    The number of capacity values returned in "capacities," or if no buffer is given, the total number of capacity values available.

    Discussion

    This function returns the supported byte capacities for the device.

  • Force data blocks in the hardware's buffer to be flushed to the media.

    Declaration

    C++

    virtual IOReturn doSynchronizeCache( void) = 0;

    Discussion

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

  • Delete unused data blocks from the media.

    Declaration

    C++

    virtual IOReturn doUnmap( IOBlockStorageDeviceExtent *extents, UInt32extentsCount, UInt32 options = 0);

    Parameters

    extents

    List of extents. See IOBlockStorageDeviceExtent. It is legal for the callee to overwrite the contents of this buffer in order to satisfy the request.

    extentsCount

    Number of extents.

  • Return additional informational string for the device.

    Declaration

    C++

    virtual char * getAdditionalDeviceInfoString( void) = 0;

    Return Value

    A pointer to a static character string.

  • Return Product Name string for the device.

    Declaration

    C++

    virtual char * getProductString( void) = 0;

    Return Value

    A pointer to a static character string.

  • Return Product Revision string for the device.

    Declaration

    C++

    virtual char * getRevisionString( void) = 0;

    Return Value

    A pointer to a static character string.

  • Return Vendor Name string for the device.

    Declaration

    C++

    virtual char * getVendorString( void) = 0;

    Return Value

    A pointer to a static character string.

  • Reports the current write cache state of the device.

    Declaration

    C++

    #ifdef __LP64__ virtual IOReturn getWriteCacheState( bool *enabled) = 0; #else /* !__LP64__ */ virtual IOReturn getWriteCacheState( bool *enabled); #endif /* !__LP64__ */

    Parameters

    enabled

    Pointer to returned result. True indicates the write cache is enabled; False indicates the write cache is disabled.

    Discussion

    Reports the current write cache state of the device. The write cache state is not guaranteed to persist across reboots and detaches.

  • Declaration

    C++

    virtual bool init( OSDictionary *properties);

    Discussion

    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.

  • Report the block size for the device, in bytes.

    Declaration

    C++

    virtual IOReturn reportBlockSize( UInt64 *blockSize) = 0;

    Parameters

    blockSize

    Pointer to returned block size value.

  • Report if the media is ejectable under software control.

    Declaration

    C++

    virtual IOReturn reportEjectability( bool *isEjectable) = 0;

    Parameters

    isEjectable

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

    Discussion

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

  • Report the highest valid block for the device.

    Declaration

    C++

    virtual IOReturn reportMaxValidBlock( UInt64 *maxBlock) = 0;

    Parameters

    maxBlock

    Pointer to returned result

  • Report the device's media state.

    Declaration

    C++

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

    Parameters

    mediaPresent

    Pointer to returned media state. True indicates media is present in the device; False indicates no media is present.

    Discussion

    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.

  • Report whether the media is removable or not.

    Declaration

    C++

    virtual IOReturn reportRemovability( bool *isRemovable) = 0;

    Parameters

    isRemovable

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

    Discussion

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

  • Report whether the media is write-protected or not.

    Declaration

    C++

    virtual IOReturn reportWriteProtection( bool *isWriteProtected) = 0;

    Parameters

    isWriteProtected

    Pointer 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).

  • Request that the device enter an idle state.

    Declaration

    C++

    virtual IOReturn requestIdle( void);

    Discussion

    Request that the device enter an idle state. The device will exit this state on the next read or write request, or as it sees necessary. One example is for a DVD drive to spin down when it enters such an idle state, and spin up on the next read request from the system.

  • Sets the write cache state of the device.

    Declaration

    C++

    #ifdef __LP64__ virtual IOReturn setWriteCacheState( bool enabled) = 0; #else /* !__LP64__ */ virtual IOReturn setWriteCacheState( bool enabled); #endif /* !__LP64__ */

    Parameters

    enabled

    True to enable the write cache; False to disable the write cache.

    Discussion

    Sets the write cache state of the device. The write cache state is not guaranteed to persist across reboots and detaches.