blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions

<GDPushChannelDelegate> Protocol Reference

Delegate for handling GDPushChannel state transitions and received Push Channel notifications (deprecated). More...

#import <GDPush.h>

List of all members.

Public Member Functions


Detailed Description

Deprecated:
This class is deprecated and will be removed in a future release. Instead of setting a PushChannel delegate, register for notifications as described in the GDPushChannel class reference.

State changes that occur when using GDPushChannel are handled by creating a class that implements this protocol. The callback for handling received Push Channel notifications is also part of this protocol.

See also:
Push Channel state transition diagram

Code Snippets

The following code snippets illustrate some common tasks.

Receive Push Channel Token

 -(void)onChannelOpen:(NSString*)token
 {
     NSLog(@"onChannelOpen token: %@", token);
     myApp.pushIsOpen = YES;
     myApp.pushToken = token;
     [myApp sendPushToken];
 }

The above snippet shows a simple onChannelOpen handler. The following takes place when the Push Channel is opened:

The sendPushToken function, which would be written by the application developer, would send the token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The server will use the token to address Push Channel notification messages back to the application. These would be received by the application's onChannelMessage handler.

Receive Push Channel notification

 -(void)onChannelMessage:(NSString*)data
 {
     NSLog(@"onChannelMessage: %@", data);
     [myApp processPush:data];
 }

The above snippet shows a simple onChannelMessage handler.

The handler logs the received data to the system monitor, then calls the application processPush function. The "payload" of the notification is passed as a parameter to the processPush function.

The processPush function, which would be written by the application developer, could initiate any of the following actions:

Handle Channel Closure

 -(void)onChannelClose:(NSString*)data
 {
     NSLog(@"onChannelClose: %@", data);
     myApp.pushIsOpen = NO;
     [myApp discardPushToken:data];
 }

The above snippet shows a simple onChannelClose handler. The following takes place when the Push Channel is closed:

The discardPushToken function would delete the application's copy of the token, possibly after checking that it matches the whichWas parameter. The function could also initiate connection of a new Push Channel, which would have a new token. See connect.

Handle Channel Error

 -(void)onChannelError:(int)error
 {
     NSLog(@"onChannelError: %d", error);
     myApp.pushIsOpen = NO;
     myApp.pushErr = error;
     [myApp discardPushToken];
 }

The above snippet shows a simple onChannelError handler.

The handler logs the error code to the system monitor, flags the channel's state as not connected, records the error code in the application, then calls the application discardPushToken function.

The discardPushToken function could do any of the following:

Handle Ping Failure

See under onChannelPingFail for an explanation of the Ping Failure feature.

 -(void)onChannelPingFail:(int)error
 {
     NSLog(@"onChannelPingFail %d", error);
     if ( error == 605 ) {
         [myApp resendPushToken];
     }
 }

The above snippet shows a simple onChannelPingFail handler.

The handler logs the error code to the system monitor, then calls the application resendPushToken function if the token was lost.

The resendPushToken function, which would be written by the application developer, would send the application's stored token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The resendPushToken function should expect that the server is not immediately available, perhaps employing a retry policy.


Member Function Documentation

- (void) onChannelOpen: (NSString *)  token
Deprecated:
This callback has been replaced by observation of GDPushChannelOpenedNotification notifications.

This callback will be invoked when the associated Push Channel is opened in the BlackBerry Dynamics proxy infrastructure. See connect. At this point, a Push Channel token will have been issued by the BlackBerry Dynamics proxy infrastructure Network Operation Center (NOC).

The function that is invoked must initiate sending of the token to the application server, out of band. The application server will then be able to use the token to address Push Channel notifications back to the application on the device, via the NOC.

See also:
Push Channel Back-End API

Invocation of this callback also notifies the application on the device that any of the following callbacks could now be invoked: onChannelMessage, onChannelPingFail, onChannelClose.

Parameters:
tokenNSString containing the Push Channel token issued by the NOC.
- (void) onChannelMessage: (NSString *)  data
Deprecated:
This callback has been replaced by observation of GDPushChannelMessageNotification notifications.

This callback will be invoked when a Push Channel notification is received on the associated Push Channel. The message will have been sent by the application server, using the Push Channel notify service, which is hosted by the BlackBerry Dynamics Network Operation Center (NOC).

The service supports a "payload" of data to be included in the notification. The data could be in any format chosen by the application developer. The payload could also be empty.

Note that Push Channel notifications 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 (onChannelClose received).

The function that is invoked could initiate the following actions:

  • Alert the user that new data is available.
  • Connect to the application server to retrieve the data.
Parameters:
dataNSString containing the data payload included by the application server, encoded in UTF-8.
Note:
Because of this callback, 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.
See also:
Push Channel Back-End API
- (void) onChannelClose: (NSString *)  data
Deprecated:
This callback has been replaced by observation of GDPushChannelClosedNotification notifications.

This callback will be invoked when the associated Push Channel is closed. This means closed by the remote end, or by the application having called disconnect.

Invocation of this callback notifies the application on the device that:

  • The associated Push Channel token cannot be used any more
  • No more Push Channel notifications will be received on this channel

If the onChannelClose was not expected, the function that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The function could also initiate release of the Push Channel object. Alternatively, reconnection could be initiated, see connect.

Parameters:
dataToken for the Push Channel that was closed.

Note that this callback is only invoked for permanent Push Channel closure. This callback is not invoked for transient losses of channel communication. For example, this callback is not invoked when the mobile device 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.

- (void) onChannelError: (int)  error
Deprecated:
This callback has been replaced by observation of GDPushChannelErrorNotification notifications.

This callback is invoked when a permanent error condition is encountered on the associated Push Channel.

Invocation of this callback notifies the application that the 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 function that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The function that is invoked should initiate reconnection, see connect, after checking that the Push Channel service is available, see GDReachability.isPushChannelAvailable.

Parameters:
errorReason code for the condition encountered, as follows.
errorChannel Error reason
0 Push is not currently connected.
200-499 Internal error.
500-599 Internal server error.
- (void) onChannelPingFail: (int)  error
Deprecated:
This callback has been replaced by observation of GDPushChannelPingFailedNotification notifications.

This callback is invoked when Ping Failure is encountered on the associated Push Channel.

The function that is invoked should initiate resending of the Push Channel token to the application server, if the token has been lost. This is similar to the processing when the channel is initially opened, see onChannelOpen. If the application server is able to accept the token, then Push Channel notification can resume.

See also:
Push Channel Back-End API

Note that Ping Fail notifications 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 (onChannelClose received).

Parameters:
errorReason code for the condition encountered, as follows.
errorPing Failure reason
600 Application server address could not be resolved via DNS
601 Could not connect to application server address
602 Application server TLS/SSL certificate invalid
603 Timed out waiting for application server HTTP response
604 Application server returned an invalid response
605 Application server indicated that token is unknown

Note that only error 605 means that the token has been lost and must be resent.


The documentation for this protocol was generated from the following file: