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 */