BlackBerry Dynamics for Xamarin Forms  10.1.0.927
Runtime library for Xamarin Forms applications
BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel Interface Reference

The Push Channel framework is a BlackBerry Dynamics feature used to receive notifications from an application server. Use of the Push Channel feature in the application is dependent on:

More...

Public Member Functions

void ConnectAsync ()
 Connect Push Channel. More...
 
void DisconnectAsync ()
 Disconnect Push Channel. More...
 

Properties

string PushChannelIdentifier [get]
 String containing the identifier for this Push Channel. More...
 
BBDPushChannelState State [get]
 The BlackBerry Dynamics Runtime sets this property to one of the BBDPushChannelState values to represent the state of the channel. More...
 

Events

EventHandler< BBDPushChannelOpenedEventArgsBBDPushChannelOpened
 Push Channel opened event. More...
 
EventHandler< BBDPushChannelClosedEventArgsBBDPushChannelClosed
 Push Channel closed event. More...
 
EventHandler< BBDPushChannelPermanentErrorEventArgsBBDPushChannelError
 Push Channel permanent error event. More...
 
EventHandler< BBDPushChannelMessageEventArgsBBDPushChannelMessage
 Push Channel message event. More...
 
EventHandler< BBDPushChannelPingFailEventArgsBBDPushChannelPingFail
 Push Channel ping failure event. More...
 

Detailed Description

The Push Channel framework is a BlackBerry Dynamics feature used to receive notifications from an application server. Use of the Push Channel feature in the application is dependent on:

  • Completion of BlackBerry Dynamics authorization processing.
  • Connection to the BlackBerry Dynamics infrastructure.

Push Channel data communication doesn't go through the proxy specified in the native settings of the device or computer on which the application is running, if any.

Member Function Documentation

void BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.ConnectAsync ( )

Connect Push Channel.

Call this method to open the Push Channel connection. This method can only be called when the channel isn't open.

This method causes a request for a Push Channel to be sent to the BlackBerry Dynamics Network Operation Center (NOC). The NOC will create the channel, and issue a Push Channel token, which can then be used to identify the channel.

The connection attempt is asynchronous. If the attempt succeeds, BBDPushChannelOpened event will be raised, and BBDPushChannelOpenedEventArgs will contain the token. If the attempt fails, BBDPushChannelError event will be raised, and BBDPushChannelPermanentErrorEventArgs will contain an error code.

void BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.DisconnectAsync ( )

Disconnect Push Channel.

Call this method to initiate permanent disconnection of the Push Channel. This method can only be called when the channel is open.

This method causes a request for Push Channel termination to be sent to the BlackBerry Dynamics Network Operation Center (NOC). The NOC will delete the channel, and invalidate the Push Channel token that was issued when the channel was initially opened.

Disconnection is asynchronous. When disconnection is complete, BBDPushChannelClosed event will be raised.

This method is for permanent closure of the channel. Transient suspension of Push Channel notifications may be more easily accomplished out-of-band, by direct communication with the application server.

If the connection with the NOC is open and operating, and the application server that was sent the token registered for isDisconnected, then a disconnect notification will be sent to the application server, by the NOC.

Property Documentation

string BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.PushChannelIdentifier
get

String containing the identifier for this Push Channel.

BBDPushChannelState BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.State
get

The BlackBerry Dynamics Runtime sets this property to one of the BBDPushChannelState values to represent the state of the channel.

Event Documentation

EventHandler<BBDPushChannelClosedEventArgs> BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.BBDPushChannelClosed

Push Channel closed event.

This event is raised when the Push Channel closes. The notification will contain the Push Channel token.

The Push Channel could have been closed by the remote end, or the application could have called DisconnectAsync.

After receiving this notification:

  • The associated Push Channel token cannot be used anymore.
  • No more messages will be received on this Push Channel.
EventHandler<BBDPushChannelPermanentErrorEventArgs> BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.BBDPushChannelError

Push Channel permanent error event.

This event is raised when a permanent error occurs on a Push Channel. The notification will contain an error code.

Receiving this notification warns the application that the associated Push Channel token cannot be used anymore, or that the channel could not be connected in the first place. Furthermore, no (more) Push Channel notifications will be received on this channel.

EventHandler<BBDPushChannelMessageEventArgs> BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.BBDPushChannelMessage

Push Channel message event.

This event is raised when a Push Channel receives a message. The notification will contain the message "payload".

The Push Channel message will have been sent by an application server, using the Push Channel notify service.

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 (DisconnectAsync called) and channel disconnection being finalized (BBDPushChannelClosed received).

The application code that handles the notification could initiate the following actions, for example:

  • Alert the user that new data is available.
  • Connect to the application server to retrieve the data.
EventHandler<BBDPushChannelOpenedEventArgs> BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.BBDPushChannelOpened

Push Channel opened event.

After a call to ConnectAsync by the application, this event is raised when the Push Channel opens. The notification will contain the Push Channel token.

The application code that handles the event 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, through the BlackBerry Dynamics proxy infrastructure.

EventHandler<BBDPushChannelPingFailEventArgs> BBDXamarinForms.Common.Interfaces.Push.IBBDPushChannel.BBDPushChannelPingFail

Push Channel ping failure event.

This event is raised when a Push Channel Ping Failure occurs. The notification will contain a ping failure reason code.

The application code that handles the notification 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. This is similar to the processing when the channel is initially opened, see BBDPushChannelOpened. 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 (DisconnectAsync called) and channel disconnection being finalized (BBDPushChannelClosed received).