NAPlatformDelegate Protocol Reference
Declared in | NAPlatform.h |
Overview
NAPlatformDelegate is the delegate protocol for the NewAer Proximity Platform. All delegate calls are dispatched asynchronously on a private queue that may not be on the main thread. Teke care when updating UI elements based on delegate calls.
Tasks
-
– registrationFailed:
Called when an event associated with application registration occurs.
required method -
– platformScanFailed:status:
Called when a scan cannot be started
required method -
– platformAdvertiseFailed:
Called when advertising cannot be started
required method -
– platformInitComplete
Called when the platform has completed initialization. Waiting for this delegate to fire ensures that all initialization is complete. You can safely call scan and advertise functions after this delegate fires.
required method -
– platformDidChangeSupportedType:status:
Called when a device scanner changes it’s status. This could be triggered by the user disabling a radio or turning on airplane mode.
required method -
– platformDidFindDevice:
Called when NAPlatform discovers a new device.
-
– platformDidLoseDevice:
Called when NAPlatform loses contact with a previously discovered device.
-
– platformDidUpdateDevice:
Called when NAPlatform updates the status of a previously discovered device. This could include updates to device health, signal strength, name or when it was last seen.
-
– platformDidReceiveMessage:from:
Called when NAPlatform receives a message from another device. You will only be able to receive a message from another device if you have enabled advertising. Not all device types can receive messages.
-
– platformDidSendMessageToDevice:withStatus:
Called when NAPlatform is finished sending a message to another device.
-
– platformDidRequestDeviceInfoFrom:
Called when NAPlatform needs user information to send to a remote peer. If this delegate is not implemented, nothing will be returned to the peer in the user info area. User info is restricted to 255 bytes of data.
-
– platformDidStartScan:
Called when a scan has successfully started for a scan type. This is called once for each device type in response to a startScanWithDeviceTypes call.
-
– platformDidStopScan:
Called when a scan has successfully stopped for a device type. This is called once for each device type in response to a stopScanWithDeviceTypes call.
-
– platformDidCompleteOneScan:
Called when one scan cycle has completed for a device type. Some device types do not return results immediately. This delegate is called after all didFindDevice delegates have been called.
-
– platformDidStartAdvertise:
Called when advertising has successfully started for a device type. This is called once for each device type in response to a startAdvertisingWithDeviceTypes call.
-
– platformDidStopAdvertise:
Called when advertising has successfully stopped for a device type. This is called once for each device type in response to a stopAdvertisingWithDeviceTypes call.
-
– platformDidWake:
Called when the platform awakens while the app is in the background. This may happen because a new device has come into range or because of other internal reasons. You may also receive platformDidFind or platformDidUpdate events if a scanner is currently running.
-
– platformWillSleep
Called when the platform is about to go back to sleep after it has been awoken. When you receive this call, you have less than one second to clean up (or request your own background time) before the platform’s background time expires.
Instance Methods
platformAdvertiseFailed:
Called when advertising cannot be started
- (void)platformAdvertiseFailed:(NADeviceType)type
Parameters
- type
The device type that advertising failed for.
Discussion
This delegate may be called any time after the advertising has started, such as when the user turns off a radio or puts their device in airplane mode.
The types of failures that can occur during advertising are enumerated in NADeviceTypeStatus.
Declared In
NAPlatform.h
platformDidChangeSupportedType:status:
Called when a device scanner changes it’s status. This could be triggered by the user disabling a radio or turning on airplane mode.
- (void)platformDidChangeSupportedType:(NADeviceType)type status:(NADeviceTypeStatus)status
Parameters
- type
The device type that changed it’s status
- status
The new status of that device type: enabled, powered off, not authorized, etc
Declared In
NAPlatform.h
platformDidCompleteOneScan:
Called when one scan cycle has completed for a device type. Some device types do not return results immediately. This delegate is called after all didFindDevice delegates have been called.
- (void)platformDidCompleteOneScan:(NADeviceType)type
Parameters
- type
The device type that scanning stopped for.
Declared In
NAPlatform.h
platformDidFindDevice:
Called when NAPlatform discovers a new device.
- (void)platformDidFindDevice:(NADevice *)device
Parameters
- device
The NADevice reference that was found
Declared In
NAPlatform.h
platformDidLoseDevice:
Called when NAPlatform loses contact with a previously discovered device.
- (void)platformDidLoseDevice:(NADevice *)device
Parameters
- device
The NADevice reference that was lost
Declared In
NAPlatform.h
platformDidReceiveMessage:from:
Called when NAPlatform receives a message from another device. You will only be able to receive a message from another device if you have enabled advertising. Not all device types can receive messages.
- (void)platformDidReceiveMessage:(NAMessage *)message from:(NADevice *)device
Parameters
- message
The message that was received by this NADevice
- device
Which device sent the message
Declared In
NAPlatform.h
platformDidRequestDeviceInfoFrom:
Called when NAPlatform needs user information to send to a remote peer. If this delegate is not implemented, nothing will be returned to the peer in the user info area. User info is restricted to 255 bytes of data.
- (NSData *)platformDidRequestDeviceInfoFrom:(NSString *)deviceId
Parameters
- deviceId
The deviceId that is requesting info: a full device object is not available at this point
Return Value
The NSData blob that holds the desired user info.
Declared In
NAPlatform.h
platformDidSendMessageToDevice:withStatus:
Called when NAPlatform is finished sending a message to another device.
- (void)platformDidSendMessageToDevice:(NADevice *)device withStatus:(NAMessageStatus)status
Parameters
- device
The device that the message was sent to
- status
The status of the message sent to the other device: success, fail, other.
Declared In
NAPlatform.h
platformDidStartAdvertise:
Called when advertising has successfully started for a device type. This is called once for each device type in response to a startAdvertisingWithDeviceTypes call.
- (void)platformDidStartAdvertise:(NADeviceType)type
Parameters
- type
The device type that advertising started for.
Declared In
NAPlatform.h
platformDidStartScan:
Called when a scan has successfully started for a scan type. This is called once for each device type in response to a startScanWithDeviceTypes call.
- (void)platformDidStartScan:(NADeviceType)type
Parameters
- type
The scan type that scanning started for.
Declared In
NAPlatform.h
platformDidStopAdvertise:
Called when advertising has successfully stopped for a device type. This is called once for each device type in response to a stopAdvertisingWithDeviceTypes call.
- (void)platformDidStopAdvertise:(NADeviceType)type
Parameters
- type
The device type that advertising stopped for.
Declared In
NAPlatform.h
platformDidStopScan:
Called when a scan has successfully stopped for a device type. This is called once for each device type in response to a stopScanWithDeviceTypes call.
- (void)platformDidStopScan:(NADeviceType)type
Parameters
- type
The device type that scanning stopped for.
Declared In
NAPlatform.h
platformDidUpdateDevice:
Called when NAPlatform updates the status of a previously discovered device. This could include updates to device health, signal strength, name or when it was last seen.
- (void)platformDidUpdateDevice:(NADevice *)device
Parameters
- device
The NADevice reference whose health was changed
Declared In
NAPlatform.h
platformDidWake:
Called when the platform awakens while the app is in the background. This may happen because a new device has come into range or because of other internal reasons. You may also receive platformDidFind or platformDidUpdate events if a scanner is currently running.
- (void)platformDidWake:(int)timeRemaining
Parameters
- timeRemaining
An approximate number of seconds before the app will return to sleep. You can safely perform additional processing as long as you finish it before this amount of time.
Discussion
If you wish to enable background scanning while the device is locked you will also need to use this delegate to present a local notification and power on the screen. This ensures that iOS enables the Bluetooth framework to find devices. You can present a notification on platformDidWake and remove the notification on platformWillSleep. You will only want to present a notification when the device is locked to avoid bothering the user when they are using another application and the device is unlocked. See the example application setupLockScreenNotifications() function for an example of how to detect this.
Declared In
NAPlatform.h
platformInitComplete
Called when the platform has completed initialization. Waiting for this delegate to fire ensures that all initialization is complete. You can safely call scan and advertise functions after this delegate fires.
- (void)platformInitComplete
Declared In
NAPlatform.h
platformScanFailed:status:
Called when a scan cannot be started
- (void)platformScanFailed:(NADeviceType)type status:(NADeviceTypeStatus)status
Parameters
- type
The scan type that scanning failed for.
- status
Why the scan failed.
Discussion
This delegate may be called any time after the scan is started, such as when the user turns off a radio or puts their device in airplane mode.
Declared In
NAPlatform.h
platformWillSleep
Called when the platform is about to go back to sleep after it has been awoken. When you receive this call, you have less than one second to clean up (or request your own background time) before the platform’s background time expires.
- (void)platformWillSleep
Declared In
NAPlatform.h
registrationFailed:
Called when an event associated with application registration occurs.
- (void)registrationFailed:(NARegistrationFailureType)error
Parameters
- error
The error that caused registration to fail.
Discussion
This delegate may be called any time after the platform is initialized if there is an error. Due to network connectivity, it may not be immediate.
The types of failures that can occur during application registration are:
typedef enum
{
NAPLATFORM_DEVELOPER_KEY_INVALID = 0, // Developer key is invalid for SDK version and bundle ID
NAPLATFORM_INTERNET_UNAVAILABLE = 1, // Internet connectivity has been unavailable and developer key check cannot complete
NAPLATFORM_SDK_VERSION_UPGRADE_REQUIRED = 2, // This SDK version is obsolete and must be updated
NAPLATFORM_FRIEND_KEY_INVALID = 3, // One of the friend application IDs that was specified is invalid or not authorized
} NARegistrationFailureType;
Declared In
NAPlatform.h