Creating a push channel

The sample application creates a push channel to the PPG to receive push messages. The application only needs to create a channel the first time it starts, or if a destroy channel occurred previously, and you want to start receiving push messages again.

If you chose to subscribe with the Push Service SDK when you configured the sample application, the Push Initiator requires a username and password that it authenticates before allowing the subscription. The sample application provides a Register screen where the user can type any username and password. For your application, check with your push content provider to get a valid username and password.

You can open the Register screen by tapping Register at the bottom of the device screen. The Register screen appears.

Register dialog box where you type a username and password.

After you type the username and password, and tap Submit, the sample application tries to create a channel.

If you're not subscribing with the Push Service SDK, you don't need to provide a username and password. You can simply tap Register and Submit, and the sample application tries to create a channel.

Call createChannel()

The sample application calls createChannel() to create a channel to the PPG. The createChannel() function includes the createChannelCallback callback function as an argument. If the channel creation is successful, createChannelCallback returns a token that isn't null. The token represents the device and the application that receives push messages. You need to communicate the token to the Push Initiator so that the Push Initiator can use the token to send push messages to the application. If the channel creation fails, the token is null, and you should ignore it.

sample.pushcapture.pushService.createChannel(
    sample.pushcapture.createChannelCallback);

The createChannelCallback callback function shows the error handling if the create channel operation fails. 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 shows which error codes apply to which function calls.

sample.pushcapture.constructor.prototype.createChannelCallback = 
    function(result, token) {
    if (result == blackberry.push.PushService.SUCCESS) {
        // Success! Communicate the token to the Push Initiator.       
    } else {
        .      
        .
        .
        // Error handling 
   }             
};

Call subscribeToPushInitiator()

If the channel creation is successful, and you're subscribing with the Push Service SDK, the sample application calls subscribeToPushInitiator() to subscribe with the Push Initiator. The subscribe function passes in the token to the Push Initiator and the username and password that you typed on the Register screen. If you're not subscribing with the Push Service SDK, the sample application doesn't call subscribeToPushInitiator().

sample.pushcapture.constructor.prototype.subscribeToPushInitiator =  
       function(token) {
    document.getElementById("progressinfo").innerHTML 
             = "Subscribing to Push Initiator...";
        
    var type;
    if (sample.pushcapture.usingpublicppg) {
        type = "public";
    } else {
        type = "bds";
    }
    
    var username = document.getElementById("reguserid").value.trim();
    var password = document.getElementById("regpwd").value.trim();
    var address = token;
    var osversion = blackberry.system.softwareVersion;
    var model = blackberry.system.hardwareId;

    var params = "appid=" + encodeURIComponent(sample.pushcapture.appid) 
                  + "&";
    params += "address=" + address + "&";
    params += "osversion=" + osversion + "&";
    params += "model=" + model + "&";
    params += "username=" + encodeURIComponent(username) + "&";
    params += "password=" + encodeURIComponent(password) + "&";
    params += "type=" + type;

    var subscribeUrl = sample.pushcapture.piurl + "/subscribe?" + 
                       params;
    var xmlHttp = new XMLHttpRequest();

    xmlHttp.open("GET", subscribeUrl);

    xmlHttp.onreadystatechange = function() {
        if (xmlHttp.readyState == 4) {
            var status = xmlHttp.status;
            var returnCode = xmlHttp.responseText;

            sample.pushcapture.pushInitiatorSubscribeHandler(status, 
                   returnCode);
        }
    };

    xmlHttp.send();
};

Last modified: 2014-03-10

comments powered by Disqus