Detailed Description

The Push Channel framework is a BlackBerry Dynamics feature used to receive notifications from an application server.

Push Channels cannot be established until BlackBerry Dynamics authorization processing is complete. In addition, Push Channels are dependent on the Push Connection. Push Channels can only be established when the Push Connection is open and operating.

Push Channel data communication does not go via the proxy specified in the device's native settings, if any.

PUSH CHANNEL USAGE

Push Channels are established by the application, then used by the server when needed. The sequence of events is as follows:

1. The application sets an event handler for Push Channel notifications.
2. The application requests a Push Channel token from the BlackBerry Dynamics proxy infrastructure.
3. The application sends the token to its server using, for example, a socket or HTTP request.
4. The application can now wait for a Push Channel notification.

Later, when the server has data for the user, the following steps take place:

5. The server sends a Push Channel notification message through the BlackBerry Dynamics proxy infrastructure. The message is addressed using the token.
6. The message is sent on, to the device, and the waiting application's event handler is invoked.

Later, when the server has more data for the user, the following steps take place:

7. The server sends another Push Channel notification message through the BlackBerry Dynamics proxy infrastructure. The message is addressed using the same token.
8. The message is sent on, to the device, and the waiting application's event handler is invoked again.

The BlackBerry Dynamics platform keeps data communications between application and server alive while the mobile application 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.

Push Channel sequence diagram

API OVERVIEW

The Push Channel API is asynchronous and state-based. The application attaches its own event-handler callbacks to the Push Channel object. The callbacks are invoked when channel events occur, or when the channel changes state. Which API functions can be called by the application at any time also depend on the channel's state.

Callbacks are attached through listener class. The states in which each callback may be expected to be invoked are detailed in the listener class's documentation, see IGDPushChannelListener.

The availability of API functions, and what actions take place, are detailed below, and summarized in the following table. The table also summarizes which callbacks may expect to be invoked in each state.

Note that an individual Push Channel might or might not be closed when the overall Push Connection is terminated.

Push Channel state transition diagram

Examples

void OnConnectionStatus(GDConnectionStatus status)
{
    if (status == GDConnectionStatus.ConnectionStatusOpen) 
    {
        GDPushChannel myChannel = new GDPushChannel();
        IGDPushChannelListener listener = new ChannelListener();
        myChannel.Init(listener);
        myChannel.Connect();
    }
}

myChannel.Disconnect();

The request to disconnect is asynchronous, with the associated IGDPushChannelListener::OnChannelClose(String) callback being invoked when the attempt succeeds (not shown).

Reference