| 1 | /*␊ |
| 2 | *␊ |
| 3 | * @APPLE_LICENSE_HEADER_START@␊ |
| 4 | * ␊ |
| 5 | * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.␊ |
| 6 | * ␊ |
| 7 | * This file contains Original Code and/or Modifications of Original Code␊ |
| 8 | * as defined in and that are subject to the Apple Public Source License␊ |
| 9 | * Version 2.0 (the 'License'). You may not use this file except in␊ |
| 10 | * compliance with the License. Please obtain a copy of the License at␊ |
| 11 | * http://www.opensource.apple.com/apsl/ and read it before using this␊ |
| 12 | * file.␊ |
| 13 | * ␊ |
| 14 | * The Original Code and all software distributed under the License are␊ |
| 15 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 16 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 17 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 18 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.␊ |
| 19 | * Please see the License for the specific language governing rights and␊ |
| 20 | * limitations under the License.␊ |
| 21 | * ␊ |
| 22 | * @APPLE_LICENSE_HEADER_END@␊ |
| 23 | */␊ |
| 24 | ␊ |
| 25 | #ifndef _IOKIT_HID_IOHIDDEVICE_H␊ |
| 26 | #define _IOKIT_HID_IOHIDDEVICE_H␊ |
| 27 | ␊ |
| 28 | #include <IOKit/IOService.h>␊ |
| 29 | #include <IOKit/IOMessage.h>␊ |
| 30 | #include <IOKit/IOBufferMemoryDescriptor.h>␊ |
| 31 | #include <IOKit/hidsystem/IOHIDDescriptorParser.h>␊ |
| 32 | #include <IOKit/hid/IOHIDKeys.h>␊ |
| 33 | ␊ |
| 34 | class IOHIDSystem;␊ |
| 35 | class IOHIDPointing;␊ |
| 36 | class IOHIDKeyboard;␊ |
| 37 | class IOHIDConsumer;␊ |
| 38 | class IOHIDElementPrivate;␊ |
| 39 | class IOHIDEventQueue;␊ |
| 40 | class IOHIDInterface;␊ |
| 41 | class IOHIDDeviceShim;␊ |
| 42 | struct IOHIDReportHandler;␊ |
| 43 | ␊ |
| 44 | /*!␊ |
| 45 | @typedef IOHIDCompletionAction␊ |
| 46 | @abstract Function called when set/get report completes␊ |
| 47 | @param target The target specified in the IOHIDCompletion struct.␊ |
| 48 | @param parameter The parameter specified in the IOHIDCompletion struct.␊ |
| 49 | @param status Completion status␊ |
| 50 | */␊ |
| 51 | typedef void (*IOHIDCompletionAction)(␊ |
| 52 | void *␉␉␉target,␊ |
| 53 | void *␉␉␉parameter,␊ |
| 54 | IOReturn␉␉status,␊ |
| 55 | UInt32␉␉␉bufferSizeRemaining);␊ |
| 56 | ␊ |
| 57 | /*!␊ |
| 58 | @typedef IOHIDCompletion␊ |
| 59 | @abstract Struct spefifying action to perform when set/get report completes.␊ |
| 60 | @param target The target to pass to the action function.␊ |
| 61 | @param action The function to call.␊ |
| 62 | @param parameter The parameter to pass to the action function.␊ |
| 63 | */␊ |
| 64 | typedef struct IOHIDCompletion {␊ |
| 65 | void * ␉␉␉target;␊ |
| 66 | IOHIDCompletionAction␉action;␊ |
| 67 | void *␉␉␉parameter;␊ |
| 68 | } IOHIDCompletion;␊ |
| 69 | ␊ |
| 70 | /*!␊ |
| 71 | @enum IOHIDReportOption␊ |
| 72 | @abstract Option bits for IOHIDDevice::handleReport, ␊ |
| 73 | IOHIDDevice::getReport, and IOHIDDevice::setReport␊ |
| 74 | @constant kIOHIDReportOptionNotInterrupt Tells method that the report␊ |
| 75 | passed was not interrupt driven.␊ |
| 76 | */␊ |
| 77 | enum␊ |
| 78 | {␊ |
| 79 | kIOHIDReportOptionNotInterrupt␉= 0x100␊ |
| 80 | };␊ |
| 81 | ␊ |
| 82 | ␊ |
| 83 | /*! @class IOHIDDevice : public IOService␊ |
| 84 | @abstract IOHIDDevice defines a Human Interface Device (HID) object,␊ |
| 85 | which will interact with the HID Manager by publishing static properties␊ |
| 86 | in the registry, and also by reporting HID events through shared memory.␊ |
| 87 | IOHIDDevice is an abstract class that must be subclassed to support a␊ |
| 88 | specific type of HID devices, such as USB HID class devices.␊ |
| 89 | <br>␊ |
| 90 | Since most HID devices are expected to be USB devices, IOHIDDevice␊ |
| 91 | uses the USB HID specification to define the format of the report␊ |
| 92 | descriptor, and also reports that are used to communicate with the␊ |
| 93 | hardware via some intervening transport layer. However, there is no␊ |
| 94 | mandate that the transport layer must be restricted to USB. A subclass␊ |
| 95 | may be created to support legacy ADB joysticks, and issue packets on␊ |
| 96 | the ADB bus and translate those packets to USB reports, and vice versa.␊ |
| 97 | IOHIDDevice does not care how those reports are generated or consumed␊ |
| 98 | by the physical device, as long as the reports abide to the USB␊ |
| 99 | specification. */␊ |
| 100 | ␊ |
| 101 | class IOHIDDevice : public IOService␊ |
| 102 | {␊ |
| 103 | OSDeclareDefaultStructors( IOHIDDevice )␊ |
| 104 | ␊ |
| 105 | friend class IOHIDLibUserClient;␊ |
| 106 | friend class IOHIDDeviceShim;␊ |
| 107 | ␊ |
| 108 | private:␊ |
| 109 | OSArray * _elementArray;␊ |
| 110 | UInt32 _dataElementIndex;␊ |
| 111 | IORecursiveLock * _elementLock;␊ |
| 112 | IOHIDReportHandler * _reportHandlers;␊ |
| 113 | IOBufferMemoryDescriptor * _elementValuesDescriptor;␊ |
| 114 | bool _readyForInputReports;␊ |
| 115 | UInt32 _reportCount;␊ |
| 116 | UInt32 _maxInputReportSize;␊ |
| 117 | UInt32 _maxOutputReportSize;␊ |
| 118 | UInt32 _maxFeatureReportSize;␊ |
| 119 | ␊ |
| 120 | struct ExpansionData { ␊ |
| 121 | OSSet * clientSet;␊ |
| 122 | IOService * seizedClient;␊ |
| 123 | AbsoluteTime eventDeadline;␊ |
| 124 | IONotifier * publishNotify;␊ |
| 125 | OSArray * inputInterruptElementArray;␊ |
| 126 | ␉␉bool performTickle;␊ |
| 127 | ␉␉IOHIDInterface * interfaceNub;␊ |
| 128 | IOHIDElementPrivate * rollOverElement;␊ |
| 129 | OSArray * hierarchElements;␊ |
| 130 | };␊ |
| 131 | /*! @var reserved␊ |
| 132 | Reserved for future use. (Internal use only) */␊ |
| 133 | ExpansionData * _reserved;␊ |
| 134 | ␊ |
| 135 | // HID report descriptor parsing support.␊ |
| 136 | ␊ |
| 137 | bool linkToParent( const OSArray * array,␊ |
| 138 | UInt32 parentIndex,␊ |
| 139 | UInt32 childIndex );␊ |
| 140 | ␊ |
| 141 | bool createCollectionElements( HIDPreparsedDataRef parseData,␊ |
| 142 | OSArray * array,␊ |
| 143 | UInt32 maxCount );␊ |
| 144 | ␊ |
| 145 | bool createValueElements( HIDPreparsedDataRef parseData,␊ |
| 146 | OSArray * array,␊ |
| 147 | UInt32 hidReportType,␊ |
| 148 | IOHIDElementType elementType,␊ |
| 149 | UInt32 maxCount );␊ |
| 150 | ␊ |
| 151 | bool createButtonElements( HIDPreparsedDataRef parseData,␊ |
| 152 | OSArray * array,␊ |
| 153 | UInt32 hidReportType,␊ |
| 154 | IOHIDElementType elementType,␊ |
| 155 | UInt32 maxCount );␊ |
| 156 | ␊ |
| 157 | bool createReportHandlerElements( HIDPreparsedDataRef parseData);␊ |
| 158 | ␊ |
| 159 | OSArray * newDeviceUsagePairs();␊ |
| 160 | ␊ |
| 161 | bool getReportCountAndSizes( HIDPreparsedDataRef parseData );␊ |
| 162 | ␊ |
| 163 | bool setReportSize( UInt8 reportID,␊ |
| 164 | IOHIDReportType reportType,␊ |
| 165 | UInt32 bits );␊ |
| 166 | ␊ |
| 167 | IOReturn createElementHierarchy( HIDPreparsedDataRef parseData );␊ |
| 168 | ␊ |
| 169 | IOReturn parseReportDescriptor( IOMemoryDescriptor * report,␊ |
| 170 | IOOptionBits options = 0 );␊ |
| 171 | ␊ |
| 172 | IOBufferMemoryDescriptor * createMemoryForElementValues();␊ |
| 173 | ␊ |
| 174 | ␊ |
| 175 | static bool _publishNotificationHandler( void * target, ␊ |
| 176 | ␉␉␉␉void * ref, IOService * newService );␊ |
| 177 | ␊ |
| 178 | protected:␊ |
| 179 | ␊ |
| 180 | /*! @function free␊ |
| 181 | @abstract Free the IOHIDDevice object.␊ |
| 182 | @discussion Release all resources that were previously allocated,␊ |
| 183 | then call super::free() to propagate the call to our superclass. */␊ |
| 184 | ␊ |
| 185 | virtual void free();␊ |
| 186 | ␊ |
| 187 | /*! @function handleOpen␊ |
| 188 | @abstract Handle a client open on the interface.␊ |
| 189 | @discussion This method is called by IOService::open() with the␊ |
| 190 | arbitration lock held, and must return true to accept the client open.␊ |
| 191 | This method will in turn call handleClientOpen() to qualify the client␊ |
| 192 | requesting the open.␊ |
| 193 | @param client The client object that requested the open.␊ |
| 194 | @param options Options passed to IOService::open().␊ |
| 195 | @param argument Argument passed to IOService::open().␊ |
| 196 | @result true to accept the client open, false otherwise. */␊ |
| 197 | ␊ |
| 198 | virtual bool handleOpen(IOService * client,␊ |
| 199 | IOOptionBits options,␊ |
| 200 | void * argument);␊ |
| 201 | ␊ |
| 202 | /*! @function handleClose␊ |
| 203 | @abstract Handle a client close on the interface.␊ |
| 204 | @discussion This method is called by IOService::close() with the␊ |
| 205 | arbitration lock held. This method will in turn call handleClientClose()␊ |
| 206 | to notify interested subclasses about the client close. If this represents␊ |
| 207 | the last close, then the interface will also close the controller before␊ |
| 208 | this method returns. The controllerWillClose() method will be called before␊ |
| 209 | closing the controller. Subclasses should not override this method.␊ |
| 210 | @param client The client object that requested the close.␊ |
| 211 | @param options Options passed to IOService::close(). */␊ |
| 212 | ␊ |
| 213 | virtual void handleClose(IOService * client, IOOptionBits options);␊ |
| 214 | ␊ |
| 215 | /*! @function handleIsOpen␊ |
| 216 | @abstract Query whether a client has an open on the interface.␊ |
| 217 | @discussion This method is always called by IOService with the␊ |
| 218 | arbitration lock held. Subclasses should not override this method.␊ |
| 219 | @result true if the specified client, or any client if none (0) is␊ |
| 220 | specified, presently has an open on this object. */␊ |
| 221 | ␊ |
| 222 | virtual bool handleIsOpen(const IOService * client) const;␊ |
| 223 | ␊ |
| 224 | /*! @function handleStart␊ |
| 225 | @abstract Prepare the hardware and driver to support I/O operations.␊ |
| 226 | @discussion IOHIDDevice will call this method from start() before␊ |
| 227 | any I/O operations are issued to the concrete subclass. Methods␊ |
| 228 | such as newReportDescriptor() are only called after handleStart()␊ |
| 229 | has returned true. A subclass that overrides this method should␊ |
| 230 | begin its implementation by calling the version in super, and␊ |
| 231 | then check the return value.␊ |
| 232 | @param provider The provider argument passed to start().␊ |
| 233 | @result True on success, or false otherwise. Returning false will␊ |
| 234 | cause start() to fail and return false. */␊ |
| 235 | ␊ |
| 236 | virtual bool handleStart( IOService * provider );␊ |
| 237 | ␊ |
| 238 | /*! @function handleStop␊ |
| 239 | @abstract Quiesce the hardware and stop the driver.␊ |
| 240 | @discussion IOHIDDevice will call this method from stop() to␊ |
| 241 | signal that the hardware should be quiesced and the driver stopped.␊ |
| 242 | A subclass that overrides this method should end its implementation␊ |
| 243 | by calling the version in super.␊ |
| 244 | @param provider The provider argument passed to stop(). */␊ |
| 245 | ␊ |
| 246 | virtual void handleStop( IOService * provider );␊ |
| 247 | ␊ |
| 248 | /*! @function newUserClient␊ |
| 249 | @abstract Handle a request to create a connection for a non kernel␊ |
| 250 | client.␊ |
| 251 | @discussion Create a new IOUserClient, or a subclass of IOUserClient,␊ |
| 252 | to service a connection to a non kernel client. This implementation␊ |
| 253 | will simply call the implementation in IOService to handle the call.␊ |
| 254 | @param owningTask The mach task requesting the connection.␊ |
| 255 | @param security_id A token representing the access level for the task.␊ |
| 256 | @param type A constant specifying the type of connection to be created.␊ |
| 257 | @param properties A dictionary of additional properties for the connection.␊ |
| 258 | @param handler The IOUserClient object returned.␊ |
| 259 | @result The return from IOService::newUserClient() is returned. */␊ |
| 260 | ␊ |
| 261 | virtual IOReturn newUserClient( task_t owningTask,␊ |
| 262 | void * security_id,␊ |
| 263 | UInt32 type,␊ |
| 264 | OSDictionary * properties,␊ |
| 265 | IOUserClient ** handler );␊ |
| 266 | IOReturn newUserClientGated(task_t owningTask,␊ |
| 267 | void * security_id,␊ |
| 268 | OSDictionary * properties,␊ |
| 269 | IOUserClient ** handler );␊ |
| 270 | ␊ |
| 271 | /*! @function publishProperties␊ |
| 272 | @abstract Publish HID properties to the I/O Kit registry.␊ |
| 273 | @discussion Called by the start() method to fetch and publish all␊ |
| 274 | HID properties to the I/O Kit registry. These properties will allow␊ |
| 275 | the HID Manager to identify all HID device(s) in the system, by␊ |
| 276 | iterating through objects that are subclasses of IOHIDDevice, and␊ |
| 277 | then fetch their published property values. The implementation in␊ |
| 278 | IOHIDDevice will call methods to get each individual HID property,␊ |
| 279 | and subclasses will not normally need to override this method.␊ |
| 280 | @param provider The provider argument passed to start().␊ |
| 281 | @result True to indicate that all properties were discovered and␊ |
| 282 | published to the registry, false otherwise. Returning false will␊ |
| 283 | cause start() to fail and return false. */␊ |
| 284 | ␊ |
| 285 | virtual bool publishProperties( IOService * provider );␊ |
| 286 | ␊ |
| 287 | public:␊ |
| 288 | ␊ |
| 289 | /*! @function init␊ |
| 290 | @abstract Initialize an IOHIDDevice object.␊ |
| 291 | @discussion Prime the IOHIDDevice object and prepare it to support␊ |
| 292 | a probe() or a start() call. This implementation will simply call␊ |
| 293 | super::init().␊ |
| 294 | @param A dictionary A property table associated with this IOHIDDevice␊ |
| 295 | instance.␊ |
| 296 | @result True on sucess, or false otherwise. */␊ |
| 297 | ␊ |
| 298 | virtual bool init( OSDictionary * dictionary = 0 );␊ |
| 299 | ␊ |
| 300 | /*! @function start␊ |
| 301 | @abstract Start up the driver using the given provider.␊ |
| 302 | @discussion IOHIDDevice will allocate resources, then call handleStart()␊ |
| 303 | before fetching the report descriptor through newReportDescriptor(), and␊ |
| 304 | publishing HID properties to the registry. Before returning true to ␊ |
| 305 | indicate success, registerService() is called to trigger client matching.␊ |
| 306 | Subclasses are recommended to override handleStart().␊ |
| 307 | @param provider The provider that the driver was matched to, and selected␊ |
| 308 | to run with.␊ |
| 309 | @result True on success, or false otherwise. */␊ |
| 310 | ␊ |
| 311 | virtual bool start( IOService * provider );␊ |
| 312 | ␊ |
| 313 | /*! @function stop␊ |
| 314 | @abstract Called by a provider (during its termination) before detaching␊ |
| 315 | all its clients.␊ |
| 316 | @discussion IOHIDDevice will call handleStop(), then release allocated␊ |
| 317 | resources. Subclasses are recommended to override handleStop().␊ |
| 318 | @param provider The provider that the driver was started on. */␊ |
| 319 | ␊ |
| 320 | virtual void stop( IOService * provider );␊ |
| 321 | ␊ |
| 322 | /*! @function matchPropertyTable␊ |
| 323 | @abstract Called by the provider during a match␊ |
| 324 | @discussion Compare the properties in the supplied table to this ␊ |
| 325 | object's properties.␊ |
| 326 | @param table The property table that this device will match against␊ |
| 327 | */␊ |
| 328 | ␊ |
| 329 | virtual bool matchPropertyTable(OSDictionary * table, SInt32 * score); ␊ |
| 330 | ␊ |
| 331 | /*! @function newTransportString␊ |
| 332 | @abstract Returns a string object that describes the transport␊ |
| 333 | layer used by the HID device.␊ |
| 334 | @result A string object. The caller must decrement the retain count␊ |
| 335 | on the object returned. */␊ |
| 336 | ␊ |
| 337 | virtual OSString * newTransportString() const;␊ |
| 338 | ␊ |
| 339 | /*! @function newManufacturerString␊ |
| 340 | @abstract Returns a string object that describes the manufacturer␊ |
| 341 | of the HID device.␊ |
| 342 | @result A string object. The caller must decrement the retain count␊ |
| 343 | on the object returned. */␊ |
| 344 | ␊ |
| 345 | virtual OSString * newManufacturerString() const;␊ |
| 346 | ␊ |
| 347 | /*! @function newProductString␊ |
| 348 | @abstract Returns a string object that describes the product␊ |
| 349 | of the HID device.␊ |
| 350 | @result A string object. The caller must decrement the retain count␊ |
| 351 | on the object returned. */␊ |
| 352 | ␊ |
| 353 | virtual OSString * newProductString() const;␊ |
| 354 | ␊ |
| 355 | /*! @function newVendorIDNumber␊ |
| 356 | @abstract Returns a number object that describes the vendor ID␊ |
| 357 | of the HID device.␊ |
| 358 | @result A number object. The caller must decrement the retain count␊ |
| 359 | on the object returned. */␊ |
| 360 | ␊ |
| 361 | virtual OSNumber * newVendorIDNumber() const;␊ |
| 362 | ␊ |
| 363 | /*! @function newProductIDNumber␊ |
| 364 | @abstract Returns a number object that describes the product ID␊ |
| 365 | of the HID device.␊ |
| 366 | @result A number object. The caller must decrement the retain count␊ |
| 367 | on the object returned. */␊ |
| 368 | ␊ |
| 369 | virtual OSNumber * newProductIDNumber() const;␊ |
| 370 | ␊ |
| 371 | /*! @function newVersionNumber␊ |
| 372 | @abstract Returns a number object that describes the version number␊ |
| 373 | of the HID device.␊ |
| 374 | @result A number object. The caller must decrement the retain count␊ |
| 375 | on the object returned. */␊ |
| 376 | ␊ |
| 377 | virtual OSNumber * newVersionNumber() const;␊ |
| 378 | ␊ |
| 379 | // *** THIS HAS BEEN DEPRECATED. PLEASE USE newSerialNumberString ***␊ |
| 380 | /*! @function newSerialNumber␊ |
| 381 | @abstract THIS HAS BEEN DEPRECATED. PLEASE USE newSerialNumberString.␊ |
| 382 | @result A number object. The caller must decrement the retain count␊ |
| 383 | on the object returned. */␊ |
| 384 | ␊ |
| 385 | virtual OSNumber * newSerialNumber() const;␊ |
| 386 | ␊ |
| 387 | /*! @function newPrimaryUsageNumber␊ |
| 388 | @abstract Returns a number object that describes the primary usage␊ |
| 389 | of the HID device.␊ |
| 390 | @result A number object. The caller must decrement the retain count␊ |
| 391 | on the object returned. */␊ |
| 392 | ␊ |
| 393 | virtual OSNumber * newPrimaryUsageNumber() const;␊ |
| 394 | ␊ |
| 395 | /*! @function newPrimaryUsagePageNumber␊ |
| 396 | @abstract Returns a number object that describes the primary usage␊ |
| 397 | page of the HID device.␊ |
| 398 | @result A number object. The caller must decrement the retain count␊ |
| 399 | on the object returned. */␊ |
| 400 | ␊ |
| 401 | virtual OSNumber * newPrimaryUsagePageNumber() const;␊ |
| 402 | ␊ |
| 403 | /*! @function newReportDescriptor␊ |
| 404 | @abstract Create and return a new memory descriptor that describes the␊ |
| 405 | report descriptor for the HID device.␊ |
| 406 | @discussion A subclass must override this pure virtual function, and␊ |
| 407 | return a memory descriptor that describes the HID report descriptor as␊ |
| 408 | defined by the USB Device Class Definition for Human Interface Devices␊ |
| 409 | Version 1.1 specification.␊ |
| 410 | @param descriptor Pointer to the memory descriptor returned. This␊ |
| 411 | memory descriptor will be released by the caller.␊ |
| 412 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 413 | ␊ |
| 414 | virtual IOReturn newReportDescriptor(␊ |
| 415 | IOMemoryDescriptor ** descriptor ) const = 0;␊ |
| 416 | ␊ |
| 417 | /*! @function handleReport␊ |
| 418 | @abstract Handle an asynchronous report received from the HID device.␊ |
| 419 | @param report A memory descriptor that describes the report.␊ |
| 420 | @param reportType The type of report.␊ |
| 421 | @param options Options to specify the request. No options are␊ |
| 422 | currently defined, and the default value is 0.␊ |
| 423 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 424 | ␊ |
| 425 | ␉virtual IOReturn handleReport(␊ |
| 426 | IOMemoryDescriptor * report,␊ |
| 427 | ␉ IOHIDReportType reportType = kIOHIDReportTypeInput,␊ |
| 428 | ␉ IOOptionBits options = 0 );␊ |
| 429 | ␊ |
| 430 | /*! @function getReport␊ |
| 431 | @abstract Get a report from the HID device.␊ |
| 432 | @discussion A completion parameter may be added in the future.␊ |
| 433 | @param report A memory descriptor that describes the memory to store␊ |
| 434 | the report read from the HID device.␊ |
| 435 | @param reportType The report type.␊ |
| 436 | @param options The lower 8 bits will represent the Report ID. The␊ |
| 437 | other 24 bits are options to specify the request.␊ |
| 438 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 439 | ␊ |
| 440 | virtual IOReturn getReport( IOMemoryDescriptor * report,␊ |
| 441 | IOHIDReportType reportType,␊ |
| 442 | IOOptionBits options );␊ |
| 443 | ␊ |
| 444 | /*! @function setReport␊ |
| 445 | @abstract Send a report to the HID device.␊ |
| 446 | @discussion A completion parameter may be added in the future.␊ |
| 447 | @param report A memory descriptor that describes the report to send␊ |
| 448 | to the HID device.␊ |
| 449 | @param reportType The report type.␊ |
| 450 | @param options The lower 8 bits will represent the Report ID. The␊ |
| 451 | other 24 bits are options to specify the request.␊ |
| 452 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 453 | ␊ |
| 454 | virtual IOReturn setReport( IOMemoryDescriptor * report,␊ |
| 455 | IOHIDReportType reportType,␊ |
| 456 | IOOptionBits options = 0 );␊ |
| 457 | ␊ |
| 458 | /*! @function getMemoryWithCurrentElementValues␊ |
| 459 | @abstract Get a reference to a memory descriptor that describes the␊ |
| 460 | memory block containing the current HID element values.␊ |
| 461 | @discussion Each HID element that can contribute to an input, output,␊ |
| 462 | or feature report, is assigned an area of memory from a common memory␊ |
| 463 | block allocated by IOHIDDevice. Each element will use its assigned␊ |
| 464 | memory area to store its current value, defined by an IOHIDElementValue␊ |
| 465 | structure. The memory described by the memory descriptor may be mapped␊ |
| 466 | to user space to allow the HID Manager to poll the current element␊ |
| 467 | value without the cost of a user-kernel transition. Subclasses should␊ |
| 468 | not override this method.␊ |
| 469 | @result A reference to a memory descriptor that describes the current␊ |
| 470 | element values, or 0 to indicate a resource shortage. */␊ |
| 471 | ␊ |
| 472 | virtual IOMemoryDescriptor * getMemoryWithCurrentElementValues() const;␊ |
| 473 | ␊ |
| 474 | /*! @function registerElement␊ |
| 475 | @abstract A registration function called by a HID element to register␊ |
| 476 | itself, and also to obtain an unique cookie identifier␊ |
| 477 | (unique per device, not unique system-wide).␊ |
| 478 | @discussion An internal data type, an IOHIDElementPrivate, is created to␊ |
| 479 | represent each HID element discovered by parsing the HID report␊ |
| 480 | descriptor. Each element created will call this method to register␊ |
| 481 | itself with its owner (IOHIDDevice), and also to obtain an element␊ |
| 482 | cookie that is used by HID Manager to specify and identify the element.␊ |
| 483 | Subclasses should not override this method.␊ |
| 484 | @param element The element that is requesting registration with its␊ |
| 485 | owner.␊ |
| 486 | @param cookie Pointer to the returned cookie assigned to this element.␊ |
| 487 | @result True on success, or false otherwise. */␊ |
| 488 | ␊ |
| 489 | virtual bool registerElement( IOHIDElementPrivate * element,␊ |
| 490 | IOHIDElementCookie * cookie );␊ |
| 491 | ␊ |
| 492 | /*! @function startEventDelivery␊ |
| 493 | @abstract Start delivering events from a HID element to the event␊ |
| 494 | queue specified.␊ |
| 495 | @discussion Clients of IOHIDDevice may create an IOHIDEventQueue, and␊ |
| 496 | then call this method to register for delivery of events generated by␊ |
| 497 | one or more HID elements to that event queue. Subclasses should not␊ |
| 498 | override this method.␊ |
| 499 | @param queue The event queue that is interested in receiving events␊ |
| 500 | generated by the HID element specified. The retain count on the queue␊ |
| 501 | will be incremented by one.␊ |
| 502 | @param cookie The cookie for a HID element published by the HID device.␊ |
| 503 | @param options Options to specify the request. No options are currently␊ |
| 504 | defined, and the default value is zero.␊ |
| 505 | @result kIOReturnSuccess on success, or kIOReturnBadArgument if the␊ |
| 506 | queue or the cookie argument specified is invalid, or kIOReturnNoMemory␊ |
| 507 | if a resource shortage was encountered. */␊ |
| 508 | ␊ |
| 509 | virtual IOReturn startEventDelivery( IOHIDEventQueue * queue,␊ |
| 510 | IOHIDElementCookie cookie,␊ |
| 511 | IOOptionBits options = 0 );␊ |
| 512 | ␊ |
| 513 | /*! @function stopEventDelivery␊ |
| 514 | @abstract Stop delivering events from one or more HID elements to the␊ |
| 515 | event queue specified.␊ |
| 516 | @discussion Clients that called startEventDelivery() must eventually␊ |
| 517 | call this method to stop event delivery to its queue from one or more␊ |
| 518 | HID elements.␊ |
| 519 | @param queue The event queue that no longer wishes to receive events␊ |
| 520 | generated by the HID element specified.␊ |
| 521 | @param cookie The cookie for a HID element published by the HID device.␊ |
| 522 | The default value of zero indicates that the queue should be removed from␊ |
| 523 | the event dispatch list of all HID elements published by the HID device.␊ |
| 524 | Subclasses should not override this method.␊ |
| 525 | @result kIOReturnSuccess if the queue was removed from the event dispatch␊ |
| 526 | list for one or more HID elements, or kIOReturnBadArgument if the queue␊ |
| 527 | or the cookie argument specified is invalid, or kIOReturnNotFound if the␊ |
| 528 | queue was not found. */␊ |
| 529 | ␊ |
| 530 | virtual IOReturn stopEventDelivery( IOHIDEventQueue * queue,␊ |
| 531 | IOHIDElementCookie cookie = 0 );␊ |
| 532 | ␊ |
| 533 | /*! @function checkEventDelivery␊ |
| 534 | @abstract Check whether events from a HID element will be delivered to␊ |
| 535 | the event queue specified.␊ |
| 536 | @param queue The event queue.␊ |
| 537 | @param cookie The cookie for a HID element published by the HID device.␊ |
| 538 | @param isActive Pointer to the return value that is set to true if events␊ |
| 539 | generated by the HID element will be delivered to the queue, or false␊ |
| 540 | otherwise. This return value is set only if kIOReturnSuccess is␊ |
| 541 | returned.␊ |
| 542 | @result kIOReturnSuccess on success, or kIOReturnBadArgument if one or␊ |
| 543 | more of the arguments provided are invalid. */␊ |
| 544 | ␊ |
| 545 | virtual IOReturn checkEventDelivery( IOHIDEventQueue * queue,␊ |
| 546 | IOHIDElementCookie cookie,␊ |
| 547 | bool * isActive );␊ |
| 548 | ␊ |
| 549 | /*! @function updateElementValues␊ |
| 550 | @abstract Updates element values from a HID device via getReport.␊ |
| 551 | @discussion A completion parameter may be added in the future.␊ |
| 552 | @param cookies A list of element cookies who's values need to be␊ |
| 553 | set on the device.␊ |
| 554 | @param cookieCount The number of element cookies.␊ |
| 555 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 556 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 0);␊ |
| 557 | virtual IOReturn updateElementValues(IOHIDElementCookie * cookies, UInt32 cookieCount = 1);␊ |
| 558 | ␊ |
| 559 | /*! @function postElementValues␊ |
| 560 | @abstract Posts element values to a HID device via setReport.␊ |
| 561 | @discussion A completion parameter may be added in the future.␊ |
| 562 | @param cookies A list of element cookies who's values need to be␊ |
| 563 | set on the device.␊ |
| 564 | @param cookieCount The number of element cookies.␊ |
| 565 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 566 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 1);␊ |
| 567 | virtual IOReturn postElementValues(IOHIDElementCookie * cookies, UInt32 cookieCount = 1);␊ |
| 568 | ␊ |
| 569 | /*! @function newSerialNumberString␊ |
| 570 | @abstract Returns a string object that describes the serial number␊ |
| 571 | of the HID device.␊ |
| 572 | @result A number object. The caller must decrement the retain count␊ |
| 573 | on the object returned. */␊ |
| 574 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 2);␊ |
| 575 | virtual OSString * newSerialNumberString() const;␊ |
| 576 | ␊ |
| 577 | /*! @function newLocationIDNumber␊ |
| 578 | @abstract Returns a number object that describes the location ID␊ |
| 579 | of the HID device.␊ |
| 580 | @result A number object. The caller must decrement the retain count␊ |
| 581 | on the object returned. */ ␊ |
| 582 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 3);␊ |
| 583 | virtual OSNumber * newLocationIDNumber() const;␊ |
| 584 | ␊ |
| 585 | /*! @function getReport␊ |
| 586 | @abstract Get a report from the HID device.␊ |
| 587 | @discussion A completion parameter may be added in the future.␊ |
| 588 | @param report A memory descriptor that describes the memory to store␊ |
| 589 | the report read from the HID device.␊ |
| 590 | @param reportType The report type.␊ |
| 591 | @param options The lower 8 bits will represent the Report ID. The␊ |
| 592 | other 24 bits are options to specify the request.␊ |
| 593 | @param completionTimeout Specifies an amount of time (in ms) after which ␊ |
| 594 | the command will be aborted if the entire command has not been completed.␊ |
| 595 | @param completion Function to call when request completes. If omitted then␊ |
| 596 | getReport() executes synchronously, blocking until the request is complete.␊ |
| 597 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 598 | ␊ |
| 599 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 4);␊ |
| 600 | virtual IOReturn getReport( IOMemoryDescriptor * report,␊ |
| 601 | IOHIDReportType reportType,␊ |
| 602 | IOOptionBits options,␊ |
| 603 | UInt32 completionTimeout,␊ |
| 604 | IOHIDCompletion␉* completion = 0);␊ |
| 605 | ␊ |
| 606 | /*! @function setReport␊ |
| 607 | @abstract Send a report to the HID device.␊ |
| 608 | @discussion A completion parameter may be added in the future.␊ |
| 609 | @param report A memory descriptor that describes the report to send␊ |
| 610 | to the HID device.␊ |
| 611 | @param reportType The report type.␊ |
| 612 | @param options The lower 8 bits will represent the Report ID. The␊ |
| 613 | other 24 bits are options to specify the request.␊ |
| 614 | @param completionTimeout Specifies an amount of time (in ms) after which ␊ |
| 615 | the command will be aborted if the entire command has not been completed.␊ |
| 616 | @param completion Function to call when request completes. If omitted then␊ |
| 617 | setReport() executes synchronously, blocking until the request is complete.␊ |
| 618 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 619 | ␊ |
| 620 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 5);␊ |
| 621 | virtual IOReturn setReport( IOMemoryDescriptor * report,␊ |
| 622 | IOHIDReportType reportType,␊ |
| 623 | IOOptionBits options,␊ |
| 624 | UInt32 completionTimeout,␊ |
| 625 | IOHIDCompletion␉* completion = 0); ␊ |
| 626 | ␊ |
| 627 | /*! @function newVendorIDSourceNumber␊ |
| 628 | @abstract Returns a number object that describes the vendor ID␊ |
| 629 | source of the HID device. ␊ |
| 630 | @result A number object. The caller must decrement the retain count␊ |
| 631 | on the object returned. */␊ |
| 632 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 6);␊ |
| 633 | virtual OSNumber * newVendorIDSourceNumber() const;␊ |
| 634 | ␊ |
| 635 | /*! @function newCountryCodeNumber␊ |
| 636 | @abstract Returns a number object that describes the country code␊ |
| 637 | of the HID device. ␊ |
| 638 | @result A number object. The caller must decrement the retain count␊ |
| 639 | on the object returned. */␊ |
| 640 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 7);␊ |
| 641 | virtual OSNumber * newCountryCodeNumber() const;␊ |
| 642 | ␊ |
| 643 | ␊ |
| 644 | /*! @function handleReportWithTime␊ |
| 645 | @abstract Handle an asynchronous report received from the HID device.␊ |
| 646 | ␉@param timeStamp The timestamp of report.␊ |
| 647 | @param report A memory descriptor that describes the report.␊ |
| 648 | @param reportType The type of report. Currently, only␊ |
| 649 | kIOHIDReportTypeInput report type is handled.␊ |
| 650 | @param options Options to specify the request. No options are␊ |
| 651 | currently defined, and the default value is 0.␊ |
| 652 | @result kIOReturnSuccess on success, or an error return otherwise. */␊ |
| 653 | ␊ |
| 654 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 8);␊ |
| 655 | ␉virtual IOReturn handleReportWithTime(␊ |
| 656 | AbsoluteTime timeStamp,␊ |
| 657 | IOMemoryDescriptor * report,␊ |
| 658 | ␉ IOHIDReportType reportType = kIOHIDReportTypeInput,␊ |
| 659 | ␉ IOOptionBits options = 0);␊ |
| 660 | ␊ |
| 661 | /*! @function newReportInterval␊ |
| 662 | @abstract Returns a number object that describes the actual polling␊ |
| 663 | interval of the HID device in microseconds. ␊ |
| 664 | @result A number object. The caller must decrement the retain count␊ |
| 665 | on the object returned. */␊ |
| 666 | OSMetaClassDeclareReservedUsed(IOHIDDevice, 9);␊ |
| 667 | virtual OSNumber * newReportIntervalNumber() const;␊ |
| 668 | ␊ |
| 669 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 10);␊ |
| 670 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 11);␊ |
| 671 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 12);␊ |
| 672 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 13);␊ |
| 673 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 14);␊ |
| 674 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 15);␊ |
| 675 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 16);␊ |
| 676 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 17);␊ |
| 677 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 18);␊ |
| 678 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 19);␊ |
| 679 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 20);␊ |
| 680 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 21);␊ |
| 681 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 22);␊ |
| 682 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 23);␊ |
| 683 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 24);␊ |
| 684 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 25);␊ |
| 685 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 26);␊ |
| 686 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 27);␊ |
| 687 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 28);␊ |
| 688 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 29);␊ |
| 689 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 30);␊ |
| 690 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 31);␊ |
| 691 | ␊ |
| 692 | #ifndef __ppc__␊ |
| 693 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 32);␊ |
| 694 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 33);␊ |
| 695 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 34);␊ |
| 696 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 35);␊ |
| 697 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 36);␊ |
| 698 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 37);␊ |
| 699 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 38);␊ |
| 700 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 39);␊ |
| 701 | OSMetaClassDeclareReservedUnused(IOHIDDevice, 40);␊ |
| 702 | #endif␊ |
| 703 | ␊ |
| 704 | };␊ |
| 705 | ␊ |
| 706 | #endif /* !_IOKIT_HID_IOHIDDEVICE_H */␊ |
| 707 | |
