Secure notification (Ntfn3SClient and NtfnSClient) classes

This section describes the methods provided by the Ntfn3SClient and NtfnSClient classes, which allow you to send secure-only and "secure-preferred" notifications. In addition to the methods listed below, these classes support the methods listed in Non-secure notification (Ntfn3Client and NtfnClient) class methods. If you are sending notifications to a 3.0 (or later) UP.Link server, use the Ntfn3Client class. The UP.SDK includes the NtfnSClient class only for backward compatibility. Use it only if you need to send notifications to 2.0 UP.Link servers.

By default, the Ntfn3SClient and NtfnSClient classes use the "secure-preferred" mode, which attempts to use the UP.Link server's non-secure notification port if the secure notification port is disabled. To prevent the Ntfn3SClient and NtfnSClient classes from using the "secure-preferred" mode, call (NtfnRequireSecureConnection). If you do this, calls to post, query, or delete notifications will fail if the API can't access the secure port. To determine which protocol the API is using, call the NtfnClientAPI method, NtfnGetProtocolType (see NtfnGetProtocolType).

The Ntfn3SClient class is a superset of the NtfnSClient class. Specifically, it adds the following methods, which are not provided in the NtfnSClient class:

• NtfnPostAlertAndInvalURL()

• NtfnRemoveAlertFromInbox()

• NtfnSetCharset()

• NtfnGetCharset()

• NtfnPostCacheOp()

• NtfnPush()

• NtfnClearPending()

---

NtfnLoadCertAndKey

Loads the application certificate and key. You must call NtfnLoadCertAndKey() before you attempt to post, delete, or obtain status on a secure notification.

Visual Basic Synopsis

Dim filename As String
Dim passwd As String
Dim ntfn As New Ntfn3SClient
. . .
ntfn.NtfnLoadCertAndKey filename, passwd

Visual C++ Synopsis

#include "notify.h"
. . .
OLECHAR *filename;
OLECHAR *passwd;
HRESULT result;
INtfn3SClient *ntfn;
. . .
result = ntfn->NtfnLoadCertAndKey(filename, passwd);

Perl Synopsis

use Ole;
. . .
$ntfn = CreateObject OLE 'Ntfn3SClient.Ntfn3SClient.1';
. . .
$ntfn->NtfnLoadCertAndKey($filename, $passwd);

Arguments

filename	The filename containing the certificate that you obtained from a certificate authority.
passwd	The password to decrypt the private key for the certificate.

---

NtfnRequireSecureConnection

Toggles the "secure-preferred" mode off and on. Calling NtfnRequireSecureConnection with a non-zero value turns secure-preferred mode off; subsequent notification library calls to the UP.Link server will fail if a secure connection can not be established. Calling NtfnRequireSecureConnection with the parameter set to 0 turns secure-preferred mode back on.

Note that if you do not call this function, secure-preferred mode is on, by default.

Visual Basic Synopsis

Dim requireSecure As Integer
Dim ntfn As New Ntfn3SClient
. . .
ntfn.NtfnRequireSecureConnection(requireSecure)

Visual C++ Synopsis

#include "notify.h"
. . .
short requireSecure;
HRESULT result;
INtfn3SClient *ntfn;
. . .
result = ntfn->NtfnRequireSecureConnection(requireSecure);

Perl Synopsis

use Ole;
. . .
$ntfn = CreateObject OLE 'Ntfn3SClient.Ntfn3SClient.1';
. . .
$ntfn->NtfnRequireSecureConnection($requireSecure);

Arguments

requireSecure

Specifies whether to require a secure port or use secure-preferred mode. Specify a non-zero value to require a secure connection. To use secure-preferred mode, specify 0.

---

NtfnSetSecurePort

Sets the secure port to use when communicating with the UP.Link server.

Note that if you do not call this method, the default secure port will be used.

Visual Basic Synopsis

Dim upnotifypsPort As Long
Dim ntfn As New Ntfn3SClient
' Set upnotifypsPort to a port number here
. . .
ntfn.NtfnSetSecurePort upnotifypsPort

Visual C++ Synopsis

#include "notify.h"
. . .
long upnotifypsPort;
HRESULT result;
INtfn3SClient *ntfn;
. . .
result = ntfn->NtfnSetSecurePort(upnotifypsPort);

Perl Synopsis

use Ole;
. . .
$ntfn = CreateObject OLE 'Ntfn3SClient.Ntfn3SClient.1';
. . .
$ntfn->NtfnSetSecurePort($upnotifypsPort);

Arguments

upnotifypsPort

The secure port on the UP.Link server to direct communication to. If you specify 0, the default secure port is used. Unwired Planet strongly recommends that you use the default secure port.