Outlook 2007 Mobile Service Guidelines (Part 1 of 3)

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary:   Learn how to build and host Web services for Microsoft Office Outlook 2007 Mobile Service. This article introduces Outlook Mobile Service (OMS) architecture and message flow and describes the communication protocols between OMS clients and Web services. (21 printed pages)

Paul Shen, Microsoft Corporation

Bing He, Microsoft Corporation

Yong Zhang, Microsoft Corporation

Judy Zhang, Microsoft Corporation

Published February 2007

Updated December 2007

Applies to:   Microsoft Office Outlook 2007

Contents

  • Introduction to Outlook Mobile Service

  • Architecture and Message Flow

  • Communication Protocols

  • Web Service URL Redirection

  • Packaging Incoming Mobile Messages

  • Conclusion

  • Additional Resources

Introduction to Outlook Mobile Service

Microsoft Office Outlook 2007 Mobile Service (OMS) is the new messaging and Personal Information Manager (PIM) component developed for Microsoft Office Outlook 2007. OMS is designed to make Outlook the best tool for mobile messaging and notification. With OMS, users can seamlessly integrate the mobile capabilities of Outlook with their mobile devices.

With the mobile messaging functionality that is provided by OMS, users can do the following:

  • Compose new text messages and multimedia messages within Outlook.

  • Forward Outlook items (including e-mail messages, meetings, and contacts) as text or multimedia messages.

  • Receive replies from mobile devices and have two-way communication between Outlook and mobile phones.

With the item redirection functionality that is provided by OMS, users not only can compose and send text and multimedia messages from within Outlook, but they can automatically redirect reminders, e-mail messages, and the next day’s schedule to a mobile phone by setting simple conditions. They can also send e-mail messages, appointments, and meeting requests to mobile phones and other e-mail addresses.

OMS is integrated into Outlook account settings, enabling seamless integration so that users can manage mobile messaging accounts in parallel with e-mail accounts. Mobile phone numbers are treated as a type of address, and users can add recipients to a mobile message by using AutoComplete, or by selecting names directly from the Outlook Address Book. They can also store and manage mobile messages in Outlook folders.

The OMS client, which is built into Outlook, sends text and multimedia messages to a Web service that is created and hosted by partners who are either carriers or mobile message content service providers. The Web service then delivers the message to a text message or multimedia message service center of carriers.

This is the first in a three-part series of articles that introduces you to OMS and provides guidelines and reference information for working with the service. For recommendations for implementing an OMS Web service, see Outlook 2007 Mobile Service Guidelines (Part 2 of 3). For information about the XML schema for data that is passed between OMS Web providers and OMS clients, see Outlook 2007 Mobile Service Guidelines (Part 3 of 3).

The audience for this article is assumed to be familiar with developing and deploying Web services. For general information on Web services, see Web Services. For additional information on how to develop Web services, refer to the documentation that is provided with the development tool that you are using.

Architecture and Message Flow

The overall architecture of OMS is a client service framework based on Web service technology. The OMS client, which is built into Outlook, encodes a mobile message as a SOAP message and sends it to the OMS Web service, where it is then encoded and delivered to the carrier's mobile message gateway. The message is then delivered to an intended user's mobile phone through the carrier’s mobile wireless networks. The OMS Web service is created and hosted by a service provider that is either a mobile telecom operator or aggregator (Internet content provider, Internet service provider, or any party that can provide a mobile messaging service). The OMS Web service specification and communication protocols between the OMS client and Web service are described in the Communication Protocols section in this article.

Messages flow back and forth between Outlook and the receiver's mobile phone via the OMS Web service and the carrier’s infrastructure, as shown in Figure 1. Replies from the receiver's mobile phone can go to the Outlook Inbox, the sender's mobile device, or both, based on the user's preferences. To deliver replies to a user’s Inbox in Outlook, the service provider packages them as Simple Mail Transfer Protocol (SMTP) e-mail messages according to the specification defined by Microsoft (see the Packaging Incoming Mobile Messages section in this article).

Figure 1. Message flow for Outlook Mobile Service

Architecture and message flow

Communication Protocols

There are several rules you must follow when developing an OMS Web service. First, the OMS Web service must follow the Web Services Description Language (WSDL). This enables the OMS client to connect with the service without any service-specific code change.

Second, the OMS Web service must support the following Web methods:

  • string GetServiceInfo()   Used to retrieve the properties of the OMS Web service.

  • string GetUserInfo(string xmsUser)   Used to retrieve the user’s information.

  • string DeliverXms(string xmsData)   Used to send mobile messages to the Web service.

Third, the OMS Web service must follow the guidelines for sending mobile messages to the OMS client as e-mail, as described in the Packaging Incoming Mobile Messages section in this article.

NoteNote

The RTM version of Microsoft Office Outlook 2007 supported the SendXms Web method. In Microsoft Office Outlook 2007 Service Pack 1 (SP1), the SendXms Web method is renamed DeliverXms. To insure that your OMS Web service works with the RTM version of Outlook 2007, Outlook 2007 SP1, and later versions of Outlook, you must support both SendXms and DeliverXms, by specifying the same definition for SendXms and for DeliverXms. After all of your subscribers upgrade to Outlook 2007 SP1 or a later version, you can discontinue support for SendXms.

Simple Web Service Implementation Example

The following code example gives an outline of a simplified implementation of the OMS Web service. The GetUserInfo() and GetServiceInfo() methods return information and the appropriate error code. The information and error codes to be returned are stored as XML files. This example assumes that a LoadXmlFromFile(string filename) method has been created that can load the XML from a file and return the result as a string, and that a private class CUserLogon has been implemented that provides user validation functionality.

using System;
using System.IO;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Web.Mail;
using System.Xml;
using System.Xml.Schema;
using System.Xml.Serialization;

[WebService(Namespace="http://schemas.microsoft.com/office/Outlook/2006/OMS")]///<Do not change the namespace!/>
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class OMSService : System.Web.Services.WebService
{
    /// <Get service information, such as the capacities of supported services./>
    [WebMethod]
    public string GetServiceInfo()
    {
        return LoadXmlFromFile("SampleServiceInfo.xml");
    }
    /// <Get user information including SMTP address and mobile phone number./>
    [WebMethod]
    public string GetUserInfo(string xmsUser)
    {
       if (!m_schemaProvider.FValidXml(xmsUser, "xmsUserSchema.xsd"))
       {
           return LoadXmlFromFile("SchemaError.xml");
       }
       CUserLogon usrLogon = new CUserLogon(xmsUser);
       if (!usrLogon.FLogon())
       {
           return LoadXmlFromFile("LogonFailed.xml");
       }
       return LoadXmlFromFile("SampleUserInfo.xml");
    }
    /// <Send SMS or MMS message data to specific recipients./>
    [WebMethod]
    public string DeliverXms(string xmsData)
    {
       if (!m_schemaProvider.FValidXml(xmsUser, "xmsDataSchema.xsd"))
       {
           return LoadXmlFromFile("SchemaError.xml");
       }
       CUserLogon usrLogon = new CUserLogon(xmsData);
       if (!usrLogon.FLogon())
       {
           return LoadXmlFromFile("LogonFailed.xml");
       }
       return LoadXmlFromFile("SampleResponse.xml");
    }

    // <Load XML file./>
    private string LoadXmlFromFile(string strFile)
    {
       // ...
    }
    // Helps validate XMS schemas
    private CSchemaProvider m_schemaProvider;
};//OMSService

// Extract user logon information from XML string and process logon validation.
private class CUserLogon 
{
    // ....
};

// Cache schema validators
private class CSchemaProvider
{
    // ....
};

The following sections describe the OMS Web service methods in greater detail and include example code and examples of the XML-formatted strings (serviceInfo, userInfo, and xmsResponse) that are passed to or from these methods. The WSDL for these Web methods, and also the schemas for the XML-formatted strings passed to or from these methods, are included in the last article of this series, Outlook 2007 Mobile Service Guidelines (Part 3 of 3).

string GetServiceInfo() Web Service Method

GetServiceInfo() returns an XML-formatted string called serviceInfo that contains basic properties of the OMS Web service, such as supported service types, parameters of supported services, and authentication types.

The OMS client built into Outlook calls GetServiceInfo() to retrieve the properties of an OMS Web service when a user sets up a new account or to update service properties after the OMS Web service has been published. With these properties, OMS configures the Web service as a supported service provider on the client side.

The following example shows a serviceInfo string returned by GetServiceInfo().

Example serviceInfo string

<?xml version="1.0" encoding="utf-8"?>
<serviceInfo xmlns="http://schemas.microsoft.com/office/Outlook/2006/OMS/serviceInfo">
<serviceProvider>ABC Company</serviceProvider>
<serviceUri>http://www.abc.com.cn/OMS3/XMS.asmx</serviceUri>
<signUpPage>http://www.abc.com.cn/ws/xmssignup.aspx/</signUpPage>
<targetLocale>2052</targetLocale>
   <localName>ABC Mobile Service</localName>
   <englishName>ABC Mobile Service</englishName>
   <authenticationType>Other</authenticationType>
   <supportedService>
      <SMS_SENDER maxRecipientsPerMessage="50" maxMessagesPerSend="20"
         maxSbcsPerMessage="140" maxDbcsPerMessage="70" />
      <MMS_SENDER supportSlide="true" maxRecipientsPerMessage="100" 
         maxSizePerMessage="30000" maxSlidesPerMessage="10" />
   </supportedService>
</serviceInfo>

Developers should also be aware of the following:

  • The serviceInfo string is transferred as a Unicode string, and then encoded as UTF-16.

  • The serviceUri value is used to identify the service uniquely. If the serviceUri of an OMS Web service is changed, the OMS client treats the service as a new OMS Web service.

  • To support long text messages, a service provider can set values of the maxSbcsPerMessage and maxDbcsPerMessage attributes of the SMS_SENDER element to values that can be supported by most models used by their subscribers.

  • If an OMS Web service sets the supportSlide attribute of the MMS_SENDER element of its serviceInfo string to be "true", this indicates that the Web service supports the Synchronized Multimedia Integration (SMIL) format. A message that uses SMIL is known as being in slide mode. If an OMS Web service that does not support SMIL receives a message in slide mode, the Web service must either report an error of type "other" or convert the message to non-slide mode.

string GetUserInfo(string xmsUser) Web Service Method

The OMS client built into Outlook retrieves a user’s mobile phone number and other information by calling GetUserInfo() with an xmsUser string as the parameter—an XML-formatted string containing the user’s authentication information, including user ID and password. GetUserInfo() returns an XML-formatted string called userInfo that contains an error element with its severity attribute set to "failure".

Error codes that are typically returned in a userInfo string are shown in Table 1.

Table 1. Errors returned by a call to GetUserInfo()

Code

Severity

Ok

Neutral

invalidUser

Failure

unregisteredUser

Failure

expiredUser

Failure

See the "OMS Error Codes" section in Outlook 2007 Mobile Service Guidelines (Part 3 of 3) for a complete list of error codes that an OMS Web service can send. Note, however, that the userInfo schema does not contain the content or recipientList child elements mentioned in that section. Also the severity attribute is optional for an error in a userInfo string, although it is required in an xmsResponse string. If no severity attribute is defined for an error element in a userInfo string, the OMS client assumes that the severity of the error is "neutral".

NoteNote

Developers should note that xmsUser and userInfo strings are transferred as Unicode strings and encoded as UTF-16.

The following code example shows an implementation of GetUserInfo() that uses an XmlTextWriter object to write the user information and error code into an XML-formatted string.

GetUserInfo() Example

// …
private const string m_sOmsNamespace = "http://schemas.microsoft.com/office/Outlook/2006/OMS";
public string GetUserInfo(string xmsUser)
{
   StringWriter stringWriter = null;
   XmlTextWriter writer = null;
   try
   {
      // Add code to verify user logon password 
      // and retrieve user information.
      // ...
      stringWriter = new StringWriter(new StringBuilder());
      writer = new XmlTextWriter(stringWriter);
      writer.WriteStartElement("userInfo", m_sOmsNamespace);
      writer.WriteStartElement("replyPhone");
      writer.WriteString(**replyPhone value**);
      writer.WriteEndElement(); // </replyPhone>
      writer.WriteStartElement("smtpAddress");
      writer.WriteString(**smtpAddress value**);
      writer.WriteEndElement(); // </smtpAddress>
      writer.WriteStartElement("error");
      writer.WriteAttributeString("code", "ok"); // return "ok" if no errors
      writer.WriteEndElement(); // </error>
      writer.WriteEndElement(); // </userInfo>
      return stringWriter.GetStringBuilder().ToString();
   }
   finally
   {
      if (writer != null)
         writer.Close();

      if (stringWriter != null)
         stringWriter.Close();
   }
}

The following examples show xmsUser and userInfo strings.

Example xmsUser string

<?xml version="1.0" encoding="utf-8"?>
<xmsUser client="Microsoft Office Outlook 12.0" xmlns = "http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <userId>myname</userId>
   <password>mypwd</password>
   <customData/>
</xmsUser>

Example userInfo string returned by GetUserInfo() after a successful call

<?xml version="1.0" encoding="utf-8"?>
<userInfo xmlns = "http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <replyPhone>090123456</replyPhone>
      <smtpAddress>userid.spmail@spdomain.com</smtpAddress> 
   <error code="ok"/>
</userInfo> 

Example userInfo string returned after an error

<?xml version="1.0" encoding="utf-8"?>
<userInfo xmlns = "http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <error code="unregistered" severity="failure"/>
</userInfo>

Now let's look more closely at the elements of a userInfo string. The replyPhone element contains the mobile number that the user used to sign up for the service with the service provider. The replyPhone value is displayed on the account setting dialog box in Outlook as the user’s default mobile number. The OMS client obtains the replyPhone value by calling GetUserInfo() when the user sets up an account. The OMS client also calls GetUserInfo() to update a user’s replyPhone when he or she views or changes the account and has not entered a mobile number, or when the OMS Web service notifies the client that the service information is changed through the "serviceUpdate" error code.

Also, the replyPhone element is used as the default callback number for some markets, such as Korea, where a callback number is required and supported. For Korea, the value of replyPhone or any other phone number that the user enters is used as the user’s callback number when a Short Message Service (SMS) or Multimedia Messaging Service (MMS) message is sent.

Finally, the smtpAddress element contains a unique SMTP address that is generated by the service provider for every subscriber. The SMTP address is used by the service provider to send replies from a mobile phone back to Outlook 2007. Creating unique SMTP addresses for every subscriber is required of OMS service providers to prevent malicious users from sending junk e-mail messages by using the SMTP address.

string DeliverXms(string xmsData) Web Service Method

The OMS client that is built into Outlook 2007 calls DeliverXms() to deliver a mobile message to the service provider. The message content is packaged as an XML-formatted string called xmsData. After the service provider has attempted to send the message, it returns an XML-formatted string called xmsResponse that contains one or more error elements that indicate the success or failure of the attempt to send the message to each intended recipient.

DeliverXms() Example

The following code example shows an implementation of DeliverXms() that uses an XmlTextWriter object to write the success or failure of the call into an xmsResponse string.

// …
private const string m_sOmsNamespace = "http://schemas.microsoft.com/office/Outlook/2006/OMS";
public string DeliverXms(string xmsData)
{
   StringWriter stringWriter = null;
   XmlTextWriter writer = null;
   try
   {
      stringWriter = new StringWriter(new StringBuilder());
      writer = new XmlTextWriter(stringWriter);
      writer.WriteStartElement("xmsResponse", m_sOmsNamespace);
      // XML format validation
      if (!m_schemaProvider.FValidXml(xmsData, "xmsDataSchema.xsd"))
      {
         BuildError(writer, "invalidFormat", true /* failure */, "", "");
         return stringWriter.GetStringBuilder().ToString();
      }
      // User validation
      CUserLogon usrLogon = new CUserLogon(xmsData);
      if (!usrLogon.FLogon())
      {
         BuildError(writer, "invalidUser", true /* failure */, "", "");
         return stringWriter.GetStringBuilder().ToString();
      }
      // Add YOUR code for your business logic to send the xmsData
      //to the intended recipients.
      // ...
      // Sent out OK.
      BuildError(writer, "ok", false /* success */, "", "");
      return stringWriter.GetStringBuilder().ToString();
   }
   catch (XmlException ex)
   {   
      // Handle exceptions.
      return  "<?xml version=\"1.0\" encoding=\"utf-16\"?>"
         + " <xmsResponse xmlns=\"http://schemas.microsoft.com/office/Outlook/2006/OMS\">"
         + " <error code=\"others\" severity=\"failure\"> <content>" + ex.Message + " </content> </error>"
         + "</xmsResponse>";
   }
   finally
   {
      if (writer != null)
          writer.Close();
      if (stringWriter != null)
          stringWriter.Close();
   }
}//end DeliverXms
// Build error elements.
private void BuildError(XmlTextWriter wr, 
   string errCode, 
   bool bFailed, 
   string strContent,
   string strRecipients)
{
   wr.WriteStartElement("error");
   wr.WriteAttributeString("code", errCode);
   wr.WriteAttributeString("severity", bFailed ? "failure" : "neutral");

   if (strContent.Length > 0)
   {
      wr.WriteStartElement("content");
      wr.WriteString(strContent);
      wr.WriteEndElement(); // </content>
   }
   if (strRecipients.Length > 0)
   {
      wr.WriteStartElement("recipientList");
      wr.WriteString(strRecipients);
      wr.WriteEndElement(); // </recipientList>
   }
   wr.WriteEndElement(); // </error>
}//end BuildError

xmsData

The xmsData string is designed to package either a text message or a multimedia message, which means that text messages and multimedia messages share the same schema. Examples of an xmsData string containing an MMS-formatted message and an xmsData string containing an SMS-formatted message are shown in the following examples.

Example xmsData string containing an SMS-formatted message

<?xml version="1.0" encoding="utf-8"?>
<xmsData client="Microsoft Office Outlook 12.0" xmlns = "http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <user>
      <userId>myname</userId>
      <password>mypwd</password>
      <replyPhone>13801391350</replyPhone>
      <customData/>
   </user>
   <xmsHead>
      <scheduled>2005-04-20T14:20:00Z</scheduled>
      <requiredService>SMS_SENDER</requiredService>
      <to>
         <recipient>135xxxx</recipient>
         <recipient>139xxxx</recipient>
      </to>
   </xmsHead>
   <xmsBody format="SMS">
      <content contentType="text/plain" contentId="Att0.txt@AB1B43B2B0594564.B94EF7ABB12B49BA"
            contentLocation="1.txt">(1/2)This is the first SMS message...</content>
      <content contentType="text/plain" contentId="Att1.txt@AB1B43B2B0594564.B94EF7ABB12B49BA"
            contentLocation="2.txt">(2/2)This is the second SMS message...</content>
   </xmsBody>
</xmsData>

Example xmsData string containing an MMS-formatted message

<?xml version="1.0" encoding="utf-8"?>
<xmsData client="Microsoft Office Outlook 12.0"xmlns = "http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <user>
      <userId>myname</userId>
      <password>mypwd</password>
      <replyPhone>13801391350</replyPhone>
      <customData/>
   </user>
   <xmsHead>
      <scheduled>2005-04-20T14:20:00Z</scheduled>
      <requiredService>MMS_SENDER</requiredService>
      <sourceType>reminder</sourceType>
      <to>
         <recipient>135xxxx</recipient>
         <recipient>139xxxx</recipient>
      </to>
      <subject>My Message</subject>
   </xmsHead>
   <xmsBody format="MMS">
      <mmsSlides>
         <head>
            <meta name="author" content="msOfficeOutlookOms" />
            <layout>
               <root-layout width="120" height="120" background-color="#ffffff" />
               <region id="image" left="0" top="0" width="120" height="90" />
               <region id="text" left="0" top="90" width="120" height="30" />
            </layout>
         </head>
         <body>
            <par dur="3000">
               <img src="cid:Att1.gif@AB1B43B2B0594564.B94EF7ABB12B49BA" region="image" />
               <text src="cid:Att0.txt@AB1B43B2B0594564.B94EF7ABB12B49BA" region="text"/>
               <audio src="cid:Att2.mid@AB1B43B2B0594564.B94EF7ABB12B49BA" />
         </par>
         </body>
      </mmsSlides>
      <content contentType="text/plain" contentId="Att0.txt@AB1B43B2B0594564.B94EF7ABB12B49BA"
            contentLocation="1.txt">This is the text part</content>
      <content contentType="image/gif" contentId="Att1.gif@AB1B43B2B0594564.B94EF7ABB12B49BA"
            contentLocation="106675.gif">/9j/4AAQ ...... AVExISEyccHhcgLikxMC4p</content>
      <content contentType="audio/midi" contentId="Att2.mid@AB1B43B2B0594564.B94EF7ABB12B49BA"
            contentLocation="1898.mid">/wDQjVYUrl ...... GoJ4e8j</content>
   </xmsBody>
</xmsData>

Supported Content Types

Short Message Service (SMS) messages support the "text/plain" content type. OMS supports the media objects listed in Table 2 for Multimedia Messaging Service (MMS) messages. On the client side, OMS converts other media types into these standard formats if needed.

Table 2. Supported content types

Content

MIME Type

Description

Text

text/plain

Plain text. Can be used by both SMS and MMS messages.

Static Image

image/jpeg

96 DPI. Smaller, or equal to, the mobile screen size defined in the root-layout element of the xmsData string. Base64 encoded. Only applies to MMS messages.

Multi-frame Image

image/gif

GIF89a, 96 DPI, maximum of 256 colors. Smaller or equal to the mobile screen size defined in the root-layout element of the xmsData string. Base64 encoded. Only applies to MMS messages.

MIDI audio format

Audio/mid

MIDI format. Base64 encoded. Only applies to MMS messages.

AMR sound format

Audio/AMR

AMR format, single channel, 8K Hz. Base64 encoded. Only applies to MMS messages.

The OMS Web service is responsible for checking whether the messages it receives in one xmsData string comply with the limitations set by the service and taking necessary actions or returning errors by using the appropriate error codes.

xmsResponse

DeliverXms() returns an XML-formatted string named xmsResponse that contains one or more error elements. As with the userInfo string, an error element that has the code attribute set to "ok" and the severity attribute set to "neutral" is used to indicate success.

The error element has two child elements: content, which is a string containing a description or parameters of the error, and recipientList, which is a string containing a semi-colon–delimited list of recipients that are affected by the error.

At most, one content element and one recipientList element can be defined for each error element. The absence of a recipientList element means that the error applies to all recipients.

Each error code has two required attributes: code and severity. The error code is case insensitive. The possible severity values are as follows:

  • The "neutral" value is the default, meaning either a complete and successful send, or the service is sending a non-error message to the OMS client.

  • The "failure" value means the message has not been delivered to one or more recipients.

The following are notes on the use of the error element and severity attribute:

  • If the error element is not included in the xmsResponse string, the OMS client assumes that a failure error occurred.

  • If the error element without the code attribute is included in an xmsResponse string, the OMS client assumes that an unknown failure error occurred.

  • If the error element without the severity attribute is included in an xmsResponse string, the OMS client assumes that the severity is "neutral."

  • If multiple error codes are returned, the error that has the highest severity decides whether the OMS client generates a Non-delivery Report (NDR) and sends it to the user. If there are one or more "failure" errors, the OMS client generates an NDR letting the user know that the message has not been delivered.

The following are examples of xmsResponse strings.

Example xmsReponse string indicating that the message was sent successfully

<?xml version="1.0" encoding="utf-8"?>
<xmsResponse xmlns="http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <error code="ok" severity="neutral"/> 
</xmsResponse>

Example xmsReponse string with a "failure" error

<?xml version="1.0" encoding="utf-8"?>
<xmsResponse xmlns="http://schemas.microsoft.com/office/Outlook/2006/OMS">
   <error code="perDayMsgLimit" severity="failure">
      <content>20 SMS</content>
      <recipientList>13601391354;13601391388</recipientList>
   </error> 
</xmsResponse>

Web Service URL Redirection

Where the exact URL to the OMS Web service has not been specified, redirection of the URL to the real Web service URL for OMS is provided to OMS clients. To get the real URL of the Web service, the OMS client first sends an empty HTTP POST request to the Web service followed by a SOAP request, and calls DeliverXms() and GetUserInfo() with an empty string as the parameter. The Web service should treat such empty HTTP POST or calls as typical requests and simply ignore them.

Packaging Incoming Mobile Messages

To enable two-way mobile message communication between Outlook and a mobile phone, the OMS Web service is required to package the reply sent from a mobile phone into a MIME (Multipurpose Internet Mail Extensions)-formatted SMTP e-mail message with an OMS-defined content class, and then send the e-mail messages to a user-designated e-mail address. When Outlook 2007 receives the SMTP e-mail messages, it recognizes the content class and treats it as a mobile message.

Figure 2 and Figure 3 are examples of SMS and MMS replies encoded in MIME-formatted e-mail messages. The following sections describe the required steps in packaging mobile messages as e-mail messages.

Message Headers

When encoding a reply into an e-mail message, set SMTP headers as described in the following sections so that the OMS client can properly recognize the incoming e-mail messages as coming from a mobile phone.

Content-Class

Set the message header "Content-class" to one of following values:

  • SMS message content class: MS-OMS-SMS

  • MMS message content class: MS-OMS-MMS

When Outlook receives e-mail messages with these content-classes, it recognizes them as text or multimedia messages and displays specific icons for them. When these messages are opened, replied to, or forwarded, they are automatically treated as mobile messages.

To ensure that the client correctly displays incoming mobile messages packaged as e-mail messages, set the proper charset for all headers containing non-US ASCII text and MIME parts of "text" media type.

X-MS-Reply-To-Mobile

Add the following header specifically for conveying the sender’s mobile number:

X-MS-Reply-To-Mobile:

The header should be a valid mobile phone number.

The following is an example of an X-MS-Reply-To-Mobile header (the first two digits of the mobile number represent the country code):

X-MS-Reply-To-Mobile:+8613601391354

To

The value of the To field is an e-mail address provided by the user for receiving incoming mobile messages:

To: someone@example.com

From

The value of the From field is the e-mail address that is used for sending the reply. OMS service providers are required to provide a unique SMTP address to every subscriber for sending back replies. The From field should look something like the following example:

From: userid.spmail@spdomain.com

Subject

If the reply e-mail message is for an incoming SMS message, the recommended value of the Subject field is either the first 40 or so characters of the SMS message body or the first line of the SMS message (if there are multiple lines in the message body).

If the reply e-mail message is for an incoming MMS message, set the Subject of the e-mail message as the Subject of the MMS message. Because MMS messages cannot be completely displayed in the Outlook Preview Pane, add a comment to the Subject of the MMS message reminding users to view the message content by opening the message as shown in the following example:

Subject of MMS Message (Open the message to view content)

Message Body

Incoming SMS Message

To compose the message body for an incoming SMS message, as shown in Figure 2, create a plain text MIME part for the SMS message content by adding the following headers:

Content-Type: text/plain; charset=xxxx

Content-Transfer-Encoding: quoted-printable

Examples of valid charset values are "us-ascii" (ASCII) and "gb2312" (Simplified Chinese). Service providers can also use multipart/alternative content-type and provide a HTML view of the message body.

Figure 2. Example of incoming SMS message packaged as e-mail message

From: "Mobile Inbound Agent" incomingmessage@service-provider.com

To: someone@example.com

Subject: This is a text message

Date: Mon, 7 Nov 2005 17:52:00 +0800

Content-class: MS-OMS-SMS

X-MS-Reply-to-mobile: +8613601391354

MIME-Version: 1.0

Content-Type: text/plain; charset="gb2312"

Content-Transfer-Encoding: quoted-printable

This is a text message from a mobile phone replying to a text message from Outlook.

Incoming MMS Message

When composing the message body for incoming MMS messages, follow the 3GPP standard in encoding MMS messages as MIME-formatted SMTP mails.

If SMIL is available, compose the MIME body as multipart/related:

Content-Type: multipart/related; type="application/smil";

The first MIME part of the SMIL file should be:

Content-Type: application/smil; name = "mmspresent.smil"

Media parts of the MMS message should be encoded as MIME parts with corresponding media types following the SMIL file.

If SMIL is not available, compose the MIME body as multipart/mixed:

Content-type: multipart/mixed

Encode media parts of the MMS message as MIME parts with the corresponding media types. Figure 3 is an example of an MMS message encoded in MIME format.

Figure 3. Example of incoming MMS message packaged as e-mail message

From: "Mobile Inbound Agent" incomingmessage@service-provider.com

To: someone@example.com

Subject: This is a multimedia message (Open the message to view its content)

Date: Mon, 7 Nov 2005 17:52:00 +0800

Content-class: MS-OMS-MMS

X-MS-Reply-to-mobile: +8613601391354

MIME-Version: 1.0

Content-Type: multipart/related; type="application/smil";

boundary="--------------Boundary=_thisisboundary"

This is a multi-part message in MIME format.

--------------Boundary=_thisisboundary

Content-Type: application/smil; name="mmspresent.smil"

Content-Location: ”mmspresent.smil”

Content-Transfer-Encoding: Base64

PHNtaWw+… 1pbD4=

--------------Boundary=_thisisboundary

Content-Type: text/plain; name="textpart.txt"

Content-Transfer-Encoding: Base64

Content-Location: textpart.txt

6Zi/5YWs5Y+45rOV5b6L5biI6IyD5Zu057uV6YGT6LCi

--------------Boundary=_thisisboundary

Content-Type: image/gif; name="imagepart.gif"

Content-Transfer-Encoding: Base64

Content-Location:imagepart.gif

R0lGODlheABaAPf/…BDQi6j4uQAxwcixRzZErI5ROjfvSHJcmRMGBAAOw==

--------------Boundary=_thisisboundary

Content-Type: audio/midi; name="audiopart.mid"

Content-Transfer-Encoding: Base64

Content-Location: audiopart.mid

TVRoZAAAAAY…XBDfwA/fwA6f4dAOgAAPwAAQwAA/y8A

--------------Boundary=_thisisboundary

Connection Security

To protect the information as it is transferred over the Internet, OMS Web services are required to support SSL (Secure Socket Layer) encryption. SSL can be used to establish more secure connections on untrusted networks, such as the Internet. SSL enables encryption and decryption of messages exchanged between client and server, thereby helping to protect messages from being read during transfer.

Conclusion

This article introduces the OMS Web service architecture and defines and explains the interfaces between the OMS Web service and the OMS client. For guidelines on hosting an OMS Web service, see Outlook 2007 Mobile Service Guidelines (Part 2 of 3). For XML schema and WSDL for the OMS Web services, see Outlook 2007 Mobile Service Guidelines (Part 3 of 3).

Additional Resources

For more information, see the following resources: