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

Properties Index

bb::network::PushCommand::Type	command [read-only]
bool	hasConnection [read-only]
QString	providerApplicationId
QString	targetKey

Public Functions Index

	PushService (QObject *parent=0)
	PushService (const QString &providerApplicationId, const QString &targetKey, QObject *parent=0)
virtual	~PushService ()
bb::network::PushCommand::Type	command () const
Q_INVOKABLE bool	hasConnection () const
QString	providerApplicationId () const
Q_INVOKABLE bool	reconnect ()
QString	targetKey () const

Public Slots Index

void	acceptPush (const QString &payloadId)
void	createChannel (const QUrl &pushProxyGatewayUrl)
void	createSession ()
void	destroyChannel ()
void	registerToLaunch ()
void	rejectPush (const QString &payloadId)
void	setProviderApplicationId (const QString &providerApplicationId)
void	setTargetKey (const QString &targetKey)
void	unregisterFromLaunch ()

Signals Index

void	connectionClosed ()
void	createChannelCompleted (const bb::network::PushStatus &status, const QString &token)
void	createSessionCompleted (const bb::network::PushStatus &status)
void	destroyChannelCompleted (const bb::network::PushStatus &status)
void	pushTransportReady (bb::network::PushCommand::Type command)
void	registerToLaunchCompleted (const bb::network::PushStatus &status)
void	simChanged ()
void	unregisterFromLaunchCompleted (const bb::network::PushStatus &status)

Properties

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

The last command that failed.

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 (
QObject *parent)

Creates a new PushService object.

Parameters
parent	The QObject that will take ownership of this object, or NULL.

Since:

BlackBerry 10.0.0

PushService (
const QString &providerApplicationId,
const QString &targetKey,
QObject *parent )

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 (
const QString &payloadId)

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 (
const QString &payloadId)

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 (
const QString &targetKey)

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 (
const bb::network::PushStatus &status,
const QString &token )

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 (
const bb::network::PushStatus &status)

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 (
const bb::network::PushStatus &status)

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 (
bb::network::PushCommand::Typecommand)

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 (
const bb::network::PushStatus &status)

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 (
const bb::network::PushStatus &status)

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

PushService

Overview

Properties Index

Public Functions Index

Public Slots Index

Signals Index

Properties

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

bool hasConnection[read-only]

QString providerApplicationId

QString targetKey

Public Functions

PushService (QObject *parent)

PushService (const QString &providerApplicationId, const QString &targetKey, QObject *parent )

virtual~PushService ()

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

Q_INVOKABLE bool hasConnection ()

QString providerApplicationId ()

Q_INVOKABLE bool reconnect ()

QString targetKey ()

Public Slots

void acceptPush (const QString &payloadId)

void createChannel (const QUrl &pushProxyGatewayUrl)

void createSession ()

void destroyChannel ()

void registerToLaunch ()

void rejectPush (const QString &payloadId)

void setProviderApplicationId (const QString &providerApplicationId)

void setTargetKey (const QString &targetKey)

void unregisterFromLaunch ()

Signals

void connectionClosed ()

void createChannelCompleted (const bb::network::PushStatus &status, const QString &token )

void createSessionCompleted (const bb::network::PushStatus &status)

void destroyChannelCompleted (const bb::network::PushStatus &status)

void pushTransportReady (bb::network::PushCommand::Typecommand)

void registerToLaunchCompleted (const bb::network::PushStatus &status)

void simChanged ()

void unregisterFromLaunchCompleted (const bb::network::PushStatus &status)

1. Download the tools

2. Try the sample apps

3. Educate yourself

4. Start developing

PushService (
QObject *parent)

PushService (
const QString &providerApplicationId,
const QString &targetKey,
QObject *parent )

void acceptPush (
const QString &payloadId)

void createChannel (
const QUrl &pushProxyGatewayUrl)

void rejectPush (
const QString &payloadId)

void setProviderApplicationId (
const QString &providerApplicationId)

void setTargetKey (
const QString &targetKey)

void createChannelCompleted (
const bb::network::PushStatus &status,
const QString &token )

void createSessionCompleted (
const bb::network::PushStatus &status)

void destroyChannelCompleted (
const bb::network::PushStatus &status)

void pushTransportReady (
bb::network::PushCommand::Typecommand)

void registerToLaunchCompleted (
const bb::network::PushStatus &status)

void unregisterFromLaunchCompleted (
const bb::network::PushStatus &status)