GDPushChannel Class |
Namespace: GD
public sealed class GDPushChannel
The GDPushChannel type exposes the following members.
Name | Description | |
---|---|---|
GDPushChannel | Initializes a new instance of the GDPushChannel class |
Name | Description | |
---|---|---|
Connect | Connect Push Channel. | |
Disconnect | Disconnect Push Channel. | |
Equals | (Inherited from Object.) | |
GetHashCode | (Inherited from Object.) | |
GetType | (Inherited from Object.) | |
Init | Constructor that prepares a new Push Channel. | |
ToString | (Inherited from Object.) |
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.
State | Functions / Actions |
---|---|
Prepared |
Application can call Connect: state becomes Connecting
Callbacks: None |
Connecting |
BlackBerry Dynamics Runtime requests a new channel from the BlackBerry Dynamics proxy infrastructure
Callbacks: OnChannelError(Int32) new state is Failed OnChannelOpen(String) new state is Open |
Open |
Application can call Disconnect: state becomes Disconnecting
Callbacks: OnChannelMessage(String) no state change OnChannelPingFail(Int32) no state change OnChannelClose(String) new state is Disconnected |
Disconnecting |
BlackBerry Dynamics Runtime requests the BlackBerry Dynamics proxy infrastructure to close the channel
Callbacks: OnChannelMessage(String) no state change OnChannelPingFail(Int32) no state change OnChannelClose(String) new state is Disconnected |
Disconnected |
Application can call Connect: state becomes Connecting
Callbacks: None |
Failed |
Application can call Connect: state becomes Connecting
Callbacks: None |
Note that an individual Push Channel might or might not be closed when the overall Push Connection is terminated.
Push Channel state transition diagram
CREATE PUSH CHANNEL
The following snippet shows a Push Channel being created as soon as the Push Connection is ready. In this case, the code to create the Push Channel is in the Push Connection's state-change handler, see also IGDPushChannelListener.
void OnConnectionStatus(GDConnectionStatus status) { if (status == GDConnectionStatus.ConnectionStatusOpen) { GDPushChannel myChannel = new GDPushChannel(); IGDPushChannelListener listener = new ChannelListener(); myChannel.Init(listener); myChannel.Connect(); } }
The above snippet shows the following taking place when the Push Channel service becomes available:
The attempt to connect is asynchronous, with the associated IGDPushChannelListener::OnChannelOpen(String) callback being invoked when the attempt succeeds (not shown).
CLOSE PUSH CHANNEL
myChannel.Disconnect();
The request to disconnect is asynchronous, with the associated IGDPushChannelListener::OnChannelClose(String) callback being invoked when the attempt succeeds (not shown).