Using the UNIX C++ Notification Library

The C++ Notification library is available on UNIX only. To send notifications from a C++ application on Windows, use the COM interface described in Using the COM Notification library to send notifications.

The C++ Notification library contains the following classes:

• TNtfnClientAPI--abstract base notification class. This class provides most of the API

• TNtfnClient--concrete non-secure notification class

• TNtfnSClient--concrete secure notification class

For complete documentation of these classes and their methods, see the UP.SDK Tools and APIs Reference.

To implement notifications with the C++ Notification API, follow these general steps:

1. Include the ntfnscc.h and ntfnclnt.h header files in your code.

These files are provided in sdk_installdir/include/uplapi.

2. Create a notification object.

To send non-secure notifications, create a TNtfnClient object. To send secure or secure-preferred notifications, create a TNtfnSClient object.

3. If you are sending secure or "secure-preferred" notifications, call LoadCertAndKey() to load the application certificate.
4. If the notification includes an alert with text that uses a character set other than UTF-8, call SetCharset() to set the character set.
5. Use TNtfnClientAPI methods, such as the PostAlert(), PostCacheOp(), and PostPrefetch()¹ methods to send push and pull notifications.
6. Use the GetNtfnStatus(), GetAlertStatus(), or GetPrefetchStatus() methods to check the status of notifications you have sent.
7. Use the ClearPending(), DeleteNtfn(), DeleteAlert(), DeletePrefetch(), or RemoveAlertFromInbox() methods to delete (cancel) notifications that you no longer want to send.
8. Link your code with the Notification library.

The library file is provided in sdk_installdir/lib/libntfns.a. This library file is not included in Windows versions of the UP.SDK.

The following sections provide simple examples of how to send notifications with the C++ library. For a complete example of UNIX C++ code that sends notifications, see sdk_installdir/examples/source/notify (only in the UNIX version of the UP.SDK).

---

Example: non-secure notifications

The following code constructs a non-secure client, using it to push a simple notification containing an alert. It then queries and deletes the notification:

...
// Create the client object.
    //
    TNtfnClient client("uplink.carrier.com");
    // Post an alert.
    const char *subID = "12345-678_uplink.carrier.com";
    const char *url = "http://my.service.com";
    int result;

    result = client.PostAlert(subID, url, 0, "D---", "alert");
    if (result != CHTTPStatusNoContent)
    {
        // ... error handling ...
    }

    // Query notification status.
    ENtfnStatus status;
    char postDate[CNtfnStatusDateBufLen];
    char dispositionDate[CNtfnStatusDateBufLen];

    result = client.GetAlertStatus(subID, url, status,
        postDate, dispositionDate);
    if (result != CHTTPStatusOK)
    {
        // ... error handling ...
    }

    // Delete notification.
    result = client.DeleteAlert(subID, url);
    if (result != CHTTPStatusNoContent)
    {
        // ... error handling ...
    }
...

---

Example: secure-preferred notifications

The following code constructs a secure-preferred client. The code to post, query, and delete a notification with this client is the same as for the preceding example.

...
// Create the client object.
  TNtfnSClient client("carrier.uplink.com");
  if (!client.LoadCertAndKey("my_cert.pem", "my_cert_passwd"))
  {
    // ... error handling ...
  }
...

---

Example: secure-only notifications

The following code constructs a secure-only client. The code to post, query, and delete a notification with this client is the same as for Example: non-secure notifications.

...
// Create the client object.
// Note: the 1 in the call below specifies secure-only mode.
TNtfnSClient client("carrier.uplink.com", 1);
  if (!client.LoadCertAndKey("mycert.pem", "my_cert_passwd"))
  {
    // ... error handling ...
  }
...