lang/LangPrimSource/HID_Utilities/IOHIDElement_.h

   1 //
   2 //      File:           IOHIDElement_.h of HID Utilities
   3 //
   4 //      Created:        9/21/06
   5 //
   6 //      Contains:       Definition of the interfaces to <IOHIDElement_.c>
   7 //
   8 //      Copyright © 2007-2009 Apple Inc., All Rights Reserved
   9 //
  10 //      Disclaimer:     IMPORTANT:  This Apple software is supplied to you by
  11 //                              Apple Inc. ("Apple") in consideration of your agreement to the
  12 //                              following terms, and your use, installation, modification or
  13 //                              redistribution of this Apple software constitutes acceptance of these
  14 //                              terms.  If you do not agree with these terms, please do not use,
  15 //                              install, modify or redistribute this Apple software.
  16 //
  17 //                              In consideration of your agreement to abide by the following terms, and
  18 //                              subject to these terms, Apple grants you a personal, non-exclusive
  19 //                              license, under Apple's copyrights in this original Apple software (the
  20 //                              "Apple Software"), to use, reproduce, modify and redistribute the Apple
  21 //                              Software, with or without modifications, in source and/or binary forms;
  22 //                              provided that if you redistribute the Apple Software in its entirety and
  23 //                              without modifications, you must retain this notice and the following
  24 //                              text and disclaimers in all such redistributions of the Apple Software.
  25 //                              Neither the name, trademarks, service marks or logos of Apple Inc.
  26 //                              may be used to endorse or promote products derived from the Apple
  27 //                              Software without specific prior written permission from Apple.  Except
  28 //                              as expressly stated in this notice, no other rights or licenses, express
  29 //                              or implied, are granted by Apple herein, including but not limited to
  30 //                              any patent rights that may be infringed by your derivative works or by
  31 //                              other works in which the Apple Software may be incorporated.
  32 //
  33 //                              The Apple Software is provided by Apple on an "AS IS" basis.  APPLE
  34 //                              MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION
  35 //                              THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS
  36 //                              FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND
  37 //                              OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS.
  38 //
  39 //                              IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL
  40 //                              OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  41 //                              SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  42 //                              INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION,
  43 //                              MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED
  44 //                              AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE),
  45 //                              STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE
  46 //                              POSSIBILITY OF SUCH DAMAGE.
  47 //
  48 #ifndef __IOHIDElement___
  49 #define __IOHIDElement___
  50
  51 //*****************************************************
  52 #pragma mark - includes & imports
  53
  54 #include <AvailabilityMacros.h>
  55
  56 #include <Carbon/Carbon.h>
  57 #include "IOHIDLib_.h"
  58 //*****************************************************
  59 #if PRAGMA_ONCE
  60 #pragma once
  61 #endif
  62
  63 #ifdef __cplusplus
  64 extern "C" {
  65 #endif
  66
  67 #if PRAGMA_IMPORT
  68 #pragma import on
  69 #endif
  70
  71 #if PRAGMA_STRUCT_ALIGN
  72 #pragma options align=mac68k
  73 #elif PRAGMA_STRUCT_PACKPUSH
  74 #pragma pack(push, 2)
  75 #elif PRAGMA_STRUCT_PACK
  76 #pragma pack(2)
  77 #endif
  78
  79 //*****************************************************
  80 #pragma mark - typedef's, struct's, enums, defines, etc.
  81 //-----------------------------------------------------
  82
  83 //*****************************************************
  84 #pragma mark - exported globals
  85 //-----------------------------------------------------
  86
  87 //*****************************************************
  88 #pragma mark - exported function prototypes
  89 //-----------------------------------------------------
  90
  91 //*************************************************************************
  92 //
  93 // HIDIsValidElement( inIOHIDElementRef )
  94 //
  95 // Purpose:     validate this element
  96 //
  97 // Inputs:      inIOHIDElementRef       - the element
  98 //
  99 // Returns:     Boolean                 - TRUE if this is a valid element ref
 100 //
 101 extern Boolean HIDIsValidElement( IOHIDElementRef inIOHIDElementRef );
 102
 103 //*************************************************************************
 104 //
 105 // IOHIDElement_GetValue( inElementRef, inIOHIDValueScaleType )
 106 //
 107 // Purpose:     returns the current value for an element( polling )
 108 //
 109 // Notes:       will return 0 on error conditions which should be accounted for by application
 110 //
 111 // Inputs:      inElementRef    - the element
 112 //                      inIOHIDValueScaleType   - scale type ( calibrated or physical )
 113 //
 114 // Returns:     double          - current value for element
 115 //
 116 extern double IOHIDElement_GetValue( IOHIDElementRef inElementRef, IOHIDValueScaleType inIOHIDValueScaleType );
 117
 118 //*************************************************************************
 119 //
 120 // IOHIDElement_GetCalibrationMin( inElementRef )
 121 //
 122 // Purpose:     get the minimum bounds for a calibrated value for this element
 123 //
 124 // Inputs:  inElementRef - the IOHIDElementRef for this element
 125 //
 126 // Returns:     CFIndex - the minimum Calibration value for this element
 127 //
 128
 129 extern CFIndex  IOHIDElement_GetCalibrationMin( IOHIDElementRef inElementRef );
 130
 131 //*************************************************************************
 132 //
 133 // IOHIDElement_SetCalibrationMin( inElementRef, inValue )
 134 //
 135 // Purpose:     set the minimum bounds for a calibrated value for this element
 136 //
 137 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 138 //                      inValue                 - the minimum bounds for a calibrated value for this element
 139 //
 140 // Returns:     nothing
 141 //
 142
 143 extern void IOHIDElement_SetCalibrationMin( IOHIDElementRef inElementRef, CFIndex inValue );
 144
 145 //*************************************************************************
 146 //
 147 // IOHIDElement_GetCalibrationMax( inElementRef )
 148 //
 149 // Purpose:     get the maximum bounds for a calibrated value for this element
 150 //
 151 // Inputs:  inElementRef - the IOHIDElementRef for this element
 152 //
 153 // Returns:     CFIndex - the maximum Calibration value for this element
 154 //
 155
 156 extern CFIndex  IOHIDElement_GetCalibrationMax( IOHIDElementRef inElementRef );
 157
 158 //*************************************************************************
 159 //
 160 // IOHIDElement_SetCalibrationMax( inElementRef, inValue )
 161 //
 162 // Purpose:     set the maximum bounds for a calibrated value for this element
 163 //
 164 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 165 //                      inValue                 - the maximum Calibration value for this element
 166 //
 167 // Returns:     nothing
 168 //
 169
 170 extern void IOHIDElement_SetCalibrationMax( IOHIDElementRef inElementRef, CFIndex inValue );
 171
 172 //*************************************************************************
 173 //
 174 // IOHIDElement_GetCalibrationSaturationMin( inElementRef )
 175 //
 176 // Purpose:     get the mininum tolerance to be used when calibrating a logical element value
 177 //
 178 // Inputs:  inElementRef - the IOHIDElementRef for this element
 179 //
 180 // Returns:     CFIndex - the maximum Calibration value for this element
 181 //
 182
 183 extern CFIndex  IOHIDElement_GetCalibrationSaturationMin( IOHIDElementRef inElementRef );
 184
 185 //*************************************************************************
 186 //
 187 // IOHIDElement_SetCalibrationSaturationMin( inElementRef, inValue )
 188 //
 189 // Purpose:     set the mininum tolerance to be used when calibrating a logical element value
 190 //
 191 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 192 //                      inValue                 - the maximum Calibration value for this element
 193 //
 194 // Returns:     nothing
 195 //
 196
 197 extern void IOHIDElement_SetCalibrationSaturationMin( IOHIDElementRef inElementRef, CFIndex inValue );
 198
 199 //*************************************************************************
 200 //
 201 // IOHIDElement_GetCalibrationSaturationMax( inElementRef )
 202 //
 203 // Purpose:     get the maximum tolerance to be used when calibrating a logical element value
 204 //
 205 // Inputs:  inElementRef - the IOHIDElementRef for this element
 206 //
 207 // Returns:     CFIndex - the maximum Calibration value for this element
 208 //
 209
 210 extern CFIndex  IOHIDElement_GetCalibrationSaturationMax( IOHIDElementRef inElementRef );
 211
 212 //*************************************************************************
 213 //
 214 // IOHIDElement_SetCalibrationSaturationMax( inElementRef, inValue )
 215 //
 216 // Purpose:     set the maximum tolerance to be used when calibrating a logical element value
 217 //
 218 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 219 //                      inValue                 - the maximum Calibration value for this element
 220 //
 221 // Returns:     nothing
 222 //
 223
 224 extern void IOHIDElement_SetCalibrationSaturationMax( IOHIDElementRef inElementRef, CFIndex inValue );
 225
 226 //*************************************************************************
 227 //
 228 // IOHIDElement_GetCalibrationDeadZoneMin( inElementRef )
 229 //
 230 // Purpose:     get the minimum bounds near the midpoint of a logical value in which the value is ignored
 231 //
 232 // Inputs:  inElementRef - the IOHIDElementRef for this element
 233 //
 234 // Returns:     CFIndex - the maximum Calibration value for this element
 235 //
 236
 237 extern CFIndex  IOHIDElement_GetCalibrationDeadZoneMin( IOHIDElementRef inElementRef );
 238
 239 //*************************************************************************
 240 //
 241 // IOHIDElement_SetCalibrationDeadZoneMin( inElementRef, inValue )
 242 //
 243 // Purpose:     set the minimum bounds near the midpoint of a logical value in which the value is ignored
 244 //
 245 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 246 //                      inValue                 - the maximum Calibration value for this element
 247 //
 248 // Returns:     nothing
 249 //
 250
 251 extern void IOHIDElement_SetCalibrationDeadZoneMin( IOHIDElementRef inElementRef, CFIndex inValue );
 252
 253 //*************************************************************************
 254 //
 255 // IOHIDElement_GetCalibrationDeadZoneMax( inElementRef )
 256 //
 257 // Purpose:     get the maximum bounds near the midpoint of a logical value in which the value is ignored
 258 //
 259 // Inputs:  inElementRef - the IOHIDElementRef for this element
 260 //
 261 // Returns:     CFIndex - the maximum Calibration value for this element
 262 //
 263
 264 extern CFIndex  IOHIDElement_GetCalibrationDeadZoneMax( IOHIDElementRef inElementRef );
 265
 266 //*************************************************************************
 267 //
 268 // IOHIDElement_SetCalibrationDeadZoneMax( inElementRef, inValue )
 269 //
 270 // Purpose:     set the maximum bounds near the midpoint of a logical value in which the value is ignored
 271 //
 272 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 273 //                      inValue                 - the maximum Calibration value for this element
 274 //
 275 // Returns:     nothing
 276 //
 277
 278 extern void IOHIDElement_SetCalibrationDeadZoneMax( IOHIDElementRef inElementRef, CFIndex inValue );
 279
 280 //*************************************************************************
 281 //
 282 // IOHIDElement_GetCalibrationGranularity( inElementRef )
 283 //
 284 // Purpose:     get the level of detail returned for a calibrated element value
 285 //
 286 // Inputs:  inElementRef - the IOHIDElementRef for this element
 287 //
 288 // Returns:     double_t - the maximum Calibration value for this element
 289 //
 290
 291 extern double_t  IOHIDElement_GetCalibrationGranularity( IOHIDElementRef inElementRef );
 292
 293 //*************************************************************************
 294 //
 295 // IOHIDElement_SetCalibrationGranularity( inElementRef, inValue )
 296 //
 297 // Purpose:     set the level of detail returned for a calibrated element value
 298 //
 299 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 300 //                      inValue                 - the the level of detail for this element
 301 //
 302 // Returns:     nothing
 303 //
 304
 305 extern void IOHIDElement_SetCalibrationGranularity( IOHIDElementRef inElementRef, double_t inValue );
 306
 307 //*************************************************************************
 308 //
 309 // IOHIDElement_SetupCalibration( inElementRef )
 310 //
 311 // Purpose:     set default values for the element calibration parameters
 312 //
 313 // Inputs:  inElementRef        - the IOHIDElementRef for this element
 314 //
 315 // Returns:     nothing
 316 //
 317
 318 extern void IOHIDElement_SetupCalibration( IOHIDElementRef inIOHIDElementRef );
 319
 320 extern Boolean IOHIDElement_GetLongProperty( IOHIDElementRef inElementRef, CFStringRef inKey, long * outValue );
 321 extern void IOHIDElement_SetLongProperty( IOHIDElementRef inElementRef, CFStringRef inKey, long inValue );
 322
 323 //*****************************************************
 324 #if PRAGMA_STRUCT_ALIGN
 325 #pragma options align=reset
 326 #elif PRAGMA_STRUCT_PACKPUSH
 327 #pragma pack(pop)
 328 #elif PRAGMA_STRUCT_PACK
 329 #pragma pack()
 330 #endif
 331
 332 #ifdef PRAGMA_IMPORT_OFF
 333 #pragma import off
 334 #elif PRAGMA_IMPORT
 335 #pragma import reset
 336 #endif
 337
 338 #ifdef __cplusplus
 339 }
 340 #endif
 341
 342 #endif  // __IOHIDElement___ //