enum	GDPushChannelState { GDPushChannelStateNone = 0, GDPushChannelStateOpen, GDPushChannelStateClosed, GDPushChannelStateError }
	Push Channel state. More...

NSString *const	GDPushChannelOpenedNotification
	Push Channel opened notification name. More...

NSString *const	GDPushChannelClosedNotification
	Push Channel closed notification name. More...

NSString *const	GDPushChannelErrorNotification
	Push Channel error notification name. More...

NSString *const	GDPushChannelMessageNotification
	Push Channel received message notification name. More...

NSString *const	GDPushChannelPingFailedNotification
	Push Channel ping failed on server notification name. More...

NSString *const	GDPushChannelTokenKey
	Key for the Push Channel token, in a notification user information dictionary. More...

NSString *const	GDPushChannelHostKey
	Key for the Push Channel host name, in a notification user information dictionary. More...

NSString *const	GDPushChannelMessageKey
	Key for the message data, in a Push Channel notification user information dictionary. More...

NSString *const	GDPushChannelErrorKey
	Key for the error code, in a Push Channel notification user information dictionary. More...

Detailed Description

Use these enumerations and constants in the application code for the BlackBerry Dynamics Push Channel event handler.

See also: GDPushChannel .

Enumeration Type Documentation

◆ GDPushChannelState

enum GDPushChannelState

Use these enumerated constants to check the state of a Push Channel. The state property always takes one of these values.

Enumerator
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.

Variable Documentation

◆ GDPushChannelOpenedNotification

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 Push Channel host name if applicable. Use GDPushChannelHostKey as the key to access the host name 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.

◆ GDPushChannelClosedNotification

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:

The associated Push Channel token cannot be used any more.
No more messages will be received on this Push Channel.

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.

◆ GDPushChannelErrorNotification

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.

◆ GDPushChannelMessageNotification

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.

Alert the user that new data is available.
Connect to the application server to retrieve the data.

Note: Because of this notification, the application code does not need to maintain a constant connection with the server. This is an important benefit of using the BlackBerry Dynamics Push Channel framework.

The value of this constant is suitable to use as the name parameter to an NSNotificationCenter addObserver call.

◆ GDPushChannelPingFailedNotification

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

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.

◆ GDPushChannelTokenKey

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.

◆ GDPushChannelHostKey

NSString* const GDPushChannelHostKey

Use this constant to get the host name of the push notification service in a notification. The address 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 *pushServiceHostName = nsNotification.userInfo[GDPushChannelHostKey];

The key will be present if the NSNotification has the name: GDPushChannelOpenedNotification .

◆ GDPushChannelMessageKey

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 .

◆ GDPushChannelErrorKey

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.