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