1/*
2 * Copyright (c) 1999-2008 Apple Computer, Inc.  All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
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#ifndef _IOKIT_HID_IOHIDTRANSACTION_USER_H
25#define _IOKIT_HID_IOHIDTRANSACTION_USER_H
26
27#include <CoreFoundation/CoreFoundation.h>
28#include <IOKit/hid/IOHIDBase.h>
29
30/*!
31	@header IOHIDTransaction
32    IOHIDTransaction defines an object used to manipulate multiple parsed items
33    (IOHIDElement) contained within a Human Interface Device (HID) object.  It
34    is used to minimize device communication when interacting with feature and
35    output type elements that are grouped by their report IDs.  IOHIDTransaction
36    is a CFType object and as such conforms to all the conventions expected such
37    object.
38    <p>
39    This documentation assumes that you have a basic understanding of the material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a>
40    For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts
41    in the "Device Access and the I/O Kit" chapter of <i>Accessing Hardware From Applications</i>.
42
43    This documentation also assumes you have read <a href="http://developer.apple.com/documentation/DeviceDrivers/HumanInterfaceDeviceForceFeedback-date.html"><i>Human Interface Device & Force Feedback</i></a>.
44    Please review documentation before using this reference.
45    <p>
46    All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDTransaction.h</font> found at
47    <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDTransaction.h</font>.
48*/
49
50__BEGIN_DECLS
51
52/*! @typedef IOHIDTransactionRef
53	This is the type of a reference to the IOHIDTransaction.
54*/
55typedef struct __IOHIDTransaction * IOHIDTransactionRef;
56
57/*!
58	@function   IOHIDTransactionGetTypeID
59	@abstract   Returns the type identifier of all IOHIDTransaction instances.
60*/
61CF_EXPORT
62CFTypeID IOHIDTransactionGetTypeID(void)
63AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
64
65/*!
66	@function   IOHIDTransactionCreate
67	@abstract   Creates an IOHIDTransaction object for the specified device.
68    @discussion IOHIDTransaction objects can be used to either send or receive
69                multiple element values.  As such the direction used should
70                represent they type of objects added to the transaction.
71    @param      allocator Allocator to be used during creation.
72    @param      device IOHIDDevice object
73    @param      direction The direction, either in or out, for the transaction.
74    @param      options Reserved for future use.
75    @result     Returns a new IOHIDTransactionRef.
76*/
77CF_EXPORT
78IOHIDTransactionRef IOHIDTransactionCreate(
79                                CFAllocatorRef                  allocator,
80                                IOHIDDeviceRef                  device,
81                                IOHIDTransactionDirectionType   direction,
82                                IOOptionBits                    options)
83AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
84
85
86/*!
87	@function   IOHIDTransactionGetDevice
88	@abstract   Obtain the device associated with the transaction.
89    @param      transaction IOHIDTransaction to be queried.
90    @result     Returns the a reference to the device.
91*/
92CF_EXPORT
93IOHIDDeviceRef IOHIDTransactionGetDevice(
94                                IOHIDTransactionRef             transaction)
95AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
96
97/*!
98	@function   IOHIDTransactionGetDirection
99	@abstract   Obtain the direction of the transaction.
100    @param      transaction IOHIDTransaction to be queried.
101    @result     Returns the transaction direction.
102*/
103CF_EXPORT
104IOHIDTransactionDirectionType IOHIDTransactionGetDirection(
105                                IOHIDTransactionRef             transaction)
106AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
107
108/*!
109	@function   IOHIDTransactionSetDirection
110	@abstract   Sets the direction of the transaction
111    @disussion  This method is useful for manipulating bi-direction (feature)
112                elements such that you can set or get element values without
113                creating an additional transaction object.
114    @param      transaction IOHIDTransaction object to be modified.
115    @param      direction The new transaction direction.
116*/
117CF_EXPORT
118void IOHIDTransactionSetDirection(
119                                IOHIDTransactionRef             transaction,
120                                IOHIDTransactionDirectionType   direction)
121AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
122
123/*!
124	@function   IOHIDTransactionAddElement
125	@abstract   Adds an element to the transaction
126    @disussion  To minimize device traffic it is important to add elements that
127                share a common report type and report id.
128    @param      transaction IOHIDTransaction object to be modified.
129    @param      element Element to be added to the transaction.
130*/
131CF_EXPORT
132void IOHIDTransactionAddElement(
133                                IOHIDTransactionRef             transaction,
134                                IOHIDElementRef                 element)
135AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
136
137/*!
138	@function   IOHIDTransactionRemoveElement
139	@abstract   Removes an element to the transaction
140    @param      transaction IOHIDTransaction object to be modified.
141    @param      element Element to be removed to the transaction.
142*/
143CF_EXPORT
144void IOHIDTransactionRemoveElement(
145                                IOHIDTransactionRef             transaction,
146                                IOHIDElementRef                 element)
147AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
148
149/*!
150	@function   IOHIDTransactionContainsElement
151	@abstract   Queries the transaction to determine if elemement has been added.
152    @param      transaction IOHIDTransaction object to be queried.
153    @param      element Element to be queried.
154    @result     Returns true or false depending if element is present.
155*/
156CF_EXPORT
157Boolean IOHIDTransactionContainsElement(
158                                IOHIDTransactionRef             transaction,
159                                IOHIDElementRef                 element)
160AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
161
162/*!
163	@function   IOHIDTransactionScheduleWithRunLoop
164	@abstract   Schedules transaction with run loop.
165    @discussion Formally associates transaction with client's run loop.
166                Scheduling this transaction with the run loop is necessary
167                before making use of any asynchronous APIs.
168    @param      transaction IOHIDTransaction object to be modified.
169    @param      runLoop RunLoop to be used when scheduling any asynchronous
170                activity.
171    @param      runLoopMode Run loop mode to be used when scheduling any
172                asynchronous activity.
173*/
174CF_EXPORT
175void IOHIDTransactionScheduleWithRunLoop(
176                                IOHIDTransactionRef             transaction,
177                                CFRunLoopRef                    runLoop,
178                                CFStringRef                     runLoopMode)
179AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
180
181/*!
182	@function   IOHIDTransactionUnscheduleFromRunLoop
183	@abstract   Unschedules transaction with run loop.
184    @discussion Formally disassociates transaction with client's run loop.
185    @param      transaction IOHIDTransaction object to be modified.
186    @param      runLoop RunLoop to be used when scheduling any asynchronous
187                activity.
188    @param      runLoopMode Run loop mode to be used when scheduling any
189                asynchronous activity.
190*/
191CF_EXPORT
192void IOHIDTransactionUnscheduleFromRunLoop(
193                                IOHIDTransactionRef             transaction,
194                                CFRunLoopRef                    runLoop,
195                                CFStringRef                     runLoopMode)
196AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
197
198/*!
199	@function   IOHIDTransactionSetValue
200	@abstract   Sets the value for a transaction element.
201    @discussion The value set is pended until the transaction is committed and
202                is only used if the transaction direction is
203                kIOHIDTransactionDirectionTypeOutput.  Use the
204                kIOHIDTransactionOptionDefaultOutputValue option to set the
205                default element value.
206    @param      transaction IOHIDTransaction object to be modified.
207    @param      element Element to be modified after a commit.
208    @param      value Value to be set for the given element.
209    @param      options See IOHIDTransactionOption.
210*/
211CF_EXPORT
212void IOHIDTransactionSetValue(
213                                IOHIDTransactionRef             transaction,
214                                IOHIDElementRef                 element,
215                                IOHIDValueRef                   value,
216                                IOOptionBits                    options)
217AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
218
219/*!
220	@function   IOHIDTransactionGetValue
221	@abstract   Obtains the value for a transaction element.
222    @discussion If the transaction direction is
223                kIOHIDTransactionDirectionTypeInput the value represents what
224                was obtained from the device from the transaction.  Otherwise,
225                if the transaction direction is
226                kIOHIDTransactionDirectionTypeOutput the value represents the
227                pending value to be sent to the device.  Use the
228                kIOHIDTransactionOptionDefaultOutputValue option to get the
229                default element value.
230    @param      transaction IOHIDTransaction object to be queried.
231    @param      element Element to be queried.
232    @param      options See IOHIDTransactionOption.
233    @result     Returns IOHIDValueRef for the given element.
234*/
235CF_EXPORT
236IOHIDValueRef IOHIDTransactionGetValue(
237                                IOHIDTransactionRef             transaction,
238                                IOHIDElementRef                 element,
239                                IOOptionBits                    options)
240AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
241
242/*!
243	@function   IOHIDTransactionCommit
244	@abstract   Synchronously commits element transaction to the device.
245    @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction,
246                default element values will be used if element values are not
247                set.  If neither are set, that element will be omitted from the
248                commit. After a transaction is committed, transaction element
249                values will be cleared and default values preserved.
250    @param      transaction IOHIDTransaction object to be modified.
251    @result     Returns kIOReturnSuccess if successful or a kern_return_t if
252                unsuccessful.
253*/
254CF_EXPORT
255IOReturn IOHIDTransactionCommit(
256                                IOHIDTransactionRef             transaction)
257AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
258
259/*!
260	@function   IOHIDTransactionCommitWithCallback
261	@abstract   Commits element transaction to the device.
262    @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction,
263                default element values will be used if element values are not
264                set.  If neither are set, that element will be omitted from the
265                commit. After a transaction is committed, transaction element
266                values will be cleared and default values preserved.
267                <br>
268                <b>Note:</b> It is possible for elements from different reports
269                to be present in a given transaction causing a commit to
270                transcend multiple reports. Keep this in mind when setting a
271                appropriate timeout.
272    @param      transaction IOHIDTransaction object to be modified.
273    @param      timeout Timeout for issuing the transaction.
274    @param      callback Callback of type IOHIDCallback to be used when
275                transaction has been completed.  If null, this method will
276                behave synchronously.
277    @param      context Pointer to data to be passed to the callback.
278    @result     Returns kIOReturnSuccess if successful or a kern_return_t if
279                unsuccessful.
280*/
281CF_EXPORT
282IOReturn IOHIDTransactionCommitWithCallback(
283                                IOHIDTransactionRef             transaction,
284                                CFTimeInterval                  timeout,
285                                IOHIDCallback                   callback,
286                                void *                          context)
287AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
288
289/*!
290    @function   IOHIDTransactionClear
291    @abstract   Clears element transaction values.
292    @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction,
293                default element values will be preserved.
294    @param      transaction IOHIDTransaction object to be modified.
295*/
296CF_EXPORT
297void IOHIDTransactionClear(
298                                IOHIDTransactionRef             transaction)
299AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
300
301__END_DECLS
302
303#endif /* _IOKIT_HID_IOHIDTRANSACTION_USER_H */