Mail & Communication

How can I programatically add or remove mail from the In and Out boxes?

The In and Out boxes are both subclasses of StackOfCards, so you can use MoveToStack() to move telecards in and out of these stacks:

 MoveToStack(myTelecard, iOutBoxStack); // to insert a message
 MoveToStack(myTelecard, iInBoxStack);  // to insert a message

or

 MoveToStack(myTelecard, nilObject);    // to remove a message

On tapping the reply stamp on the telecard, the original message that is being replied to appears on the screen. Where does the reply card keep information about the received message?

The message on the Telecard contains an inReplyTo field which contains a message ID. This message ID is used to find the message, via FindMessageID(). Telecard_GoToInReplyToCard does all this, the ReplyStamp_Action method just calls GoToInReplyToCard().

I have a piece of stationery that is used to send a message back to me when the user taps the response button in the package scene in the storeroom. Right now, the user has to manually select a delivery means. I would like the message to be already set up to be sent via the fax number the address card included in my software package. How can I do this?

Check out the PackageScenes sample code. This package shows you how to implement functionality for all the buttons that can appear in the package scene, including how to create a letter that is automatically filled out when the user taps the response button.

I've created my own ElectronicMailServer. The Clear and Summary commands in the In box still refer to PersonaLink. What do I need to do to implement these commands?

The Clear and Summary commands only work with MagicMail services (a.k.a. PersonaLink) in Magic Cap 1.0. This is a weak area in the mail framework; these commands will be better supported in the future, or at the very least, move from the in box into the service provider's building downtown, so they don't show up when they can't be used.

However, if you poke around in the in box with the tinker tool and the inspector, you'll see that the Clear command calls InBox_EmptyMailbox and Summary calls InBox_RequestSummaries. These routines are just cover routines to do their thing for the preferred service provider. The more general routines are EmptyMailboxForService() and RequestSummariesForService(). If you want to implement these features, these are the routines you would use. You could then install additional Clear and Summary commands into the In box, or overlay the existing buttons, or simply make these commands available from your service provider's building downtown. (If you install one, that is.)

The mail buttons in the in box seems to be hard-wired to PersonaLink. How can I get it to collect from my mail service?

The mail button in the in box is a scripted button that calls PostOffice_ContactMailServices when tapped. This ultimately calls PostOffice_CollectMail. PostOffice_CollectMail is not specific to PersonaLink, unless there are no other ElectronicMailServices registered with the post office.

If no services are registered with the post office, then the lessons in Magic Cap will lead the user through AT&T registration. If only one service has been registered, the post office will use that service to collect mail when the button is pressed (and since the AT&T service is the only one "built into" Magic Cap, these behaviors could lead one to believe the button only works for PersonaLink). If more than one service is present then the user gets a window with a choice list that lets them choose a service from which to collect mail, so the framework is there for another service to hook into.

PostOffice_CollectMail looks at an indexical, iCollectingMailServices, to decide whether or not to initiate the PersonaLink sign-up lesson (if the list is empty then the lesson is started). A list of services to choose from will appear if there is more than one provider card in the iCollectingMailServices list.

PostOffice_CollectMail will initiate collection if the service is also in the iEnabledServicesList. Your service can get there in a couple of different ways.

  1. You can put it there. This is appropriate, if you are the only service in the iCollectingMailServices list.
  2. The system can put it there. This will happen if the multi-service window is displayed (because there is more than one service to choose from) and the user checks your service. Of course, your service will be removed from the enabled list if the user unchecks it in the list.

Note that your service shouldn't be in any of these lists unless the user is registered for your service.

I've noticed that the images on a name card are not sent through the Telescript service by default: The only way to make sure your whole namecard gets to somebody (including sticky notes, images, etc...) is to explicitly mail it to that person. Does the Telescript service strip non address and phone objects from the AddressCard or is it Magic Cap that strips it before the card gets sent to the directory service?

The answer lies in understanding the relationship between a Telescript AddressCard object and a Magic Cap NameCard/AddressCard combination. Magic Cap NameCard objects are the viewable manifestation of, and contain a reference to, an AddressCard object. Magic Cap AddressCard objects are the equivalent of a Telescript AddressCard. The extra goodies (Magic Cap viewables) you can drop onto a NameCard are part of the NameCard, not the AddressCard. It's the AddressCard object that's sent to the Telescript service, not the NameCard, which is why all those cool stamps you put on your name card don't get sent to the Telescript service.

When is the right time for an ElectronicMailService to destroy a TransferTicket? Or does the PostOffice do that automatically? A lot of them seem to hang around so I don't think the Post Office is supposed to get rid of them. Assuming that the Post Office does not clean these things up, is the right place to do it within TerminateConnection()?

TransferTickets should be destroyed when a message is removed from the send queue by the PostOffice, so ElectronicMailServices shouldn't have to delete them. What you could be seeing are objects which are marked for deletion, but whose space hasn't been reclaimed by the system yet.

When you enter a new phone number for a person, the number is automatically parsed as (aaa) nnn-nnnn. How can I do this in my package?

Class Telenumber is a class which knows a lot about formatting phone numbers. The fragment below uses a Telenumber to format the number. You can probably gain a lot by using Telenumbers to store and process phone numbers in your package.

Private void
FormatPhoneNumber(uchar* numberString)
{
   ObjectID teleNumber = NewTransient(Telenumber_, nil);
   ObjectID telephone = StringToText(numberString);

   // Set up the text field of the Telenumber to contain the phone text
   SetTelephone(teleNumber, telephone);
   
   // Clean up the phone number, guessing at an area code if necessary
   CleanUpPhoneNumber(teleNumber);

   // Convert the prettified Text object back into the string
   AbsolutePhoneNumber(teleNumber, numberString);

   // Avoid them leaks!
   Destroy(teleNumber);
}

Is there XModem support in Magic Cap?

No.