Push Channel state.
More...Use these enumerations and constants in the application code for the BlackBerry Dynamics Push Channel event handler.
| enum GDPushChannelState |
Use these enumerated constants to check the state of a Push Channel. The state property always takes one of these values.
| GDPushChannelStateNone |
Initial state, before opening. |
| GDPushChannelStateOpen |
The Push Channel is open. The connect function has been called and a Push Channel token has been issued. A message could be received on the channel. |
| GDPushChannelStateClosed |
The Push Channel is closed. The channel could have been closed by the remote end, or the application could have called disconnect. |
| GDPushChannelStateError |
There is an error on the Push Channel. If the initial connect fails, the channel enters this state instead of the open state. A channel can also enter this state later, after entering the open state, if a permanent error occurs. If a Push Channel token had been issued, then it cannot be used any more. No (more) Push Channel messages will be received on this channel. |
| NSString* const GDPushChannelOpenedNotification |
After a call to connect by the application, an NSNotification with this name is posted when the Push Channel opens. The notification object will be the corresponding GDPushChannel instance. The notification will have a user information dictionary that contains the Push Channel token. Use GDPushChannelTokenKey as the key to access the token value.
The application code that handles the notification must initiate sending of the Push Channel token to the application server, out of band. The application server will then be able to use the token to address Push Channel messages back to the application, via the BlackBerry Dynamics proxy infrastructure. See the Push Channel Back-End API.
After receiving this notification, the application could receive any of the following for the same channel.
The value of this constant is suitable to use as the name parameter to an NSNotificationCenter addObserver call.
| NSString* const GDPushChannelClosedNotification |
An NSNotification with this name is posted when a Push Channel closes. The notification object will be the corresponding GDPushChannel instance. The notification will have a user information dictionary that contains the Push Channel token. Use GDPushChannelTokenKey as the key to access the token value.
The Push Channel could have been closed by the remote end, or the application could have called disconnect.
After receiving this notification:
If the notification wasn't expected, the application code that handles it could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The code could also initiate release of the Push Channel object. Alternatively, reconnection could be initiated, see connect.
Note that this notification is only sent for permanent Push Channel closure; not for transient losses of channel communication. For example, this notification wouldn't be sent in the case of an application on a mobile device that loses packet data coverage or otherwise cannot connect to the BlackBerry Dynamics proxy infrastructure. The status of the connection to the infrastructure can be monitored by using the GDReachability programming interface.
The value of this constant is suitable to use as the name parameter to an NSNotificationCenter addObserver call.
| NSString* const GDPushChannelErrorNotification |
An NSNotification with this name is posted when a permanent error occurs on a Push Channel. The notification object will be the GDPushChannel instance corresponding to the channel on which the error occurred. The notification will have a user information dictionary that contains an error code. Use GDPushChannelErrorKey as the key to access the error.
| Error code | Channel Error reason |
|---|---|
| 0 | Push is not currently connected. |
| 200-499 | Internal error. |
| 500-599 | Internal server error. |
Receiving this notification warns the application that the associated Push Channel token cannot be used any more, or that the channel could not be connected in the first place. Furthermore, no (more) Push Channel notifications will be received on this channel.
The application code that handles the notification could alert the user that Push Channel messages will not be received, or cause this to be displayed as an ongoing state. The code should also initiate reconnection, see connect, after checking that the Push Channel service is available. Service availability can be checked by using the GDReachability programming interface.
The value of this constant is suitable to use as the name parameter to an NSNotificationCenter addObserver call.
| NSString* const GDPushChannelMessageNotification |
An NSNotification with this name is posted when a Push Channel receives a message. The notification object will be the corresponding GDPushChannel instance. The notification will have a user information dictionary that contains the message "payload". Use GDPushChannelMessageKey as the key to access the message.
The Push Channel message will have been sent by an application server, using the Push Channel notify service. See the Push Channel Back-End API.
The service supports a "payload" of data to be included in the message. The data could be in any format chosen by the application developer. The payload could also be empty.
Note that a Push Channel message can be received at any time when the channel is open. This includes the interval between the request for disconnection (disconnect called) and channel disconnection being finalized (GDPushChannelClosedNotification received).
The application code that handles the notification could initiate the following actions, for example.
The value of this constant is suitable to use as the name parameter to an NSNotificationCenter addObserver call.
| NSString* const GDPushChannelPingFailedNotification |
An NSNotification with this name is posted when a Push Channel Ping Failure occurs. The notification object will be the GDPushChannel instance corresponding to the channel on which the ping failure occurred. The notification will have a user information dictionary that contains a ping failure reason code. Use GDPushChannelErrorKey as the key to access the code.
| Reason code | Failure |
|---|---|
| 600 | Application server address could not be resolved by the domain name service (DNS). |
| 601 | Could not connect to application server address. |
| 602 | Application server electronic certificate for Secure Socket Layer or Transport Layer Security (SSL/TLS) connection is invalid. |
| 603 | Timed out waiting for application server HTTP response. |
| 604 | Application server returned an invalid response. |
| 605 | Application server indicated that the token has been lost. |
The application code that handles the notification should initiate resending of the Push Channel token to the application server, if the token has been lost. Loss of token is indicated by reason code 605, see above. This is similar to the processing when the channel is initially opened, see GDPushChannelOpenedNotification. If the application server is able to accept the token, then Push Channel notification can resume.
Note that ping failure can occur at any time when the channel is open. This includes the interval between the request for disconnection (disconnect called) and channel disconnection being finalized (GDPushChannelClosedNotification received).
Ping Failure is an optional feature of the Push Channel framework. The application server can register a ping address after receiving the Push Channel token from the mobile application.
If the application server registers a ping address, then it will be periodically checked ("pinged") by the BlackBerry Dynamics Network Operation Center (NOC). If the server does not respond to a ping, then the NOC notifies the application that requested the corresponding Push Channel.
The purpose of this feature is to support servers that lose the Push Channel token when they are restarted.
See the Push Channel Back-End API for details of Ping Failure registration.
| NSString* const GDPushChannelTokenKey |
Use this constant to access the Push Channel token in a notification. The token will be in the posted NSNotification instance, in the user information dictionary, with this value as its key. It will be an NSString.
Example of usage:
NSString *token = nsNotification.userInfo[GDPushChannelTokenKey];
The key will be present if the NSNotification has one of the following values as its name.
| NSString* const GDPushChannelMessageKey |
Use this constant to access the message data in a Push Channel notification. The message will be in the posted NSNotification instance, in the user information dictionary, with this value as its key. It will be an NSString.
Example of usage:
NSString *message = nsNotification.userInfo[GDPushChannelMessageKey];
The key will be present if the NSNotification has the name: GDPushChannelMessageNotification.
| NSString* const GDPushChannelErrorKey |
Use this constant to access the error code in a Push Channel notification. The code will be in the posted NSNotification instance, in the user information dictionary, with this value as its key. It will be an NSInteger value.
Example of usage:
NSInteger code = [nsNotification.userInfo[GDPushChannelErrorKey] integerValue];
The key will be present if the NSNotification has one of the following values as its name.