Root/
Source at commit 1445 created 12 years 11 months ago. By jrcs, Revert "Print the multiboot_magic" Only used for debugging purpose | |
---|---|
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 |