1/* 2 * @APPLE_LICENSE_HEADER_START@ 3 * 4 * Copyright (c) 2008 Apple, Inc. All Rights Reserved. 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 25#ifndef _IOHIDUSERDEVICE_H 26#define _IOHIDUSERDEVICE_H 27 28/* 29 * Kernel 30 */ 31 32#include <IOKit/hid/IOHIDDevice.h> 33 34class IOHIDResourceDeviceUserClient; 35 36/*! @class IOHIDUserDevice : public IOHIDDevice 37 @abstract 38*/ 39class IOHIDUserDevice : public IOHIDDevice 40{ 41 OSDeclareDefaultStructors(IOHIDUserDevice); 42 43private: 44 OSDictionary * _properties; 45 IOHIDResourceDeviceUserClient * _provider; 46 47protected: 48/*! @function free 49 @abstract Free the IOHIDDevice object. 50 @discussion Release all resources that were previously allocated, 51 then call super::free() to propagate the call to our superclass. */ 52 virtual void free(); 53 54/*! @function handleStart 55 @abstract Prepare the hardware and driver to support I/O operations. 56 @discussion IOHIDDevice will call this method from start() before 57 any I/O operations are issued to the concrete subclass. Methods 58 such as newReportDescriptor() are only called after handleStart() 59 has returned true. A subclass that overrides this method should 60 begin its implementation by calling the version in super, and 61 then check the return value. 62 @param provider The provider argument passed to start(). 63 @result True on success, or false otherwise. Returning false will 64 cause start() to fail and return false. */ 65 virtual bool handleStart(IOService * provider); 66 67/*! @function handleStop 68 @abstract Quiesce the hardware and stop the driver. 69 @discussion IOHIDDevice will call this method from stop() to 70 signal that the hardware should be quiesced and the driver stopped. 71 A subclass that overrides this method should end its implementation 72 by calling the version in super. 73 @param provider The provider argument passed to stop(). */ 74 virtual void handleStop(IOService * provider); 75 76public: 77/*! @function withProperties 78 @abstract Creates a device with properties. 79 @param properties Dictionary containing preflighted properties corresponding to device keys from IOHIDKeys.h. 80 @result The new device created. 81*/ 82 static IOHIDUserDevice * withProperties(OSDictionary * properties); 83 84/*! @function initWithProperties 85 @abstract Initialize an IOHIDUserDevice object. 86 @discussion Prime the IOHIDUserDevice object and prepare it to support 87 a probe() or a start() call. 88 @param properties Dictionary containing preflighted properties corresponding to device keys from IOHIDKeys.h. 89 @result True on sucess, or false otherwise. */ 90 virtual bool initWithProperties(OSDictionary * properties); 91 92/*! @function newReportDescriptor 93 @abstract Create and return a new memory descriptor that describes the 94 report descriptor for the HID device. 95 @result kIOReturnSuccess on success, or an error return otherwise. */ 96 virtual IOReturn newReportDescriptor(IOMemoryDescriptor ** descriptor ) const; 97 98/*! @function newTransportString 99 @abstract Returns a string object that describes the transport 100 layer used by the HID device. 101 @result A string object. The caller must decrement the retain count 102 on the object returned. */ 103 virtual OSString * newTransportString() const; 104 105/*! @function newManufacturerString 106 @abstract Returns a string object that describes the manufacturer 107 of the HID device. 108 @result A string object. The caller must decrement the retain count 109 on the object returned. */ 110 virtual OSString * newManufacturerString() const; 111 112/*! @function newProductString 113 @abstract Returns a string object that describes the product 114 of the HID device. 115 @result A string object. The caller must decrement the retain count 116 on the object returned. */ 117 virtual OSString * newProductString() const; 118 119/*! @function newVendorIDNumber 120 @abstract Returns a number object that describes the vendor ID 121 of the HID device. 122 @result A number object. The caller must decrement the retain count 123 on the object returned. */ 124 virtual OSNumber * newVendorIDNumber() const; 125 126/*! @function newProductIDNumber 127 @abstract Returns a number object that describes the product ID 128 of the HID device. 129 @result A number object. The caller must decrement the retain count 130 on the object returned. */ 131 virtual OSNumber * newProductIDNumber() const; 132 133/*! @function newVersionNumber 134 @abstract Returns a number object that describes the version number 135 of the HID device. 136 @result A number object. The caller must decrement the retain count 137 on the object returned. */ 138 virtual OSNumber * newVersionNumber() const; 139 140/*! @function newSerialNumberString 141 @abstract Returns a string object that describes the serial number 142 of the HID device. 143 @result A number object. The caller must decrement the retain count 144 on the object returned. */ 145 virtual OSString * newSerialNumberString() const; 146 147/*! @function newVendorIDSourceNumber 148 @abstract Returns a number object that describes the vendor ID 149 source of the HID device. 150 @result A number object. The caller must decrement the retain count 151 on the object returned. */ 152 virtual OSNumber * newVendorIDSourceNumber() const; 153 154/*! @function newCountryCodeNumber 155 @abstract Returns a number object that describes the country code 156 of the HID device. 157 @result A number object. The caller must decrement the retain count 158 on the object returned. */ 159 virtual OSNumber * newCountryCodeNumber() const; 160 161/*! @function newReportIntervalNumber 162 @abstract Returns a number object that describes the report interval 163 of the HID device. 164 @result A number object. The caller must decrement the retain count 165 on the object returned. */ 166 virtual OSNumber * newReportIntervalNumber() const; 167 168 /*! @function newLocationIDNumber 169 @abstract Returns a number object that describes the location 170 of the HID device. 171 @result A number object. The caller must decrement the retain count 172 on the object returned. */ 173 virtual OSNumber *newLocationIDNumber() const; 174 175/*! @function getReport 176 @abstract Get a report from the HID device. 177 @discussion A completion parameter may be added in the future. 178 @param report A memory descriptor that describes the memory to store 179 the report read from the HID device. 180 @param reportType The report type. 181 @param options The lower 8 bits will represent the Report ID. The 182 other 24 bits are options to specify the request. 183 @result kIOReturnSuccess on success, or an error return otherwise. */ 184 IOReturn getReport(IOMemoryDescriptor *report, 185 IOHIDReportType reportType, 186 IOOptionBits options ); 187 188/*! @function setReport 189 @abstract Send a report to the HID device. 190 @discussion A completion parameter may be added in the future. 191 @param report A memory descriptor that describes the report to send 192 to the HID device. 193 @param reportType The report type. 194 @param options The lower 8 bits will represent the Report ID. The 195 other 24 bits are options to specify the request. 196 @result kIOReturnSuccess on success, or an error return otherwise. */ 197 IOReturn setReport(IOMemoryDescriptor *report, 198 IOHIDReportType reportType, 199 IOOptionBits options); 200 201}; 202 203 204#endif /* !_IOHIDUSERDEVICE_H */ 205 206