src/joystick/darwin/SDL_sysjoystick.c

   1 /*
   2         SDL - Simple DirectMedia Layer
   3     Copyright (C) 1997-2009 Sam Lantinga
   4
   5         This library is free software; you can redistribute it and/or
   6         modify it under the terms of the GNU Library General Public
   7         License as published by the Free Software Foundation; either
   8         version 2 of the License, or (at your option) any later version.
   9
  10         This library is distributed in the hope that it will be useful,
  11         but WITHOUT ANY WARRANTY; without even the implied warranty of
  12         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13         Library General Public License for more details.
  14
  15         You should have received a copy of the GNU Library General Public
  16         License along with this library; if not, write to the Free
  17         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18
  19         Sam Lantinga
  20         slouken@libsdl.org
  21 */
  22 #include "SDL_config.h"
  23
  24 #ifdef SDL_JOYSTICK_IOKIT
  25
  26 /* SDL joystick driver for Darwin / Mac OS X, based on the IOKit HID API */
  27 /* Written 2001 by Max Horn */
  28
  29 #include <unistd.h>
  30 #include <ctype.h>
  31 #include <sysexits.h>
  32 #include <mach/mach.h>
  33 #include <mach/mach_error.h>
  34 #include <IOKit/IOKitLib.h>
  35 #include <IOKit/IOCFPlugIn.h>
  36 #ifdef MACOS_10_0_4
  37 #include <IOKit/hidsystem/IOHIDUsageTables.h>
  38 #else
  39 /* The header was moved here in Mac OS X 10.1 */
  40 #include <Kernel/IOKit/hidsystem/IOHIDUsageTables.h>
  41 #endif
  42 #if MAC_OS_X_VERSION_MIN_REQUIRED == 1030
  43 #include "10.3.9-FIX/IOHIDLib.h"
  44 #else
  45 #include <IOKit/hid/IOHIDLib.h>
  46 #endif
  47 #include <IOKit/hid/IOHIDKeys.h>
  48 #include <CoreFoundation/CoreFoundation.h>
  49 #include <Carbon/Carbon.h> /* for NewPtrClear, DisposePtr */
  50
  51 #include "SDL_joystick.h"
  52 #include "../SDL_sysjoystick.h"
  53 #include "../SDL_joystick_c.h"
  54
  55 struct recElement
  56 {
  57         IOHIDElementCookie cookie;                              /* unique value which identifies element, will NOT change */
  58         long min;                                                               /* reported min value possible */
  59         long max;                                                               /* reported max value possible */
  60 #if 0
  61         /* TODO: maybe should handle the following stuff somehow? */
  62
  63         long scaledMin;                                                 /* reported scaled min value possible */
  64         long scaledMax;                                                 /* reported scaled max value possible */
  65         long size;                                                              /* size in bits of data return from element */
  66         Boolean relative;                                               /* are reports relative to last report (deltas) */
  67         Boolean wrapping;                                               /* does element wrap around (one value higher than max is min) */
  68         Boolean nonLinear;                                              /* are the values reported non-linear relative to element movement */
  69         Boolean preferredState;                                 /* does element have a preferred state (such as a button) */
  70         Boolean nullState;                                              /* does element have null state */
  71 #endif /* 0 */
  72
  73         /* runtime variables used for auto-calibration */
  74         long minReport;                                                 /* min returned value */
  75         long maxReport;                                                 /* max returned value */
  76
  77         struct recElement * pNext;                              /* next element in list */
  78 };
  79 typedef struct recElement recElement;
  80
  81 struct joystick_hwdata
  82 {
  83         IOHIDDeviceInterface ** interface;              /* interface to device, NULL = no interface */
  84
  85         char product[256];                                                      /* name of product */
  86         long usage;                                                             /* usage page from IOUSBHID Parser.h which defines general usage */
  87         long usagePage;                                                 /* usage within above page from IOUSBHID Parser.h which defines specific usage */
  88
  89         long axes;                                                              /* number of axis (calculated, not reported by device) */
  90         long buttons;                                                   /* number of buttons (calculated, not reported by device) */
  91         long hats;                                                              /* number of hat switches (calculated, not reported by device) */
  92         long elements;                                                  /* number of total elements (shouldbe total of above) (calculated, not reported by device) */
  93
  94         recElement* firstAxis;
  95         recElement* firstButton;
  96         recElement* firstHat;
  97
  98         int removed;
  99         int uncentered;
 100
 101         struct joystick_hwdata* pNext;                  /* next device */
 102 };
 103 typedef struct joystick_hwdata recDevice;
 104
 105
 106 /* Linked list of all available devices */
 107 static recDevice *gpDeviceList = NULL;
 108
 109
 110 static void HIDReportErrorNum (char * strError, long numError)
 111 {
 112         SDL_SetError(strError);
 113 }
 114
 115 static void HIDGetCollectionElements (CFMutableDictionaryRef deviceProperties, recDevice *pDevice);
 116
 117 /* returns current value for element, polling element
 118  * will return 0 on error conditions which should be accounted for by application
 119  */
 120
 121 static SInt32 HIDGetElementValue (recDevice *pDevice, recElement *pElement)
 122 {
 123         IOReturn result = kIOReturnSuccess;
 124         IOHIDEventStruct hidEvent;
 125         hidEvent.value = 0;
 126
 127         if (NULL != pDevice && NULL != pElement && NULL != pDevice->interface)
 128         {
 129                 result = (*(pDevice->interface))->getElementValue(pDevice->interface, pElement->cookie, &hidEvent);
 130                 if (kIOReturnSuccess == result)
 131                 {
 132                         /* record min and max for auto calibration */
 133                         if (hidEvent.value < pElement->minReport)
 134                                 pElement->minReport = hidEvent.value;
 135                         if (hidEvent.value > pElement->maxReport)
 136                                 pElement->maxReport = hidEvent.value;
 137                 }
 138         }
 139
 140         /* auto user scale */
 141         return hidEvent.value;
 142 }
 143
 144 static SInt32 HIDScaledCalibratedValue (recDevice *pDevice, recElement *pElement, long min, long max)
 145 {
 146         float deviceScale = max - min;
 147         float readScale = pElement->maxReport - pElement->minReport;
 148         SInt32 value = HIDGetElementValue(pDevice, pElement);
 149         if (readScale == 0)
 150                 return value; /* no scaling at all */
 151         else
 152                 return ((value - pElement->minReport) * deviceScale / readScale) + min;
 153 }
 154
 155
 156 static void HIDRemovalCallback(void * target,
 157                                IOReturn result,
 158                                void * refcon,
 159                                void * sender)
 160 {
 161         recDevice *device = (recDevice *) refcon;
 162         device->removed = 1;
 163         device->uncentered = 1;
 164 }
 165
 166
 167
 168 /* Create and open an interface to device, required prior to extracting values or building queues.
 169  * Note: appliction now owns the device and must close and release it prior to exiting
 170  */
 171
 172 static IOReturn HIDCreateOpenDeviceInterface (io_object_t hidDevice, recDevice *pDevice)
 173 {
 174         IOReturn result = kIOReturnSuccess;
 175         HRESULT plugInResult = S_OK;
 176         SInt32 score = 0;
 177         IOCFPlugInInterface ** ppPlugInInterface = NULL;
 178
 179         if (NULL == pDevice->interface)
 180         {
 181                 result = IOCreatePlugInInterfaceForService (hidDevice, kIOHIDDeviceUserClientTypeID,
 182                                                                                                         kIOCFPlugInInterfaceID, &ppPlugInInterface, &score);
 183                 if (kIOReturnSuccess == result)
 184                 {
 185                         /* Call a method of the intermediate plug-in to create the device interface */
 186                         plugInResult = (*ppPlugInInterface)->QueryInterface (ppPlugInInterface,
 187                                                                 CFUUIDGetUUIDBytes (kIOHIDDeviceInterfaceID), (void *) &(pDevice->interface));
 188                         if (S_OK != plugInResult)
 189                                 HIDReportErrorNum ("CouldnÕt query HID class device interface from plugInInterface", plugInResult);
 190                         (*ppPlugInInterface)->Release (ppPlugInInterface);
 191                 }
 192                 else
 193                         HIDReportErrorNum ("Failed to create **plugInInterface via IOCreatePlugInInterfaceForService.", result);
 194         }
 195         if (NULL != pDevice->interface)
 196         {
 197                 result = (*(pDevice->interface))->open (pDevice->interface, 0);
 198                 if (kIOReturnSuccess != result)
 199                         HIDReportErrorNum ("Failed to open pDevice->interface via open.", result);
 200                 else
 201                         (*(pDevice->interface))->setRemovalCallback (pDevice->interface, HIDRemovalCallback, pDevice, pDevice);
 202
 203         }
 204         return result;
 205 }
 206
 207 /* Closes and releases interface to device, should be done prior to exting application
 208  * Note: will have no affect if device or interface do not exist
 209  * application will "own" the device if interface is not closed
 210  * (device may have to be plug and re-plugged in different location to get it working again without a restart)
 211  */
 212
 213 static IOReturn HIDCloseReleaseInterface (recDevice *pDevice)
 214 {
 215         IOReturn result = kIOReturnSuccess;
 216
 217         if ((NULL != pDevice) && (NULL != pDevice->interface))
 218         {
 219                 /* close the interface */
 220                 result = (*(pDevice->interface))->close (pDevice->interface);
 221                 if (kIOReturnNotOpen == result)
 222                 {
 223                         /* do nothing as device was not opened, thus can't be closed */
 224                 }
 225                 else if (kIOReturnSuccess != result)
 226                         HIDReportErrorNum ("Failed to close IOHIDDeviceInterface.", result);
 227                 /* release the interface */
 228                 result = (*(pDevice->interface))->Release (pDevice->interface);
 229                 if (kIOReturnSuccess != result)
 230                         HIDReportErrorNum ("Failed to release IOHIDDeviceInterface.", result);
 231                 pDevice->interface = NULL;
 232         }
 233         return result;
 234 }
 235
 236 /* extracts actual specific element information from each element CF dictionary entry */
 237
 238 static void HIDGetElementInfo (CFTypeRef refElement, recElement *pElement)
 239 {
 240         long number;
 241         CFTypeRef refType;
 242
 243         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementCookieKey));
 244         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 245                 pElement->cookie = (IOHIDElementCookie) number;
 246         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementMinKey));
 247         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 248                 pElement->minReport = pElement->min = number;
 249         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementMaxKey));
 250         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 251                 pElement->maxReport = pElement->max = number;
 252 /*
 253         TODO: maybe should handle the following stuff somehow?
 254
 255         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementScaledMinKey));
 256         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 257                 pElement->scaledMin = number;
 258         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementScaledMaxKey));
 259         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 260                 pElement->scaledMax = number;
 261         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementSizeKey));
 262         if (refType && CFNumberGetValue (refType, kCFNumberLongType, &number))
 263                 pElement->size = number;
 264         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsRelativeKey));
 265         if (refType)
 266                 pElement->relative = CFBooleanGetValue (refType);
 267         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsWrappingKey));
 268         if (refType)
 269                 pElement->wrapping = CFBooleanGetValue (refType);
 270         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementIsNonLinearKey));
 271         if (refType)
 272                 pElement->nonLinear = CFBooleanGetValue (refType);
 273         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementHasPreferedStateKey));
 274         if (refType)
 275                 pElement->preferredState = CFBooleanGetValue (refType);
 276         refType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementHasNullStateKey));
 277         if (refType)
 278                 pElement->nullState = CFBooleanGetValue (refType);
 279 */
 280 }
 281
 282 /* examines CF dictionary vlaue in device element hierarchy to determine if it is element of interest or a collection of more elements
 283  * if element of interest allocate storage, add to list and retrieve element specific info
 284  * if collection then pass on to deconstruction collection into additional individual elements
 285  */
 286
 287 static void HIDAddElement (CFTypeRef refElement, recDevice* pDevice)
 288 {
 289         recElement* element = NULL;
 290         recElement** headElement = NULL;
 291         long elementType, usagePage, usage;
 292         CFTypeRef refElementType = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementTypeKey));
 293         CFTypeRef refUsagePage = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementUsagePageKey));
 294         CFTypeRef refUsage = CFDictionaryGetValue (refElement, CFSTR(kIOHIDElementUsageKey));
 295
 296
 297         if ((refElementType) && (CFNumberGetValue (refElementType, kCFNumberLongType, &elementType)))
 298         {
 299                 /* look at types of interest */
 300                 if ((elementType == kIOHIDElementTypeInput_Misc) || (elementType == kIOHIDElementTypeInput_Button) ||
 301                         (elementType == kIOHIDElementTypeInput_Axis))
 302                 {
 303                         if (refUsagePage && CFNumberGetValue (refUsagePage, kCFNumberLongType, &usagePage) &&
 304                                 refUsage && CFNumberGetValue (refUsage, kCFNumberLongType, &usage))
 305                         {
 306                                 switch (usagePage) /* only interested in kHIDPage_GenericDesktop and kHIDPage_Button */
 307                                 {
 308                                         case kHIDPage_GenericDesktop:
 309                                                 {
 310                                                         switch (usage) /* look at usage to determine function */
 311                                                         {
 312                                                                 case kHIDUsage_GD_X:
 313                                                                 case kHIDUsage_GD_Y:
 314                                                                 case kHIDUsage_GD_Z:
 315                                                                 case kHIDUsage_GD_Rx:
 316                                                                 case kHIDUsage_GD_Ry:
 317                                                                 case kHIDUsage_GD_Rz:
 318                                                                 case kHIDUsage_GD_Slider:
 319                                                                 case kHIDUsage_GD_Dial:
 320                                                                 case kHIDUsage_GD_Wheel:
 321                                                                         element = (recElement *) NewPtrClear (sizeof (recElement));
 322                                                                         if (element)
 323                                                                         {
 324                                                                                 pDevice->axes++;
 325                                                                                 headElement = &(pDevice->firstAxis);
 326                                                                         }
 327                                                                 break;
 328                                                                 case kHIDUsage_GD_Hatswitch:
 329                                                                         element = (recElement *) NewPtrClear (sizeof (recElement));
 330                                                                         if (element)
 331                                                                         {
 332                                                                                 pDevice->hats++;
 333                                                                                 headElement = &(pDevice->firstHat);
 334                                                                         }
 335                                                                 break;
 336                                                         }
 337                                                 }
 338                                                 break;
 339                                         case kHIDPage_Button:
 340                                                 element = (recElement *) NewPtrClear (sizeof (recElement));
 341                                                 if (element)
 342                                                 {
 343                                                         pDevice->buttons++;
 344                                                         headElement = &(pDevice->firstButton);
 345                                                 }
 346                                                 break;
 347                                         default:
 348                                                 break;
 349                                 }
 350                         }
 351                 }
 352                 else if (kIOHIDElementTypeCollection == elementType)
 353                         HIDGetCollectionElements ((CFMutableDictionaryRef) refElement, pDevice);
 354         }
 355
 356         if (element && headElement) /* add to list */
 357         {
 358                 pDevice->elements++;
 359                 if (NULL == *headElement)
 360                         *headElement = element;
 361                 else
 362                 {
 363                         recElement *elementPrevious, *elementCurrent;
 364                         elementCurrent = *headElement;
 365                         while (elementCurrent)
 366                         {
 367                                 elementPrevious = elementCurrent;
 368                                 elementCurrent = elementPrevious->pNext;
 369                         }
 370                         elementPrevious->pNext = element;
 371                 }
 372                 element->pNext = NULL;
 373                 HIDGetElementInfo (refElement, element);
 374         }
 375 }
 376
 377 /* collects information from each array member in device element list (each array memeber = element) */
 378
 379 static void HIDGetElementsCFArrayHandler (const void * value, void * parameter)
 380 {
 381         if (CFGetTypeID (value) == CFDictionaryGetTypeID ())
 382                 HIDAddElement ((CFTypeRef) value, (recDevice *) parameter);
 383 }
 384
 385 /* handles retrieval of element information from arrays of elements in device IO registry information */
 386
 387 static void HIDGetElements (CFTypeRef refElementCurrent, recDevice *pDevice)
 388 {
 389         CFTypeID type = CFGetTypeID (refElementCurrent);
 390         if (type == CFArrayGetTypeID()) /* if element is an array */
 391         {
 392                 CFRange range = {0, CFArrayGetCount (refElementCurrent)};
 393                 /* CountElementsCFArrayHandler called for each array member */
 394                 CFArrayApplyFunction (refElementCurrent, range, HIDGetElementsCFArrayHandler, pDevice);
 395         }
 396 }
 397
 398 /* handles extracting element information from element collection CF types
 399  * used from top level element decoding and hierarchy deconstruction to flatten device element list
 400  */
 401
 402 static void HIDGetCollectionElements (CFMutableDictionaryRef deviceProperties, recDevice *pDevice)
 403 {
 404         CFTypeRef refElementTop = CFDictionaryGetValue (deviceProperties, CFSTR(kIOHIDElementKey));
 405         if (refElementTop)
 406                 HIDGetElements (refElementTop, pDevice);
 407 }
 408
 409 /* use top level element usage page and usage to discern device usage page and usage setting appropriate vlaues in device record */
 410
 411 static void HIDTopLevelElementHandler (const void * value, void * parameter)
 412 {
 413         CFTypeRef refCF = 0;
 414         if (CFGetTypeID (value) != CFDictionaryGetTypeID ())
 415                 return;
 416         refCF = CFDictionaryGetValue (value, CFSTR(kIOHIDElementUsagePageKey));
 417         if (!CFNumberGetValue (refCF, kCFNumberLongType, &((recDevice *) parameter)->usagePage))
 418                 SDL_SetError ("CFNumberGetValue error retrieving pDevice->usagePage.");
 419         refCF = CFDictionaryGetValue (value, CFSTR(kIOHIDElementUsageKey));
 420         if (!CFNumberGetValue (refCF, kCFNumberLongType, &((recDevice *) parameter)->usage))
 421                 SDL_SetError ("CFNumberGetValue error retrieving pDevice->usage.");
 422 }
 423
 424 /* extracts device info from CF dictionary records in IO registry */
 425
 426 static void HIDGetDeviceInfo (io_object_t hidDevice, CFMutableDictionaryRef hidProperties, recDevice *pDevice)
 427 {
 428         CFMutableDictionaryRef usbProperties = 0;
 429         io_registry_entry_t parent1, parent2;
 430
 431         /* Mac OS X currently is not mirroring all USB properties to HID page so need to look at USB device page also
 432          * get dictionary for usb properties: step up two levels and get CF dictionary for USB properties
 433          */
 434         if ((KERN_SUCCESS == IORegistryEntryGetParentEntry (hidDevice, kIOServicePlane, &parent1)) &&
 435                 (KERN_SUCCESS == IORegistryEntryGetParentEntry (parent1, kIOServicePlane, &parent2)) &&
 436                 (KERN_SUCCESS == IORegistryEntryCreateCFProperties (parent2, &usbProperties, kCFAllocatorDefault, kNilOptions)))
 437         {
 438                 if (usbProperties)
 439                 {
 440                         CFTypeRef refCF = 0;
 441                         /* get device info
 442                          * try hid dictionary first, if fail then go to usb dictionary
 443                          */
 444
 445
 446                         /* get product name */
 447                         refCF = CFDictionaryGetValue (hidProperties, CFSTR(kIOHIDProductKey));
 448                         if (!refCF)
 449                                 refCF = CFDictionaryGetValue (usbProperties, CFSTR("USB Product Name"));
 450                         if (refCF)
 451                         {
 452                                 if (!CFStringGetCString (refCF, pDevice->product, 256, CFStringGetSystemEncoding ()))
 453                                         SDL_SetError ("CFStringGetCString error retrieving pDevice->product.");
 454                         }
 455
 456                         /* get usage page and usage */
 457                         refCF = CFDictionaryGetValue (hidProperties, CFSTR(kIOHIDPrimaryUsagePageKey));
 458                         if (refCF)
 459                         {
 460                                 if (!CFNumberGetValue (refCF, kCFNumberLongType, &pDevice->usagePage))
 461                                         SDL_SetError ("CFNumberGetValue error retrieving pDevice->usagePage.");
 462                                 refCF = CFDictionaryGetValue (hidProperties, CFSTR(kIOHIDPrimaryUsageKey));
 463                                 if (refCF)
 464                                         if (!CFNumberGetValue (refCF, kCFNumberLongType, &pDevice->usage))
 465                                                 SDL_SetError ("CFNumberGetValue error retrieving pDevice->usage.");
 466                         }
 467
 468                         if (NULL == refCF) /* get top level element HID usage page or usage */
 469                         {
 470                                 /* use top level element instead */
 471                                 CFTypeRef refCFTopElement = 0;
 472                                 refCFTopElement = CFDictionaryGetValue (hidProperties, CFSTR(kIOHIDElementKey));
 473                                 {
 474                                         /* refCFTopElement points to an array of element dictionaries */
 475                                         CFRange range = {0, CFArrayGetCount (refCFTopElement)};
 476                                         CFArrayApplyFunction (refCFTopElement, range, HIDTopLevelElementHandler, pDevice);
 477                                 }
 478                         }
 479
 480                         CFRelease (usbProperties);
 481                 }
 482                 else
 483                         SDL_SetError ("IORegistryEntryCreateCFProperties failed to create usbProperties.");
 484
 485                 if (kIOReturnSuccess != IOObjectRelease (parent2))
 486                         SDL_SetError ("IOObjectRelease error with parent2.");
 487                 if (kIOReturnSuccess != IOObjectRelease (parent1))
 488                         SDL_SetError ("IOObjectRelease error with parent1.");
 489         }
 490 }
 491
 492
 493 static recDevice *HIDBuildDevice (io_object_t hidDevice)
 494 {
 495         recDevice *pDevice = (recDevice *) NewPtrClear (sizeof (recDevice));
 496         if (pDevice)
 497         {
 498                 /* get dictionary for HID properties */
 499                 CFMutableDictionaryRef hidProperties = 0;
 500                 kern_return_t result = IORegistryEntryCreateCFProperties (hidDevice, &hidProperties, kCFAllocatorDefault, kNilOptions);
 501                 if ((result == KERN_SUCCESS) && hidProperties)
 502                 {
 503                         /* create device interface */
 504                         result = HIDCreateOpenDeviceInterface (hidDevice, pDevice);
 505                         if (kIOReturnSuccess == result)
 506                         {
 507                                 HIDGetDeviceInfo (hidDevice, hidProperties, pDevice); /* hidDevice used to find parents in registry tree */
 508                                 HIDGetCollectionElements (hidProperties, pDevice);
 509                         }
 510                         else
 511                         {
 512                                 DisposePtr((Ptr)pDevice);
 513                                 pDevice = NULL;
 514                         }
 515                         CFRelease (hidProperties);
 516                 }
 517                 else
 518                 {
 519                         DisposePtr((Ptr)pDevice);
 520                         pDevice = NULL;
 521                 }
 522         }
 523         return pDevice;
 524 }
 525
 526 /* disposes of the element list associated with a device and the memory associated with the list
 527  */
 528
 529 static void HIDDisposeElementList (recElement **elementList)
 530 {
 531         recElement *pElement = *elementList;
 532         while (pElement)
 533         {
 534                 recElement *pElementNext = pElement->pNext;
 535                 DisposePtr ((Ptr) pElement);
 536                 pElement = pElementNext;
 537         }
 538         *elementList = NULL;
 539 }
 540
 541 /* disposes of a single device, closing and releaseing interface, freeing memory fro device and elements, setting device pointer to NULL
 542  * all your device no longer belong to us... (i.e., you do not 'own' the device anymore)
 543  */
 544
 545 static recDevice *HIDDisposeDevice (recDevice **ppDevice)
 546 {
 547         kern_return_t result = KERN_SUCCESS;
 548         recDevice *pDeviceNext = NULL;
 549         if (*ppDevice)
 550         {
 551                 /* save next device prior to disposing of this device */
 552                 pDeviceNext = (*ppDevice)->pNext;
 553
 554                 /* free element lists */
 555                 HIDDisposeElementList (&(*ppDevice)->firstAxis);
 556                 HIDDisposeElementList (&(*ppDevice)->firstButton);
 557                 HIDDisposeElementList (&(*ppDevice)->firstHat);
 558
 559                 result = HIDCloseReleaseInterface (*ppDevice); /* function sanity checks interface value (now application does not own device) */
 560                 if (kIOReturnSuccess != result)
 561                         HIDReportErrorNum ("HIDCloseReleaseInterface failed when trying to dipose device.", result);
 562                 DisposePtr ((Ptr)*ppDevice);
 563                 *ppDevice = NULL;
 564         }
 565         return pDeviceNext;
 566 }
 567
 568
 569 /* Function to scan the system for joysticks.
 570  * Joystick 0 should be the system default joystick.
 571  * This function should return the number of available joysticks, or -1
 572  * on an unrecoverable fatal error.
 573  */
 574 int SDL_SYS_JoystickInit(void)
 575 {
 576         IOReturn result = kIOReturnSuccess;
 577         mach_port_t masterPort = 0;
 578         io_iterator_t hidObjectIterator = 0;
 579         CFMutableDictionaryRef hidMatchDictionary = NULL;
 580         recDevice *device, *lastDevice;
 581         io_object_t ioHIDDeviceObject = 0;
 582
 583         SDL_numjoysticks = 0;
 584
 585         if (gpDeviceList)
 586         {
 587                 SDL_SetError("Joystick: Device list already inited.");
 588                 return -1;
 589         }
 590
 591         result = IOMasterPort (bootstrap_port, &masterPort);
 592         if (kIOReturnSuccess != result)
 593         {
 594                 SDL_SetError("Joystick: IOMasterPort error with bootstrap_port.");
 595                 return -1;
 596         }
 597
 598         /* Set up a matching dictionary to search I/O Registry by class name for all HID class devices. */
 599         hidMatchDictionary = IOServiceMatching (kIOHIDDeviceKey);
 600         if (hidMatchDictionary)
 601         {
 602                 /* Add key for device type (joystick, in this case) to refine the matching dictionary. */
 603
 604                 /* NOTE: we now perform this filtering later
 605                 UInt32 usagePage = kHIDPage_GenericDesktop;
 606                 UInt32 usage = kHIDUsage_GD_Joystick;
 607                 CFNumberRef refUsage = NULL, refUsagePage = NULL;
 608
 609                 refUsage = CFNumberCreate (kCFAllocatorDefault, kCFNumberIntType, &usage);
 610                 CFDictionarySetValue (hidMatchDictionary, CFSTR (kIOHIDPrimaryUsageKey), refUsage);
 611                 refUsagePage = CFNumberCreate (kCFAllocatorDefault, kCFNumberIntType, &usagePage);
 612                 CFDictionarySetValue (hidMatchDictionary, CFSTR (kIOHIDPrimaryUsagePageKey), refUsagePage);
 613                 */
 614         }
 615         else
 616         {
 617                 SDL_SetError("Joystick: Failed to get HID CFMutableDictionaryRef via IOServiceMatching.");
 618                 return -1;
 619         }
 620
 621         /*/ Now search I/O Registry for matching devices. */
 622         result = IOServiceGetMatchingServices (masterPort, hidMatchDictionary, &hidObjectIterator);
 623         /* Check for errors */
 624         if (kIOReturnSuccess != result)
 625         {
 626                 SDL_SetError("Joystick: Couldn't create a HID object iterator.");
 627                 return -1;
 628         }
 629         if (!hidObjectIterator) /* there are no joysticks */
 630         {
 631                 gpDeviceList = NULL;
 632                 SDL_numjoysticks = 0;
 633                 return 0;
 634         }
 635         /* IOServiceGetMatchingServices consumes a reference to the dictionary, so we don't need to release the dictionary ref. */
 636
 637         /* build flat linked list of devices from device iterator */
 638
 639         gpDeviceList = lastDevice = NULL;
 640
 641         while ((ioHIDDeviceObject = IOIteratorNext (hidObjectIterator)))
 642         {
 643                 /* build a device record */
 644                 device = HIDBuildDevice (ioHIDDeviceObject);
 645                 if (!device)
 646                         continue;
 647
 648                 /* dump device object, it is no longer needed */
 649                 result = IOObjectRelease (ioHIDDeviceObject);
 650 /*              if (KERN_SUCCESS != result)
 651                         HIDReportErrorNum ("IOObjectRelease error with ioHIDDeviceObject.", result);
 652 */
 653
 654                 /* Filter device list to non-keyboard/mouse stuff */
 655                 if ( (device->usagePage != kHIDPage_GenericDesktop) ||
 656                      ((device->usage != kHIDUsage_GD_Joystick &&
 657                       device->usage != kHIDUsage_GD_GamePad &&
 658                       device->usage != kHIDUsage_GD_MultiAxisController)) ) {
 659
 660                         /* release memory for the device */
 661                         HIDDisposeDevice (&device);
 662                         DisposePtr((Ptr)device);
 663                         continue;
 664                 }
 665
 666                 /* Add device to the end of the list */
 667                 if (lastDevice)
 668                         lastDevice->pNext = device;
 669                 else
 670                         gpDeviceList = device;
 671                 lastDevice = device;
 672         }
 673         result = IOObjectRelease (hidObjectIterator); /* release the iterator */
 674
 675         /* Count the total number of devices we found */
 676         device = gpDeviceList;
 677         while (device)
 678         {
 679                 SDL_numjoysticks++;
 680                 device = device->pNext;
 681         }
 682
 683         return SDL_numjoysticks;
 684 }
 685
 686 /* Function to get the device-dependent name of a joystick */
 687 const char *SDL_SYS_JoystickName(int index)
 688 {
 689         recDevice *device = gpDeviceList;
 690
 691         for (; index > 0; index--)
 692                 device = device->pNext;
 693
 694         return device->product;
 695 }
 696
 697 /* Function to open a joystick for use.
 698  * The joystick to open is specified by the index field of the joystick.
 699  * This should fill the nbuttons and naxes fields of the joystick structure.
 700  * It returns 0, or -1 if there is an error.
 701  */
 702 int SDL_SYS_JoystickOpen(SDL_Joystick *joystick)
 703 {
 704         recDevice *device = gpDeviceList;
 705         int index;
 706
 707         for (index = joystick->index; index > 0; index--)
 708                 device = device->pNext;
 709
 710         joystick->hwdata = device;
 711         joystick->name = device->product;
 712
 713         joystick->naxes = device->axes;
 714         joystick->nhats = device->hats;
 715         joystick->nballs = 0;
 716         joystick->nbuttons = device->buttons;
 717
 718         return 0;
 719 }
 720
 721 /* Function to update the state of a joystick - called as a device poll.
 722  * This function shouldn't update the joystick structure directly,
 723  * but instead should call SDL_PrivateJoystick*() to deliver events
 724  * and update joystick device state.
 725  */
 726 void SDL_SYS_JoystickUpdate(SDL_Joystick *joystick)
 727 {
 728         recDevice *device = joystick->hwdata;
 729         recElement *element;
 730         SInt32 value, range;
 731         int i;
 732
 733         if (device->removed)  /* device was unplugged; ignore it. */
 734         {
 735                 if (device->uncentered)
 736                 {
 737                         device->uncentered = 0;
 738
 739                         /* Tell the app that everything is centered/unpressed... */
 740                         for (i = 0; i < device->axes; i++)
 741                                 SDL_PrivateJoystickAxis(joystick, i, 0);
 742
 743                         for (i = 0; i < device->buttons; i++)
 744                                 SDL_PrivateJoystickButton(joystick, i, 0);
 745
 746                         for (i = 0; i < device->hats; i++)
 747                                 SDL_PrivateJoystickHat(joystick, i, SDL_HAT_CENTERED);
 748                 }
 749
 750                 return;
 751         }
 752
 753         element = device->firstAxis;
 754         i = 0;
 755         while (element)
 756         {
 757                 value = HIDScaledCalibratedValue(device, element, -32768, 32767);
 758                 if ( value != joystick->axes[i] )
 759                         SDL_PrivateJoystickAxis(joystick, i, value);
 760                 element = element->pNext;
 761                 ++i;
 762         }
 763
 764         element = device->firstButton;
 765         i = 0;
 766         while (element)
 767         {
 768                 value = HIDGetElementValue(device, element);
 769         if (value > 1)  /* handle pressure-sensitive buttons */
 770             value = 1;
 771                 if ( value != joystick->buttons[i] )
 772                         SDL_PrivateJoystickButton(joystick, i, value);
 773                 element = element->pNext;
 774                 ++i;
 775         }
 776
 777         element = device->firstHat;
 778         i = 0;
 779         while (element)
 780         {
 781                 Uint8 pos = 0;
 782
 783                 range = (element->max - element->min + 1);
 784                 value = HIDGetElementValue(device, element) - element->min;
 785                 if (range == 4) /* 4 position hatswitch - scale up value */
 786                         value *= 2;
 787                 else if (range != 8) /* Neither a 4 nor 8 positions - fall back to default position (centered) */
 788                         value = -1;
 789                 switch(value)
 790                 {
 791                         case 0:
 792                                 pos = SDL_HAT_UP;
 793                                 break;
 794                         case 1:
 795                                 pos = SDL_HAT_RIGHTUP;
 796                                 break;
 797                         case 2:
 798                                 pos = SDL_HAT_RIGHT;
 799                                 break;
 800                         case 3:
 801                                 pos = SDL_HAT_RIGHTDOWN;
 802                                 break;
 803                         case 4:
 804                                 pos = SDL_HAT_DOWN;
 805                                 break;
 806                         case 5:
 807                                 pos = SDL_HAT_LEFTDOWN;
 808                                 break;
 809                         case 6:
 810                                 pos = SDL_HAT_LEFT;
 811                                 break;
 812                         case 7:
 813                                 pos = SDL_HAT_LEFTUP;
 814                                 break;
 815                         default:
 816                                 /* Every other value is mapped to center. We do that because some
 817                                  * joysticks use 8 and some 15 for this value, and apparently
 818                                  * there are even more variants out there - so we try to be generous.
 819                                  */
 820                                 pos = SDL_HAT_CENTERED;
 821                                 break;
 822                 }
 823                 if ( pos != joystick->hats[i] )
 824                         SDL_PrivateJoystickHat(joystick, i, pos);
 825                 element = element->pNext;
 826                 ++i;
 827         }
 828
 829         return;
 830 }
 831
 832 /* Function to close a joystick after use */
 833 void SDL_SYS_JoystickClose(SDL_Joystick *joystick)
 834 {
 835         /* Should we do anything here? */
 836         return;
 837 }
 838
 839 /* Function to perform any system-specific joystick related cleanup */
 840 void SDL_SYS_JoystickQuit(void)
 841 {
 842         while (NULL != gpDeviceList)
 843                 gpDeviceList = HIDDisposeDevice (&gpDeviceList);
 844 }
 845
 846 #endif /* SDL_JOYSTICK_IOKIT */