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_IOHIDINTERFACE_H
26#define _IOKIT_HID_IOHIDINTERFACE_H
27
28#include <IOKit/IOService.h>
29#include <IOKit/hid/IOHIDKeys.h>
30
31class IOHIDDevice;
32
33/*! @class IOHIDInterface : public IOService
34    @abstract In kernel interface to a HID device.
35    @discussion
36*/
37
38class IOHIDInterface: public IOService
39{
40    OSDeclareDefaultStructors( IOHIDInterface )
41
42public:
43
44    /*! @typedef IOHIDInterface::InterruptReportAction
45        @abstract Callback to handle an asynchronous report received from
46        the HID device.
47        @discussion This callback is set when calling IOHIDInterface::open.
48        @param target Pointer to your data object.
49        @param timestamp Time when the report was delivered.
50        @param report A memory descriptor that describes the report.
51        @param reportType The type of report.
52        @param reportID The ID of the report.
53        @param refcon void * pointer to more data.
54    */
55    typedef void (*InterruptReportAction)(
56                                OSObject *                  target,
57                                AbsoluteTime                timestamp,
58                                IOMemoryDescriptor *        report,
59                                IOHIDReportType             type,
60                                UInt32                      reportID,
61                                void *                      refcon);
62
63    /*!
64        @typedef IOHIDInterface::CompletionAction
65        @discussion Function called when HID I/O completes.
66        @param target
67        @param refcon
68        @param status Completion status.
69        @param bufferSizeRemaining Bytes left to be transferred.
70    */
71
72    typedef void (*CompletionAction)(
73                                OSObject *                  target,
74                                void *                      refcon,
75                                IOReturn                    status,
76                                UInt32                      bufferSizeRemaining);
77
78private:
79    IOHIDDevice *               _owner;
80    OSArray *                   _elementArray;
81    InterruptReportAction       _interruptAction;
82    void *                      _interruptRefCon;
83    OSObject *                  _interruptTarget;
84    OSString *                  _transportString;
85    OSString *                  _manufacturerString;
86    OSString *                  _productString;
87    OSString *                  _serialNumberString;
88    UInt32                      _locationID;
89    UInt32                      _vendorID;
90    UInt32                      _vendorIDSource;
91    UInt32                      _productID;
92    UInt32                      _version;
93    UInt32                      _countryCode;
94    IOByteCount                 _maxReportSize[kIOHIDReportTypeCount];
95
96    struct ExpansionData {
97        UInt32                  reportInterval;
98    };
99    /*! @var reserved
100        Reserved for future use.  (Internal use only)  */
101    ExpansionData *             _reserved;
102
103protected:
104
105    /*!
106        @function free
107        @abstract Free the IOHIDInterface object.
108        @discussion Release all resources that were previously allocated,
109        then call super::free() to propagate the call to our superclass.
110    */
111
112    virtual void            free();
113
114public:
115
116    static IOHIDInterface * withElements ( OSArray * elements );
117
118    /*!
119        @function init
120        @abstract Initialize an IOHIDInterface object.
121        @discussion Prime the IOHIDInterface object and prepare it to support
122        a probe() or a start() call. This implementation will simply call
123        super::init().
124        @param A dictionary A property table associated with this IOHIDInterface
125        instance.
126        @result True on sucess, or false otherwise.
127    */
128
129    virtual bool            init( OSDictionary * dictionary = 0 );
130
131    /*!
132        @function start
133        @abstract Start up the driver using the given provider.
134        @discussion IOHIDInterface will allocate resources. Before returning true
135        to indicate success, registerService() is called to trigger client matching.
136        @param provider The provider that the driver was matched to, and selected
137        to run with.
138        @result True on success, or false otherwise.
139    */
140
141    virtual bool            start( IOService * provider );
142
143
144    virtual void            stop( IOService * provider );
145    /*!
146        @function matchPropertyTable
147        @abstract Called by the provider during a match
148        @discussion Compare the properties in the supplied table to this
149        object's properties.
150        @param table The property table that this device will match against
151    */
152
153    virtual bool            matchPropertyTable(
154                                OSDictionary *              table,
155                                SInt32 *                    score);
156
157    virtual bool            open (
158                                IOService *                 client,
159                                IOOptionBits                options,
160                                InterruptReportAction       action,
161                                void *                      refCon);
162
163    virtual void			close(
164								IOService *					client,
165								IOOptionBits				options = 0 );
166
167    virtual OSString *      getTransport ();
168    virtual UInt32          getLocationID ();
169    virtual UInt32          getVendorID ();
170    virtual UInt32          getVendorIDSource ();
171    virtual UInt32          getProductID ();
172    virtual UInt32          getVersion ();
173    virtual UInt32          getCountryCode ();
174    virtual OSString *      getManufacturer ();
175    virtual OSString *      getProduct ();
176    virtual OSString *      getSerialNumber ();
177    virtual IOByteCount     getMaxReportSize (IOHIDReportType type);
178
179    virtual OSArray *       createMatchingElements (
180                                OSDictionary *              matching            = 0,
181                                IOOptionBits                options             = 0);
182
183    virtual void            handleReport (
184                                AbsoluteTime                timeStamp,
185                                IOMemoryDescriptor *        report,
186                                IOHIDReportType             reportType,
187                                UInt32                      reportID,
188                                IOOptionBits                options             = 0);
189
190    virtual IOReturn        setReport (
191                                IOMemoryDescriptor *        report,
192                                IOHIDReportType             reportType,
193                                UInt32                      reportID            = 0,
194                                IOOptionBits                options             = 0);
195
196    virtual IOReturn        getReport (
197                                IOMemoryDescriptor *        report,
198                                IOHIDReportType             reportType,
199                                UInt32                      reportID            = 0,
200                                IOOptionBits                options             = 0);
201
202    virtual IOReturn        setReport (
203                                IOMemoryDescriptor *        report,
204                                IOHIDReportType             reportType,
205                                UInt32                      reportID,
206                                IOOptionBits                options,
207                                UInt32                      completionTimeout,
208                                CompletionAction *          completion          = 0);
209
210    virtual IOReturn        getReport (
211                                IOMemoryDescriptor *        report,
212                                IOHIDReportType             reportType,
213                                UInt32                      reportID,
214                                IOOptionBits                options,
215                                UInt32                      completionTimeout,
216                                CompletionAction *          completion          = 0);
217    virtual IOReturn        message(
218                                UInt32 type,
219                                IOService * provider,
220                                void * argument = NULL);
221
222    OSMetaClassDeclareReservedUsed(IOHIDInterface,  0);
223    virtual UInt32             getReportInterval ();
224
225    OSMetaClassDeclareReservedUnused(IOHIDInterface,  1);
226    OSMetaClassDeclareReservedUnused(IOHIDInterface,  2);
227    OSMetaClassDeclareReservedUnused(IOHIDInterface,  3);
228    OSMetaClassDeclareReservedUnused(IOHIDInterface,  4);
229    OSMetaClassDeclareReservedUnused(IOHIDInterface,  5);
230    OSMetaClassDeclareReservedUnused(IOHIDInterface,  6);
231    OSMetaClassDeclareReservedUnused(IOHIDInterface,  7);
232    OSMetaClassDeclareReservedUnused(IOHIDInterface,  8);
233    OSMetaClassDeclareReservedUnused(IOHIDInterface,  9);
234    OSMetaClassDeclareReservedUnused(IOHIDInterface, 10);
235    OSMetaClassDeclareReservedUnused(IOHIDInterface, 11);
236    OSMetaClassDeclareReservedUnused(IOHIDInterface, 12);
237    OSMetaClassDeclareReservedUnused(IOHIDInterface, 13);
238    OSMetaClassDeclareReservedUnused(IOHIDInterface, 14);
239    OSMetaClassDeclareReservedUnused(IOHIDInterface, 15);
240    OSMetaClassDeclareReservedUnused(IOHIDInterface, 16);
241    OSMetaClassDeclareReservedUnused(IOHIDInterface, 17);
242    OSMetaClassDeclareReservedUnused(IOHIDInterface, 18);
243    OSMetaClassDeclareReservedUnused(IOHIDInterface, 19);
244    OSMetaClassDeclareReservedUnused(IOHIDInterface, 20);
245    OSMetaClassDeclareReservedUnused(IOHIDInterface, 21);
246    OSMetaClassDeclareReservedUnused(IOHIDInterface, 22);
247    OSMetaClassDeclareReservedUnused(IOHIDInterface, 23);
248    OSMetaClassDeclareReservedUnused(IOHIDInterface, 24);
249    OSMetaClassDeclareReservedUnused(IOHIDInterface, 25);
250    OSMetaClassDeclareReservedUnused(IOHIDInterface, 26);
251    OSMetaClassDeclareReservedUnused(IOHIDInterface, 27);
252    OSMetaClassDeclareReservedUnused(IOHIDInterface, 28);
253    OSMetaClassDeclareReservedUnused(IOHIDInterface, 29);
254    OSMetaClassDeclareReservedUnused(IOHIDInterface, 30);
255    OSMetaClassDeclareReservedUnused(IOHIDInterface, 31);
256};
257
258#endif /* !_IOKIT_HID_IOHIDINTERFACE_H */
259