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