8.2 The Message Framework

The message framework, consisting of the single NSMailDelivery class, provides the functionality needed to send email messages from within an application. The NSMailDelivery class defines three methods:

• hasDeliveryClassBeenConfigured

• deliverMessage:headers:format:protocol:

• deliverMessage:subject:to:

The first method, hasDeliveryClassBeenConfigured, returns a BOOL value that indicates whether the operating system is configured to send messages. To make sure that any attempt to send a message is not in vain, invoke this method before sending a message, and handle appropriately if NO is returned. Message sending is enabled by configuring a default email account in the Internet System Preferences pane.

The second method, deliverMessage:headers:format:protocol:, delivers a message whose text is contained in an NSAttributedString. The standard message headers, such as "To", "From", and "Subject", are passed in the headers: parameter as a dictionary. In this dictionary, the key is the header name. For example, the recipient's email address would be an NSString value in the dictionary for the key @"To". Example 8-6 shows how to use this dictionary and the mail delivery methods.

The third parameter specifies the message's format, which can be one of two constants: NSASCIIMailFormat or NSMIMEMailFormat. If NSASCIIMailFormat is specified as the format, then the attributed string is stripped of any rich text formatting information. NSMIMEMailFormat, on the other hand, preserves the rich text formatting when sending the message.

The final argument specifies the protocol used to deliver the message. Passing nil, which causes the delivery to default to the system default protocol, is preferable. The other choice is to pass the constant NSSMTPDeliveryProtocol, specifying that the method should be delivered with the SMTP protocol.

The final method defined in NSMailDelivery is deliverMessage:subject:to:. This convenience method sends the first argument's plain text NSString to the sender specified in the last argument. The subject: argument specifies a subject for the message.

Example 8-6. Using the message framework class NSMailDelivery

BOOL status = NO;

// Send an attribute string message
NSAttributedString *msg = [[NSAtrributedString strin alloc]
      initWithString:@"This is a message with no formatting."];

NSMutableDictionary * hdrs = [NSMutableDictionary dictionary];
[hdrs setObject:@"someone@someplace.com" forKey:@"To"];
[hdrs setObject:@"me@myplace.com" forKey:@"From"];
[hdrs setObject:@"Boring email" forKey:@"Subject"];

status = [NSMailDelivery deliverMessage:msg 
       headers:hdrs
        format:NSASCIIMailFormat
      protocol:nil];

// Use the convenience method
status = [NSMailDelivery deliverMessage:@"This is another boring email message."
         subject:@"Nothing to important"
              to:@"someone@somplace.com"];

In this example, the variable status was set to the return value of the message delivery methods. The return values from these two methods indicate whether or not the message was successfully sent.