lang/LangPrimSource/HID_Utilities_10_4/HID_Queue_Utilities.h

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