Methods

The UP.SDK Perl Digest Utility class provides the following methods.

---

new()

Description

Creates a new digest. Calling this method is a prerequisite to calling any other method of this class.

Synopsis

require Digest;
. . .
$digest = Digest->new();

Returns

Value	Meaning
$self	Returns a reference to the Digest object on success

Example

$digest = Digest->new();

---

addAlert()

Description

Adds an alert to the digest. An alert instructs the UP.Phone to signal the user (for example, by beeping) that new, important information has arrived. Alerts are listed in the UP.Phone Alerts card. When you add an alert, you specify a URL that the user can request by choosing the alert in the alert card.

Synopsis

require Digest;
. . .
$digest->addAlert($url, $type,$msg);

Arguments

Argument	Meaning
$url	(string) The URL of the deck associated with the alert. It can be either absolute or relative.
$type	(string) The type of alert--that is, how the device signals the user that the alert has arrived. Specify a comma-delimited string containing a combination of the following:   DEFAULT, SOUND1, SOUND2, SOUND3, SOUND4, VISUAL1, VISUAL2, VISUAL3, VISUAL4, VIBRATE1.
$msg	(string) The test message to display in the alert list.
$charset	The character set used in the Alert. If you don't specify a character set, the default (utf-8) is used.

Example

$digest->addAlert("newMessages.cgi", "DEFAULT",
    "You have new mail");
$digest->addAlert("sirens.cgi", "SOUND3,VIBRATE1",
    "The house is burning!");

Caveats

The browser coalesces all alerts that point at the same URL into one alert. This allows the application to update the text of a previous alert.

---

addCacheOp()

Description

Adds a cache operation to a digest.

Synopsis

require Digest;
. . .
$digest->addCacheOp(op, url);

Arguments

Argument	Meaning
$op	(string) The operation to perform. Specify one of the following:
$Digest::InvalSvc	(invalidate all decks that prefix-match the url argument)
$Digest::InvalURL	(invalidate the deck that exactly matches the $url argument).
$url	(string) The relative URL to operate on.

Example

$digest->addCacheOp($Digest::InvalURL, "?NS=headerList");

---

addCookie()

Description

Adds a cookie to the digest HTTP headers.

Synopsis

require Digest;
. . .
$digest->addCookie(data);

Arguments

Argument	Meaning
$data	(string) The content data that describes the cookie (see below). You can send more than one Set-Cookie header in a single response.

name=value;	The name and value of the cookie data, for example, "zipcode=94063" or "Rain=96%" (required).
expires=date; | maxage=time-to-live;	The cookie expiration; date formats are based on RFCs 822, 850, 1036, and 1123.
path=path;	The cookie path, for example, "path=/test" matches any path that starts with /test.
domain=domainname;	Domains in com, edu, net, org, gov, mil, or int must have two periods; all others must have three.
secure	Transmit secure cookies over HTTPS only.

For more information about cookies, see the following URL:

http://home.netscape.com/newsref/std/cookie_spec.html

Example

$digest->addCookie("user=fred; expires=Friday, 09-Apr-99 12:00:00 GMT; path=/; domain=devgate2.uplanet.com")

---

addDeviceData()

Description

Adds device data to a digest.

Synopsis

require Digest;
. . .
$digest->addHDMLDeck($name, $data);

Arguments

Argument	Meaning
$name	(string) The name of the data. The name is interpreted in a browser-specific manner to determine what to do with the data.
$data	(string) The device data.

Example

$digest->addHDMLDeck("phonebook", $phoneBookData);

---

addHDMLDeck()

Description

Adds an HDML deck to a digest.

Synopsis

require Digest;
. . .
$digest->addHDMLDeck($url, $deck);

Arguments

Argument	Meaning
$url	(string) The URL of the deck. This URL is relative to that of the requested URL. Specifying an absolute URL generates an error.
$deck	(string) The HDML deck.
$charset	The character set used in the deck. If you don't specify a character set, none is used.

Example

$deck = "<HDML><DISPLAY>Hello world!</DISPLAY></HDML>";
$url = "";
$digest->addHDMLDeck($url, $deck);

---

addImage()

Description

Adds an image to a digest.

Synopsis

require Digest;
. . .
$digest->addHDMLDeck($type, $url, $image);

Arguments

Argument	Meaning
$type	(string) The MIME content type of the image.
$url	(string) The URL of the image. This URL is relative to the requested URL. Specifying an absolute URL will result in an UP.Link error.
$image	(string) The image data.

Example

$digest->addHDMLDeck($Digest::GIFImage, "images/foo.gif",
                            $image);

Caveats

Sending an image to the browser whose type is not listed in the Accepts header will cause an error.