PushService

Creates a PushService object. The PushService object will only be available if the successCallback function is called. It will not be available if the failCallback function is called instead.

// For a consumer application (using the public/BIS PPG)
var ops = { invokeTargetId : 'com.sample.pushtest.target', 
            appId : 'appId1', 
            ppgUrl : 'https://cp123.pushapi.na.blackberry.com' };

// For an enterprise application (using the enterprise/BES PPG)
// var ops = { invokeTargetId : 'com.sample.pushtest.target' }; 

// Or, for an enterprise application with an application ID: 
// var ops = { invokeTargetId : 'com.sample.pushtest.target', 
//             appId : 'appId1' };

try {
    blackberry.push.PushService.create(ops, 
        successCallback, 
        failCallback, 
        simChangeCallback, 
        pushTransportReadyCallback);
} catch (err) {
    console.log("Create was called more than once with different " 
        + "values for options.invokeTargetId or options.appId.");
    console.log(err);
}

function successCallback(pushService) {
    // The create operation was a success
    // Save the pushService object to a global variable
    // Now, use the pushService object to now perform a 
    // launchApplicationOnPush, createChannel, destroyChannel, etc.
    pushService.createChannel(createChannelCallback);
}

function failCallback(result) {
    // The create operation failed
    // You should compare the result code against the error  
    // constants in this PushService class that apply for 
    // create and take the recommended action for that constant
    if (result === blackberry.push.PushService.INTERNAL_ERROR) {
        // Retry the create up to a certain number of attempts 
        // and then display an error to the user
    }
    // ... handle the other possible error constants 
    // from the PushService class
}

function simChangeCallback() {
    // The SIM card was changed and the channel has been 
    // destroyed since a new user might be using the device.
    // It is recommended that the user of this application be 
    // re-authenticated with the Push Initiator (if your 
    // Push Initiator implementation supports subscription) 
    // followed by a call to createChannel.
}

function pushTransportReadyCallback(lastFailedOperation) {
    // This callback will be called when a create channel
    // or destroy channel was previously attempted and it 
    // failed with a PUSH_TRANSPORT_UNAVAILABLE or a 
      // PPG_SERVER_ERROR error code and now the 
    // network/push transport/PPG is available again. 
    // The operation indicated by lastFailedOperation should 
    // be retried again.
    if (lastFailedOperation === 
        blackberry.push.PushService.CREATE_CHANNEL_OPERATION) {
        pushService.createChannel(createChannelCallback);
    } else if (lastFailedOperation === 
       blackberry.push.PushService.DESTROY_CHANNEL_OPERATION) {
       pushService.destroyChannel(destroyChannelCallback);
    }
}

Creates a push channel for the given application. Once a channel is created, it will survive application restarts and therefore does not necessarily need to be called on every application start up.

However, for a consumer application, since it is possible for the public/BIS PPG to destroy a channel under certain circumstances it may be advisable to periodicially re-create the channel (e.g. once a month).

A successful create must have been done before calling this function.

This function should be called in order for an application to be able to start receiving pushes. If a destroyChannel call is then made, no pushes will be able to be received until a createChannel call is made again.

pushService.createChannel(createChannelCallback);

function createChannelCallback(result, token) {
    if (result === blackberry.push.PushService.SUCCESS) {
        // Success, so a token should be available
        // Subscribe with the Push Initiator using this  
        // token (if your Push Initiator supports subscription) 
        // so that you can push to this user using this token
    } else if (result === 
        blackberry.push.PushService.INTERNAL_ERROR) {
        // Retry the createChannel up to a certain number of  
        // attempts and then display an error to the user
    } else if ... (handle all the error codes possible for 
                   createChannel - see the error constants 
                   in this PushService class)
}

Destroys a push channel for the given application.

A successful create must have been done and a channel must have been created using createChannel before calling this function.

This function should be called in order for an application to stop receiving pushes. No pushes will be received after a destroyChannel call until a createChannel call is made after that.

pushService.destroyChannel(destroyChannelCallback);

function destroyChannelCallback(result) {
    if (result === blackberry.push.PushService.INTERNAL_ERROR) {
        // Retry the destroyChannel up to a certain number  
        // of attempts and then display an error to the user
    } else if ... (handle all the error codes possible for 
                   destroyChannel - see the error constants 
                   in this PushService class)
}

Extracts the PushPayload from the passed in invoke request.

A successful create must have been done before calling this function.

Returns the parsed out PushPayload object.

try {
    var pushPayload = 
        pushService.extractPushPayload(invokeRequest);

    // pushPayload.data is of type Blob
    // If the Blob is known to contain text, 
    // then do something like this:
    blobToText(pushPayload.data, "UTF-8", textConversionCallback);

    // If the Blob is known to contain binary, then do 
    // something like this to get an ArrayBuffer:
    // blobToArrayBuffer(pushPayload.data, 
    //     binaryConversionCallback);
} catch (err) {
    console.log("Was unable to parse the invoke request.");
    console.log(err);
}

function blobToText(blob, encoding, callback) {
    var reader = new FileReader();
  	
    reader.onload = function(evt) {
        // No errors, get the result and call the callback
        callback(evt.target.result);
    };
   	
    reader.onerror = function(evt) {
        console.log("Error converting Blob to string: " + 
            evt.target.error);
    };
       
    reader.readAsText(blob, encoding);
}

function textConversionCallback(str) {
    console.log("Data received: " + str);
}

function blobToArrayBuffer(blob, callback) {
    var reader = new FileReader();
   	
    reader.onload = function(evt) {
        // No errors, get the result and call the callback
        callback(evt.target.result);
    };
   	
    reader.onerror = function(evt) {
        console.log("Error converting Blob to ArrayBuffer: " + 
            evt.target.error);
    };
       
    reader.readAsArrayBuffer(blob);
}

function binaryConversionCallback(arrayBuffer) {
    // Process the ArrayBuffer containing 
    // binary content as needed
}

Indicates whether or not the application should be launched (started up) if it is currently closed (not running) and a new push is received. The default system behaviour is to not launch the application.

A successful create must have been done before calling this function.

It is important to note that the shouldLaunch flag is only persisted once a channel has been created using the createChannel function. In other words, once the create channel function has been called the state of the shouldLaunch flag is persisted between application and device restarts. The flag is only removed once the destroy channel function is called. This flag can be toggled at any time using this function but, again, its value is only persisted once the create channel function has been called at least once for the lifetime of the application.

// Indicate that you want the application to launch on a new push
pushService.launchApplicationOnPush(true, 
    launchApplicationCallback);

// To indicate that you do not want to launch on a new push, 
// either leave the default behaviour or call:
// pushService.launchApplicationOnPush(false, 
//     launchApplicationCallback);

function launchApplicationOnPush(result) {
   if (result === blackberry.push.PushService.INTERNAL_ERROR) {
     // Retry the launchApplicationOnPush up to a certain number 
     // of attempts and then display an error to the user
   } else if ... (handle all the error codes possible for 
                  launchApplicationOnPush - see the error 
                  constants in this PushService class)
}

Result code for an operation that was performed successfully.

Operations this code applies to: create, createChannel, destroyChannel, launchApplicationOnPush

Result error code for an internal error.

Operations this error can occur on: create, createChannel, destroyChannel, launchApplicationOnPush

Recommended action: Retrying the operation might correct the issue.

Result error code for an invalid device PIN as determined by the PPG.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Retrying the operation might correct the issue. The PIN is obtained under the covers by the public/BIS PPG. It very rarely has issues obtaining the device PIN, so a retry might fix this.

Result error code for an invalid provider application ID. Either an invalid one was specified or none at all.

Operations this error can occur on: create, createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Specifying a valid value for options.appId in the static create function and retrying might correct the issue.

Result error code when attempting to call destroy channel again after a successful destroy channel has already been done.

Operations this error can occur on: destroyChannel (only if using public/BIS PPG)

Recommended action: Most applications will typically want to just ignore this error code when it comes back.

Result error code when attempting to call destroy channel after a content provider has already done the destroying of the channel by unregistering a user.

Operations this error can occur on: destroyChannel (only if using public/BIS PPG)

Recommended action: Most applications will typically want to just ignore this error code when it comes back.

This result error code should not typically be encountered. It would only occur if a create or destroy channel operation internally causes the state of a subscriber on the PPG to be in an invalid state.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: If this error occurs, it should be logged and reported to the RIM support team.

Result error code for when a destroy channel operation fails because the subscriber could not be found on the PPG's end.

Operations this error can occur on: destroyChannel (only if using public/BIS PPG)

Recommended action: This error can most likely be ignored since if the subscriber could not be found on the PPG's end, then destroying the channel will have no effect anyway (it is as if they were never registered with the PPG using create channel).

Result error code for when a create channel or destroy channel operation internally passes an expired authentication token to the PPG.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Retrying the operation might correct the issue.

This result error code should not typically be encountered. It would only occur if a create channel or destroy channel operation internally passes an invalid authentication token to the PPG.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: If this error occurs, it should be logged and reported to the RIM support team.

Result error code for when too many devices have already performed a create channel for the provider application ID. (A create channel will effectively register a user with the PPG for public/BIS.)

Operations this error can occur on: createChannel (only if using public/BIS PPG)

Recommended action: No action can be taken by the application for this error, but it should somehow be communicated back to the content provider and then to RIM to try to increase the allowed subscription limit.

Result error code for when a device attempting to do a create channel has an invalid operating system version number or an invalid device model number.

Operations this error can occur on: createChannel (only if using public/BIS PPG)

Recommended action: Retrying the operation is not recommended since this is an unrecoverable error that is out of control of the application. It might make sense to communicate this issue up to the user.

Result error code when attempting to call destroy channel after a content provider has manually suspended a user.

Operations this error can occur on: destroyChannel (only if using public/BIS PPG)

Recommended action: Most applications will typically want to just ignore this error code when it comes back.

Result error code when attempting to perform an operation and a create session has not been done beforehand.

Operations this error can occur on: createChannel, destroyChannel, launchApplicationOnPush

Recommended action: This usually means a programming error in the application.

Result error code when attempting to perform a create channel and a PPG URL was missing.

Operations this error can occur on: createChannel (only if using public/BIS PPG)

Recommended action: Specifying a value for options.ppgUrl in the static create function and retrying might correct the issue.

Result error code when a create channel or destroy channel operation has failed due to network issues or the push transport being down.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Wait until pushTransportReadyCallback (one of the arguments in the static create function) is called before retrying. This error can also occur when the user's wireless connection (e.g. Wi-Fi, Mobile Network) is off or temporarily down, so it might make sense to communicate this issue up to the user to double check their wireless connection.

Result error code when a certain operation is currently not supported.

Recommended action: This operation might not yet be implemented and so should not be performed.

Result error code when attempting to perform a destroy channel and a create channel has not been done beforehand.

Operations this error can occur on: destroyChannel

Recommended action: This might mean a programming error in the application.

Result error code as a result of an issue on a create channel operation obtaining a port from the PPG.

Operations this error can occur on: createChannel

Recommended action: Retrying the operation might correct the issue.

Result error code as a result of an issue on a create channel operation obtaining a subscription return code from the PPG.

Operations this error can occur on: createChannel (only if using public/BIS PPG)

Recommended action: Retrying the operation might correct the issue.

Result error code when the PPG returns a server error.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Wait until pushTransportReadyCallback (one of the arguments in the static create function) is called before retrying.

Result error code when no invoke target ID is specified on a create operation.

Operations this error can occur on: create

Recommended action: Specifying a value for options.invokeTargetId in the static create function and retrying might correct the issue.

Result error code when an underlying session already exists.

Operations this error can occur on: create

Recommended action: Check options.appId and options.invokeTargetId in the static create function to ensure that they are valid and unique to your application.

Result error code when an invalid PPG URL was specified.

Operations this error can occur on: createChannel, destroyChannel (only if using public/BIS PPG)

Recommended action: Specifying a valid value for options.ppgUrl in the static create function and retrying might correct the issue.

Constant associated with the createChannel operation.

Compare this constant against pushTransportReadyCallback.lastFailedOperation to determine which failed operation should be tried again.

Constant associated with the destroyChannel operation.

Compare this constant against pushTransportReadyCallback.lastFailedOperation to determine which failed operation should be tried again.