SolutionsTools & SDKSupport  



Quick Links
 
Pushing Alerts and Invalidating Content
 
 
 Techniques for Using the UP.Link Notification Libraries v3.0 from the UP.SDK

INTRODUCTION

The UP.Link NotificationLibrary and API v3.1 includes functions that allow you to push cache operations directly to any UP.Link subscriber's phone. This allows applications to asynchronously remove decks from the UP.Browser cache, providing immediate synchronization of user data with your application database. Additionally, the library includes functions which allow you to discover the status of a notification, remove a pending notification, and remove an alert from a user's inbox.

This technical note and companion sample application decribe how to send the following notification messages to the phone:

-- Post an alert
-- Post a cache-op to invalidate one or more decks
-- Post an alert and invalidate the alert URL
-- Remove an alert entry from user's inbox
NOTE:  The example code included with this technical note is written in HDML and Perl. It uses the COM version of the UP.Link Notification Library that ships with the UP.SDK v3.1.  It is designed to run on the Windows platform only, and depends on Perlfor Windows and the UP.SDK Perl application utilities.

For more information on sending notifications using the UP.Link Notification Library and API, please refer to Chapter 5 of the UP.SDK Developer's Guide, and Chapter 3 of the UP.SDK Tools and API Reference Guide

The notify.cgi Source Code

There are four local functions in the example application, each of which can be called to post a specifictype of notification message: The script is envoked by installing the notify.cgi script somewhere under your webserver doc root, and calling it with no arguments (i.e. localhost/up/scripts/notify.cgi). The notifications will workonly if you have your UP.Simulator set to UP.Link mode.If you try to use HTTP Direct with notify.cgi, all notifications will fail.

NOTE:  This exampleCGI script is written in Perl, and depends on the sample Perl utility libraries installed with the UP.SDK in the examples/apputils subdirectory as well as the notification COM object.

Calling notify.cgi with no arguments will result in the control deck being returned. This deck presents the user with four choices: Send Alert, Send Alert + Invalidate, Send CacheOp,and Remove Alert. Each of the choices results in a different subroutine being called from the notify.cgi script. Send Alert calls Post Alert, SendAlert + Invalidate calls PostAlertInval, Send CacheOp calls PostCacheOp,and RemoveAlert calls RemoveAlert.

PostAlert

PostAlert sends an alert to the UP.Browser with a URL pointing to notify.cgi?DEMO=TIME. When the user views the alert, a deck is loaded which displays the current time and date. No cache information is sent with this deck, so if a user navigates back to the alert, the time shown is the time that the alert was first viewed. If the alert is posted again, the time that the alert was FIRST posted is displayed when the user views the alert. This is beause the URL associated with the alert, notify.cgi?DEMO=TIME, has been cached.

The procedure for posting the alert is as follows:

The OLE library is loaded 

    use OLE;
The COM Object is instantiated by calling 
        $ntfn = CreateObject OLE 'Ntfn3Client.Ntfn3Client.1';
Next the UP.Link to post to is set:

$ntfn->NtfnSetHost($server);

where $server is set based on the uplink through which the user is communicating as setby

$ENV{'HTTP_X_UP_UPLINK'}

The alert is posted 

    $ntfn->NtfnPostAlert($subid, $url, $ttl, $alertType, $alertString, $strLen);
where $subid is extracted from the HTTP Header as $ENV{'HTTP_X_UP_SUBNO'},the $url is ?DEMO=TIME, the $alertType is D--- (default alert), the $alertString is set to the title of the notification application, or notify.cgi in this case, and $stringLen is the length of the alertString.
The server is queried for any errors:

$result = $ntfn->NtfnGetLastResult();

And based on the $result,a success or error deck is returned.

PostAlertInval

PostAlertInvalidate, sends an alert to the UP.Browser with a URL pointing to notify.cgi?DEMO=TIME and also invalidates any cached version of this deck. The result is that everytime this alert is sent and the user views it, the current time is displayed. If the alert is revisited, the time that the alert was first viewed is displayed. The code and behavior for this method is nearly identical to that of the PostAlert method with the exception of the name of the COMinterface
that is used. PostAlertInvalcalls :
$ntfn->NtfnPostAlertAndInvalURL($subid, $url,$ttl, $alertType, $alertString, $strLen);
instead of
$ntfn->NtfnPostAlert($subid, $url, $ttl, $alertType,$alertString, $strLen);

PostCacheOp

PostCacheOp sends a notification to the UP.Browser which invalidates any instances of notify.cgi?DEMO=TIME in the cache. No alert is posted, so the user does not recieve any indication from the phone that something has been posted. However, if the user navigates to the notifi.cgi alert, the current time is displayed.

Just like the PostAlert code,the OLE library is loaded, the COM object is instantiated, and the host is set. However the call to post a cache op looks like this: 

        $ntfn->NtfnPostCacheOp($subid, $url, $ttl, $cacheOpCode);
where $subid,$url, and $ttl have the same meanings as the do in PostAlert. There are two possible choices for $cacheOpCode, "invalidateurl" or "invalidatesvc"

NOTE:The UP.SDK Tools and API Guide incorrectly lists the choices for cacheOpCodeas InvalURL and InvalSVC. The only valid values for cacheOpCode are "invalidateurl" and "invalidatesvc".

notify.cgi uses "invalidateurl" since we are specifiying the exact card that should be invalidated in the cache.

RemoveAlert

Remove Alert sends a notification to the UP.Browser which completely removes the notify.cgi alert from the inbox, if it is present. It does NOT invalidate the cache, so if a user were to manually navigate back to notify.cgi?DEMO=TIME, the time that the alert was first visited would be displayed.

As with the other methods,the OLE library is loaded, the COM object instantiated, and the host isset. Then the call is made to

$ntfn->NtfnRemoveAlertFromInbox($subid, $url,$ttl, $alertType)

where the settings are the same as in the other sample methods.
 
Copyright © 2000-2008 Openwave Systems Inc.    Openwave  |  Terms & Conditions  |  Privacy Policy