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

IOMedia

Inherits from:	IOStorage
Declared In:	IOMedia.h

Overview

A random-access disk device abstraction.

Discussion

The IOMedia class is a random-access disk device abstraction. It provides a consistent interface for both real and virtual disk devices, for subdivisions of disks such as partitions, for supersets of disks such as RAID volumes, and so on. It extends the IOStorage class by implementing the appropriate open, close, read, write, and matching semantics for media objects. The properties it has reflect the properties of real disk devices, such as ejectability and writability.

The read and write interfaces support byte-level access to the storage space, with the appropriate deblocking handled by the block storage driver, however, a typical client will want to get the natural block size in order to optimize access to the real disk device. A read or write is accepted so long as the client's access is valid, the media is formatted and the transfer is within the bounds of the media. An optional non-zero base (offset) is then applied before the read or write is passed to provider object.

Functions

getAttributes
getBase
getContent
getContentHint
getPreferredBlockSize
getSize
handleClose
handleIsOpen
handleOpen
init
isEjectable
isFormatted
isWhole
isWritable
read
synchronizeCache
write

getAttributes

public

virtual IOMediaAttributeMask getAttributes() const;

Return Value

Media attributes, such as ejectability and removability. See IOMediaAttributeMask.

Discussion

Ask the media object for its attributes.

getBase

public

virtual UInt64 getBase() const;

Discussion

Ask the media object for its byte offset relative to its provider media object below it in the storage hierarchy. Media offset, in bytes.

getContent

public

virtual const char * getContent() const;

Return Value

Description of media's contents.

Discussion

Ask the media object for a description of its contents. The description is the same as the hint at the time of the object's creation, but it is possible that the description has been overridden by a client (which has probed the media and identified the content correctly) of the media object. It is more accurate than the hint for this reason. The string is formed in the likeness of Apple's "Apple_HFS" strings or in the likeness of a UUID.

The content description can be overridden by any client that matches onto this media object with a match category of kIOStorageCategory. The media object checks for a kIOMediaContentMaskKey property in the client, and if it finds one, it copies it into kIOMediaContentKey property.

getContentHint

public

virtual const char * getContentHint() const;

Return Value

Hint of media's contents.

Discussion

Ask the media object for a hint of its contents. The hint is set at the time of the object's creation, should the creator have a clue as to what it may contain. The hint string does not change for the lifetime of the object and is also formed in the likeness of Apple's "Apple_HFS" strings or in the likeness of a UUID.

getPreferredBlockSize

public

virtual UInt64 getPreferredBlockSize() const;

Return Value

Natural block size, in bytes.

Discussion

Ask the media object for its natural block size. This information is useful to clients that want to optimize access to the media.

getSize

public

virtual UInt64 getSize() const;

Return Value

Media size, in bytes.

Discussion

Ask the media object for its total length in bytes.

handleClose

protected

virtual void handleClose(
    IOService *client,
    IOOptionBits options);

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.

This implementation replaces the IOService definition of handleClose().

handleIsOpen

protected

virtual bool handleIsOpen(
    const IOService * client) const;

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.

This implementation replaces the IOService definition of handleIsOpen().

handleOpen

protected

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

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.

This implementation replaces the IOService definition of handleOpen().

init

public

virtual bool init(
    UInt64 base, 
    UInt64 size, 
    UInt64 preferredBlockSize, 
    IOMediaAttributeMask attributes, 
    bool isWhole, 
    bool isWritable, 
    const char * contentHint = 0, 
    OSDictionary *properties = 0);

Parameters

base: Media offset, in bytes.
size: Media size, in bytes.
preferredBlockSize: Natural block size, in bytes.
attributes: Media attributes, such as ejectability and removability. See IOMediaAttributeMask.
isWhole: Indicates whether the media represents the whole disk.
isWritable: Indicates whether the media is writable.
contentHint: Hint of media's contents (optional). See getContentHint().
properties: Substitute property table for this object (optional).

Return Value

Returns true on success, false otherwise.

Discussion

Initialize this object's minimal state.

isEjectable

public

virtual bool isEjectable() const;

Return Value

Returns true if the media is ejectable, false otherwise.

Discussion

Ask the media object whether it is ejectable.

isFormatted

public

virtual bool isFormatted() const;

Return Value

Returns true if the media is formatted, false otherwise.

Discussion

Ask the media object whether it is formatted.

isWhole

public

virtual bool isWhole() const;

Return Value

Returns true if the media represents the whole disk, false otherwise.

Discussion

Ask the media object whether it represents the whole disk.

isWritable

public

virtual bool isWritable() const;

Return Value

Returns true if the media is writable, false otherwise.

Discussion

Ask the media object whether it is writable.

read

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.

synchronizeCache

public

virtual IOReturn synchronizeCache(
    IOService *client);

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

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.

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