Class Reference

Shared Instance

• + sharedHIDRemote

Compatibility Information

• + isCandelairInstalled
• + isCandelairInstallationRequiredForRemoteMode:
• - aluminiumRemoteSystemSupportLevel

Starting and stopping

• - startRemoteControl:
• - stopRemoteControl

Status information

• - isStarted
• - activeRemoteControlCount
• - lastSeenModel
• - setLastSeenModel
• - lastSeenRemoteControlID

Delegate

• - setDelegate:
• - delegate

Event control

• - setSimulateHoldEvents:
• - simulateHoldEvents
• - setUnusedButtonCodes:
• - unusedButtonCodes

Compatibility control (expert APIs)

• - setEnableSecureEventInputWorkaround:
• - enableSecureEventInputWorkaround
• - setExclusiveLockLendingEnabled:
• - exclusiveLockLendingEnabled

Delegate Reference

Event handling

• - hidRemote:eventWithButton:isPressed:fromHardwareWithAttributes:

Notification of remote ID changes

• - hidRemote:remoteIDChangedOldID:newID:forHardwareWithAttributes: (optional)

Notification of device additions/removals

• - hidRemote:foundNewHardwareWithAttributes: (optional)
• - hidRemote:failedNewHardwareWithError: (optional)
• - hidRemote:releasedHardwareWithAttributes: (optional)

Device matching control

• - hidRemote:inspectNewHardwareWithService:prematchResult: (optional)

Exclusive Lock Lending

• - hidRemote:lendExclusiveLockToApplicationWithInfo: (optional)
• - hidRemote:exclusiveLockReleasedByApplicationWithInfo: (optional)
• - hidRemote:shouldRetryExclusiveLockWithInfo: (optional)

Class methods

sharedHIDRemote

+ (HIDRemote *)sharedHIDRemote

Description

Instead of allocating and initializing the instance yourself, you can make use of the +sharedHIDRemote singleton. Please note that using the +sharedHIDRemote method doesn't hinder you from creating additional instances using alloc and init. Please make sure you only use one of the two approaches in your code.

Return value

The HIDRemote instance globally shared in your application. You should not -release the returned object.

isCandelairInstalled

+ (BOOL)isCandelairInstalled

Description

Determine whether the Candelair driver version 1.7.0 or later is installed.

Return value

YES, if it is installed. NO, if it isn't.

isCandelairInstallationRequiredForRemoteMode:

+ (BOOL)isCandelairInstallationRequiredForRemoteMode:(HIDRemoteMode)hidRemoteMode

Description

Determine whether the user needs to install the Candelair driver in order for your application to get access to the IR Receiver in a specific mode.

Right now, the Candelair driver only needs to be installed under OS 10.6 and 10.6.1 when accessing the IR Receiver in an exclusive mode.

Parameters

hidRemoteMode

The mode you'd like to start your instance of HIDRemote in lateron. Please see startRemoteControl for a description of the possible values.

Return value

YES, if the user runs your application on an operating system version that makes the installation of the Candelair driver necessary for your application to get access to the IR Receiver in the specified mode.

NO, if the operating system version in use either doesn't make the installation of the Candelair driver a necessity - or - if it is already installed.

Instance methods

aluminiumRemoteSystemSupportLevel

- (HIDRemoteAluminumRemoteSupportLevel)aluminiumRemoteSystemSupportLevel

Description

Determine the level of support for the aluminum remote on the current system. Don't use this method to determine whether or not an aluminum remote is being used. Instead, use -lastSeenModel for this purpose.

Return value

kHIDRemoteAluminumRemoteSupportLevelNone

This system has no support for the Aluminum Remote at all. Note that, when an aluminum remote is used, you'll still get button press events, but you won't get separate kHIDRemoteButtonCodeCenter and kHIDRemoteButtonCodePlay button events. Instead, you'll receive kHIDRemoteButtonCodeCenter events for both buttons.

kHIDRemoteAluminumRemoteSupportLevelEmulation

This system possibly has support for the Aluminum Remote (via emulation).

kHIDRemoteAluminumRemoteSupportLevelNative

This system has native support for the Aluminum Remote. Your application will receive separate kHIDRemoteButtonCodeCenter and kHIDRemoteButtonCodePlay button events for the center and play button respectively, when an Aluminum Remote is used.

startRemoteControl:

- (BOOL)startRemoteControl:(HIDRemoteMode)hidRemoteMode

Description

Starts the HIDRemote in the respective mode kHIDRemoteModeShared, kHIDRemoteModeExclusive or kHIDRemoteModeExclusiveAuto.

Parameters

hidRemoteMode

HIDRemote can be started in several modes that behave differently:

kHIDRemoteModeShared

Share the remote/receiver device(s) with others. Button press events will be received by your application and all other applications that acquired a shared lock on the same devices for as long as there is no exclusive lock on them.

kHIDRemoteModeExclusive

Try to acquire an exclusive lock on the remote/receiver device(s). If successful, this makes it impossible for other applications to also acquire an exclusive lock. You therefore should only use this mode if you really need to. If you really need to, please consider turning on Exclusive Lock Lending.

kHIDRemoteModeExclusiveAuto (RECOMMENDED)

Try to acquire an exclusive lock on the remote/receiver device(s) whenever your application has focus. Temporarily release control over the remote when another application has focus. Using this mode ensures best compatibility with other applications.

Return value

YES, if setup was successful. NO, if an error occured during setup. Note that a successful setup does not mean that you gained the respective level of access or that remote control hardware was actually found. This is only the case if -activeRemoteControlCount returns a value greater zero. I.e. your setup code could look like this:

if ((hidRemoteControl = [HIDRemoteControl sharedHIDRemote]) != nil) { [hidRemoteControl setDelegate:myDelegate]; if ([HIDRemote isCandelairInstallationRequiredForRemoteMode:kHIDRemoteModeExclusiveAuto]) { NSLog(@"Installation of Candelair required."); // See DemoController.m for a reusable code snippet presenting an // alert and offering to open related URLs } else { if ([hidRemoteControl startRemoteControl:kHIDRemoteModeExclusiveAuto]) { NSLog(@"HIDRemote has started successfully."); if ([hidRemoteControl activeRemoteControlCount]) { NSLog(@"HIDRemote has found %d remotes.", [hidRemoteControl activeRemoteControlCount]); } else { NSLog(@"HIDRemote has not found any remotes it could use. Will use remotes as they become available."); } } else { // .. Setup failed .. } } }

stopRemoteControl

- (void)stopRemoteControl

Description

Stops the HIDRemote. You will no longer get remote control and button events after this. If your application did have exclusive access prior to calling this function, other applications can now gain access again.

isStarted

- (BOOL)isStarted

Description

Determine, whether the HIDRemote has been started with -startRemoteControl:.

Return value

YES, if it was started. NO, if it was not.

activeRemoteControlCount

- (unsigned)activeRemoteControlCount

Description

Determine the number of remote controls/receivers HIDRemote has currently opened in the mode supplied to -startRemoteControl:

Return value

The number of remote controls/receivers HIDRemote has currently opened. Zero if none could be found or opened.

lastSeenRemoteControlID

- (SInt32)lastSeenRemoteControlID

Description

Returns the ID of the remote from which the last button press was received. You can sign up your delegate for ID change notifications by implementing the (optional) -hidRemote:remoteIDChangedOldID:newID:forHardwareWithAttributes: selector.

Return value

The ID of the last seen remote. Returns -1, if the ID is unknown.

setLastSeenModel

- (void)setLastSeenModel:(HIDRemoteModel)aModel

Description

Manually sets the value for the last seen remote model. Please note that this value is reset to kHIDRemoteModelUndetermined when the user uses another remote/the ID of the remote changes. The remote model is usually auto-detected as soon as a short press of the Center or Play button occurs.

lastSeenModel

- (HIDRemoteModel)lastSeenModel

Description

Returns, from which remote control model the last button press originated.

If your application needs to know whether its controlled with the six buttons of a white plastic remote or the seven buttons of an aluminum remote, request your user to press the button labeled with >|| on their remote. Then, when you receive the next button event with button code kHIDRemoteButtonCodeCenter or kHIDRemoteButtonCodePlay, call -lastSeenModel. If it returns kHIDRemoteModelUndetermined or kHIDRemoteModelWhitePlastic, assume a white plastic remote. If it returns kHIDRemoteModelAluminum, assume an aluminum remote.

Return value

kHIDRemoteModelUndetermined

The model couldn't be determined yet.

kHIDRemoteModelWhitePlastic

The model is most likely a white plastic remote.

kHIDRemoteModelAluminum

The model is an aluminum remote.

setDelegate:

- (void)setDelegate:(NSObject <HIDRemoteDelegate> *)newDelegate

Description

Set a new delegate object. This object has to conform to the HIDRemoteDelegate protocol.

Parameters

newDelegate

The object conforming to the HIDRemoteDelegate protocol that you want to use as a delegate. The delegate only needs to implement the hidRemote:eventWithButton:isPressed:fromHardwareWithAttributes: selector. All other selectors are optional.

IMPORTANT: The delegate is not retained. Make sure you execute a -[hidRemoteInstance setDelegate:nil] in the -dealloc method of your delegate.

delegate

- (NSObject <HIDRemoteDelegate> *)delegate

Description

Get the current delegate object.

Return value

The current delegate object.

setSimulateHoldEvents

- (void)setSimulateHoldEvents:(BOOL)newSimulateHoldEvents

Description

Set whether hold events should be simulated for the + and - buttons. The simulation is active by default. This value should only be changed when no button is currently pressed (f.ex. before calling -startRemoteControl:). The behaviour is undefined if a button press is currently in progress.

Parameters

newSimulateHoldEvents

YES to enable hold event simulation. NO to disable hold event emulation.

simulateHoldEvents

- (BOOL)simulateHoldEvents

Description

Determine whether the simulation of hold events for the + and - buttons is currently active.

Return value

YES or NO depending on whether the simulation is currently active.

setUnusedButtonCodes:

- (void)setUnusedButtonCodes:(NSArray *)newArrayWithUnusedButtonCodesAsNSNumbers

Description

Set an array of NSNumbers with HIDRemoteButtonCodes that are not used by your application. This is empty by default. By providing this information, you improve interoperation with popular remote control solutions such as Remote Buddy. If, for example, you don't use the MenuHold button code, you'd express it like this in your sourcecode:

if (hidRemote = [HIDRemote sharedHIDRemote]) { // .. [hidRemote setUnusedButtonCodes:[NSArray arrayWithObjects:[NSNumber numberWithInt:(int)kHIDRemoteButtonCodeMenuHold], nil]]; // .. }

Advanced remote control solutions such as Remote Buddy do then know that you're not using the MenuHold button code and can automatically create a mapping table for your application, with all buttons presses except MenuHold being forwarded to your application. For MenuHold, Remote Buddy might map an action to open its own menu.

Parameters

newArrayWithUnusedButtonCodesAsNSNumbers

Array containing HIDRemoteButtonCodes (as NSNumbers) that are not used by your application.

unusedButtonCodes

- (NSArray *)unusedButtonCodes

Description

Returns an array of NSNumbers with HIDRemoteButtonCodes your application does not use. This area needs to previously be set using -setUnusedButtonCodes:. For more information, see the description for -setUnusedButtonCodes:

Return value

An array of NSNumbers with HIDRemoteButtonCodes your application does not use.

setEnableSecureEventInputWorkaround:

- (void)setEnableSecureEventInputWorkaround:(BOOL)newEnableSecureEventInputWorkaround

Description

Enables/disables a workaround to a locking issue introduced with Security Update 2008-004 / 10.4.9 and beyond. Essentially, without this workaround enabled, using an application that uses a password textfield would degrade exclusive locks to shared locks with the result being that both normal OS X as well as your application would react to the same HID event when really only your application should. Credit for finding this workaround goes to Martin Kahr.

Enabled by default.

Parameters

newEnableSecureEventInputWorkaround

YES to enable the workaround. NO to disable the workaround.

enableSecureEventInputWorkaround

- (BOOL)enableSecureEventInputWorkaround

Description

Determine whether aforementioned workaround is active.

Return value

YES or NO.

setExclusiveLockLendingEnabled:

- (void)setExclusiveLockLendingEnabled:(BOOL)newExclusiveLockLendingEnabled

Description

Enables/disables lending of the exclusive lock to other applications when in kHIDRemoteModeExclusive mode.

Enable this option only when you are writing a background application that keeps a permanent, exclusive lock on the IR receiver.

When this option is enabled and another application using the HIDRemote class indicates that it'd like to get exclusive access to the IR receiver itself while your application is having it, your application's instance of HIDRemote automatically stops and signals the other application that it can now get exclusive access. When the other application's HIDRemote instance no longer uses the IR receiver exclusively, it lets your application know so that it can recover its exclusive lock.

This option is disabled by default. Unless you have special needs, you really should use the kHIDRemoteModeExclusiveAuto mode for best compatibility with other applications.

Parameters

newExclusiveLockLendingEnabled

YES to enable exclusive lock lending. NO to disable it.

exclusiveLockLendingEnabled

-(BOOL)exclusiveLockLendingEnabled

Description

Returns the status of the Exclusive Lock Lending feature for this instance of HIDRemote.

Return value

YES or NO.

Delegate methods

hidRemote:eventWithButton:isPressed:fromHardwareWithAttributes:

- (void)hidRemote:(HIDRemote *)hidRemote eventWithButton:(HIDRemoteButtonCode)buttonCode isPressed:(BOOL)isPressed fromHardwareWithAttributes:(NSMutableDictionary *)attributes

Description

Notification about button events. You receive one press and one release event per button press.

Parameters

hidRemote

The HIDRemote instance sending this message.

buttonCode

The HIDRemoteButtonCode of the button that was pressed

isPressed

YES, if the button was pressed, NO, if the button was released

attributes

Dictionary with more information about the device by which the button event was received.

hidRemote:remoteIDChangedOldID:newID:forHardwareWithAttributes:

- (void)hidRemote:(HIDRemote *)hidRemote remoteIDChangedOldID:(SInt32)oldID newID:(SInt32)newID forHardwareWithAttributes:(NSMutableDictionary *)attributes
(optional)

Description

Invoked when the the ID of the sending remote has changed.

Parameters

hidRemote

The HIDRemote instance sending this message.

oldID

The ID of the remote previous signals came from. -1 if the ID of the previously used remote is unknown.

newID

The ID of the remote used now.

attributes

Dictionary with more information about the device whose remote ID changed.

hidRemote:foundNewHardwareWithAttributes:

- (void)hidRemote:(HIDRemote *)hidRemote foundNewHardwareWithAttributes:(NSMutableDictionary *)attributes
(optional)

Description

Invoked when a new device was found and added to HIDRemote's pool.

Parameters

hidRemote

The HIDRemote instance sending this message.

attributes

Dictionary with more information about the device.

hidRemote:failedNewHardwareWithError:

- (void)hidRemote:(HIDRemote *)hidRemote failedNewHardwareWithError:(NSError *)error
(optional)

Description

Invoked when initialization of a newly found device in the mode specified in the -startRemoteControl: call failed

Parameters

hidRemote

The HIDRemote instance sending this message.

error

The IOKit error code - packaged as NSError.

hidRemote:releasedHardwareWithAttributes:

- (void)hidRemote:(HIDRemote *)hidRemote releasedHardwareWithAttributes:(NSMutableDictionary *)attributes
(optional)

Description

Invoked when a device was removed from HIDRemote's pool.

Parameters

hidRemote

The HIDRemote instance sending this message.

attributes

Dictionary with more information about the device.

hidRemote:inspectNewHardwareWithService:prematchResult:

- (BOOL)hidRemote:(HIDRemote *)hidRemote inspectNewHardwareWithService:(io_service_t)service prematchResult:(BOOL)prematchResult
(optional)

Description

Invoked when new hardware was found. Allows additional control over which IOKit devices should be used by this instance. Implement this delegate method only if you know PRECISELY what you are doing.

Parameters

hidRemote

The HIDRemote instance sending this message.

service

The found IOKit service to inspect.

prematchResult

YES, if HIDRemote would use this device, NO if it wouldn't use this device.

Return value

Return YES, if HIDRemote should add this device to its pool. Return NO, if HIDRemote should not use this device.

hidRemote:lendExclusiveLockToApplicationWithInfo:

- (BOOL)hidRemote:(HIDRemote *)hidRemote lendExclusiveLockToApplicationWithInfo:(NSDictionary *)applicationInfo
(optional)

Description

Invoked when another application would like to lend your exclusive lock.

Parameters

hidRemote

The HIDRemote instance sending this message.

applicationInfo

Information about the application that returns the lock it lent from you. Usually contains values for the keys kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).

Return value

Return YES, if you'd like to lend your exclusive lock for use by the application. Return NO, if you don't want to lend your exclusive lock to the other application. The default is YES.

hidRemote:exclusiveLockReleasedByApplicationWithInfo:

- (void)hidRemote:(HIDRemote *)hidRemote exclusiveLockReleasedByApplicationWithInfo:(NSDictionary *)applicationInfo
(optional)

Description

Invoked, when an application you previously lent your exclusive lock to, no longer needs it. If you implement this delegate method, you need to call [hidRemote startRemoteControl:kHIDRemoteModeExclusive]; yourself. If you don't implement this delegate method, HIDRemote will do this for you.

Parameters

hidRemote

The HIDRemote instance sending this message.

applicationInfo

Information about the application that returns the lock it lent from you. Usually contains values for the keys kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).

hidRemote:shouldRetryExclusiveLockWithInfo:

- (BOOL)hidRemote:(HIDRemote *)hidRemote shouldRetryExclusiveLockWithInfo:(NSDictionary *)applicationInfo
(optional)

Description

Invoked, when your instance of HIDRemote was informed by another application that an exclusive lock on additional devices may now be possible.

Parameters

hidRemote

The HIDRemote instance sending this message.

applicationInfo

Information about the application that informed your HIDRemote instance. Usually contains values for the keys kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).

Return value

YES, if you'd like HIDRemote to restart and retry to acquire exclusive locks on all devices it finds. NO, if you want to ignore the information. The default is YES.