Using IOHIDManager to Get Modifier Key Events

Question

I'm trying to use IOHIDManager to get modifier key events because Cocoa flagsChanged events are lacking (difficult to differentiate between press/release, left/right if both are down, etc.) Here's the code where I create the manager and register the callback.

IOHIDManagerRef hidManager = IOHIDManagerCreate(kCFAllocatorDefault,
        kIOHIDOptionsTypeNone);
if (CFGetTypeID(hidManager) != IOHIDManagerGetTypeID())
    return 1;

CFMutableDictionaryRef capsLock =
    myCreateDeviceMatchingDictionary(0x07, 0x39);
CFMutableDictionaryRef lctrl =
    myCreateDeviceMatchingDictionary(0x07, 0xE0);
CFMutableDictionaryRef lshift =
    myCreateDeviceMatchingDictionary(0x07, 0xE1);
CFMutableDictionaryRef lalt =
    myCreateDeviceMatchingDictionary(0x07, 0xE2);
CFMutableDictionaryRef lsuper =
    myCreateDeviceMatchingDictionary(0x07, 0xE3);
CFMutableDictionaryRef rctrl =
    myCreateDeviceMatchingDictionary(0x07, 0xE4);
CFMutableDictionaryRef rshift =
    myCreateDeviceMatchingDictionary(0x07, 0xE5);
CFMutableDictionaryRef ralt =
    myCreateDeviceMatchingDictionary(0x07, 0xE6);
CFMutableDictionaryRef rsuper =
    myCreateDeviceMatchingDictionary(0x07, 0xE7);

CFMutableDictionaryRef matchesList[] = {
    capsLock,
    lctrl,
    lshift,
    lalt,
    lsuper,
    rctrl,
    rshift,
    ralt,
    rsuper
};
CFArrayRef matches = CFArrayCreate(kCFAllocatorDefault,
        (const void **)matchesList, 9, NULL);
IOHIDManagerSetDeviceMatchingMultiple(hidManager, matches);

IOHIDManagerRegisterInputValueCallback(hidManager,
        myHandleModifiersCallback, NULL);

IOHIDManagerScheduleWithRunLoop(hidManager, CFRunLoopGetMain(),
        kCFRunLoopDefaultMode);

IOHIDManagerOpen(hidManager, kIOHIDOptionsTypeNone);

However, the callback is never being run. Am I missing anything?

I don't fully understand HID usage pages, so I didn't know whether or not to use Generic Desktop Page (0x01) with the keyboard usage ID (06) or the Keyboard/Keypad Page (0x07) with Usage IDs for the individual keys. Maybe that has something to do with it?

Allurement

Answer 1

I figured it out. The way to do it is to use the Generic Desktop Page (0x01) Keyboard (06) (and Keypad (07) for completeness) for use with IOHIDManagerSetDeviceMatchingMultiple, and then the input value callback gets Keyboard/Keypad Usage Page (0x07) stuff.

For example, to setup a an HIDManager for all keyboards/keypads, one could do something like:

IOHIDManagerRef hidManager = IOHIDManagerCreate(kCFAllocatorDefault,
        kIOHIDOptionsTypeNone);

CFMutableDictionaryRef keyboard =
    myCreateDeviceMatchingDictionary(0x01, 6);
CFMutableDictionaryRef keypad =
    myCreateDeviceMatchingDictionary(0x01, 7);

CFMutableDictionaryRef matchesList[] = {
    keyboard,
    keypad,
};
CFArrayRef matches = CFArrayCreate(kCFAllocatorDefault,
        (const void **)matchesList, 2, NULL);
IOHIDManagerSetDeviceMatchingMultiple(hidManager, matches);

IOHIDManagerRegisterInputValueCallback(hidManager,
        myHIDKeyboardCallback, NULL);

IOHIDManagerScheduleWithRunLoop(hidManager, CFRunLoopGetMain(),
        kCFRunLoopDefaultMode);

IOHIDManagerOpen(hidManager, kIOHIDOptionsTypeNone);

Where myCreateDeviceMatchingDictionary is something like:

CFMutableDictionaryRef myCreateDeviceMatchingDictionary(UInt32 usagePage,
        UInt32 usage) {
    CFMutableDictionaryRef ret = CFDictionaryCreateMutable(kCFAllocatorDefault,
            0, &kCFTypeDictionaryKeyCallBacks,
            &kCFTypeDictionaryValueCallBacks);
    if (!ret)
        return NULL;

    CFNumberRef pageNumberRef = CFNumberCreate(kCFAllocatorDefault,
            kCFNumberIntType, &usagePage );
    if (!pageNumberRef) {
        CFRelease(ret);
        return NULL;
    }

    CFDictionarySetValue(ret, CFSTR(kIOHIDDeviceUsagePageKey), pageNumberRef);
    CFRelease(pageNumberRef);

    CFNumberRef usageNumberRef = CFNumberCreate(kCFAllocatorDefault,
            kCFNumberIntType, &usage);
    if (!usageNumberRef) {
        CFRelease(ret);
        return NULL;
    }

    CFDictionarySetValue(ret, CFSTR(kIOHIDDeviceUsageKey), usageNumberRef);
    CFRelease(usageNumberRef);

    return ret;
}

And myHIDKeyboardCallback is something like:

void myHIDKeyboardCallback(void *context, IOReturn result, void *sender,
        IOHIDValueRef value) {
    IOHIDElementRef elem = IOHIDValueGetElement(value);
    if (IOHIDElementGetUsagePage(elem) != 0x07)
        return;
    uint32_t scancode = IOHIDElementGetUsage(elem);
    if (scancode < 4 || scancode > 231)
        return;
    long pressed = IOHIDValueGetIntegerValue(value);
    // ... Do something ...
}

Note that the callback seems to be called multiple times per press or release but with usage IDs outside the normal range, which is what the "if (scancode < 4 || scancode > 231)" is for.

Allurement

Where did you find information on how to parse the value in your callback, to get stuff like the scancode? Do you have some (readable) reference on that, or how did you figure it out? – Wholesale

Answer 2

thx for providing the answer to your question.

instead of the if-statement in myHIDKeyboardCallback, which checks scancode<4 or scancode>231 you could use IOHIDManagerSetInputValueMatching.

// before IOHIDManagerOpen
int usageMin = 4;
CFNumberRef minNumberRef = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &usageMin);
CFDictionarySetValue(inputValueFilter, CFSTR(kIOHIDElementUsageMinKey), minNumberRef);
CFRelease(minNumberRef);

int usageMax = 231;
CFNumberRef maxNumberRef = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &usageMax);
CFDictionarySetValue(inputValueFilter, CFSTR(kIOHIDElementUsageMaxKey), maxNumberRef);
CFRelease(maxNumberRef);

IOHIDManagerSetInputValueMatching(hidManager, inputValueFilter);

it is more LOC then a simple if-statement, but you end up with a cleaner callback.

Bilestone

Good to know. I imagine you can also restrict element usage pages to 0x07 with kIOHIDElementUsagePageKey. Is this necessary, though? Do keyboard/keypad devices ever generate non-0x07 elements? I imagine it's possible if, say, you have an external keyboard with trackpad or joystick built-in or something. – Allurement

i have never used a keyboard like this (i.e. with a joystick or similar build in), but i would expect the second device and the keyboard to have their events being separated. but i can't tell for sure. – Bilestone

Do you have any good sources on how to use the IOHID API? (I'm mainly interested in reading mouse/keyboard input.) It's fairly simple to create the IOHIDManager and find matching devices and so on just by following Apple's documentation, but how to parse the data sent to your callbacks is much less clear. It sounds like you have some experience with the API, so do you know of any good references for figuring this stuff out? – Wholesale