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