1/*
2 * Copyright (c) 1999-2008 Apple Computer, Inc.  All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24#ifndef _IOKIT_HID_IOHIDQUEUE_USER_H
25#define _IOKIT_HID_IOHIDQUEUE_USER_H
26
27#include <CoreFoundation/CoreFoundation.h>
28#include <IOKit/hid/IOHIDBase.h>
29
30/*!
31	@header IOHIDQueue
32    IOHIDQueue defines an object used to queue values from input parsed items
33    (IOHIDElement) contained within a Human Interface Device (HID) object.  This
34    object is useful when you need to keep track of all values of an input
35    element, rather than just the most recent one.  IOHIDQueue is a CFType
36    object and as such conforms to all the conventions expected such object.
37    <p>
38    IOHIDQueue should be considered optional and is only useful for working with
39    complex input elements.  These elements include those whose length are
40    greater than sizeof(CFIndex) or elements that are duplicate items.
41    Whenever possible please defer to using
42    IOHIDManagerRegisterInputValueCallback or
43    IOHIDDeviceRegisterInputValueCallback.
44    <p>
45    <b>Note:</b>Absolute element values (based on a fixed origin) will only be
46    placed on a queue if there is a change in value.
47    <p>
48    This documentation assumes that you have a basic understanding of the material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a>
49    For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts
50    in the "Device Access and the I/O Kit" chapter of <i>Accessing Hardware From Applications</i>.
51
52    This documentation also assumes you have read <a href="http://developer.apple.com/documentation/DeviceDrivers/HumanInterfaceDeviceForceFeedback-date.html"><i>Human Interface Device & Force Feedback</i></a>.
53    Please review documentation before using this reference.
54    <p>
55    All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDQueue.h</font> found at
56    <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDQueue.h</font>.
57*/
58
59__BEGIN_DECLS
60
61/*! @typedef IOHIDQueueRef
62	This is the type of a reference to the IOHIDQueue.
63*/
64typedef struct __IOHIDQueue * IOHIDQueueRef;
65
66/*!
67	@function   IOHIDQueueGetTypeID
68	@abstract   Returns the type identifier of all IOHIDQueue instances.
69*/
70CF_EXPORT
71CFTypeID IOHIDQueueGetTypeID(void)
72AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
73
74/*!
75	@function   IOHIDQueueCreate
76	@abstract   Creates an IOHIDQueue object for the specified device.
77    @discussion Take care in specifying an appropriate depth to prevent dropping
78                events.
79    @param      allocator Allocator to be used during creation.
80    @param      device IOHIDDevice object
81    @param      depth The number of values that can be handled by the queue.
82    @param      options Reserved for future use.
83    @result     Returns a new IOHIDQueueRef.
84*/
85CF_EXPORT
86IOHIDQueueRef IOHIDQueueCreate(
87                                CFAllocatorRef                  allocator,
88                                IOHIDDeviceRef                  device,
89                                CFIndex                         depth,
90                                IOOptionBits                    options)
91AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
92
93/*!
94	@function   IOHIDQueueGetDevice
95	@abstract   Obtain the device associated with the queue.
96    @param      queue IOHIDQueue to be queried.
97    @result     Returns the a reference to the device.
98*/
99CF_EXPORT
100IOHIDDeviceRef IOHIDQueueGetDevice(
101                                IOHIDQueueRef                   queue)
102AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
103
104
105/*!
106	@function   IOHIDQueueGetDepth
107	@abstract   Obtain the depth of the queue.
108    @param      queue IOHIDQueue to be queried.
109    @result     Returns the queue depth.
110*/
111CF_EXPORT
112CFIndex IOHIDQueueGetDepth(
113                                IOHIDQueueRef                   queue)
114AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
115
116/*!
117	@function   IOHIDQueueSetDepth
118	@abstract   Sets the depth of the queue.
119    @discussion Set the appropriate depth value based on the number of elements
120                contained in a queue.
121    @param      queue IOHIDQueue object to be modified.
122    @param      depth The new queue depth.
123*/
124CF_EXPORT
125void IOHIDQueueSetDepth(
126                                IOHIDQueueRef                   queue,
127                                CFIndex                         depth)
128AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
129
130/*!
131	@function   IOHIDQueueAddElement
132	@abstract   Adds an element to the queue
133    @param      queue IOHIDQueue object to be modified.
134    @param      element Element to be added to the queue.
135*/
136CF_EXPORT
137void IOHIDQueueAddElement(
138                                IOHIDQueueRef                   queue,
139                                IOHIDElementRef                 element)
140AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
141
142/*!
143	@function   IOHIDQueueRemoveElement
144	@abstract   Removes an element from the queue
145    @param      queue IOHIDQueue object to be modified.
146    @param      element Element to be removed from the queue.
147*/
148CF_EXPORT
149void IOHIDQueueRemoveElement(
150                                IOHIDQueueRef                   queue,
151                                IOHIDElementRef                 element)
152AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
153
154/*!
155	@function   IOHIDQueueContainsElement
156	@abstract   Queries the queue to determine if elemement has been added.
157    @param      queue IOHIDQueue object to be queried.
158    @param      element Element to be queried.
159    @result     Returns true or false depending if element is present.
160*/
161CF_EXPORT
162Boolean IOHIDQueueContainsElement(
163                                IOHIDQueueRef                   queue,
164                                IOHIDElementRef                 element)
165AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
166
167/*!
168    @function   IOHIDQueueStart
169    @abstract   Starts element value delivery to the queue.
170    @param      queue IOHIDQueue object to be started.
171*/
172CF_EXPORT
173void IOHIDQueueStart(           IOHIDQueueRef                   queue)
174AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
175
176/*!
177    @function   IOHIDQueueStop
178    @abstract   Stops element value delivery to the queue.
179    @param      queue IOHIDQueue object to be stopped.
180*/
181CF_EXPORT
182void IOHIDQueueStop(            IOHIDQueueRef                   queue)
183AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
184
185/*!
186	@function   IOHIDQueueScheduleWithRunLoop
187	@abstract   Schedules queue with run loop.
188    @discussion Formally associates queue with client's run loop. Scheduling
189                this queue with the run loop is necessary before making
190                use of any asynchronous APIs.
191    @param      queue IOHIDQueue object to be modified.
192    @param      runLoop RunLoop to be used when scheduling any asynchronous
193                activity.
194    @param      runLoopMode Run loop mode to be used when scheduling any
195                asynchronous activity.
196*/
197CF_EXPORT
198void IOHIDQueueScheduleWithRunLoop(
199                                IOHIDQueueRef                   queue,
200                                CFRunLoopRef                    runLoop,
201                                CFStringRef                     runLoopMode)
202AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
203
204/*!
205	@function   IOHIDQueueUnscheduleFromRunLoop
206	@abstract   Unschedules queue with run loop.
207    @discussion Formally disassociates queue with client's run loop.
208    @param      queue IOHIDQueue object to be modified.
209    @param      runLoop RunLoop to be used when scheduling any asynchronous
210                activity.
211    @param      runLoopMode Run loop mode to be used when scheduling any
212                asynchronous activity.
213*/
214CF_EXPORT
215void IOHIDQueueUnscheduleFromRunLoop(
216                                IOHIDQueueRef                   queue,
217                                CFRunLoopRef                    runLoop,
218                                CFStringRef                     runLoopMode)
219AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
220
221/*!
222	@function   IOHIDQueueRegisterValueAvailableCallback
223	@abstract   Sets callback to be used when the queue transitions to non-empty.
224    @discussion In order to make use of asynchronous behavior, the queue needs
225                to be scheduled with the run loop.
226    @param      queue IOHIDQueue object to be modified.
227    @param      callback Callback of type IOHIDCallback to be used when data is
228                placed on the queue.
229    @param      context Pointer to data to be passed to the callback.
230*/
231CF_EXPORT
232void IOHIDQueueRegisterValueAvailableCallback(
233                                IOHIDQueueRef                   queue,
234                                IOHIDCallback                   callback,
235                                void *                          context)
236AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
237
238/*!
239    @function   IOHIDQueueCopyNextValue
240    @abstract   Dequeues a retained copy of an element value from the head of an
241                IOHIDQueue.
242    @discussion Because the value is a retained copy, it is up to the caller to
243                release the value using CFRelease. Use with setValueCallback to
244                avoid polling the queue for data.
245    @param      queue IOHIDQueue object to be queried.
246    @result     Returns valid IOHIDValueRef if data is available.
247*/
248CF_EXPORT
249IOHIDValueRef IOHIDQueueCopyNextValue(
250                                IOHIDQueueRef                   queue)
251AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
252
253/*!
254    @function   IOHIDQueueCopyNextValueWithTimeout
255    @abstract   Dequeues a retained copy of an element value from the head of an
256                IOHIDQueue.  This method will block until either a value is
257                available or it times out.
258    @discussion Because the value is a retained copy, it is up to the caller to
259                release the value using CFRelease. Use with setValueCallback to
260                avoid polling the queue for data.
261    @param      queue IOHIDQueue object to be queried.
262    @param      timeout Timeout before aborting an attempt to dequeue a value
263                from the head of a queue.
264    @result     Returns valid IOHIDValueRef if data is available.
265*/
266CF_EXPORT
267IOHIDValueRef IOHIDQueueCopyNextValueWithTimeout(
268                                IOHIDQueueRef                   queue,
269                                CFTimeInterval                  timeout)
270AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
271
272__END_DECLS
273
274#endif /* _IOKIT_HID_IOHIDQUEUE_USER_H */