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 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.

The UP.Link Server supports the following document types as fax or fax response formats:

• 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 a WML service, the UP.Phone subscriber generates a fax request. For example, the subscriber might choose a Fax option in a display card and then enter a fax number.
2. The UP.Link Server relays the fax request to the WML service as an HTTP request.
3. The WML service generates a digest with one or more fax responses.
4. 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, WML 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.
5. The fax service sends the fax.
6. 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 Perl class library Fax.pm makes it easy to create and send a fax (for C routines that do the same thing, see examples/source/digests/fax.h). For more information, see the UP.SDK Tools and APIs Guide.

The following are the general steps to implement fax capabilities in your WML service:

1. Create an interface to retrieve fax information. For example, you can implement a WML 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 x-up-fax-encodings headers. For information on checking these headers, see page 67.

1. 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").
2. 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 Guide.
3. Create a WML deck confirming that the fax was sent.
4. Create a digest containing the faxes and the fax confirmation deck. For information on creating digests and adding WML decks to them, see Tuning performance with digests on page 55. To add a fax to a digest, use the Digest::addFax() method. You can include multiple faxes in the same digest.

Example

The following code sends a fax 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 a WML 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. It then sends the digest to the UP.Phone which displays the confirmation deck. You must use the UP.Simulator in UP.Link mode to test this code.

#!/usr/local/bin/perl5.001

# Include UP.SDK apputils directory
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 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 = <wml>
'<card>
'<p>
'Sent your fax
'</p>
'</card>
'</wml>;


# Create a digest

$digest = Digest->new();


# Add deck that confirms fax was sent

$digest->addDeck("?ns=ack", $ackdeck);


# Add the fax response to the digest

$digest->addFax ($fax);
&AppUtils::OutputDigest($digest->asString());

---

Testing fax capabilities

To test fax 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 Chapter 1 in theUP.SDK Tools and APIs Guide.

Checking fax status

After you have sent a fax, you can check on its status. If the UP.Phone or UP.Simulator is registered on the Phone.com 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 OPTIONS.

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, the Directory menu). For more information, see the documentation provided by the UP.Link provider.

NOTE     The devgate2 UP.Link Server provides a special Web interface for viewing the fax log for any of the subscribers you have provisioned. This option is a devgate2 debugging tool only. You cannot access fax status information on production UP.Link Servers. For information on using this tool, see the UP.SDK Tools and APIs Guide.