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