Mac Developer Library

Developer

IOStorage Class Reference

Options
Deployment Target:

On This Page
Language:

IOStorage

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.6 and later.

The common base class for mass storage objects.

The IOStorage class is the common base class for mass storage objects. It is an abstract class that defines the open/close/read/write APIs that need to be implemented in a given subclass. Synchronous versions of the read/write APIs are provided here -- they are coded in such a way as to wrap the asynchronous versions implemented in the subclass.

  • Declaration

    C++

    static void complete( IOStorageCompletion *completion, IOReturn status, UInt64 actualByteCount = 0);

    Parameters

    completion

    Completion information for the data transfer.

    status

    Status of the data transfer.

    actualByteCount

    Actual number of bytes transferred in the data transfer.

    Discussion

    Invokes the specified completion action of the read/write request. If the completion action is unspecified, no action is taken. This method serves simply as a convenience to storage subclass developers.

  • Declaration

    C++

    virtual IOStorage * copyPhysicalExtent( IOService *client, UInt64 *byteStart, UInt64 *byteCount);

    Parameters

    client

    Client requesting the operation.

    byteStart

    Starting byte offset for the operation. Returns a physical byte offset, relative to the physical storage object, on success.

    byteCount

    Size of the operation. Returns the actual number of bytes which can be transferred, relative to the physical storage object, on success.

    Return Value

    A reference to the physical storage object, which should be released by the caller, or a null on error.

    Discussion

    Convert the specified byte offset into a physical byte offset, relative to a physical storage object. This call should only be made within the context of lockPhysicalExtents().

  • Declaration

    C++

    virtual void handleClose( IOService *client, IOOptionBitsoptions) = 0;

    Parameters

    client

    Client requesting the close.

    options

    Options for the close. Set to zero.

    Discussion

    The handleClose method closes the client's access to this object.

  • Declaration

    C++

    virtual bool handleIsOpen( const IOService *client) const = 0;

    Parameters

    client

    Client to check the open state of. Set to zero to check the open state of all clients.

    Return Value

    Returns true if the client was (or clients were) open, false otherwise.

    Discussion

    The handleIsOpen method determines whether the specified client, or any client if none is specified, presently has an open on this object.

  • Declaration

    C++

    virtual bool handleOpen( IOService *client, IOOptionBitsoptions, void *access) = 0;

    Parameters

    client

    Client requesting the open.

    options

    Options for the open. Set to zero.

    access

    Access level for the open. Set to kIOStorageAccessReader or kIOStorageAccessReaderWriter.

    Return Value

    Returns true if the open was successful, false otherwise.

    Discussion

    The handleOpen method grants or denies permission to access this object to an interested client. The argument is an IOStorageAccess value that specifies the level of access desired -- reader or reader-writer.

    This method can be invoked to upgrade or downgrade the access level for an existing client as well. The previous access level will prevail for upgrades that fail, of course. A downgrade should never fail. If the new access level should be the same as the old for a given client, this method will do nothing and return success. In all cases, one, singular close-per-client is expected for all opens-per-client received.

  • Declaration

    C++

    virtual bool lockPhysicalExtents( IOService *client);

    Parameters

    client

    Client requesting the operation.

    Return Value

    Returns true if the lock was successful, false otherwise.

    Discussion

    Lock the contents of the storage object against relocation temporarily, for the purpose of getting physical extents.

  • Declaration

    C++

    virtual bool open( IOService *client, IOOptionBitsoptions, IOStorageAccessaccess);

    Parameters

    client

    Client requesting the open.

    options

    Options for the open. Set to zero.

    access

    Access level for the open. Set to kIOStorageAccessReader or kIOStorageAccessReaderWriter.

    Return Value

    Returns true if the open was successful, false otherwise.

    Discussion

    Ask the storage object for permission to access its contents; the method is equivalent to IOService::open(), but with the correct parameter types.

    This method may also be invoked to upgrade or downgrade the access of an existing open (if it fails, the existing open prevails).

  • Declaration

    C++

    #ifdef __LP64__ virtual IOReturn read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes = 0, UInt64 *actualByteCount = 0); #else /* !__LP64__ */ virtual IOReturn read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, UInt64 *actualByteCount = 0); #endif /* !__LP64__ */

    Parameters

    client

    Client requesting the read.

    byteStart

    Starting byte offset for the data transfer.

    buffer

    Buffer for the data transfer. The size of the buffer implies the size of the data transfer.

    attributes

    Attributes of the data transfer. See IOStorageAttributes.

    actualByteCount

    Returns the actual number of bytes transferred in the data transfer.

    Return Value

    Returns the status of the data transfer.

    Discussion

    Read data from the storage object at the specified byte offset into the specified buffer, synchronously. When the read completes, this method will return to the caller. The actual byte count field is optional.

  • Declaration

    C++

    #ifdef __LP64__ virtual void read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion) = 0; #else /* !__LP64__ */ virtual void read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion); #endif /* !__LP64__ */

    Parameters

    client

    Client requesting the read.

    byteStart

    Starting byte offset for the data transfer.

    buffer

    Buffer for the data transfer. The size of the buffer implies the size of the data transfer.

    attributes

    Attributes of the data transfer. See IOStorageAttributes. It is the responsibility of the callee to maintain the information for the duration of the data transfer, as necessary.

    completion

    Completion routine to call once the data transfer is complete. It is the responsibility of the callee to maintain the information for the duration of the data transfer, as necessary.

    Discussion

    Read data from the storage object at the specified byte offset into the specified buffer, asynchronously. When the read completes, the caller will be notified via the specified completion action.

    The buffer will be retained for the duration of the read.

  • Declaration

    C++

    virtual IOReturn synchronizeCache( IOService *client) = 0;

    Parameters

    client

    Client requesting the cache synchronization.

    Return Value

    Returns the status of the cache synchronization.

    Discussion

    Flush the cached data in the storage object, if any, synchronously.

  • Declaration

    C++

    virtual void unlockPhysicalExtents( IOService *client);

    Parameters

    client

    Client requesting the operation.

    Discussion

    Unlock the contents of the storage object for relocation again. This call must balance a successful call to lockPhysicalExtents().

  • Declaration

    C++

    virtual IOReturn unmap( IOService *client, IOStorageExtent *extents, UInt32extentsCount, UInt32 options = 0);

    Parameters

    client

    Client requesting the operation.

    extents

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

    extentsCount

    Number of extents.

    Return Value

    Returns the status of the operation.

    Discussion

    Delete unused data from the storage object at the specified byte offsets, synchronously.

  • Declaration

    C++

    #ifdef __LP64__ virtual IOReturn write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes = 0, UInt64 *actualByteCount = 0); #else /* !__LP64__ */ virtual IOReturn write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, UInt64 *actualByteCount = 0); #endif /* !__LP64__ */

    Parameters

    client

    Client requesting the write.

    byteStart

    Starting byte offset for the data transfer.

    buffer

    Buffer for the data transfer. The size of the buffer implies the size of the data transfer.

    attributes

    Attributes of the data transfer. See IOStorageAttributes.

    actualByteCount

    Returns the actual number of bytes transferred in the data transfer.

    Return Value

    Returns the status of the data transfer.

    Discussion

    Write data into the storage object at the specified byte offset from the specified buffer, synchronously. When the write completes, this method will return to the caller. The actual byte count field is optional.

  • Declaration

    C++

    #ifdef __LP64__ virtual void write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion) = 0; #else /* !__LP64__ */ virtual void write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion); #endif /* !__LP64__ */

    Parameters

    client

    Client requesting the write.

    byteStart

    Starting byte offset for the data transfer.

    buffer

    Buffer for the data transfer. The size of the buffer implies the size of the data transfer.

    attributes

    Attributes of the data transfer. See IOStorageAttributes. It is the responsibility of the callee to maintain the information for the duration of the data transfer, as necessary.

    completion

    Completion routine to call once the data transfer is complete. It is the responsibility of the callee to maintain the information for the duration of the data transfer, as necessary.

    Discussion

    Write data into the storage object at the specified byte offset from the specified buffer, asynchronously. When the write completes, the caller will be notified via the specified completion action.

    The buffer will be retained for the duration of the write.