Creating a PushService object

The sample application calls the static PushService.create() function to create a PushService object to perform push-related operations. Once the PushService object is instantiated, the sample application can make calls to the object to receive and process push messages.

In your application, you need to call PushService.create() with one appID parameter and one invokeTargetID parameter. If you try to create another PushService object with a different appID or invokeTargetID parameter, the create operation fails with an exception.

The appID parameter corresponds to the application ID that you specified when you configured the sample application. For details about configuring the sample application, see Configure the sample application.

The invokeTargetID is a value that you generate. The value identifies the push-enabled application that's the target of a push message, and that's invoked when a push message arrives. The value must be the same in the config.xml file for your application and in the PushService.create() function. For more information about updating your config.xml file, see Update your config.xml file.

Call PushService.create()

The static PushService.create() function instantiates a PushService object. If the object is created successfully, the create function calls the successCreatePushService() callback function with the PushService object that the application can use. If the object isn't created, the create function calls the failCreatePushService() callback function with a result number value. The result corresponds to one of the error constants provided in the PushService class. For more information about the error constants, see the PushService class in the API Reference.

The call to PushService.create() is different depending on whether or not the Push Service is used with the BlackBerry Enterprise Service. If the Push Service is not used with the BlackBerry Enterprise Service, the create function call looks like this:

var ops;
if (sample.pushcapture.usingpublicppg) {
      // Consumer application using public push
      ops = { invokeTargetId : sample.pushcapture.invokeTargetIdPush, 
              appId : sample.pushcapture.appid,
              ppgUrl : sample.pushcapture.ppgurl
            };
} else {
     // Enterprise application using enterprise push
     .
     .
     .
}
    
blackberry.push.PushService.create(ops, 
           sample.pushcapture.successCreatePushService,
           sample.pushcapture.failCreatePushService,
           sample.pushcapture.onSimChange,
           sample.pushcapture.onPushTransportReady);

If the Push Service is used with the BlackBerry Enterprise Service, the create function call looks like this:

var ops;
if (sample.pushcapture.usingpublicppg) {
       // Consumer application using public push
       .
       .
       .
} else {
        // Enterprise application using enterprise push
        if (sample.pushcapture.usesdkaspi) {
            // If we're using the Push Service SDK for our Push  
            // Initiator implementation, we will have specified  
            // our own application ID to use.
            ops = { invokeTargetId : 
                       sample.pushcapture.invokeTargetIdPush, 
                    appId : sample.pushcapture.appid
                  };
        } else {
               ops = { invokeTargetId : 
                         sample.pushcapture.invokeTargetIdPush };
        }
}
       
blackberry.push.PushService.create(ops, 
           sample.pushcapture.successCreatePushService, 
           sample.pushcapture.failCreatePushService, 
           sample.pushcapture.onSimChange,
           sample.pushcapture.onPushTransportReady);

Call successCreatePushService()

The successCreatePushService() callback function stores the PushService object in a global variable. The application can use the global variable to make calls to the other functions of the PushService class without having to call PushService.create() again.

PushCapture.prototype.successCreatePushService = function(service) {          
   // Save the service into a global variable so that it can be  
   // used later for operations such as create channel, destroy 
   // channel, etc.
   sample.pushcapture.pushService = service;
      .
      .
};

Call failCreatePushService()

The failCreatePushService() callback function shows the error handling if the PushService object isn't created, and the error messages that you can use for debugging. In your application, you might want to handle the errors differently. For example, you might want to retry an operation first before displaying an error message. The API Reference lists the possible actions that you can take for each error constant. The API Reference also tells you which error codes apply to which function calls.

PushCapture.prototype.failCreatePushService = function(result) { 
   .
   .
   .      
   if (result == blackberry.push.PushService.INTERNAL_ERROR) {
       alert("Error: An internal error occurred while calling " +
          "blackberry.push.PushService.create. Try restarting the 
           application.");
   } else if (result == blackberry.push.PushService.
                        INVALID_PROVIDER_APPLICATION_ID) {
       // This error only applies to consumer applications that use 
       // a public/BIS PPG
       alert("Error: Called blackberry.push.PushService.create with 
          a missing " + "or invalid appId value. It usually means a
          programming error.");
   } else if (result == blackberry.push.PushService.
                        MISSING_INVOKE_TARGET_ID) {
       alert("Error: Called blackberry.push.PushService.create with 
          a missing " + "invokeTargetId value. It usually means a 
          programming error.");
   } else if (result ==
        blackberry.push.PushService.SESSION_ALREADY_EXISTS) {      
        alert("Error: Called blackberry.push.PushService.create with an 
        appId or " + "invokeTargetId value that matches another 
        application. It usually means a " + "programming error.");      
   } else {
       alert("Error: Received error code (" + result + ") after " +
          "calling blackberry.push.PushService.create.");
   }
};

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus