# AHKHID Documentation

#

AHKHID exposes the API calls necessary in order to interact with HID devices. This page contains all the information you need to use it.
Download: AHKHID, Example 1, Example 2 and Example 3. Forum post here.

Table of Contents
How do I map buttons on my keyboard/mouse/device? References Function List Flags for AHKHID_GetDevInfo() (DI_) Flags for AHKHID_GetInputInfo() (II_) Flags for AHKHID_AddRegister() or AHKHID_Register() (RIDEV_) Raw input flags Interpreting II_MSE_FLAGS Interpreting II_MSE_BUTTONFLAGS Interpreting II_KBD_FLAGS Other constants

### How do I map buttons on my keyboard/mouse/device? (top)

Before going ahead and registering devices, you need to understand how registration works. You cannot register a device in specific. HID devices are categorized into what is called Top Level Collections (TLCs). In other words, a whole class of devices might be listed under the same TLC. What constitutes a TLC is the "Usage Page" value and the "Usage" value. For example, all keyboards are categorized under the keyboard TLC which is Usage Page 1 and Usage 6. Similarly, mice are under the TLC with Usage Page 1 and Usage 2.
When registering, you can only tell Windows which TLCs you'd like to register with your application. However, you can still tell apart which HID device sent what upon reception of the data (at least for HID devices other than keyboards and mice). Therefore, even if you have two HID devices under the same TLC, you can still tell them apart by comparing data specific to each, such as Vendor ID, Product ID, etc...
The first thing you need to do when mapping data from your HID device, is to find out where it comes from (from which HID device), and what it looks like. You can use Example 1 and 2 for that. Example 1 allows you to explore the different HID devices connected to your computer (and find out what TLC they belong to), and Example 2 allows you to examine the data coming out of them (by plugging in the TLC you found in Example 1).
Once you know what that keyboard/mouse/HID button press generates, there are different ways you can integrate it into your script. The simplest would be to use #Include to include AHKHID, and then do a call at the beginning of your script to AHKHID_Register() and use your OnMessage() sub to treat the data. Or if you just need the bare minimum in order to interact with a non-keyboard-or-mouse device, you can simply copy/paste the AHKHID_Register() function as well as the AHKHID_GetInputData() function into your script. For more information on how to use those functions, you can look into Example 2.

### Function List (top)

    USING THE CONSTANTS:

    If you explicitly #include AHKHID in your script, you will have all the constants available to you. Otherwise, if AHKHID is
    in your library folder and you do not wish to explicitly #include it, you can call AHKHID_UseConstants() to have the
    constants available to you.
    _____________________
    AHKHID_UseConstants()

    See the section above titled "USING THE CONSTANTS"
    ___________________________________
    AHKHID_Initialize(bRefresh = False)

    You don't have to call this function manually. It is automatically called by other functions to get the pointer of the
    RAWINPUTDEVICELIST struct array. However, if a new device is plugged in, you will have to refresh the listing by calling it
    with bRefresh = True. Returns -1 on error (with error message in ErrorLevel).
    ____________________
    AHKHID_GetDevCount()

    Returs the number of HID devices connected to this computer.
    Returns -1 on error (with error message in ErrorLevel).
    ______________________
    AHKHID_GetDevHandle(i)

    Returns the handle of device i (starts at 1).
    Mostly used internally for API calls.
    __________________________
    AHKHID_GetDevIndex(Handle)

    Returns the index (starts at 1) of the device in the enumeration with matching handle.
    Returns 0 if not found.
    ______________________________________
    AHKHID_GetDevType(i, IsHandle = False)

    Returns the type of the device. See the RIM_ constants for possible values.
    If IsHandle is false, then i is considered the index (starts at 1) of the device in the enumeration.
    Otherwise it is the handle of the device.
    ______________________________________
    AHKHID_GetDevName(i, IsHandle = False)

    Returns the name of the device (or empty string on error, with error message in ErrorLevel).
    If IsHandle is false, then i is considered the index (starts at 1) of the device in the enumeration.
    Otherwise it is the handle of the device.
    ____________________________________________
    AHKHID_GetDevInfo(i, Flag, IsHandle = False)

    Retrieves info from the RID_DEVICE_INFO struct. To retrieve a member, simply use the corresponding flag. A list of flags
    can be found at the top of the script (the constants starting with DI_). Each flag corresponds to a member in the struct.
    If IsHandle is false, then i is considered the index (starts at 1) of the device in the enumeration. Otherwise it is the
    handle of the device. Returns -1 on error (with error message in ErrorLevel).

    See Example 1 for an example on how to use it.
    _______________________________________________________________________________
    AHKHID_AddRegister(UsagePage = False, Usage = False, Handle = False, Flags = 0)

    Allows you to queue up RAWINPUTDEVICE structures before doing the registration. To use it, you first need to initialize the
    variable by calling AHKHID_AddRegister(iNumberOfElements). To then add to the stack, simply call it with the parameters you
    want (eg. AHKHID_AddRegister(1,6,MyGuiHandle) for keyboards). When you're finally done, you just have to call
    AHKHID_Register() with no parameters. The function returns -1 if the struct is full. Redimensioning the struct will erase
    all previous structs added. On success, it returns the address of the array of structs (if you'd rather manipulate it
    yourself).

    See Example 2 for an example on how to use it.

    You will need to do this if you want to use advance features of the RAWINPUTDEVICE flags. For example, if you want to
    register all devices using Usage Page 1 but would like to exclude devices of Usage Page 1 using Usage 2 (keyboards), then
    you need to place two elements in the array. The first one is AHKHID_AddRegister(1,0,MyGuiHandle,RIDEV_PAGEONLY) and the
    second one is AHKHID_AddRegister(1,2,MyGuiHandle,RIDEV_EXCLUDE).

    Tip: Have a look at all the flags you can use (see the constants starting with RIDEV_). The most useful is RIDEV_INPUTSINK.
    Tip: Set Handle to 0 if you want the WM_INPUT messages to go to the window with keyboard focus.
    Tip: To unregister, use the flag RIDEV_REMOVE. Note that you also need to use the RIDEV_PAGEONLY flag if the TLC was
    registered with it.
    ____________________________________________________________________________
    AHKHID_Register(UsagePage = False, Usage = False, Handle = False, Flags = 0)

    This function can be used in two ways. If no parameters are specified, it will use the RAWINPUTDEVICE array created through
    AHKHID_AddRegister() and register. Otherwise, it will register only the specified parameters. For example, if you just want
    to register the mouse, you can simply do AHKHID_Register(1,2,MyGuiHandle). Returns 0 on success, returns -1 on error (with
    error message in ErrorLevel).

    See Example 2 for an example on how to use it with the RAWINPUTDEVICE.
    See Example 3 for an example on how to use it only with the specified parameters.
    ____________________________________
    AHKHID_GetRegisteredDevs(ByRef uDev)

    This function allows you to get an array of the TLCs that have already been registered.
    It fills uDev with an array of RAWINPUTDEVICE and returns the number of elements in the array.
    Returns -1 on error (with error message in ErrorLevel).

    See Example 2 for an example on how to use it.
    ______________________________________
    AHKHID_GetInputInfo(InputHandle, Flag)

    This function is used to retrieve the data upon receiving WM_INPUT messages. By passing the lParam of the WM_INPUT (0xFF00)
    messages, it can retrieve all the members of the RAWINPUT structure, except the raw data coming from HID devices (use
    AHKHID_GetInputData for that). To retrieve a member, simply specify the flag corresponding to the member you want, and call
    the function. A list of all the flags can be found at the top of this script (the constants starting with II_). Returns -1
    on error (with error message in ErrorLevel).

    See Example 2 for an example on how to use it to retrieve each member of the structure.
    See Example 3 for an example on how to interpret members which represent flags.

    Tip: You have to use Critical in your message function or you might get invalid handle errors.
    Tip: You can check the value of wParam to know if the application was in the foreground upon reception (see RIM_INPUT).
    _____________________________________________
    AHKHID_GetInputData(InputHandle, ByRef uData)

    This function is used to retrieve the data sent by HID devices of type RIM_TYPEHID (ie. neither keyboard nor mouse) upon
    receiving WM_INPUT messages. CAUTION: it does not check if the device is indeed of type HID. It is up to you to do so (you
    can use GetInputInfo for that). Specify the lParam of the WM_INPUT (0xFF00) message and the function will put in uData the
    raw data received from the device. It will then return the size (number of bytes) of uData. Returns -1 on error (with error
    message in ErrorLevel).

    See Example 2 for an example on how to use it (although you need an HID device of type RIM_TYPEHID to test it).

### Flags for AHKHID_GetDevInfo() (top)

    DI_DEVTYPE                  := 4    ;Type of the device. See RIM_ constants.

    DI_MSE_ID                   := 8    ;ID for the mouse device.
    DI_MSE_NUMBEROFBUTTONS      := 12   ;Number of buttons for the mouse.
    DI_MSE_SAMPLERATE           := 16   ;Number of data points per second. This information may not be applicable for every
    									;mouse device.
    DI_MSE_HASHORIZONTALWHEEL   := 20   ;Vista only: TRUE if the mouse has a wheel for horizontal scrolling; otherwise, FALSE.

    DI_KBD_TYPE                 := 8    ;Type of the keyboard.
    DI_KBD_SUBTYPE              := 12   ;Subtype of the keyboard.
    DI_KBD_KEYBOARDMODE         := 16   ;Scan code mode.
    DI_KBD_NUMBEROFFUNCTIONKEYS := 20   ;Number of function keys on the keyboard.
    DI_KBD_NUMBEROFINDICATORS   := 24   ;Number of LED indicators on the keyboard.
    DI_KBD_NUMBEROFKEYSTOTAL    := 28   ;Total number of keys on the keyboard.

    DI_HID_VENDORID             := 8    ;Vendor ID for the HID.
    DI_HID_PRODUCTID            := 12   ;Product ID for the HID.
    DI_HID_VERSIONNUMBER        := 16   ;Version number for the HID.
    DI_HID_USAGEPAGE            := 20 | 0x0100  ;Top-level collection Usage Page for the device.
    DI_HID_USAGE                := 22 | 0x0100  ;Top-level collection Usage for the device.

### Flags for AHKHID_GetInputInfo() (top)

    II_DEVTYPE          := 0    ;Type of the device generating the raw input data. See RIM_ constants.
    II_DEVHANDLE        := 8    ;Handle to the device generating the raw input data.

    II_MSE_FLAGS        := 16 | 0x0100  ;Mouse state. This member can be any reasonable combination of the following values
                                        ; -> see MOUSE constants.
    II_MSE_BUTTONFLAGS  := 20 | 0x0100  ;Transition state of the mouse buttons. This member can be one or more of the following
                                        ;values -> see RI_MOUSE constants.
    II_MSE_BUTTONDATA   := 22 | 0x1100  ;If usButtonFlags is RI_MOUSE_WHEEL, this member is a signed value that specifies the
                                        ;wheel delta.
    II_MSE_RAWBUTTONS   := 24           ;Raw state of the mouse buttons.
    II_MSE_LASTX        := 28 | 0x1000  ;Motion in the X direction. This is signed relative motion or absolute motion,
                                        ;depending on the value of usFlags.
    II_MSE_LASTY        := 32 | 0x1000  ;Motion in the Y direction. This is signed relative motion or absolute motion,
                                        ;depending on the value of usFlags.
    II_MSE_EXTRAINFO    := 36           ;Device-specific additional information for the event.

    II_KBD_MAKECODE     := 16 | 0x0100  ;Scan code from the key depression. The scan code for keyboard overrun is
                                        ;KEYBOARD_OVERRUN_MAKE_CODE.
    II_KBD_FLAGS        := 18 | 0x0100  ;Flags for scan code information. It can be one or more of the following values
                                        ;-> see RI_KEY constants.
    II_KBD_VKEY         := 22 | 0x0100  ;Microsoft Windows message compatible virtual-key code.
    II_KBD_MSG          := 24           ;Corresponding window message, for example WM_KEYDOWN, WM_SYSKEYDOWN, and so forth.
    II_KBD_EXTRAINFO    := 28           ;Device-specific additional information for the event.

    II_HID_SIZE         := 16           ;Size, in bytes, of each HID input in bRawData.
    II_HID_COUNT        := 20           ;Number of HID inputs in bRawData.

    ;DO NOT USE WITH AHKHID_GetInputInfo. Use AHKHID_GetInputData instead to retrieve the raw data.
    II_HID_DATA         := 24           ;Raw input data as an array of bytes.

### Flags for AHKHID_AddRegister() or AHKHID_Register() (top)

    RIDEV_REMOVE        := 0x00000001   ;If set, this removes the top level collection from the inclusion list. This tells the
                                        ;operating system to stop reading from a device which matches the top level collection.
    RIDEV_EXCLUDE       := 0x00000010   ;If set, this specifies the top level collections to exclude when reading a complete
                                        ;usage page. This flag only affects a TLC whose usage page is already specified with
                                        ;RIDEV_PAGEONLY.
    RIDEV_PAGEONLY      := 0x00000020   ;If set, this specifies all devices whose top level collection is from the specified
                                        ;usUsagePage. Note that usUsage must be zero. To exclude a particular top level
                                        ;collection, use RIDEV_EXCLUDE.
    RIDEV_NOLEGACY      := 0x00000030   ;If set, this prevents any devices specified by usUsagePage or usUsage from generating
                                        ;legacy messages. This is only for the mouse and keyboard. See Remarks.
    RIDEV_INPUTSINK     := 0x00000100   ;If set, this enables the caller to receive the input even when the caller is not in
                                        ;the foreground. Note that hwndTarget must be specified.
    RIDEV_CAPTUREMOUSE  := 0x00000200   ;If set, the mouse button click does not activate the other window.
    RIDEV_NOHOTKEYS     := 0x00000200   ;If set, the application-defined keyboard device hotkeys are not handled. However, the
                                        ;system hotkeys; for example, ALT+TAB and CTRL+ALT+DEL, are still handled. By default,
                                        ;all keyboard hotkeys are handled. RIDEV_NOHOTKEYS can be specified even if
                                        ;RIDEV_NOLEGACY is not specified and hwndTarget is NULL.
    RIDEV_APPKEYS       := 0x00000400   ;Microsoft Windows XP Service Pack 1 (SP1): If set, the application command keys are
                                        ;handled. RIDEV_APPKEYS can be specified only if RIDEV_NOLEGACY is specified for a
                                        ;keyboard device.
    RIDEV_EXINPUTSINK   := 0x00001000   ;Vista only: If set, this enables the caller to receive input in the background only if
                                        ;the foreground application does not process it. In other words, if the foreground
                                        ;application is not registered for raw input, then the background application that is
                                        ;registered will receive the input.

### Interpreting II_MSE_FLAGS (top)

    MOUSE_MOVE_RELATIVE         := 0     ;Mouse movement data is relative to the last mouse position.
    MOUSE_MOVE_ABSOLUTE         := 1     ;Mouse movement data is based on absolute position.
    MOUSE_VIRTUAL_DESKTOP       := 0x02  ;Mouse coordinates are mapped to the virtual desktop (for a multiple monitor system)
    MOUSE_ATTRIBUTES_CHANGED    := 0x04  ;Mouse attributes changed; application needs to query the mouse attributes.

### Interpreting II_MSE_BUTTONFLAGS (top)

    RI_MOUSE_LEFT_BUTTON_DOWN   := 0x0001   ;Self-explanatory
    RI_MOUSE_LEFT_BUTTON_UP     := 0x0002   ;Self-explanatory
    RI_MOUSE_RIGHT_BUTTON_DOWN  := 0x0004   ;Self-explanatory
    RI_MOUSE_RIGHT_BUTTON_UP    := 0x0008   ;Self-explanatory
    RI_MOUSE_MIDDLE_BUTTON_DOWN := 0x0010   ;Self-explanatory
    RI_MOUSE_MIDDLE_BUTTON_UP   := 0x0020   ;Self-explanatory
    RI_MOUSE_BUTTON_4_DOWN      := 0x0040   ;XBUTTON1 changed to down.
    RI_MOUSE_BUTTON_4_UP        := 0x0080   ;XBUTTON1 changed to up.
    RI_MOUSE_BUTTON_5_DOWN      := 0x0100   ;XBUTTON2 changed to down.
    RI_MOUSE_BUTTON_5_UP        := 0x0200   ;XBUTTON2 changed to up.
    RI_MOUSE_WHEEL              := 0x0400   ;Raw input comes from a mouse wheel. The wheel delta is stored in usButtonData.

### Interpreting II_KBD_FLAGS (top)

    RI_KEY_MAKE             := 0
    RI_KEY_BREAK            := 1
    RI_KEY_E0               := 2
    RI_KEY_E1               := 4
    RI_KEY_TERMSRV_SET_LED  := 8
    RI_KEY_TERMSRV_SHADOW   := 0x10

### Other constants (top)

    ;Device type values returned by AHKHID_GetDevType() as well as DI_DEVTYPE and II_DEVTYPE
    RIM_TYPEMOUSE       := 0    ;The device is a mouse.
    RIM_TYPEKEYBOARD    := 1    ;The device is a keyboard.
    RIM_TYPEHID         := 2    ;The device is an Human Interface Device (HID) that is not a keyboard and not a mouse.

    ;Different values wParam can take on during a WM_INPUT message
    RIM_INPUT       := 0    ;Input occurred while the application was in the foreground. The application must call
                            ;DefWindowProc so the system can perform cleanup.
    RIM_INPUTSINK   := 1    ;Input occurred while the application was not in the foreground. The application must call
                            ;DefWindowProc so the system can perform the cleanup.

    ;Flag for the II_KBD_MAKECODE member in the event of a keyboard overrun
    KEYBOARD_OVERRUN_MAKE_CODE  := 0xFF