Push Channel event type. More...
This enumeration represents the type of a Push Channel event being notified to the application. The getEventType helper method returns one of these values.
Public Attributes | |
None =(0) | |
Unused. | |
Open =(1) | |
Push Channel opened. More... | |
Close =(2) | |
Push Channel closed. More... | |
Error =(3) | |
Push Channel error. More... | |
Message =(4) | |
Push Channel message received. More... | |
PingFail =(5) | |
Push Channel Ping Fail. More... | |
Open =(1) |
After a call to connect by the application, an Intent with this event type is sent by local broadcast when the Push Channel opens. The Intent will have a Bundle that contains
The application code that handles the Intent 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 Intent, the application could receive any of the following for the same channel.
Close =(2) |
An Intent with this event type is sent by local broadcast when a Push Channel closes. The Intent will have a Bundle that contains the Push Channel token value. Use the getToken helper to extract the token.
The Push Channel could have been closed by the remote end, or the application could have called disconnect .
After receiving this Intent:
If the Intent 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 Intent is only sent for permanent Push Channel closure; not for transient losses of channel communication. For example, this event 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 GDNetworkInfo programming interface.
Error =(3) |
An Intent with this event type is sent by local broadcast when a permanent error occurs on a Push Channel. The Intent will have a Bundle that contains an error code. Use the getErrorCode helper to extract the error.
Error code | Channel Error reason |
---|---|
0 | Push is not currently connected. |
200-499 | Internal error. |
500-599 | Internal server error. |
Receiving this Intent 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 Intent 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 GDNetworkInfo programming interface.
Message =(4) |
An Intent with this event type is sent by local broadcast when a Push Channel receives a message. The Intent will have a Bundle that contains the message "payload". Use the getMessage helper to extract 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 (PushChannelEventType.Close
received).
The application code that handles the Intent could initiate the following actions, for example.
PingFail =(5) |
An Intent with this event type is sent by local broadcast when a Push Channel Ping Failure occurs. The Intent will have a Bundle that contains the ping failure reason code. Use the getPingFailCode helper to extract 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 Intent 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 under PushChannelEventType.Open
, above. 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 (PushChannelEventType.Close
received).
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.