+ (HIDRemote *)sharedHIDRemote
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.
The HIDRemote instance globally shared in your application. You should not -release the returned object.
+ (BOOL)isCandelairInstalled
Determine whether the Candelair driver version 1.7.0 or later is installed.
YES, if it is installed. NO, if it isn't.
+ (BOOL)isCandelairInstallationRequiredForRemoteMode:(HIDRemoteMode)hidRemoteMode
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.
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.
- (HIDRemoteAluminumRemoteSupportLevel)aluminiumRemoteSystemSupportLevel
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.
kHIDRemoteAluminumRemoteSupportLevelNonekHIDRemoteButtonCodeCenter and kHIDRemoteButtonCodePlay button events. Instead, you'll receive kHIDRemoteButtonCodeCenter events for both buttons.kHIDRemoteAluminumRemoteSupportLevelEmulationkHIDRemoteAluminumRemoteSupportLevelNativekHIDRemoteButtonCodeCenter and kHIDRemoteButtonCodePlay button events for the center and play button respectively, when an Aluminum Remote is used.- (BOOL)startRemoteControl:(HIDRemoteMode)hidRemoteMode
Starts the HIDRemote in the respective mode kHIDRemoteModeShared, kHIDRemoteModeExclusive or kHIDRemoteModeExclusiveAuto.
HIDRemote can be started in several modes that behave differently:
kHIDRemoteModeSharedkHIDRemoteModeExclusivekHIDRemoteModeExclusiveAuto (RECOMMENDED)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 .. } } }
- (void)stopRemoteControl
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.
- (BOOL)isStarted
Determine, whether the HIDRemote has been started with -startRemoteControl:.
YES, if it was started. NO, if it was not.
- (unsigned)activeRemoteControlCount
Determine the number of remote controls/receivers HIDRemote has currently opened in the mode supplied to -startRemoteControl:
The number of remote controls/receivers HIDRemote has currently opened. Zero if none could be found or opened.
- (SInt32)lastSeenRemoteControlID
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.
The ID of the last seen remote. Returns -1, if the ID is unknown.
- (void)setLastSeenModel:(HIDRemoteModel)aModel
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.
- (HIDRemoteModel)lastSeenModel
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.
kHIDRemoteModelUndeterminedkHIDRemoteModelWhitePlastickHIDRemoteModelAluminum- (void)setDelegate:(NSObject <HIDRemoteDelegate> *)newDelegate
Set a new delegate object. This object has to conform to the HIDRemoteDelegate protocol.
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.
- (NSObject <HIDRemoteDelegate> *)delegate
Get the current delegate object.
The current delegate object.
- (void)setSimulateHoldEvents:(BOOL)newSimulateHoldEvents
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.
- (BOOL)simulateHoldEvents
Determine whether the simulation of hold events for the + and - buttons is currently active.
YES or NO depending on whether the simulation is currently active.
- (void)setUnusedButtonCodes:(NSArray *)newArrayWithUnusedButtonCodesAsNSNumbers
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.
- (NSArray *)unusedButtonCodes
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:
An array of NSNumbers with HIDRemoteButtonCodes your application does not use.
- (void)setEnableSecureEventInputWorkaround:(BOOL)newEnableSecureEventInputWorkaround
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.
- (BOOL)enableSecureEventInputWorkaround
Determine whether aforementioned workaround is active.
YES or NO.
- (void)setExclusiveLockLendingEnabled:(BOOL)newExclusiveLockLendingEnabled
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.
-(BOOL)exclusiveLockLendingEnabled
Returns the status of the Exclusive Lock Lending feature for this instance of HIDRemote.
YES or NO.
- (void)hidRemote:(HIDRemote *)hidRemote eventWithButton:(HIDRemoteButtonCode)buttonCode isPressed:(BOOL)isPressed fromHardwareWithAttributes:(NSMutableDictionary *)attributes
Notification about button events. You receive one press and one release event per button press.
- (void)hidRemote:(HIDRemote *)hidRemote remoteIDChangedOldID:(SInt32)oldID newID:(SInt32)newID forHardwareWithAttributes:(NSMutableDictionary *)attributes
Invoked when the the ID of the sending remote has changed.
- (void)hidRemote:(HIDRemote *)hidRemote foundNewHardwareWithAttributes:(NSMutableDictionary *)attributes
Invoked when a new device was found and added to HIDRemote's pool.
- (void)hidRemote:(HIDRemote *)hidRemote failedNewHardwareWithError:(NSError *)error
Invoked when initialization of a newly found device in the mode specified in the -startRemoteControl: call failed
- (void)hidRemote:(HIDRemote *)hidRemote releasedHardwareWithAttributes:(NSMutableDictionary *)attributes
Invoked when a device was removed from HIDRemote's pool.
- (BOOL)hidRemote:(HIDRemote *)hidRemote inspectNewHardwareWithService:(io_service_t)service prematchResult:(BOOL)prematchResult
Return YES, if HIDRemote should add this device to its pool. Return NO, if HIDRemote should not use this device.
- (BOOL)hidRemote:(HIDRemote *)hidRemote lendExclusiveLockToApplicationWithInfo:(NSDictionary *)applicationInfo
Invoked when another application would like to lend your exclusive lock.
kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).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.
- (void)hidRemote:(HIDRemote *)hidRemote exclusiveLockReleasedByApplicationWithInfo:(NSDictionary *)applicationInfo
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.
kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).- (BOOL)hidRemote:(HIDRemote *)hidRemote shouldRetryExclusiveLockWithInfo:(NSDictionary *)applicationInfo
Invoked, when your instance of HIDRemote was informed by another application that an exclusive lock on additional devices may now be possible.
kHIDRemoteDNStatusPIDKey (the application's PID) and kCFBundleIdentifierKey (the application's bundle identifier).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.