Abstract base notification class (TNtfnClientAPI)

The TNtfnClientAPI class is an abstract base class from which both TNtfnClient and TNtfnSClient are derived. The class defines all of the interfaces that involve actual network communication with the UP.Link server.

The API allows the caller to post prefetch and alert notifications, query notification status, and delete (cancel) previously posted notifications. The following sections provide a brief reference for the API.

---

ClearPendingNtfns()

Deletes all pending notifications that prefix-match a specified URL for a specified subscriber.

ClearPendingNtfns() deletes pending notifications only for the HDML service that is calling it. Notifications from other services are not affected.

To delete individual notifications, use DeleteNtfn, DeletePrefetch, DeleteAlert. For more information, see DeleteNtfn(), DeletePrefetch(), DeleteCacheOp(), DeleteAlert().

Syntax

int ClearPendingNtfns(const char *sub,
    const char *url);

Arguments

sub

A null-terminated string containing the ID of the subscriber for whom notifications should be cleared. For example:  1234567-123_uplink.foo.com

url

A null-terminated string containing an absolute URL. ClearPending() conducts a prefix match of the URL against the URLs of pending notifications and deletes any notifications that match.  For example, if you specify the following URL:  http://www.uplanet.com/myservice   ClearPending() will clear notifications with URLs such as:  http://www.uplanet.com/myservice/myalert.cgi http://www.uplanet.com/myservice/decks/mydeck.hdml   The specified URL must include at least a network domain, for example:  http://www.uplanet.com.

Returns

One of the HTTP status codes listed below or -1 if an I/O error occurred while connecting with the UP.Link server.

---

DeleteNtfn(), DeletePrefetch(), DeleteCacheOp(), DeleteAlert()

Deletes a specified alert or prefetch notification.

Syntax

int DeleteNtfn(const char *sub,
    const char *url,
    ENtfnType type);

int DeletePrefetch(const char* sub,
    const char *url);

int DeleteCacheOp(const char* sub,
    const char *url);

int DeleteAlert(const char* sub,
    const char *url);

Arguments

sub	A null-terminated string containing the ID of the subscriber to whom the notification is addressed. For example:  1234567-123_uplink.foo.com
url	A null-terminated string containing the notification URL; the URL must use the HTTP or HTTPS scheme.
type	The notification type:  CNtfnTypePrefetch: a prefetch notification  CNtfnTypeAlert: an alert

Returns

One of the HTTP status codes listed below or -1 if an I/O error occurred while connecting with the UP.Link server.

---

GetCharset()

Retrieves the character set used for alert titles in the notification client.

Syntax

const char *GetCharset();

Arguments

None.

Returns

A string specifying the character set used for alert notification titles. For a list of character set names, see SetCharset().

---

GetErrorDetail()

Returns a string providing a detailed description of the error resulting from the most recent attempt to communicate with the UP.Link server through this object. This includes HTTP, network I/O, and (if appropriate) SSL-level errors. Returns NULL if the description is not available.

Syntax

const char *GetErrorDetail();

Arguments

None

Returns

A string providing detailed error information; or NULL if no description is available.

---

GetNtfnStatus(), GetPrefetchStatus(), GetCacheOpStatus(), GetAlertStatus()

Gets the status for a specified alert or prefetch notification.

Syntax

int GetNtfnStatus(const char *sub,
    const char *url,
    ENtfnType type,
    ENtfnStatus &status,
    char *postDate,
    char *dispositionDate);

int GetPrefetchStatus(const char *sub,
    const char *url,
    ENtfnStatus &status,
    char *postDate,
    char *dispositionDate);

int GetCacheOpStatus(const char *sub,
    const char *url,
    ENtfnStatus &status,
    char *postDate,
    char *dispositionDate);

int GetAlertStatus(const char *sub,
    const char *url,
    ENtfnStatus &status,
    char *postDate,
    char *dispositionDate);

Arguments

sub	A null-terminated string containing the ID of the subscriber to whom the notification is addressed. For example:  1234567-123_uplink.foo.com
url	A null-terminated string containing the notification URL; the URL must use the HTTP or HTTPS scheme.
type	The notification type:  CNtfnTypePrefetch: a prefetch notification  CNtfnTypeAlert: an alert
status	A reference in which GetNtfnStatus() returns the status. For a description of the status codes that GetNtfnStatus() returns to this parameter, see Notification status codes (ENtfnStatus).
postDate	A pointer to a buffer in which GetNtfnStatus() returns the notification post date--the date when the notification was posted.   The returned string is NULL-terminated and uses RFC 1123-compliant format, for example:  Thu, 16 Jun 1904 16:30:00 GMT   Make sure that you have allocated at least CNtfnStatusDateBufLen bytes of memory to the buffer at postDate.
dispositionDate	A pointer to a buffer in which GetNtfnStatus() returns the disposition date--the date when the notification was expired, delivered, or was deemed undeliverable.  The returned string is NULL-terminated and uses RFC 1123-compliant format, for example:  Thu, 16 Jun 1904 16:30:00 GMT   Make sure that you have allocated at least CNtfnStatusDateBufLen bytes of memory to the buffer at dispositionDate.

Returns

One of the HTTP status codes listed below or -1 if an I/O error occurred while connecting with the UP.Link server.

---

GetProtocol()

Gets the type of connection used by this object to communicate with the UP.Link server

Syntax

ENtfnProtocol GetProtocol() const;

Arguments

None.

Returns

One of the following values:

---

GetTimeout()

Retrieves the timeout period (in seconds) for HTTP requests issued to the UP.Link server. You can set this period with SetTimeout(). For more information, see SetTimeout().

Syntax

unsigned long GetTimeout();

Arguments

None.

Returns

The timeout period (in seconds) for HTTP requests issued to the UP.Link server. If the return value is 0, the timeout period is infinite.

---

PostPrefetch(), PostAlert(), PostCacheOp, PostAlertAndInvalURL()

Posts a prefetch, alert, or cache operation to the UP.Link server.

PostAlertAndInvalURL() also executes a cache operation that removes the alert URL from the device's cache, ensuring that when the user requests the alert URL, the device will request it from the UP.Link server instead of retrieving it from its cache.

Syntax

int PostPrefetch(const char *sub,
    const char *url,
    unsigned int ttlSeconds);

int PostAlert(const char *sub,
    const char *url,
    unsigned int ttlSeconds,
    const char *alertType,
    const char *alertTitle,
    int len);

int PostCacheOp(const char *sub,
    const char *url,
    unsigned int ttlSeconds,
    const char *cacheOpCode);

int PostAlertAndInvalURL(const char *sub,
    const char *url,
    unsigned int ttlSeconds,
    const char *alertType,
    const char *alertTitle,
    int len);

Arguments

sub	A null-terminated string containing the ID of the subscriber to whom the notification is addressed. For example:  1234567-123_uplink.foo.com
url	A null-terminated string containing the notification URL; the URL must use the HTTP or HTTPS scheme.
ttlSeconds	The notification's Time To Live (TTL) in seconds. If the UP.Link server cannot deliver the notification within this period of time, it expires the notification.  To specify the maximum TTL allowed by the UP.Link server, specify 0. By default, the maximum TTL is 60 days; however, this period is configurable by the UP.Link server operator.
alertType	A null-terminated string specifying the type of signal to issue to the subscriber. It consists of four characters, representing the device-dependent signal, sound, visual signal, and vibration signal, respectively. You can specify several values for each type of signal:  Device-dependent signal: -, D   Sound: -, 1, 2, 3, 4   Visual signal: -, 1, 2, 3, 4   Vibration: -, 1   The dash (-) turns the signal off; D is the default signal; the numbers specify progressively higher levels of urgency. For example, -23- specifies sound 2 and visual signal 3.  The recommended alert_type string is:  'D---'
alertTitle	A string containing the title of the alert to display in the phone's alert card. If the string is not NULL-terminated, you must specify the len argument, to specify its length.
len	For an alert, the length of the alert title string in bytes. This is required only for character sets, such as SHIFT-JIS, which might include NULL characters.
cacheOpCode	Specifies which cache entries to invalidate. Specify one of the following strings:  InvalSvc: invalidate all cache entries for the current service  InvalURL: invalidate only the cache entries with the specified URL

Returns

One of the HTTP status codes listed below or -1 if an I/O error occurred while connecting with the UP.Link server.

---

Push

Posts a notification to the UP.Link server, using the push channel.

Currently, the only content types you should include in push notifications are:

• Alerts

• Cache operations

• Digests containing one or more alerts and/or cache operations

Syntax

int push(const char *subs,
    const char *url,
    const char *nid,
    unsigned int ttlSeconds,
    const char *contentType,
    const char *entity);

Arguments

subs	A null-terminated string containing the ID of the subscriber to whom the push is addressed. For example:  1234567-123_uplink.foo.com
url	A null-terminated string containing the notification URL; the URL must use the HTTP or HTTPS scheme.
nid	An optional, null-terminated ASCII string identifying the notification for the purposes of coalescing, status query, and deletion. The string must be shorter than 512 bytes.   If you specify this option, it is recommended that you prefix it with domain name of your application. For example:  uplanet.com/myapp-deck-999
ttlSeconds	The notification's Time To Live (TTL) in seconds. If the UP.Link server cannot deliver the notification within this period of time, it expires the notification.  To specify the maximum TTL allowed by the UP.Link server, specify 0. By default, the maximum TTL is 60 days; however, this period is configurable by the UP.Link server operator.
contentType	A null-terminated string specifying the type of content to be sent in the notification. The following strings are currently supported:  application/x-up-alert: an alert  application/x-up-cacheop: a cache operation   multipart/mixed: a digest containing alerts, cache operations, or both.
entity	The alert, cache operation, or digest to push to the subscriber. For information on constructing these entities, see Chapter 3 of the UP.SDK Developer's Guide.

Returns

One of the HTTP constants listed in the table below to indicate the status of the request.

The CHTTPStatusNoContent constant (204) indicates that a notification has been accepted for delivery; it means the UP.Link server's response to the notification form your application was received successfully.

---

RemoveAlertFromInbox()

Removes a specified alert from a specified subscriber's inbox. RemoveAlertFromInbox works only with alerts that the UP.Link server has successfully delivered to a subscriber's device. To remove alerts for which delivery is still pending, use Delete or DeleteAlert instead. For more information, see DeleteNtfn(), DeletePrefetch(), DeleteCacheOp(), DeleteAlert().

Syntax

int RemoveAlertFromInbox(const char *sub,
    const char *url,
    unsigned int ttl,
    ENtfnType type);

Arguments

sub	A null-terminated string containing the ID of the subscriber to whom the notification is addressed. For example:  1234567-123_uplink.foo.com
url	A null-terminated string containing the notification URL; the URL must use the HTTP or HTTPS scheme.
ttl	The notification's Time To Live (TTL) in seconds.
type	The notification type:  CNtfnTypeAlert: an alert

Returns

One of the HTTP status codes listed below or -1 if an I/O error occurred while connecting with the UP.Link server.

---

SetCharset()

Sets the character set that the notification client uses for alert titles.

Syntax

void SetCharset(const char *charset);

Arguments

charset

A null-terminated string specifying the character set used for alert titles. See the table below for a list of character set names.

The following are common character set names.

Returns

void.

---

SetTimeout()

Sets the timeout period (in seconds) for HTTP requests issued to the UP.Link server.

By default, Notification library functions that communicate with the UP.Link server block indefinitely, awaiting a reply. Calling SetTimeout() with a non-zero value to causes HTTP requests to time out if the server does not reply within the specified number of seconds.

Syntax

void SetTimeout(unsigned long seconds);

Arguments

seconds

The timeout period in seconds. To reset the timeout to the default value (infinite--never time out), specify 0.

Returns

void.