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