Class: GDPushChannel

GDPushChannel()

This class encapsulates the GD Push Channel object. The Push Channel framework is a BlackBerry Dynamics (GD) feature used to receive notifications from an application server. Note that the GD Push Channel feature is not part of the native iOS notification feature set; however, Push Channels are dependent on the Push Connection, and Push Channels can only be established when the Push Connection is open and operating.

Push Channels are established from the client end, then used by the server when needed. The sequence of events is as follows:
  1. The client sets an event handler for Push Channel notifications
  2. The client application requests a Push Channel token from the BlackBerry Dynamics proxy infrastructure
  3. The client application sends the token to its server using, for example, a socket or HTTP request
  4. The client can now wait for a Push Channel notification
The BlackBerry Dynamics platform keeps data communications between client and server alive while the client is waiting for a Push Channel notification. This is achieved by sending "heartbeat" messages at an interval that is dynamically optimized for battery and network performance.

NOTE: Create a new push channel by calling GDPushConnection.createPushChannel.

Constructor

new GDPushChannel()

Properties:
Name Type Description
onChannelResponse function This function is the callback handler that is called whenever a response is returned from the channel connection. This function should check the value of the responseType returned and determine the required action to take. If the responseType = "open", then the channelID returned in the response should be used to reference this channel in subsequent calls over this connection (see GDPushChannel.close). NOTE: This function is required to be a non-null value.
Source:

Methods

close(channelID)

Call this function to initiate permanent disconnection of the Push Channel. This function causes a request for Push Channel termination to be sent to the BlackBerry Dynamics proxy infrastructure Network Operating Center (NOC). The NOC will delete the channel, and invalidate the Push Channel token that was issued when the channel was initially opened.
Parameters:
Name Type Description
channelID string The unique ID for the push channel to close.
Source:
Example
See the example below (it is added to GDPushChannel.open() method).

open() → {GDPushChannelResponse}

Call this function to open the Push Channel. This function can only be called when the channel is not open. This function causes a request for a Push Channel to be sent to the Good Dynamics proxy infrastructure Network Operating Center (NOC). The NOC will create the channel, and issue a Push Channel token, which can then be used to identify the channel. Logically, Push Channels exist within the Push Connection. Opening a Push Channel will not succeed if the Push Connection is not open and operating.
Source:
Returns:
A push channel response object in JSON format. The result should be parsed and saved as a GDPushChannelResponse object in the callback handler. If the channel was opened then the response object will be initialize with a channelID property that can be used to reference this channel connection. Additionally, the response will also contain a token that uniquely identifies the device associated with this push channel. Since this is an asynchronous call, the response will be returned via the onChannelResponse callback.
Type
GDPushChannelResponse
Example
function myPushConnection(){
    var myConnection;
    var channel = null;
    var savedChannelID = null;
    //--GDPushConnection
    myConnection = window.plugins.GDPushConnection;

    try {
        myConnection = window.plugins.GDPushConnection;
    } catch(e) {
        throw new Error("Unable to initialize the GD Connection (mConnection).");
    }

   //-- GDPushChannelResponse
   function pushChannelResponse(response){
       try {
           var channelResponse = mConnection.parseChannelResponse(response);
           throw new Error("Got response channelID: " + channelResponse.channelID);
           throw new Error("Got response responseType: " + channelResponse.responseType);
           throw new Error("Got response responseData: " + channelResponse.responseData);
           switch(channelResponse.responseType) {
           case "open":
               savedChannelID = channelResponse.channelID;
               throw new Error("Channel connection opened with ID :" + savedChannelID);

               // send application server the savedChannelID (token) here

           case "message":
               // handle pushed message from the server
               channel.close(channelResponse.channelID);
               break;
           case "error":
               throw new Error("Received an error status from the channel connection.");
               break;
           case "close":
               throw new Error("Channel connection closed successfully.");
           case "pingFail":
               break;
           default:
               break;
           }
       } catch(e) {
           throw new Error("Invalid response object sent to channel response callback handler.");
       }
   };

   function pushConnectionOk(){
       //-- GDPushChannel
       channel = myConnection.createPushChannel(pushChannelResponse);
       channel.open();
   };

   if(myConnection !== "undefined"){
       myConnection.isConnected(
       function(result) {
           throw new Error("Push connection is established.");
           pushConnectionOk();
       },
       function(result) {
           throw new Error("An error occurred while checking the status of the push connection: " + result);
       });
   };
};