lang/LangPrimSource/HID_Utilities/HID_Queue_Utilities.h

   1 //
   2 // File:       HID_Queue_Utilities.h
   3 //
   4 // Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple Inc. ("Apple")
   5 //             in consideration of your agreement to the following terms, and your use,
   6 //             installation, modification or redistribution of this Apple software
   7 //             constitutes acceptance of these terms.  If you do not agree with these
   8 //             terms, please do not use, install, modify or redistribute this Apple
   9 //             software.
  10 //
  11 //             In consideration of your agreement to abide by the following terms, and
  12 //             subject to these terms, Apple grants you a personal, non - exclusive
  13 //             license, under Apple's copyrights in this original Apple software ( the
  14 //             "Apple Software" ), to use, reproduce, modify and redistribute the Apple
  15 //             Software, with or without modifications, in source and / or binary forms;
  16 //             provided that if you redistribute the Apple Software in its entirety and
  17 //             without modifications, you must retain this notice and the following text
  18 //             and disclaimers in all such redistributions of the Apple Software. Neither
  19 //             the name, trademarks, service marks or logos of Apple Inc. may be used to
  20 //             endorse or promote products derived from the Apple Software without specific
  21 //             prior written permission from Apple.  Except as expressly stated in this
  22 //             notice, no other rights or licenses, express or implied, are granted by
  23 //             Apple herein, including but not limited to any patent rights that may be
  24 //             infringed by your derivative works or by other works in which the Apple
  25 //             Software may be incorporated.
  26 //
  27 //             The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  28 //             WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  29 //             WARRANTIES OF NON - INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A
  30 //             PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION
  31 //             ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
  32 //
  33 //             IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  34 //             CONSEQUENTIAL DAMAGES ( INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  35 //             SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  36 //             INTERRUPTION ) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION
  37 //             AND / OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER
  38 //             UNDER THEORY OF CONTRACT, TORT ( INCLUDING NEGLIGENCE ), STRICT LIABILITY OR
  39 //             OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40 //
  41 // Copyright ( C ) 2001-2008 Apple Inc. All Rights Reserved.
  42 //
  43
  44 #ifndef _HID_Queue_Utilities_h_
  45 #define _HID_Queue_Utilities_h_
  46
  47 #include "HID_Utilities.h"
  48
  49 // ==================================
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 // ==================================
  56
  57 enum
  58 {
  59     kDeviceQueueSize = 50       // this is wired kernel memory so should be set to as small as possible
  60                                                         // but should account for the maximum possible events in the queue
  61                                                         // USB updates will likely occur at 100 Hz so one must account for this rate of
  62                                                         // if states change quickly (updates are only posted on state changes)
  63 };
  64
  65 // ==================================
  66
  67 // Create and open an interface to device, required prior to extracting values or building queues
  68 // int HIDCreateOpenDeviceInterface (void * hidDevice, pRecDevice pDevice);
  69
  70 // queues specific element, performing any device queue set up required
  71 int  HIDQueueElement (pRecDevice pDevice, pRecElement pElement);
  72
  73 // adds all elements to queue, performing any device queue set up required
  74 int  HIDQueueDevice (pRecDevice pDevice);
  75
  76 // removes element for queue, if last element in queue will release queue and device
  77 int  HIDDequeueElement (pRecDevice pDevice, pRecElement pElement);
  78
  79 // completely removes all elements from queue and releases queue and device
  80 int  HIDDequeueDevice (pRecDevice pDevice);
  81
  82 // releases all device queues for quit or rebuild (must be called)
  83 int  HIDReleaseAllDeviceQueues (void);
  84
  85 // releases interface to device, should be done prior to exiting application (called from ReleaseHIDDeviceList)
  86 int  HIDCloseReleaseInterface (pRecDevice pDevice);
  87
  88 // returns true if an event is avialable for the element and fills out *pHIDEvent structure, returns false otherwise
  89 // pHIDEvent is a poiner to a IOHIDEventStruct, using void here for compatibility, users can cast a required
  90 unsigned char HIDGetEvent (pRecDevice pDevice, void * pHIDEvent);
  91
  92 // returns current value for element, creating device interface as required, polling element
  93 // Note: this DOES NOT release the inteface so applications must properly release devices via ReleaseHIDDeviceList
  94 int HIDGetElementValue (pRecDevice pDevice, pRecElement pElement);
  95
  96 #ifdef __cplusplus
  97 }
  98 #endif
  99
 100 #endif // _HID_Queue_Utilities_h_
 101