ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

 


IOStorage

Inherits from:
Declared In:

Overview

The common base class for mass storage objects.

Discussion

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.



Functions

complete
handleClose
handleIsOpen
handleOpen
open
read(IOService *, UInt64, IOMemoryDescriptor *, IOStorageAttributes *, IOStorageCompletion *)
read(IOService *, UInt64, IOMemoryDescriptor *, UInt64 *)
synchronizeCache
write(IOService *, UInt64, IOMemoryDescriptor *, IOStorageAttributes *, IOStorageCompletion *)
write(IOService *, UInt64, IOMemoryDescriptor *, UInt64 *)

complete


public

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.


handleClose


protected

virtual void handleClose( IOService *client, IOOptionBits options) = 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.


handleIsOpen


protected

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.


handleOpen


protected

virtual bool handleOpen( IOService *client, IOOptionBits options, 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.


open


public

virtual bool open( IOService *client, IOOptionBits options, IOStorageAccess access);
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).


read(IOService *, UInt64, IOMemoryDescriptor *, IOStorageAttributes *, IOStorageCompletion *)


public

virtual void read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion);
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.


read(IOService *, UInt64, IOMemoryDescriptor *, UInt64 *)


public

virtual IOReturn read( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, UInt64 *actualByteCount = 0);
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.

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.


synchronizeCache


public

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.


write(IOService *, UInt64, IOMemoryDescriptor *, IOStorageAttributes *, IOStorageCompletion *)


public

virtual void write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, IOStorageAttributes *attributes, IOStorageCompletion *completion);
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.


write(IOService *, UInt64, IOMemoryDescriptor *, UInt64 *)


public

virtual IOReturn write( IOService *client, UInt64 byteStart, IOMemoryDescriptor *buffer, UInt64 *actualByteCount = 0);
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.

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.


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.

 

Last Updated: 2008-12-19