PushService

Since: BlackBerry 10.0.0

#include <bb/network/PushService>

To link against this class, add the following line to your .pro file: LIBS += -lbbnetwork

Manages all interactions with the Push Proxy Gateway (PPG).

A PushService allows a push-enabled application to send requests to the PPG.

The PushService supports both sending requests and receiving responses from the PPG. Applications that receive response messages while they are running are notified via the [command]Completed() signal.

The following commands are supported by the PushService:

The application can send an application level acknowledgement that indicates whether the application accepted or rejected the pushed content ( acceptPush() or rejectPush() ).

Overview

Public Functions Index

PushService (QObject *parent=0)
PushService (const QString &providerApplicationId, const QString &targetKey, QObject *parent=0)
virtual ~PushService ()
bb::network::PushCommand::Typecommand () const
Q_INVOKABLE boolhasConnection () const
QStringproviderApplicationId () const
Q_INVOKABLE boolreconnect ()
QStringtargetKey () const

Public Slots Index

voidacceptPush (const QString &payloadId)
voidcreateChannel (const QUrl &pushProxyGatewayUrl)
voidcreateSession ()
voiddestroyChannel ()
voidregisterToLaunch ()
voidrejectPush (const QString &payloadId)
voidsetProviderApplicationId (const QString &providerApplicationId)
voidsetTargetKey (const QString &targetKey)
voidunregisterFromLaunch ()

Signals Index

voidconnectionClosed ()
voidcreateChannelCompleted (const bb::network::PushStatus &status, const QString &token)
voidcreateSessionCompleted (const bb::network::PushStatus &status)
voiddestroyChannelCompleted (const bb::network::PushStatus &status)
voidpushTransportReady (bb::network::PushCommand::Type command)
voidregisterToLaunchCompleted (const bb::network::PushStatus &status)
voidsimChanged ()
voidunregisterFromLaunchCompleted (const bb::network::PushStatus &status)

Properties

bb::network::PushCommand::Type command[read-only]

The last command that failed.

The returned value can be either a CreateChannel or DestroyChannel.

Since:

BlackBerry 10.0.0

bool hasConnection[read-only]

Specifies whether the PushService has a connection to the Push Agent.

Since:

BlackBerry 10.0.0

QString providerApplicationId

The provider application ID.

Since:

BlackBerry 10.0.0

QString targetKey

The target key.

Since:

BlackBerry 10.0.0

Public Functions

PushService (

Creates a new PushService object.

Parameters
parent

The QObject that will take ownership of this object, or NULL.
Since:

BlackBerry 10.0.0

PushService (

Creates a new PushService object.

Parameters
providerApplicationId

The unique identifier of the push-enabled application.

targetKey

The invocation target key.

parent

The QObject that will take ownership of this object, or NULL.
Since:

BlackBerry 10.0.0

virtual~PushService ()

Destructor.

Since:

BlackBerry 10.0.0

bb::network::PushCommand::Type command ()

Retrieves the last failed command.

The returned value can be either a CreateChannel or DestroyChannel.

Return:

The last failed command as specified in PushCommand.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool hasConnection ()

Determines whether the PushService has a connection to the Push Agent.

Return:

true if the PushService has a connection to the Push Agent, false otherwise.

Since:

BlackBerry 10.0.0

QString providerApplicationId ()

Gets the provider application ID.

Return:

The provider application ID.

Since:

BlackBerry 10.0.0

Q_INVOKABLE bool reconnect ()

Reconnects the PushService to the Push Agent.

Return:

true if the PushService was able to reconnect to the Push Agent, false otherwise.

Since:

BlackBerry 10.2.0

QString targetKey ()

Gets the target key associated with this PushService.

Return:

The target key associated with this PushService.

Since:

BlackBerry 10.0.0

Public Slots

void acceptPush (

Accepts a push message.

If the Push Initiator requires an application level acknowledgement for a particular push message, this function sends an affirmative message back to the PPG to indicate that the application accepted the pushed content.

Parameters
payloadId

The unique identifier of the push notification which is stored in the PushPayload object.
Since:

BlackBerry 10.0.0

void createChannel (
  • const QUrl &pushProxyGatewayUrl)

Creates a channel for receiving push messages from the Push Initiator.

Once the channel is successfully established, the application does not have to call this again. The PushService maintains the channel. However, there are some cases where you might have to create the channel again (for example, if the SIM card is removed from the device).

Parameters
pushProxyGatewayUrl

The URL of the Push Proxy Gateway (PPG).
Since:

BlackBerry 10.0.0

void createSession ()

Creates a session between the application and the Push Service Notification agent (PNS agent).

Creating a session sets up inter-process communication between the application and the PNS agent. This must be called every time the application is launched.

Since:

BlackBerry 10.0.0

void destroyChannel ()

Destroys the channel when the application no longer needs it.

Since:

BlackBerry 10.0.0

void registerToLaunch ()

Registers the application to be launched in the background upon receiving a push message.

Since:

BlackBerry 10.0.0

void rejectPush (

Rejects a push message.

If the Push Initiator requires an application level acknowledgement for a particular push message, this function sends a negative message back to the PPG to indicate that the application rejected the pushed content. This generally means that the Push Initiator should try to resend the push message. If the Push Initiator did not request an acknowledgement, this function does nothing.

Parameters
payloadId

The unique identifier of the push notification which is stored in the PushPayload object.
Since:

BlackBerry 10.0.0

void setProviderApplicationId (
  • const QString &providerApplicationId)

Changes the provider application ID represented by this object.

Parameters
providerApplicationId

The provider application ID
Since:

BlackBerry 10.0.0

void setTargetKey (

Changes the target key represented by this object.

Parameters
targetKey

The target key
Since:

BlackBerry 10.0.0

void unregisterFromLaunch ()

Cancels a previous registerToLaunch() request.

Since:

BlackBerry 10.0.0

Signals

void connectionClosed ()

Emitted when the connection to the Push Agent has been deleted.

When this happens, the application needs to re-establish the connection with the Push Agent by calling reconnect() periodically until reconnect() returns true. After reconnect() returns true, the application must then call createSession().

Since:

BlackBerry 10.2.0

void createChannelCompleted (

Emitted when a response to the createChannel() request is received.

Parameters
status

A PushStatus response for the createChannel() request call

token

The token received from the PPG after successfully creating the push channel. This token should be communicated to the Push Initiator.
Since:

BlackBerry 10.0.0

void createSessionCompleted (

Emitted when a response to the createSession() request is received.

Parameters
status

The PushStatus response for the createSession() request call
Since:

BlackBerry 10.0.0

void destroyChannelCompleted (

Emitted when a response for the destroyChannel() request is received.

Parameters
status

A PushStatus response for the destroyChannel() request call.
Since:

BlackBerry 10.0.0

void pushTransportReady (

Emitted when a previous createChannel() or destroyChannel request failed with a TransportFailure (10103) or SubscriptionContentNotAvailable (10110) status code.

Here's an example of how to initiate the requests again after they fail:

if (command == bb::network::PushCommand::CreateChannel) {
    pushService->createChannel(pushProxyGatewayUrl);
}
else if (command == bb::network::PushCommand::DestroyChannel) {
    pushService->destroyChannel();
}
Parameters
command

The last command that failed (either a CreateChannel or DestroyChannel).
Since:

BlackBerry 10.0.0

void registerToLaunchCompleted (

Emitted when a response for the registerToLaunch() request is received.

Parameters
status

A PushStatus response for the registerToLaunch() request call.
Since:

BlackBerry 10.0.0

void simChanged ()

Emitted when the SIM card is changed.

When this happens, the PPG stops delivering push messages. To continue receiving content, you must call createChannel() again.

Since:

BlackBerry 10.0.0

void unregisterFromLaunchCompleted (

Emitted when a response for the unregisterFromLaunch() request is received.

Parameters
status

A PushStatus response for the unregisterFromLaunch() request call.
Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus