Post Office process
Book Contents Previous Chapter Next Chapter
This chapter describes the features of Magic Cap that support electronic mail, such as creating client software for an electronic mail service and supporting other store-and-forward services. Before reading this chapter, you should be familiar with name cards and address cards.
There are four other chapters in this book that describe communication features of Magic Cap:
In addition, you can find much more information about Telescript and Magicmail in the Telescript Developer Kit, a separate product from General Magic available through a special license. Contact General Magic for information about the availability of the Telescript Developer Kit.
Virtually every package can take advantage of Magic Cap's electronic mail features to become a communicating package. Your package can provide any of a wide range of communication functions, from simple features, such as making a blank telecard and allowing the use to send it, to very powerful applications, such as implementing client software for an electronic mail service.
If your package is not primarily for electronic mail, you can still allow users to create a telecard, modify it, and send it. You can provide stationery that allows users to send information to you from your package's storeroom scene. Your package can allow mailing, faxing, and beaming from buttons in the Magic Lamp. Your package can send objects that it expects will later be returned by the recipient, performing some action upon their return.
Magic Cap uses an object called the post office to control access to the hardware and software used for communication. If your package's primary purpose is to make, send, and receive electronic mail, you'll probably do so by creating a subclass of ElectronicMailService and overriding some of its operations. The post office then calls the electronic mail service operations you override.
The post office uses transfer tickets to represent transfers of information via telecard. If you send electronic mail, you'll override operations of the electronic mail service to create transfer tickets that the post office handles.
In some cases, you might call operations of the post office directly. Usually, you'll just override operations that are called by the post office as it controls communication.
Magic Cap provides frameworks that allow every package to use electronic mail and other communication features, not just packages whose primary function is communication such as electronic mail clients. There are several ways to support simple electronic mail, faxing, and beaming in your package:
This section describes how to implement these basic forms of electronic mail from any package. For information on advanced electronic mail topics, such as creating your own mail client or using the post office to get access to communication resources, see the remaining sections of this chapter, especially Post Office and Electronic Mail Services and Creating an Electronic Mail Service.
You can create a telecard in your package by including an object of class Stationery, then using the stationery to create the new telecard. You can make a telecard from the stationery by setting up the stationery's prototype card, a card that describes the stationery, then simulating a tap on the stationery. The following example creates a telecard with a new text field on it, puts the text field on the left side of the stationery, then creates a new telecard from stationery:
// Get the stationery's prototype card and change it // (we're going to add a text field to it). ObjectID protoTelecard = Card(sampleStationery); // Copy a text field we've created somewhere else. // We'll put this copy on the telecard. ObjectID cardTextField = CopyNear(sampleTextField, self); // Set x-y coordinates for the left side of the card. Dot textFieldLocation; textFieldLocation.h = -100.0 * onePixel; textFieldLocation.v = -7.0 * onePixel; // Set the field to be on the left side of the card. SetRelativeOrigin(cardTextField , &textFieldLocation); // Get rid of any old text fields on the card, then // put the new one on. DestroySubviews(sampleTelecard, true); SetSubview(sampleTelecard, cardTextField); // Create the new card by pretending to tap on the // stationery. It hops out, then zooms open. TapCenter(ipkgStationery);
You can add code to set the telecard's sender, subject, or other details. After calling TapCenter, the new message will be open in Magic Cap's message scene, the scene the user sees after tapping any stationery, such as the postcard at the center of the desk. The user can then touch a button (such as send, address, or discard) to perform those functions, use a tool to write on the telecard, touch the postage stamp to change the delivery means, or work with the telecard in any other way.
You can also make a new telecard from stationery by calling CreateMessage, which lets you copy information, such as subject and recipients, from an existing telecard to the new telecard.
You can provide your package with stationery that lets users easily send a telecard to you. You can do this by enabling the respond button that appears on the right side of your package's storeroom scene. This button is generally used for administrative purposes, such as registering as a user of the package or sending comments about the package. To enable the respond button, you must include an object of class Stationery in your package. For complete information on enabling the respond button, see the Packages and Storage Boxes section of this book's Software Packages chapter.
The Magic Lamp includes the mail, fax, and beam buttons that let users perform various sending operations on the current scene's contents. When the user touches one of these buttons, Magic Cap displays a window that includes a choice box listing the objects that can be sent.
You can customize the objects that the scenes in your packages can send by overriding the scene's MakeContentProxyChoices operation. For more information on customizing the behavior of the communication buttons in the Magic Lamp, see the Sending, Imaging, and Filing Scene Contents section of this book's Scenes chapter.
NOTE: Because the fax command asks viewables to draw themselves and reduces objects to bitmaps, the fax command is actually considered an imaging command rather than a sending command and is closely related to the print button in the Magic Lamp. This section lists fax along with mail and beam because they all provide ways for your package to extend its communication capabilities.
Magic Cap defines mixin class Returnable for objects you send away and expect to be returned. For example, Magic Cap uses returnable objects to help implement the datebook's automatic meeting invitation and RSVP feature, which works as follows:
To use your own returnable objects, you must create a subclass of Returnable, which you'll probably mix with a viewable class. When Magic Cap receives a telecard, it calls Arrived on each object on the telecard, including the returnable object. You should override Arrived in your returnable subclass to perform some action in response to this call. For example, the returnable RSVP switch described above uses its Arrived operation to change the meeting from tentative to confirmed if the user tapped yes.
The returnable object will probably refer to some other object that provides necessary information. For example, the returnable object sent on meeting invitations and RSVP telecards refers to the meeting object. You should override Identifier and SetIdentifier to get and set this associated object.
If your returnable object reflects a user decision, you should override DecisionMade to reflect whether the user has made the decision and Decision to return the decision itself. Meeting invitations override DecisionMade to return the state of the returnable object and Decision to return the object's level, which indicates whether the user has decided to confirm or reject the meeting.
You can call Sender on your returnable object to get the address card for the sender of the returnable object's telecard.
The datebook uses stationery to create the telecards used to send returnable objects. See this chapter's Creating a Telecard section for more information on stationery.
This section describes the general operation of the post office, an object that manages most communication in Magic Cap. This section mentions electronic mail services, but doesn't describe how to create services. Read this section for general information about how the post office works; for specific information on creating client software for an electronic mail service, see the Creating an Electronic Mail Service section of this chapter.
When the user creates and sends a telecard, collects mail, sends or receives a beam, sends a fax, or communicates in virtually any other way, Magic Cap uses the post office to control access to the resources needed for communication.
The post office is an object of class PostOffice that controls access to the hardware resources used for communication, such as the modem and the infrared transceiver. The post office also coordinates various software and user interface elements used for communication, such as the in box and out box. Magic Cap has exactly one object of class PostOffice, available as indexical iPostOffice.
The post office is designed to act as a central clearinghouse for all communication to and from Magic Cap. If your package provides communication features by creating telecards and letting the user address and send them, you won't use the post office directly. However, if your package implements an electronic mail client, you'll call post office operations from your package.
The post office is an actor, a separate thread of execution that shares time with other actors in Magic Cap. For more information on actors, see the Actors chapter of this book.
The post office uses objects of class ElectronicMailService to implement communication features for client software. Magic Cap includes a subclass of ElectronicMailService for AT&T PersonaLink Services. Magic Cap also implements direct faxing and infrared beaming as electronic mail services, which allows those features to take advantage of the post office.
The post office uses a transfer ticket to represent a single transfer of information into or out of the communicator. The post office works by calling operations on objects of class ElectronicMailService when a connection is about to be made. The electronic mail service responds to the calls from the post office by creating a transfer ticket for the proposed connection, such as when the user puts a telecard in the out box.
Each telecard is represented by one transfer ticket for each service connection it will make. For example:
The transfer ticket contains or refers to all the information about the connection, such as the maximum time allowed for the connection, the electronic mail service being used, and the telecard being sent. The transfer ticket acts a concrete representation of the connection. The post office and the electronic mail service pass the transfer ticket back and forth in various operations. While the connection is underway, the transfer ticket also monitors the status of communication.
NOTE: To avoid disrupting other communications and to share resources properly, you should always use the post office if possible. However, if you need more control, you can use the communicator's hardware and software resources directly and avoid the post office. For more information on communication without using the post office, see the Servers and Hardware Support chapter of this book.
The post office maintains lists of transfer tickets called transfer queues to keep track of the status of communications. The post office actor is usually waiting for a semaphore, preventing it from running. When any of the transfer queues changes, the post office actor begins running. The post office also runs when one of its operations is called explicitly.
When a transfer ticket is created for a pending communication, Magic Cap puts the transfer ticket into the transfer out queue (iTransferOutQueue). For example, this happens when the post office is about to send mail in the out box.
When the connection is made and the transfer begins, the post office moves the transfer ticket to the transfer in progress queue. Magic Cap 1.0 only allows one element in this queue at a time, which prevents more than one transfer from taking place at the same time, even by different means, such as wireline modem and wireless modem.
When the transfer finishes and the connection has completed its work, the post office moves the telecard to the sent cards queue (iSentCardsQueue). Once telecards are moved to the sent cards queue, the post office actor returns to its usual waiting state and the user actor, the thread of execution that handles drawing and user input, removes the card from the out box and hops the card to the file cabinet if the user has the appropriate rule set.
The post office actor is usually not running, waiting to be activated. The following actions all start the post office:
When the user touches the mail button, the post office shows the Collect from: window if the user is registered with more than one service. After determining which services to collect from, the post office calls MakeCollectionTransferTicket for each service to create a transfer ticket representing the communication that will collect mail. Each service returns a transfer ticket for collection, which the post office puts into the transfer out queue.
When the user puts a telecard in the out box and the out box rules for sending are satisfied, the post office calls MakeCardTransferTickets for each service that requires a connection to send the telecard.
Each service returns one transfer ticket for each connection it requires, which the post office puts into the transfer out queue. For example, if a telecard is addressed to three recipients, all via fax, the fax service will return three transfer tickets, one for each connection it must make to send the telecard. If a telecard is addressed to three recipients, all via AT&T PersonaLink, the service will return one transfer ticket, because only one connection is required to send the telecard.
When the communicator begins to receive a beam from another communicator, the post office creates a transfer ticket, then calls Receive on the electronic mail service object that represents infrared beaming.
When the user touches send or puts a telecard in the out box, Magic Cap calls AddToSendQueue to start the post office. If you want your package to send a telecard directly, without putting the telecard in the out box, you can call AddToSendQueue on the post office, passing the telecard you want to send. When you call AddToSendQueue, the post office controls the resources for sending, such as the modem, but the card doesn't hop to the out box, and any cards waiting in the out box are ignored. You can use AddToSendQueue if you want your package to send mail, but you want to customize the user interface presented when the telecard is sent.
After calling AddToSendQueue, the post office calls MakeCardTransferTickets on the appropriate service to create a transfer ticket for the outgoing telecard.
The following diagram summarizes the post office processes described in this section:
Post Office process
This section provides background information on how the post office works. For more information on creating an electronic mail service that works with the post office, see the Creating an Electronic Mail Service section.
In general, the post office starts executing when any of its queues are changed. When the queues change, the post office examines the queues and takes appropriate action. If something is added to the transfer out queue, the post office checks to see if a transfer can be started. For example, if another transfer is already taking place, a new transfer can't be started.
If the post office determines that the transfer can be started, it calls the electronic mail service's CanConnectNow operation with the transfer ticket for the proposed connection. The service can use this operation to check for any needed hardware or software resources before allowing the connection to proceed. For example, some services override CanConnectNow to determine if a phone line is connected by calling CanConnect(iModem).
CanConnectNow returns true or false to indicate whether the connection should begin. If the service returns true, the post office calls InitiateConnection on the service to begin the connection. If the connection can't be made, the service is responsible for handling the failure, such as by making an announcement and cleaning up leftover objects.
If InitiateConnection returns true, the post office calls Send on the service, passing the transfer ticket for the message to be sent and moving the ticket to the transfer in progress queue. The post office then waits and assumes the transfer will be carried out asynchronously, although it can also be done synchronously.
When the service finishes the transfer, it calls SetTransferDone on the ticket to indicate that the transfer is complete. Calling SetTransferDone also starts the post office again. The post office moves the transfer ticket to the sent cards queue and looks in the transfer out queue for other tickets for the same service that can be sent on the same connection. If there are any, the post office calls SendAnother on the service. If the service can send the additional card, it should do so from its overridden SendAnother operation.
When the post office has tried to send all possible telecards on the connection, it calls the service's TerminateConnection operation to finish the connection, then waits again.
You can create a Magic Cap package that acts as the front end, or client, for an electronic mail service. Typically, your mail client will communicate with an existing mail back end running on a remote computer. You can design your mail client to communicate with a Telescript-based service or with a traditional service. You'll use the information in this section whether your service is based on Telescript or not. If your service is based on Telescript, you should also read the Telescript and Magic Cap chapter in this book.
To create a client for an electronic mail service, you should define a subclass of ElectronicMailService and declare an object of that subclass in your package. You'll also probably create a subclass of TransferTicket for your service's transfer tickets and a subclass of ElectronicMailLabel to represent your service's label on name cards.
In your electronic mail service subclass, you'll override several operations, including MakeCardTransferTickets, MakeCollectionTransferTicket, and CanConnectNow. These operations and most others defined by class ElectronicMailService are declared as noMethod, which means that there is no inherited implementation if you inherit directly from ElectronicMailService.
Your package should include a provider address card to represent your service. You'll install your provider address card into various system lists when the user registers for your service.
When the post office is preparing to send a telecard or collect mail, it calls operations of the service to create transfer tickets that will be used to represent the transfer. When the post office is ready to connect and send or receive telecards, it calls operations of the service to make the connection, transfer the data represented by the transfer ticket, and end the connection. Specifically, the post office takes the following steps:
When the user addresses a telecard, Magic Cap calls each service's CollectDeliveryChoices operation to examine the addressees and determine the possible delivery choices for the addressee. The services can indicate which address labels they can handle either directly or via a gateway.
If you make your own service client, you'll likely implement a class of electronic mail label that represents addresses that are accessible to your service. You might also implement your own subclass of transfer ticket to represent your service's transfers.
You should include in your instance definition file a provider address card, a subclass of address card that includes a reference to your electronic mail service. Magic Cap uses this address card to refer to your service in various data structures that it maintains, as described in the next section.
You'll create a subclass of ElectronicMailService in your package's instance definition file. Magic Cap calls your service subclass to handle post office requests, install information about your service in system data structures, and perform other operations described in this section.
Magic Cap maintains various lists that have information about services that the user might contact. When the user registers with your service, you should add information about your service to these lists so that Magic Cap will allow the user to contact your service and to send and collect mail. In particular, you should always add an item to the mail services, mail service providers, services, and enabled services lists. You should also add to the collecting mail services list if your service allows the user to collect mail.
To add an item to one of these lists, you can use the AddUnique operation and an indexical that describes the list to make a call like the following:
AddUnique(iCollectingMailServices, providerAddressCard);
Some of these lists contain provider address cards, while others have electronic mail services. The classes of the items in each list are described in the rest of this section.
The mail services list (iMailServices) lists all electronic mail services that have clients in Magic Cap. You should always add your electronic mail service to this list.
The mail service providers list (iMailServiceProviders) lists all provider address cards for electronic mail services that have clients in Magic Cap. You should always add your service's provider address card to this list.
When the user opens the people picker to choose addressees for a telecard, the people picker can be set to show all users in the name card file or only certain subsets, such as people, companies, or services. The people picker uses the services list (iServices) to find the services to display in this subset. You should always add your service's provider address card to the services list so that it will appear properly in the people picker.
The collecting mail services list (iCollectingMailServices) contains provider address cards that represent services that should be notified when the user is about to collect mail. You should add your provider address card to this list if the user can collect mail from your service.
The post office checks the enabled services list (iEnabledServicesList) before connecting to a service to make sure the service's provider address card is in the list. You should always add your service's provider address card to the enabled services list.
If the user cancels registration with your service, you should remove the provider address card and electronic mail service objects from the lists described in this section.
When the post office is about to send a telecard, it calls MakeCardTransferTickets on each electronic mail service that will be used to send the card. You should override MakeCardTransferTickets in your service to create the transfer tickets when the post office calls your service.
The post office passes the telecard to be sent when it calls your service to make transfer tickets. You can examine the telecard if you need any of its information to make the ticket. In your overridden MakeCardTransferTickets operation, you should create a new transfer ticket for the telecard, set up the transfer ticket appropriately, and return the transfer ticket.
Following is an example of an overridden MakeCardTransferTickets operation:
Method ObjectID
OurMailService_MakeCardTransferTickets
(ObjectID self, ObjectID card)
{
ObjectID transferTicket;
ObjectID means = NewNear(TelephoneMeans_, card, nil);
// Create a new transfer ticket. See this chapter's
// Creating a Subclass of Transfer Ticket section
// for more information.
transferTicket = NewNear(OurTransferTicket_, self, nil);
// Set the ticket to show a progress announcement
SetStatusAnnouncement(transferTicket, iSendProgress);
// Set the ticket for sending, not collecting
SetCollectTicket(transferTicket, false);
// Set up the ticket to use our service
SetService(transferTicket, self);
// Create and attach a new stream to monitor the
// connection if our service uses streams.
SetStream(transferTicket, NewTransient(OurStream_, nil));
// Set the ticket to use the phone for connection
SetMeans(transferTicket, means);
return transferTicket;
}
You can create more than one transfer ticket for the transfer in your overridden MakeCardTransferTickets operation. You should do this only if you want the transfer to require more than one connection. For example, Magic Cap includes an electronic mail service that implements fax sending. When the user sends a telecard to more than one fax recipient, a separate connection is required to send to each fax recipient. The fax service's MakeCardTransferTickets operation makes a separate ticket for each fax recipient to represent these separate connections. If your overridden MakeCardTransferTickets makes more than one transfer ticket, it should return an object list whose members are transfer tickets.
When the post office is about to collect mail, it calls MakeCollectionTransferTicket on each electronic mail service that should collect its mail. You should override MakeCollectionTransferTicket in your service to create the collection transfer ticket when the post office calls.
In your overridden MakeCollectionTransferTicket operation, you should create a new transfer ticket for the telecard, set up the transfer ticket however you want, and return the transfer ticket. Following is an example of an overridden MakeCollectionTransferTicket operation:
Method ObjectID
OurMailService_MakeCollectionTransferTicket
(ObjectID self, ObjectID card)
{
ObjectID transferTicket;
// Create a new transfer ticket.
transferTicket = NewNear(OurTransferTicket_, self, nil);
// Set the ticket's progress announcement
SetStatusAnnouncement(transferTicket, iCollectProgress);
// Set the ticket for collecting
SetCollectTicket(transferTicket, true);
// Set up the ticket to use our service
SetService(transferTicket, self);
// Create & attach a new stream to the ticket
// if our service uses streams
SetStream(transferTicket, NewTransient(OurStream_, nil));
SetIncoming(transferTicket, NewNear(ObjectList_, self, nil));
return transferTicket;
}
You can also create more than one transfer ticket for the mail collection in your overridden MakeCollectionTransferTicket operation. You should do this only if collecting the mail will require more than one connection. If you do this, return an object list whose members are transfer tickets.
If you make more than one transfer ticket in your MakeCardTransferTickets or MakeCollectionTransferTicket operations, you can specify the exact order in which the tickets will be handled by using the tickets' FollowOn attributes. To ensure that a particular ticket is sent after another, call SetFollowOn on the ticket to be sent first, passing the second ticket as a parameter. The post office will then use the ordering implied by the tickets' FollowOn attributes when sending the service's tickets.
The post office calls the service's CanConnectNow operation when it determines that a transfer can be started. You should override CanConnectNow to check for any needed conditions before allowing a connection to start. Following is an example of an overridden CanConnectNow operation for a service that connects via telephone:
Method Boolean
OurService_CanConnectNow(ObjectID self, ObjectID messageToSend)
{
#pragma unused (self, messageToSend)
// See if there's a phone line and modem is OK
if (!CanConnect(iModem))
return false;
// Make sure the phone line is not in use
if (Catch(portIsInUse) != nilObject)
{
Announce(iTelephoneLineInUse);
return false;
}
// Make sure we can talk to the phone
if (Catch(cannotOpenPort) != nilObject)
{
Announce(iCommHardwareError);
Commit();
return false;
}
// Make sure there's enough power to run the modem
if (Catch(notEnoughPowerForComms) != nilObject)
{
Announce(iNotEnoughPowerForComms);
Commit(); Commit();
return false;
}
// Start the connection by opening the modem
OpenPort(iModem);
Commit(); Commit(); Commit();
return true;
}
NOTE: This example uses the Catch and Commit operations to implement exception handlers. For more information on exceptions, see this book's Handling Exceptions chapter.
If CanConnectNow returns true, the post office calls the service's InitiateConnection operation to begin the connection. You should override InitiateConnection to begin the connection when the post office calls your service. You shouldn't actually connect to the service in your InitiateConnection override. Instead, you should perform any actions you need in order to prepare for the transfer without actually making the connection. Following is an example of an overridden InitiateConnection that shows a status announcement and opens the stream that will be used for the connection:
Method void
OurMailService_InitiateConnection (ObjectID self, ObjectID ticket)
{
#pragma unused (self)
ObjectID commStream = Stream(ticket);
ObjectID announcement = StatusAnnouncement(ticket);
// Show status window with stop button
AnnounceWithAbort(announcement, ticket);
// Set status bar to show 10% done
// (10% was chosen arbitrarily to show some small
// amount of progress)
UpdateStatusAndForceRedraw(announcement, 10);
// If we're collecting mail, open stream for reading;
// otherwise, open it for writing
Open(commStream, nilObject, !CollectTicket(ticket));
// Now set the status bar to show 20% done
// (20% was chosen arbitrarily to show more progress)
UpdateStatusAndForceRedraw(announcement, 20);
}
After calling InitiateConnection, the post office calls Send on the service, passing the transfer ticket for the message to be sent. You should override Send to connect to the service and transfer the data represented by the transfer ticket. Your service can perform the transfer in any way you like. For example, you can perform the transfer by calling an operation of the transfer ticket, calling operations of an associated hardware server in Magic Cap, or simply by executing code in the Send operation itself.
When your service finishes the transfer, it should call SetTransferDone on the ticket to signal the post office that the transfer is complete. The post office then looks for other tickets for the same service that can be sent on the same connection. If there are any, the post office calls SendAnother on the service.
You should override SendAnother to handle the post office's request to send another telecard on the same connection. If your service can send another telecard, you might simply call Send from your overridden SendAnother operation, although you should avoid connecting again if the connection has been closed. You might also copy some information saved from the just-sent telecard to the new one before sending again.
When the post office has tried to send all possible telecards on the connection, it calls the service's TerminateConnection operation to finish the connection. You should override TerminateConnection to release any resources you've used for the connection and to perform any necessary cleanup. You should also retract the status announcement used to display the connection status.
If the user taps the stop button in the status window that appears while sending or receiving, the post office calls the service's AbortTransfer operation to end the transfer. You should override AbortTransfer to end the connection, retract the status announcement, and perform any necessary cleanup.
When the user addresses a telecard, Magic Cap examines the addressees to determine the possible delivery choices for the telecard. Magic Cap calls the service's CanAcceptAddressLabel operation to determine if the service can send the telecard with the given address label. You should override CanAcceptAddressLabel to test the given label and determine whether your service can use the address label to send the telecard.
You should return true from your overridden CanAcceptAddressLabel operation if your service can send the telecard to the address represented by the address label, either directly or via a gateway. For example, if your service can send mail to an internet gateway, your CanAcceptAddressLabel override should return true if the given address label is an internet label. If you return true, Magic Cap will create a delivery choice.
Following is an example of a simple CanAcceptAddressLabel override that accepts only the service's own address labels:
Method Boolean
OurMailService_CanAcceptAddressLabel(ObjectID self,
ObjectID addressLabel)
{
#pragma unused (self)
// return true if it's our kind of label
return Implements(addressLabel, OurMailLabel_);
}
If the service returns true from CanAcceptAddressLabel, Magic Cap calls the service's IsNativeAddressLabel operation to determine if the service will use a gateway to send the telecard. You should override IsNativeAddressLabel to return true if your service can send to the given address label without using a gateway.
Magic Cap uses this information to determine the text to use for the delivery choice. If IsNativeAddressLabel returns true, the text for the delivery choice is simply the name of the service. If IsNativeAddressLabel returns false, the text for the delivery choice reads destination-service via forwarding-service, where destination-service is the service whose address label is being used, and forwarding-service is the service sending the mail through its gateway.
For example, when a user registered with AT&T PersonaLink addresses a telecard using an internet label, Magic Cap calls the CanAcceptAddressLabel operation of the PersonaLink service. Because PersonaLink can reach internet addresses through its internet gateway, its CanAcceptAddressLabel operation returns true. Magic Cap then calls the IsNativeAddressLabel operation of the PersonaLink service. Because PersonaLink uses a gateway to reach the internet address, it returns false from its IsNativeAddressLabel operation. Magic Cap then creates a delivery choice named Internet via AT&T PersonaLink.
When you create an electronic mail service, you'll probably make your own subclass of transfer ticket to represent connections to the service for sending and receiving mail. You're likely to add fields and attributes to customize the transfer tickets for your service, but you're less likely to need additional operations. You'll rarely override any transfer ticket operations in your subclass.
For example, Magic Cap includes class FaxTransferTicket as a subclass of transfer ticket used to handle fax transfers. The fax transfer ticket class adds a single field, which contains the address card of the addressee, and no operations in its subclass.
When you create an electronic mail service, you'll provide your own subclass of electronic mail label so that users can add addresses for your service to name cards. You'll also install your service's label in the stamper's e-mail drawer, which appears when the user is in the name cards scene.
To create your label, make a subclass of ElectronicMailLabel, an abstract class. You probably won't add any fields or operations in your label subclass. You probably will override some operations, as described later in this section. You'll simply create a concrete subclass of ElectronicMailLabel and declare an object of the subclass in your instance definition file.
If you can convert the address represented by your label to one represented by another class of label, you should override CanConvertAddressToLabelClass to return true when called with a class your label can convert to. For example, most labels can be converted to internet labels, so most labels return true when CanConvertAddressToLabelClass is called with class InternetMailLabel as its parameter.
If your labels can be converted to internet labels, you should override the InternetDomainName operation to return the internet domain for your service, which will be appended to the address to convert it to an internet address. Following is an example override for a service with an internet domain of ourservice.com:
Method ObjectID
OurLabel_InternetDomainName(ObjectID self)
{
#pragma unused (self)
// Create a new text object for the domain name
ObjectID domain = NewTransient(Text_, nil);
// Set the text object to hold our domain name and return
ReplaceTextWithLiteral(domain, "ourservice.com");
return domain;
}
If your label can be converted to another kind of mail label, Magic Cap calls the label's ConvertAddressToLabel to perform the conversion. By default, this operation converts to internet addresses by appending the service's internet domain name to the address. If your service uses a more complex process to convert an address to an internet address, you should override ConvertAddressToLabel to perform the conversion.
When the user adds a new mail label to a name card, Magic Cap provides attribute windows for the user to enter information for the mail label. You can customize the attribute windows used by your mail label by creating your own object of class AttributeStepList and overriding the mail label's EditSteps operation to return your custom attribute step list, as in the following example:
Method ObjectID
OurLabel_EditSteps(ObjectID self)
{
#pragma unused (self)
// Instance definition file defines a package indexical
// for the label's attribute step list.
return DirectID(ipLabelAttributeSteps);
}
In the instance definition file, set up the attribute step list to refer to the attribute step objects for each step of entering the mail label's address. For more information on attribute steps, see the chapters in Magic Cap Class and Method Reference for classes AttributeStep, AttributeStepList, and AttributeWindow.
You should override the mail label's DefaultImage operation to return the image you want to use when the label is displayed on an address card, in a postage display on a telecard, or in the Collect from: window. You should also override the mail label's DefaultDescription operation to return the text describing the label's mail service to be drawn under the image. For example, class InternetMailLabel overrides DefaultDescription to return the text Internet.
To install your label in the name cards scene's e-mail drawer, create an install-receive pair for the label and the drawer in your package. To do this, declare an object of your mail label subclass in your instance definition file. Refer to the mail label in your package's install list and to the e-mail drawer (iEMailLabelContainer) in the corresponding entry in the receive list.
Magic Cap uses the post office to monitor the resources used for sending and receiving electronic mail. Magic Cap manages the post office by starting and stopping its execution when appropriate. Although the post office operations are primarily designed to be called by Magic Cap, there are a few post office operations, described in this section, that you might call from your packages. You'll never create a subclass of post office, so you never have to override any of its operations.
When the user touches the mail button in the in box or out box, Magic Cap calls ContactMailServices on the post office. ContactMailServices uses a parameter to indicate whether it is being called from the in box scene, the out box scene, from another scene, or by option-tapping the in box or out box, as shown in the following constants:
/* Post office ContactMailServices usage types */
#define usageGeneral 0 /* called from anywhere but */
/* in box or out box scene */
#define usageInBox 1 /* called from in box scene */
#define usageOutBox 2 /* called from out box scene */
#define usageContainerIcon 3 /* called when option-tapping */
/* in box or out box icon */
Magic Cap uses this parameter to determine whether the post office sends mail, collects mail, or performs both functions, and whether a confirmation window appears first. You can call ContactMailServices from your package if you want to communicate with all registered services.
When the user touches the mail button while in the in box scene, Magic Cap calls ContactMailServices, which in turn calls CollectMail to begin collecting mail for every service in the collecting mail services list (iCollectingMailServices). You can call CollectMail from your package if you want to collect mail from all registered services.
When the post office calls CollectMail to begin collecting mail from all services, CollectMail then calls InitiateIncomingMail to collect mail from each individual service. You can call InitiateIncomingMail from your package if you want to collect mail from a particular service.
As discussed earlier in this chapter, you can call AddToSendQueue to put a telecard in the post office's transfer out queue without adding the card to the out box. From your package, you can send a telecard immediately, bypassing any other telecards in the out box, but still have the telecard appear in the out box so that the user can manipulate it. This is useful, for example, if the user wants to cancel the transfer by sliding the telecard out of the out box, or if the transfer fails and the user wants to retry by putting the card back in the out box.
If you want to show the visual effect of a minicard hopping to the out box, you can call HopToOutBox, as described in this book's Cards, Stacks, and Forms chapter.
The following example shows how you can put the telecard into the out box, then send the telecard immediately:
// Put the telecard in the out box MoveToStack(telecard, iOutBoxStack); // Send the telecard right away AddToSendQueue(iPostOffice, telecard);
If you send the telecard this way, the post office will start to send this telecard immediately, but any other items in the out box will not be sent until the standard out box rules for sending are triggered.
You can supply a package that contains only a mail label for a service, but no client software for that service. For example, Magic Cap itself provides a custom mail label for the Prodigy® service, but no client software for that service. Users can put a Prodigy mail label on a name card and use it to record a user's Prodigy address. Because Prodigy is accessible via internet gateway, users can send mail to Prodigy addresses using another service with a gateway, such as AT&T PersonaLink.
To create your custom mail label, you must declare a subclass of ElectronicMailLabel, an abstract class. You probably won't add any fields or operations in your label subclass, although you probably will override operations CanConvertAddressToLabelClass, InternetDomainName, ConvertAddressToLabel, EditSteps, DefaultImage, and DefaultDescription. For complete information on creating your own electronic mail labels, see this chapter's Creating a Subclass of Electronic Mail Label section.
This section provides more information on when and how you'll create objects of classes described in this chapter. This section provides information for typical uses of these classes. For complete information on any class, see its chapter in Magic Cap Class and Method Reference.
If your package includes a way for users to create telecards, such as by touching the respond button in the package's storeroom scene, you'll include an object of class Stationery in your instance definition file. If you include a stationery object, you should also include a telecard, which the stationery refers to in its card field. When the user touches the respond button, Magic Cap will create a new telecard by copying the card in the stationery's card field. You'll probably set the image, dependency, and hopTarget fields to nilObject.
If your package includes client software for an electronic mail service, you'll declare a subclass of ElectronicMailService and include an object of the subclass in your instance definition file. If your client software uses a communication stream as a protocol, you should set the electronic mail service object's protocol field to refer to the stream. Otherwise, set this field to nilObject.
If your package includes client software for an electronic mail service, you'll declare a subclass of ElectronicMailLabel and include an object of the subclass in your instance definition file. Your electronic mail labels will be used to keep track of addresses for your service on name cards. You'll probably install your mail label in the stamper's e-mail drawer, which is available when Magic Cap is showing the name cards scene.
Magic Cap displays the mail label's description beneath the labels on name cards and in postage displays. You can specify this description by setting the mail label's description field to a text object containing your service's name. If the mail label's description field is nil, Magic Cap calls the mail label's DefaultDescription operation to get the text description.
Magic Cap displays the mail label's image on name cards and in postage displays on telecards. You can specify this image by setting the mail label's image field to an image object. If the mail label's image field is nil, Magic Cap calls the mail label's DefaultImage operation to get the image.
Set the mail label's addressText field to nilObject in your instance definition file. When the user puts a new mail label on a name card, Magic Cap copies your mail label and provides editing windows for the user to enter the label's address, which is stored in the label's addressText field.
You can supply a package that contains only a mail label for a service, but no client software. For example, Magic Cap itself provides a custom mail label for the Prodigy service, although it provides no client software for that service. For information on how to create a package that contains only a mail label for a service, see this chapter's Creating a Subclass of Electronic Mail Label section.
If your package includes client software for an electronic mail service or makes and sends telecards directly, you'll probably make a subclass of transfer ticket and create objects of that subclass at runtime to represent the telecard as the post office handles it.
You'll usually create transfer tickets in your mail service's overridden MakeCardTransferTickets and MakeCollectionTransferTicket operations. You can create a transfer ticket by calling NewNear, as in the following example:
transferTicket = NewNear(OurTransferTicket_, self, nil);
You probably won't ever declare transfer ticket objects in your instance definition files.
You'll never create any objects of class PostOffice, either in your instance definition files or at runtime, and you'll rarely call operations of this class. If your package includes client software for an electronic mail service, you'll work with this important class by overriding various operations called by the single object of post office that is created and managed by Magic Cap itself.
For more information on how the post office works, see this chapter's Post Office and Electronic Mail Services section.
For more information, see these topics in Magic Cap Class and Method Reference:
class ElectronicMailService
operations and attributes:
AbortTransfer AddToSendQueue CanAcceptAddressLabel CanConnectNow InitiateConnection IsNativeAddressLabel MakeCardTransferTickets MakeCollectionTransferTicket Receive Send SendAnother SetTransferDone TerminateConnection
fields:
protocol
class Stationery
operations and attributes:
CreateMessage
fields:
card dependency hopTarget image
class ElectronicMailLabel
operations and attributes:
CanConvertAddressToClass ConvertAddressToLabel DefaultDescription DefaultImage EditSteps InternetDomainName
fields:
addressText description image privacy
class PostOffice
operations and attributes:
CollectMail ContactMailServices InitiateIncomingMail
class TransferTicket
operations and attributes:
FollowOn
class Returnable
operations and attributes:
Decision DecisionMade Identifier Sender
indexicals:
iCollectingMailServices iEmailLabelContainer iEnabledServicesList iMailServiceProviders iMailServices iSentCardsQueue iServices iTransferOutQueue
Book Contents Previous Chapter Next Chapter