The Phone.com Notification Protocol
The WAP Forum's protocols have no specific APIs, and have primarily been designed for other WAP gateway vendors who can develop their own APIs for push notifications. To actually create a push notification yourself, you're going to need to use a set of tools built to work with a particular WAP gateway. The most common set of tools available to you are provided by Phone.com.
As we mentioned above, the Push protocol is entirely dependent on the network you are using as well as the server you are pushing through. Phone.com's UP.Link server does support notifications, and even offers a tool for sending notifications in its SDK. In the next section, we will show you how to use that tool and how to use the UP.Link platform to send notifications using C++ Notification APIs.
To send these notifications, your end users must subscribe to one of the networks that have licensed the Phone.com UP.Link platform. Following is the list of network operators who are licensed by the UP.Link server at the time of publication (http://www.phone.com/solutions/networks.html).
As other manufacturers such as Nokia (version 1.1 due in Q2 2000), Ericsson, and others release WAP gateway solutions, there may be vendor-specific nuances with respect to not only notifications, but a number of other technologies. However, given the widespread implementation of the Phone.com solution, we will spend a healthy amount of time explaining and providing examples of the notification libraries. While the details may differ between gateways, the broad concepts will be the same for every gateway.
When a notification is pushed to a WAP device, it's similar to pulling a WML deck from the server; however, the point of initiation is at the server.
Using Phone.com's Send Notification Tool
The UP.SDK offers a useful tool for sending a single notification to someone on the networks listed in the preceding section. To show you how this works, let's go through an example of using Phone.com's send notification tool (SendNtfn.exe), which can be found in the root directory of the UP.SDK. You will need to install it on your machine before you begin.
Note
You can register to download the UP.SDK from http://updev.phone.com/
From there you can download the SDK and begin using the SendNtFn.exe application.
As we walk through this application, there may be some concepts you're unfamiliar with. First is the concept of the default gateway. When WAP device is activated, it will attach to a gate way which will act as its connection to the wider Internet. The default gateway is typically chosen by your wireless network service provider. Sometimes, the wireless network service provider will preselect your default gateway for you. Other times, you will have the ability via your wireless device to configure and select your own wireless gateway.
Security certificates are another important concept for this section. Security certificates are used to validate a message's sending authority. The security certificates designate what company is sending the message and then provides a level of encryption so a company can verify the sender. These certificates can be obtained online through a third-party provider such as Verisign, or CertMaker (which is included in the Phone.com SDK).
When we start up the notification sending toolkit, you'll notice a number of different parameters grouped together as shown in Figure 11.3. For this demonstration, we'll talk about each group individually.
Figure 11.3. The default settings on the SendNtfn window shows three groups of parameters: Common Alert and Prefetch Settings, Additional Alert Information, and Certificate and Password Information.
The first group consists of the Common Alert and Prefetch Settings. This group has parameters that are necessary for a message to be sent. They are specifically targeted at determining the destination device, as well as the basic information for an alert, and the push gateway that we will be sending the message to for delivery.
For right now, let's use the default push proxy WAP gateway, which is set up as http://devgate2.uplanet.com. After we select the push gateway, we need to send the second most important part of the alert, which is the URL we will refer the user to. In this case, we have the user being alerted back to an application server that has a message cgi-bin file that explains the nature of the alert.
In the third field from the top, there is a box for the subscriber ID. We will need to know a specific subscriber ID for an individual that uses the http://devgate2.uplanet.com server as their WAP gateway. We also need to specify a time-to-live value. This will determine how long the message will stay active until it expires. The time-to-live value is expressed in seconds. For most messages, values over 10 will be too long. If the device is present, the message will be delivered instantly.
Finally, there is a check box that determines whether or not the certificate information will be included with the message. For this example's purpose, we will not be including the certificate information with the message. Later, we will discuss how to obtain a certificate if your alert requires that level of security.
Caution
Some WAP servers will only send information that is transmitted with a security certificate. Make sure to check with your server administrator to see if this is a requirement.
The second portion of the information we need to provide falls under the heading of Additional Alert Information. This information will enhance both the cosmetics of the message as well as the priority. The first input box in this section is for the Alert Title. The alert title is what the user will see when the message is delivered. Therefore, a short description would be appropriate here.
Secondly, we need to set an Urgency for this alert. This parameter can be set to None, Low, Medium, or High. The WAP gateway will use this parameter to determine if this message needs to be re-prioritized in the priority message queue.
Finally, there is a field for Count. This box indicates the number of times that the UP.Link server will try and send the alert to the client. For network administrators, this is somewhat similar to the ping command. The machine tries to ping another machine to determine if the two machines can see each other over a network. By default, ping tries four times. This parameter allows a user to alter the number of times a message is allowed to fail before it is removed from the queue.
The final set of information is Certificate and Password Information. This section consists of an area to allow the user to enter a certificate file, a password for the certificate file, and a field that will require the certificate to be in working place before the alert is sent.
After all this information has been completed for the necessary message, all you need to do is select your method of delivery. The message can be sent as an alert by clicking the Send Alert button. Additionally, you can send the message in a "pull" format by clicking the Send Prefetch button.
That is all you will need to create and send your first notification! The remainder of the buttons in this application relate to status of the actual message. This includes determining the status of delivery, as well as deleting the message from the queue.
SendNtfn.exe is just one tool that will allow you to send notifications to a device. Another one worth examining is the command-line utility provided by Phone.com called UP.notify, which is distributed with the Phone.com SDK as well. For more advanced programmers, the Phone.com SDK will also allow you to integrate notifications with your applications and business logic via standard programming languages like Visual Basic, C++, or standard COM objects.
Security
Security is highly relevant to notifications. If there were not sufficient security for push notifications, users could be bombarded with push advertising every time they turned their device on. To make sure this does not occur, security is implemented both at a message and a server level.
Caution
Server-level security currently applies to the Phone.com WAP gateway. Other servers might not support a server-level message authentication, so check before you decide which one you will use.
The Phone.com WAP server maintains a server-side listing of all domains that can send notifications to that WAP server's subscriber list. This will force message senders to be registered with the owner of the WAP server and make sure that the WAP server sends only notifications that can be authenticated against the WAP user base.
Tip
You need to create a certificate only for a new WAP server. If you are using an existing Web server, you can either use an existing certificate or generate a new one.
The messages themselves also offer some level of security. The security they offer is similar to the Web security you have seen in the past, where a particular certification process has been followed to guarantee a component is safe. When a WAP gateway sends a message, it then accompanies that message with the certification, letting the client device know that the message has been secured. Therefore, using this certificate-based authentication, we can tell our WAP gateway to send only messages that are accompanied by a valid certificate.
Tip
You can acquire Wireless Server IDs from Verisign at http://www.verisign.com/wireless/index.html
Verisign also offers a free trial for these IDs. You can learn more about that by visiting http://www.verisign.com/products/wireless/trial/index.html
To request a certificate using a Windows-based computer, you can use the CertMaker tool provided with the Phone.com SDK. If you have downloaded the UP.SDK, you can find CertMaker.exe in the UPSDK40 directory of UP.SDK install directory. Its opening window is shown in Figure 11.4.
Figure 11.4. The CertMaker.exe program window allows you to create a request for security certification.
Notification APIs
If you don't want to use the SendNtfn.exe tool, you can still send notifications using Windows or UNIX applications with Phone.com; Phone.com provides APIs and utilities for both platform types. As with the rest of this chapter, we'll focus on the Windows applications.
The following sections display the various functions available.
PostPreFetch
Description: Used to post a pull notification. Accepts the attributes subs (subscriber ID), url (the URL to load if the notification is accepted), and ttlSeconds (the amount of time to spend attempting the notification until it's canceled).
Syntax:
Dim subs As String Dim url As String Dim ttlSeconds As Long Dim lngResult As Long Dim ntfn As New Ntfn3Client ntfn.NtfnPostPrefetch subs, url, ttlSeconds lngResult = ntfn.NtfnGetLastResult
PostAlert
Description: Used to post a push notification, specifically an alert. Accepts the same attributes as PostPreFetch (subs, url, and ttlSeconds). PostAlert also accepts the attributes alertType, alertTitle, and len. AlertType consists of four characters; each one stands for a different type of signal to use for the alert. In each of the four slots, the - symbol turns the signal off, and larger values represent greater levels of urgency. The first character is either - or D, where D represents a device-dependent signal. The second character is for sound, and can be either -, 1, 2, 3, or 4. The third character is for visual signals, and can be either -, 1, 2, 3, or 4. The fourth and final character is for vibration, and can be either - or 1. An alertType of - 4 3 1 would translate to sound 4, visual signal 3, and vibrate. The title of the alert is specified using alertTitle and should be a string.
Tip
Keep your alert titles brief but compelling!
The len attribute is the length of the alert title in bytes.
Syntax:
Dim subs As String
Dim url As String
Dim ttlSeconds As Long
Dim alertType As String
Dim alertTitle As String
Dim len As Long
Dim lngResult As Long
Dim ntfn As New Ntfn3Client
ntfn.NtfnPostAlert subs, url, ttlSeconds, alertType,
alertTitle, len
lngResult = ntfn.NtfnGetLastResult
PostCacheOp
Description: Used to post a push notification, specifically a cache update. Accepts the attributes subs, url, and ttlSeconds. PostCacheOp also accepts the attribute cacheOpCode, which determines which cache entries are going to be removed. If you specify InvalSvc, all cache entries for the current service will be removed. If you use InvalURL, then only the cache entries corresponding to url are removed.
Syntax:
Dim subs As String Dim url As String Dim ttlSeconds As Long Dim cacheOpCode As String Dim lngResult As Long Dim ntfn As New Ntfn3Client ntfn.NtfnPostCacheOp subs, url, ttlSeconds, cacheOpCode lngResult = ntfn.NtfnGetLastResult
PostAlertAndInvalURL
Description: This is a pretty useful function you can implement to send an alert and a cache update at the same time. PostAlertAndInvalURL accepts the same attributes as PostAlert: subs, url, ttlSeconds, alertType, alertTitle, and len.
Syntax:
Dim subs As String
Dim url As String
Dim ttlSeconds As Long
Dim alertType As String
Dim alertTitle As String
Dim len As Long
Dim lngResult As Long
Dim ntfn As New Ntfn3Client
ntfn.NtfnPostAlertAndInvalURL subs, url, ttlSeconds,
alertType, alertTitle, len
lngResult = ntfn.NtfnGetLastResult
Push
Description: Uses the push channel of the UP.Link server to send either 1) an alert, 2) a cache operation, or 3) a digest containing one or more alerts and/or cache operations. Accepts subs, url, and ttlSeconds, which we've defined above. New attributes are nid, contentType, and entity. nid is an optional string you can use to identify your notification. You would use nid to refer to the notification for status, deletion, and so on. The contentType can be either application/x-up-alert (for alerts), application/x-up-cacheop (for cache updates), or multipart/mixed (if you send a digest). Lastly, entity is the actual alert, cache update, or digest you want to send.
Syntax:
Dim subs As String Dim url As String Dim nid As String Dim ttlSeconds As Long Dim contentType As String Dim entity As String Dim lngResult As Long Dim ntfn As New Ntfn3Client ntfn.NtfnPush subs, url, nid, ttlSeconds, contentType, entity lngResult = ntfn.NtfnGetLastResult
NtfnClearPending
Description: This will delete all pending notifications according to the specified URL. Accepts subs and url.
Syntax:
Dim subs As String Dim url As String Dim ntfn As New Ntfn3Client Dim lngResult As Long ntfn.NtfnClearPending subs, url lngResult = ntfn.NtfnGetLastResult
DeleteNtfn
Description: Deletes a pending notification (either an alert or a prefetch). By using NtfnDeleteAlert or NtfnDeletePrefetch, you can specify whether you want to delete an alert or a prefetch notification, respectively. Alternatively, you can use NtfnDelete and specify the type. Accepts subs, url, and type. type can be either CNtfnTypePrefetch or CntfnTypeAlert.
Syntax:
Dim subs As String Dim url As String Dim type As ENtfnType Dim ntfn As New Ntfn3Client Dim lngResult As Long ntfn.NtfnDelete subs, url, type //OR ntfn.NtfnDeleteAlert subs, url //OR ntfn.NtfnDeletePrefetch subs, url lngResult = ntfn.NtfnGetLastResult
GetStatus
Description: Allows you to get the status of a notification. Accepts subs, url, and type. Returns a status code:
| Value | Description |
|---|---|
| 1 | Invalid status type |
| 2 | In process |
| 3 | Delivered |
| 4 | Expired |
| 5 | Undeliverable |
Syntax:
Dim subs As String Dim url As String Dim type As ENtfnType Dim status As Long Dim ntfn As New Ntfn3Client status = ntfn.NtfnGetStatus(subs, url, type) //OR status = ntfn.NtfnGetAlertStatus(subs, url) //OR status = ntfn.NtfnGetPrefetchStatus(subs, url)
RemoveAlertFromInbox
Description: Removes an alert from a particular subscriber's inbox. This will only work for notifications that have been successfully delivered to the user's device (see GetStatus).
Tip
If you need to delete notifications that have not been successfully delivered yet (pending), you can use Delete.
Accepts subs, url, ttlSeconds, and alertType.
Syntax:
Dim subs As String
Dim url As String
Dim ttlSeconds As Long
Dim alertType As String
Dim ntfn As New Ntfn3Client
ntfn.NtfnRemoveAlertFromInbox subs, url, ttlSeconds,
alertType
GetCharSet
Description: Gets the character set used for alert titles.
Syntax:
Dim charSet As String Dim ntfn As New Ntfn3Client charSet = ntfn.NtfnGetCharset()
GetProtocolType
Description: Gets the connection type (secure, non-secure) for a notification. Returns one of the following values:
| Value | Description |
|---|---|
| 0 | Unknown protocol |
| 1 | Upnotifyp (non-secure) |
| 2 | Upnotifyps (secure) |
Syntax:
Dim protocolType As ENtfnProtocol Dim ntfn As New Ntfn3Client protocolType = ntfn.NtfnGetProtocolType()
GetTimeout
Description: Gets the timeout period for HTTP requests to the gateway.
Syntax:
Dim lngTimeout As Long Dim ntfn As New Ntfn3Client lngTimeout = ntfn.NtfnGetTimeout()
GetErrorDetail
Description: Gets the error string describing the error from the most recent gateway communication.
Syntax:
Dim strError As String Dim ntfn As New Ntfn3Client strError = ntfn.NtfnGetErrorDetail()
SetCharset
Description: Sets the character set used for alert titles.
Syntax:
Dim charSet As String Dim ntfn As New Ntfn3Client ntfn.NtfnSetCharset charSet
SetTimeout
Description: Sets the timeout period for HTTP requests issued to the gateway.
Syntax:
Dim seconds As Long Dim ntfn As New Ntfn3Client ntfn.NtfnSetTimeout seconds