ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IODataQueueClient.h

Include Path:	<IOKit/IODataQueueClient.h>
Path:	/System/Library/Frameworks/IOKit.framework/Versions/A/Headers/IODataQueueClient.h
Includes:	<sys/cdefs.h> <AvailabilityMacros.h> <libkern/OSTypes.h> <mach/port.h> <IOKit/IOReturn.h> <IOKit/IODataQueueShared.h>

Overview

This header contains functions to allow a user-space client to interact with an I/O Kit data queue. These queues are typically used to allow a device driver or family to communicate a continuous stream of data to a client, such as might be required for an audio device serial port driver.

Functions

IODataQueueAllocateNotificationPort: Allocates and returns a new mach port able to receive data available notifications from an IODataQueue.
IODataQueueDataAvailable: Determines if more data is available on the queue.
IODataQueueDequeue: Dequeues the next available entry on the queue and copies it into the given data pointer.
IODataQueueEnqueue: Enqueues a new entry on the queue.
IODataQueuePeek: Peeks at the next entry on the queue.
IODataQueueSetNotificationPort: Creates a simple mach message targeting the mach port specified in port.
IODataQueueWaitForAvailableData: Wait for an incoming dataAvailable message on the given notifyPort.

IODataQueueAllocateNotificationPort

Allocates and returns a new mach port able to receive data available notifications from an IODataQueue.

mach_port_t IODataQueueAllocateNotificationPort();

Return Value

Returns a newly allocated mach port on success. On failure, it returns MACH_PORT_NULL.

Discussion

This port is intended to be passed down into the kernel and into an IODataQueue to allow it to send the appropriate notification. The returned mach port is allocated with a queue limit of one message. This allows only one mach message to be queued up at a time. The IODataQueue code is written with the restriction in mind and will only queue up a message if no messages alread have been sent.

IODataQueueDataAvailable

Determines if more data is available on the queue.

Boolean IODataQueueDataAvailable(
    IODataQueueMemory *dataQueue);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel.

Return Value

Returns true if data is available and false if not.

IODataQueueDequeue

Dequeues the next available entry on the queue and copies it into the given data pointer.

IOReturn IODataQueueDequeue(
    IODataQueueMemory *dataQueue,
    void *data,
    uint32_t *dataSize);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel.
data: A pointer to the data memory region in which to copy the next entry data on the queue. If this parameter is 0 (NULL), it will simply move to the next entry.
dataSize: A pointer to the size of the data parameter. On return, this contains the size of the actual entry data - even if the original size was not large enough.

Return Value

Returns kIOReturnSuccess on success. Other return values possible are: kIOReturnUnderrun - queue is empty, kIOReturnBadArgument - no dataQueue or no dataSize, kIOReturnNoSpace - dataSize is too small for entry.

Discussion

This function will dequeue the next available entry on the queue. If a data pointer is provided, it will copy the data into the memory region if there is enough space available as specified in the dataSize parameter. If no data pointer is provided, it will simply move the head value past the current entry.

IODataQueueEnqueue

Enqueues a new entry on the queue.

IOReturn IODataQueueEnqueue(
    IODataQueueMemory *dataQueue,
    void *data,
    uint32_t dataSize);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel created from an IOSharedDataQueue.
data: Pointer to the data to be added to the queue.
dataSize: Size of the data pointed to by data.

Return Value

Returns kIOReturnSuccess on success. Other return values possible are: kIOReturnOverrun - queue is full.

Discussion

This method adds a new data entry of dataSize to the queue. It sets the size parameter of the entry pointed to by the tail value and copies the memory pointed to by the data parameter in place in the queue. Once that is done, it moves the tail to the next available location. When attempting to add a new entry towards the end of the queue and there isn't enough space at the end, it wraps back to the beginning.
If the queue is empty when a new entry is added, the port specified in IODataQueueSetNotificationPort will be used to send a message to the client process that data is now available.
Please note that using this method without mapped memory create from an IOSharedDataQueue will result in undefined behavior.

Availability: Introduced in Mac OS X v10.5.

IODataQueuePeek

Peeks at the next entry on the queue.

IODataQueueEntry *IODataQueuePeek(
    IODataQueueMemory *dataQueue);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel.

Return Value

Returns a pointer to the next IODataQueueEntry if one is available. Zero is returned if the queue is empty.

Discussion

This function can be used to look at the next entry which allows the entry to be received without having to copy it with IODataQueueDequeue. In order to do this, call IODataQueuePeek to get the entry. Then call IODataQueueDequeue with a NULL data pointer. That will cause the head to be moved to the next entry, but no memory to be copied.

IODataQueueSetNotificationPort

Creates a simple mach message targeting the mach port specified in port.

IOReturn IODataQueueSetNotificationPort(
    IODataQueueMemory *dataQueue,
    mach_port_t notifyPort);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel created from an IOSharedDataQueue.
notifyPort: The mach port to target with the notification message.

Return Value

Returns kIOReturnSuccess on success. Returns kIOReturnBadArgument if either dataQueue is 0 (NULL).

Discussion

This message is sent when data is added to an empty queue. It is to notify another user process that new data has become available. Please note that using this method without mapped memory create from an IOSharedDataQueue will result in undefined behavior.

Availability: Introduced in Mac OS X v10.5.

IODataQueueWaitForAvailableData

Wait for an incoming dataAvailable message on the given notifyPort.

IOReturn IODataQueueWaitForAvailableData(
    IODataQueueMemory *dataQueue,
    mach_port_t notificationPort);

Parameters

dataQueue: The IODataQueueMemory region mapped from the kernel.
notifyPort: Mach port on which to listen for incoming messages.

Return Value

Returns kIOReturnSuccess on success. Returns kIOReturnBadArgument if either dataQueue is 0 (NULL) or notiryPort is MACH_PORT_NULL. Returns the result of the mach_msg() listen call on the given port.

Discussion

This method will simply wait for an incoming message on the given notifyPort. Once it is received, the return from mach_msg() is returned.

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: 2009-02-23