Difference between revisions of "IOHIDFamily"

From iPhone Development Wiki
Jump to: navigation, search
m (Services)
(filled out missing media key decriptions)
Line 52: Line 52:
  
 
== Keyboard events ==
 
== Keyboard events ==
The iPhoneOS button events are in fact treated as "keyboard" events. The following shows how to identify them<ref>http://ftp.sunet.se/pub/os/OpenBSD/src/share/misc/usb_hid_usages</ref>:
+
The iPhoneOS button events are in fact treated as "keyboard" events. The following shows how to identify them<ref>http://ftp.sunet.se/pub/os/OpenBSD/src/share/misc/usb_hid_usages</ref> or <ref>http://www.usb.org/developers/devclass_docs/Hut1_11.pdf</ref>:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 71: Line 71:
 
| 12 || 0x40, 0x223 || Menu
 
| 12 || 0x40, 0x223 || Menu
 
|-
 
|-
| 12 || 0xb3, 0xb4, 0xb5, 0xe2 || ?
+
| 12 || 0xb3 || Fast forward
 +
|-
 +
| 12 || 0xb4 || Rewind
 +
|-
 +
| 12 || 0xb5 || Scan Next Track
 +
|-
 +
| 12 || 0xe2 || Mute
 
|-
 
|-
 
| 12 || 0xb8, 0x1ae || Media key (to toggle the soft keyboard)
 
| 12 || 0xb8, 0x1ae || Media key (to toggle the soft keyboard)

Revision as of 10:00, 23 December 2011

IOHIDFamily is a kernel extension that provides an abstract interface of with human interface devices (HID), e.g. the touchscreen, buttons, accelerometer, etc. In the user-land, there are 2 kinds of APIs associated to the IOHIDFamily: (1) the "public" ones, which are intended for HID driver writers; (2) the "private" ones, which are intended for event processing. This document will only outline the private APIs. References to the public one can be found in [1].

Class structure

Users of IOHID always first create an IOHIDEventSystem object that interfaces with the whole HID system. An event system consists of multiple IOHIDServices and IOHIDDisplays.

Services are various interfaces to the IOHIDLibPlugin kernel plugin (located at /System/Library/Extensions/IOHIDFamily.kext/PlugIns/IOHIDLib.plugin/IOHIDLib). They accept direct human input, and are the sources of all IOHIDEvents.

Displays are, obviously, the LCD screen. The IOHIDDisplay class can only control the brightness, not colors of individual pixels (Drawing is controlled by the VRAM). You only can control the displays indirectly by changing properties of the event system.

IOHID defines 20 types of events, of which the SpringBoard only handles 4 of them: keyboard (for buttons), digitizer (i.e. touchscreen), accelerometer and proximity events (temperature events are handled by IOKit directly). Each event may contain sub-events.

Example

#include <IOKit/hid/IOHIDEventSystem.h>
#include <stdio.h>

void handle_event (void* target, void* refcon, IOHIDServiceRef service, IOHIDEventRef event) {
  // handle the events here.
  printf("Received event of type %2d from service %p.\n", IOHIDEventGetType(event), service);
}

int main () {
  // Create and open an event system.
  IOHIDEventSystemRef system = IOHIDEventSystemCreate(NULL);
  IOHIDEventSystemOpen(system, handle_event, NULL, NULL, NULL);

  printf("HID Event system should now be running. Hit enter to quit any time.\n");
  getchar();

  IOHIDEventSystemClose(system, NULL);
  CFRelease(system);
  return 0;
}

Services

To access the services, you have to first match them using IOHIDEventSystemCopyMatchingServices. These criteria can be obtained using ioreg -l.

Service Name match CFBundleIdentifier PrimaryUsagePage PrimaryUsage
AppleLIS302DL (Accelerometer) accelerometer,lis302dl com.apple.driver.AppleEmbeddedAccelerometer 0xff00 3
AppleISL29003 (ALS) als,isl29003 com.apple.driver.AppleEmbeddedLightSensor 0xff00 4
AppleProxShim (ProximitySensor) als,ct700 com.apple.driver.AppleIntegratedProxALSSensor 0xff00 8
AppleM68Buttons (Buttons) buttons com.apple.driver.AppleM68Buttons 11 1
AppleMultitouchZ2SPI (Touchscreen) multi-touch,z2 com.apple.driver.AppleMultitouchSPI - -

Keyboard events

The iPhoneOS button events are in fact treated as "keyboard" events. The following shows how to identify them[1] or [2]:

Usage page Usage Button
1 0x83 Wake up (Calls -[SBUIController wakeUp:] in SpringBoard.)
7 - Hardware keyboard events
11 0x21 Headset button
11 0x23 Obsolete hold
11 0x2e Ringer
12 0x30 Lock
12 0x40, 0x223 Menu
12 0xb3 Fast forward
12 0xb4 Rewind
12 0xb5 Scan Next Track
12 0xe2 Mute
12 0xb8, 0x1ae Media key (to toggle the soft keyboard)
12 0xe9 Volume increase
12 0xea Volume decrease
0xff01 ≤0x20 Apple vender keyboard event
0xff07 1 Headset availability changed

References