include/SDL_joystick.h
changeset 6690 9548c8a58103
parent 6138 4c64952a58fb
child 6707 70eeb7e3ec2f
     1.1 --- a/include/SDL_joystick.h	Mon Nov 26 14:59:07 2012 -0800
     1.2 +++ b/include/SDL_joystick.h	Mon Nov 26 16:37:54 2012 -0800
     1.3 @@ -23,6 +23,17 @@
     1.4   *  \file SDL_joystick.h
     1.5   *  
     1.6   *  Include file for SDL joystick event handling
     1.7 + *
     1.8 + * The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks, with the exact joystick
     1.9 + *   behind a device_index changing as joysticks are plugged and unplugged.
    1.10 + *
    1.11 + * The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
    1.12 + *   then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
    1.13 + *
    1.14 + * The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of 
    1.15 + *   the device (a X360 wired controller for example). This identifier is platform dependent.
    1.16 + *
    1.17 + *
    1.18   */
    1.19  
    1.20  #ifndef _SDL_joystick_h
    1.21 @@ -51,10 +62,11 @@
    1.22  struct _SDL_Joystick;
    1.23  typedef struct _SDL_Joystick SDL_Joystick;
    1.24  
    1.25 -
    1.26 +typedef int SDL_JoystickID;
    1.27 +	
    1.28  /* Function prototypes */
    1.29  /**
    1.30 - *  Count the number of joysticks attached to the system
    1.31 + *  Count the number of joysticks attached to the system right now
    1.32   */
    1.33  extern DECLSPEC int SDLCALL SDL_NumJoysticks(void);
    1.34  
    1.35 @@ -63,7 +75,7 @@
    1.36   *  This can be called before any joysticks are opened.
    1.37   *  If no name can be found, this function returns NULL.
    1.38   */
    1.39 -extern DECLSPEC const char *SDLCALL SDL_JoystickName(int device_index);
    1.40 +extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index);
    1.41  
    1.42  /**
    1.43   *  Open a joystick for use.  
    1.44 @@ -76,14 +88,47 @@
    1.45  extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index);
    1.46  
    1.47  /**
    1.48 - *  Returns 1 if the joystick has been opened, or 0 if it has not.
    1.49 + *  Return the name for this currently opened joystick.
    1.50 + *  If no name can be found, this function returns NULL.
    1.51   */
    1.52 -extern DECLSPEC int SDLCALL SDL_JoystickOpened(int device_index);
    1.53 +extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick * joystick);
    1.54 +	
    1.55 +/* A structure that encodes the stable unique id for a joystick device */
    1.56 +typedef struct
    1.57 +{
    1.58 +	Uint8 data[16];
    1.59 +} JoystickGUID;
    1.60 +
    1.61 +/**
    1.62 + *  Return the GUID for the joystick at this index
    1.63 + */
    1.64 +extern DECLSPEC JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_index);
    1.65 +
    1.66 +/**
    1.67 + *  Return the GUID for this opened joystick
    1.68 + */
    1.69 +extern DECLSPEC JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick * joystick);
    1.70 +
    1.71 +/**
    1.72 + *  Return a string representation for this guid. You are responsible for freeing memory from this call
    1.73 + */
    1.74 +extern DECLSPEC char *SDLCALL SDL_JoystickGetGUIDString(JoystickGUID guid);
    1.75 +
    1.76 +/**
    1.77 + *  convert a string into a joystick formatted guid
    1.78 + */
    1.79 +extern DECLSPEC JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const char *pchGUID);
    1.80 +
    1.81 +
    1.82 +/**
    1.83 + *  Returns 1 if the joystick has been opened and currently connected, or 0 if it has not.
    1.84 + */
    1.85 +extern DECLSPEC int SDLCALL SDL_JoystickGetAttached(SDL_Joystick * joystick);
    1.86  
    1.87  /**
    1.88   *  Get the device index of an opened joystick.
    1.89   */
    1.90 -extern DECLSPEC int SDLCALL SDL_JoystickIndex(SDL_Joystick * joystick);
    1.91 +extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick * joystick);
    1.92  
    1.93  /**
    1.94   *  Get the number of general axis controls on a joystick.