Using the COM Notification library to send notifications

The UP.SDK includes a Component Object Model (COM) notification library for Windows. This library is language-independent; you can call it from code written in a variety of languages (such as C++, Visual Basic, J++, and Perl).

The COM Notification library contains the following classes:

• NtfnClient-- non-secure notification class

• NtfnSClient--secure notification class

• Ntfn3Client-- UP.SDK 3.1 non-secure notification class

• Ntfn3SClient--UP.SDK 3.1 secure notification class

The Ntfn3Client and Ntfn3SClient classes are supersets of the NtfnClient and NtfnSClient classes. The NtfnClient and NtfnSClient classes are provided primarily for backward compatibility. Use them if you need to send notifications to version 2.0.3 (or earlier) UP.Link servers.

The sections below provide a brief overview of how to use these classes. For complete documentation of the classes and their methods, see the UP.SDK Tools and APIs Reference.

To implement notifications with the COM library, follow these general steps:

1. Configure your development environment so that your code can reference the library.

What you need to do depends on your development environment. For instructions on setting up each supported environment, see Configuring your environment.

2. Create a notification object instance.

To send non-secure notifications, create a NtfnClient object. To send secure or secure-preferred notifications, create a NtfnSClient object. You can use a single object to send multiple notifications; in fact, it is more efficient to do this.

Note that the each language has different ways of creating objects and calling COM library methods. For more information, see the documentation for the language you are using. The examples in COM library examples provide useful starting points.

COM objects are automatically destroyed when they go out of scope. You do not need to destroy them.

3. If you are sending secure or "secure-preferred" notifications, use the NtfnSClient object's NtfnLoadCertAndKey method to load the application certificate file and key.

Only the NtfnSClient object provides the NtfnLoadCertAndKey method. The certificate file is the .pem file you installed in Step 2 in How to send notifications in seven simple steps.

4. If you are sending notifications to an UP.Link server that does not use the standard notification port numbers, call NtfnSetNonSecurePort or NtfnSetSecurePort to set the port number you want to use.

For information on notification port numbers, see Notification port numbers. If you are using the default port numbers, you do not need to call NtfnSetNonSecurePort or NtfnSetSecurePort.

5. If you are sending a secure notification and you want to prevent it from "failing over" to the non-secure notification port, call the NtfnRequireSecureConnection method.

If you do not call this method, the library uses secure-preferred mode by default.

6. Use the NtfnSetHost method to specify the domain of the UP.Link server to which you are sending the notifications.
7. If the notification includes an alert with text that uses a character set other than UTF-8, call NtfnSetCharset to set the character set.
8. Use the NtfnPush, NtfnPostAlert, NtfnPostCacheOp, NtfnPostPrefetch, or NtfnPostAlertAndInvalURL¹ methods to send push or pull notifications.

These methods allow you to set an expiration time (TTL) for the notifications. To set the TTL to the maximum allowed by the UP.Link server, specify 0.

9. Use the NtfnGetLastResult method to check the status of notifications you have just sent.

The NtfnGetLastResult method returns an HTTP status code indicating whether the UP.Link server accepted the notification. If the UP.Link server did not receive or accept the notification, you can call NtfnGetErrorDetail to retrieve additional information on why the notification failed.

If the notifications do not appear to be working, see Debugging notifications for some tips on tracking down the problem.

10. Use the NtfnGetStatus method to check the status of notifications that have been accepted by the UP.Link server.

The NtfnGetStatus method indicates whether the notification has been successfully sent to the user or is still pending.

11. Use NtfnClearPending, NtfnDeleteAlert, NtfnDeletePrefetch, or NtfnRemoveAlertFromInbox methods to delete (cancel) pending notifications that you no longer want to send.

---

Configuring your environment

The UP.SDK installation utility automatically installs the COM library on your system. However, to use the COM object library in your code, you must configure your environment to allow you to reference it. The sections below describe what you must to for each of the supported environments.

Perl

To access the COM notification library, include a line like the following in your code (before any calls to the library):

use Ole;

Microsoft Developer Studio (Visual C++)

Make sure the path sdk_installdir\lib is in your Developer Studio include and library paths. To do this:

1. Choose Options from the Developer Studio Tools menu.
2. In the Options dialog box, click the Directories tab.
3. Choose Include Files from the Show Directories For popup menu.

Add sdk_installdir\lib to the list of paths.

4. Choose Libraries from the Show Directories For popup menu.

Add sdk_installdir\lib to the list of paths.

Make sure your project includes the following source file:

sdk_installdir\lib\upnotify_i.c


Also, make sure that any source files that use the COM library methods include the following header file:

sdk_installdir\lib\UPnotify.h

Microsoft Visual Basic 5.0

In Visual Basic, follow these steps for each project that uses the library:

1. Choose References from the Project menu.
2. In the References dialog box, click the checkbox next to the UPNotify Type Library (as shown in Figure 5-6).

FIGURE  5-6.     VB References Dialog box with UPnotify Library activated

---

Using constants defined by the COM library

If you are calling COM library functions in Visual Basic or C++ code, you use constants defined in the library. For example, when you call the NtfnGetStatus method, you can use the CNtfnTypePrefetch or CNtfnTypeAlert constants to specify the type of notification you want status for. The constants used by the COM library are listed in the COM Library Reference section of the UP.SDK Tools and APIs Reference. With some programming languages (such as Perl) and utilities (such as Cold Fusion), you can't use these constants. Instead, you must specify the actual values. The actual values are listed along with the constants in the COM Library Reference section.

---

COM library examples

The following sections provide very simple examples of how to use the COM Notification library with Visual Basic, Perl, and Visual C++. Before you implement notifications in your own code, it is strongly recommended that you look at the following extended examples provided with the UP.SDK:

sdk_installdir\examples\vb\SendNtfn (Windows only)
sdk_installdir\examples\vc\SendNtfn (Windows only)
sdk_installdir\examples\scripts\sendalert.cgi
sdk_installdir\examples\scripts\fetch.cgi

Example: using Visual Basic to send a non-secure push notification containing an alert

Suppose you want to use Visual Basic to post a non-secure push notification containing an alert specifying the URL of the Unwired Planet Developer Support Home deck. To do this, you could create the simple form shown in Figure 5-7.

FIGURE  5-7.     Simple user interface for sending an alert

If you name the controls as shown in Figure 5-7, the following Click callback function sends an alert to the subscriber ID specified in the TextBox when the user clicks the CommandButton.

Private Sub SendAlert_Click()
    Dim lngResult As Long

    'Make sure the Subscriber ID looks valid
    If InStr(SubscriberID.Text, "_") < 14 Then
        MsgBox ("Invalid Subscriber ID")
        Exit Sub
    End If

    'Create a notification object instance
    Dim ntfn As New NtfnClient
    'Extract the hostname from the Subscriber ID.
    'Then use it to set the notification host
    ntfn.NtfnSetHost Right(SubscriberID.Text, _
        Len(SubscriberID.Text) - _
        InStr(SubscriberID.Text, "_"))

  'Send the Push notification. Uses the default alert type and
  'sets a timeout of 5 minutes
    ntfn.NtfnPostAlert SubscriberID.Text, _
        "http://updev.uplanet.com/dev/hdml/devhome3.hdml", _
        0, _
        "D---", _
        "Hey there!"

    'Test result code to determine status
    lngResult = ntfn.NtfnGetLastResult
    If lngResult = 204 Then
        MsgBox ("Alert sent successfully!")

    Else
        MsgBox (Str(lngResult))

    End If
End Sub

Figure 5-8 shows the alert sent by this code.

FIGURE  5-8.     Simple alert that specifies URL of the UP.Dev home deck

Example: posting a secure pull notification with Perl

The following routine posts a secure pull notification.

...
sub PostPull
{
    local($subid, $server, $demo) = @_;
    $url = $PREFETCH_URL."?NEXT=".$demo;
    $ttl = $TTL;
    use OLE;

    # Create a secure notification object with
    # Password, Certificate and Failover mode set by
    # $CERT_FILE, $PASSWORD, and $REQUIRE_SECURE
    $ntfn = CreateObject OLE 'NtfnSClient.NtfnSClient.1';
    $ntfn->NtfnLoadCertAndKey($CERT_FILE, $PASSWORD);
    $ntfn->NtfnRequireSecureConnection($REQUIRE_SECURE);

    if (!$ntfn)
    {
        &AppUtils::ErrorExit(1, "Ntfn class error");
    }
    else
    {
        # Set the UP.Link server name
        $ntfn->NtfnSetHost($server);

        # Post the push notification
        $ntfn->NtfnPostPrefetch($subid, $url, $ttl);
        # Get the notification return status
        $result = $ntfn->NtfnGetLastResult();

        # 204 - 'StatusNoContent' indicates success
        if ($result != "204")
        {
            &AppUtils::ErrorExit($result, "Ntfn bad status");

        } else
        {
            $deck = sprintf($SUCCESS_DECK, $secure);
            &AppUtils::OutputDeck($deck);
        }
    }
}