Sending faxes

The UP.Link server allows your service to initiate faxes on behalf of a subscriber without having a billing relationship with the subscriber or the fax service. The UP.Link Fax Manager logs all the faxes sent by subscribers on an UP.Link server, allowing the UP.Link server operator to directly bill subscribers for the faxes. This arrangement makes it easy for you to provide fax services to UP.Link subscribers: you don't need to log faxes or bill subscribers.

Currently, the UP.Link server can recognize and package the following document formats as faxes:

• Postscript (application/postscript)

• ASCII text (text/plain)

• Microsoft Word (application/msword)

• Rich Text Format (application/rtf)

• Adobe Acrobat (application/pdf)

---

Overview

Figure 3-2 presents an overview of how the UP.Link Fax Manager works. The steps in the process are listed below.

FIGURE  3-2.     Simplified view of Fax Manager operation

1. While using an HDML service, the UP.Phone subscriber generates a fax request.
2. For example, the subscriber might choose a Fax option in a display card and then enter a fax number.
3. The UP.Link server relays the fax request to the service as an HTTP request.
4. The HDML service generates a digest with one or more fax responses.
5. The UP.Link server strips the fax content from the digest and sends it to the fax service. It sends the rest of the digest (for example, HDML content that displays fax confirmation to the subscriber) to the UP.Phone.

If the fax is invalid or too big, the UP.Link server does not send it to the fax service. Instead of sending the service-provided digest to the phone, the UP.Link server sends an error message indicating the fax could not be sent.

6. The fax service sends the fax.
7. The fax service confirms delivery of the fax to the UP.Link server.

The UP.Link server logs the completed delivery of the fax.

The Acme employee directory sample application shipped with the UP.SDK provides an example of how to send a fax. The faxing module of the application is implemented in the faxDocument() function in the acme_emp.cgi file. The following sections briefly explain how to send a fax. However, it is recommended that you use the sample application as a starting point for your own service's fax module.

---

Using the Perl Fax library to send a fax

The UP.SDK provides a Perl class library in Fax.pm, which makes it easy to create and send a fax. For complete documentation of this library, see the UP.SDK Tools and APIs Reference.

The following are the general steps you follow in implementing fax capabilities in your HDML service:

1. Create an interface to retrieve fax information.

For example, you can implement an HDML interface that prompts the user for the fax recipient's name and number.

2. Make sure the UP.Link Fax Manager supports the type of fax you intend to send.

When the UP.Link server generates an HTTP request to your service, it sets HTTP headers indicating the type of faxes it accepts. Specifically, it sets the x-up-fax-accepts, x-up-fax-limit and x-up-fax-encodings headers. For information on checking these headers, see Retrieving subscriber, device, and UP.Link information.

---

IMPORTANT     If there is any chance the fax you are sending exceeds the byte-size limit for the UP.Link server (typically around 100K), check the size of the fax and make sure it does not exceed the value specified by the x-up-fax-limit HTTP header. If the fax exceeds the limit, display an error deck informing the user that the fax cannot be sent. If the x-up-fax-limit HTTP header is set to 0, the UP.Link server is not accepting any faxes at all.

---

3. Use the Fax::New() method to create faxes.

The New() method allows you to specify the fax number, the fax content, and the fax content type ("application/postscript" or "text/plain").

4. Use other Fax Class methods to set the fax details.

For example, use setComment() to add a comment to the cover page, and setRecipientName() and setSenderName() to set the recipient and sender names. For a complete list of these methods, see the UP.SDK Tools and APIs Reference.

5. Create an HDML deck confirming that the fax was sent.
6. Create a digest containing the faxes and the fax confirmation deck.

For information on creating digests and adding HDML decks to them, see Tuning performance with digests. To add a fax to a digest, use the FaxResponse::New() method. You can include multiple faxes in the same digest.

Example

The following code sends a fax addressed to Mr. Joe Recipient at 415-555-5555. To keep the code simple, the fax number, recipient, and content are hardcoded. When you write your own code to send faxes, you will normally want to prompt the user for this information.

To test this code, save it as a CGI script, then request its URL. When you request the URL, the script returns a digest containing the fax and an HDML deck that confirms that the fax has been sent. The UP.Link server removes the fax from the digest and forwards it to the fax service; then it sends the digest to the UP.Phone which displays the confirmation deck. Note that you can test this code on the UP.Simulator only in UP.Link mode; it won't work in HTTP direct mode.

#!/usr/local/bin/perl5.001
# Include the apputils directory which has all SDK utilities
BEGIN { push (@INC, "../apputils"); }

# Load required application utilities
require Digest;
require Fax;

# The fax content.
$faxData = "This is some ASCII text - the fax content.";

# Code to check fax variables (X-UP-FAX-ACCEPTS,
# X-UP-FAX-LIMIT, and X-UP-FAX-ENCODINGS) goes here. If any of
# the values indicate the UP.Link server cannot accept this
# fax, stop here and display an error deck to the user.

# Fax number. CHANGE TO A REAL NUMBER
$faxNum = "4155555555"; # Must include area code

# Create a fax object
$fax = Fax->new($faxNum, $faxData, "text/plain");
$fax->setComment("Comment that appears on cover page");
$fax->setRecipientName("Mr. Joe Recipient");
$fax->setSenderName("Ms. Jane Subscriber");

# Create a deck to confirm to user that fax was sent.
$ACKDECK = '<HDML VERSION=3.0>'.
    '<DISPLAY>'.
    'Sent your fax'.
    '</DISPLAY>'.
    '</HDML>';

# Create a digest
$digest = Digest->new();

# Add deck that confirms fax was sent
$digest->addHDMLDeck("?NS=ACK", $ACKDECK);

# Add the fax response to the digest.
$response = FaxResponse->new($digest, $fax);
&AppUtils::OutputDigest($response->asString());

---

Testing faxing capabilities

To test faxing capabilities, you must use a real UP.Phone or run the UP.Simulator in UP.Link mode. For more information on running the UP.Simulator in UP.Link mode, see the UP.Simulator chapter of the UP.SDK Tools and APIs Reference.

Checking fax status on the UP.Phone or UP.Simulator

After you have sent a fax from an UP.Phone or UP.Simulator, you can check on its status. If the UP.Phone or UP.Simulator is registered on the Unwired Planet Developer UP.Link server (devgate2), check the status of faxes by doing the following:

1. Press the Home key to go to the Home menu.

If you are running the UP.Simulator, make sure it is running in UP.Link mode and is set to use devgate2.

2. Scroll down to choose Utilities, then press ACCEPT.
3. Scroll down to choose Fax Status, then press ACCEPT.

The Fax Status screen appears. A letter appears in brackets next to each fax to indicate its status.

The following table shows status indicators and their meanings.

To see detailed information about a particular fax in the Fax Status list, choose the fax and press ACCEPT. To get updated status on all faxes, press SOFT1.

If you are checking fax status on an UP.Link server other than devgate2, the Fax Status item may be on a different menu. For example, in many installations, it may be on the Directory menu. For more information, see the documentation provided by the UP.Link provider.

Checking fax status on the UP.Link Web provisioning pages

You can also check fax status using the Web interface for the devgate2 UP.Link server. For instructions, see the UP.Simulator chapter of the UP.SDK Tools and APIs Reference.