Office 2010 Mobile Service Guidelines (Part 1 of 3)

Article
07/24/2014

Summary: Learn how to build and host Web services for Microsoft Office 2010 Mobile Service (OMS). This article introduces OMS architecture and message flow and describes the communication protocols between OMS clients and Web services. Note that Office Mobile Service in Office 2010 is the updated version of Outlook Mobile Service in the 2007 Microsoft Office system. (20 printed pages)

In this article
Introduction to Office Mobile Service
Architecture and Message Flow
Communication Protocols
Web Service URL Redirection
Packaging Incoming Mobile Messages
Conclusion
Additional Resources

Published: April 2010

Provided by: Effon Khoo, Microsoft Corporation | Ken Wang, Microsoft Corporation | Dongdong Guo, Microsoft Corporation | Zhigang Zhuang, Microsoft Corporation | Qingzhong Cai, Microsoft Corporation

Contents

Introduction to Office Mobile Service
Architecture and Message Flow
Communication Protocols
Web Service URL Redirection
Packaging Incoming Mobile Messages
Conclusion
Additional Resources

Introduction to Office Mobile Service

Microsoft Office 2010 Mobile Service (OMS) is the messaging component developed for Microsoft Outlook 2010 and Microsoft SharePoint 2010. With OMS, users can seamlessly integrate the mobile capabilities of Outlook and SharePoint 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.
Receive alert messages from SharePoint on mobile phones.
Extend the messaging capability of Outlook and SharePoint OMS via the provided object model.

Office Mobile Service in Outlook

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 and SharePoint, 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.

Office Mobile Service in SharePoint 2010

In SharePoint 2010, a user can receive text message (SMS) alerts via OMS. The user can be notified of the status of documents or SharePoint lists and receive text messages reporting any changes, as well as the URL of the document or the list, if required.

Additional Information

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 about implementing an OMS Web service, see Office 2010 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 Office 2010 Mobile Service Guidelines (Part 3 of 3).

The audience for this article should be familiar with developing and deploying Web services. For general information about Web services, see Web Services. For more information about 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 or SharePoint, 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.

Currently, SharePoint 2010 delivers mobile messages to an OMS Web service in a one-way manner, but Outlook is able to have two-way communication with the OMS Web service. 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 Office Mobile Service in Outlook

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()—Retrieves the properties of the OMS Web service.
string GetUserInfo(string xmsUser)—Retrieves the user’s information.
string DeliverXms(string xmsData)—Sends one mobile message to the Web service.
string DeliverXmsBatch(string packageXml)—Sends multiple xmsData strings in a batch to the Web service.

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

Note

If you are upgrading your OMS Web service from Microsoft Office Outlook 2007, note that the SendXms Web method has been renamed as DeliverXms since Outlook 2007 Service Pack 1 (SP1). If you need your OMS Web service to work with the RTM version of Outlook 2007, as well as with Outlook 2007 SP1 or Outlook 2010, 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 Outlook 2010, 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="https://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, Office 2010 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 code example shows a serviceInfo string returned by GetServiceInfo().

<?xml version="1.0" encoding="utf-8"?>
<serviceInfo 
    xmlns="https://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 uniquely identify the service. 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. xmsUser is an XML-formatted string that contains 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". The schema for xmsUser is included in the last article of this series, Office 2010 Mobile Service Guidelines (Part 3 of 3).

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 Office 2010 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".

Note

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.

// ...
private const string m_sOmsNamespace = "https://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 = "https://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 = "https://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 = "https://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.

In Outlook 2007, the replyPhone element was used as the default callback number for some markets, such as Korea, where a callback number is required and supported. In Outlook 2010, the feature is discontinued and this element is not required.

Finally, the smtpAddress element contains a unique SMTP address that the service provider generates for every subscriber. The service provider uses the SMTP address to send replies from a mobile phone back to Outlook. 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 or SharePoint 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.

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 = "https://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=\
            "https://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. The following examples show an xmsData string that contains an MMS-formatted message and an xmsData string that contains an SMS-formatted message.

Example xmsData string that contains an SMS-formatted message

<?xml version="1.0" encoding="utf-8"?>
<xmsData client="Microsoft Office Outlook 12.0" xmlns = "https://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 that contains an MMS-formatted message

<?xml version="1.0" encoding="utf-8"?>
<xmsData client="Microsoft Office Outlook 12.0"xmlns = "https://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>

string DeliverXmsBatch(string packageXml) Web Service Method

The OMS client that is built into SharePoint calls DeliverXmsBatch() to deliver a number of xmsData elements in a single XML transaction to the service provider. The message content is packaged as an XML-formatted string called packageXml. After the service provider attempts to send the message, it returns an XML-formatted string called xmsResponses that contains one or more error elements that indicate the success or failure of each attempt to send the message to each intended recipient.

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

// ...
private const string m_sOmsNamespace = "https://schemas.microsoft.com/office/Outlook/2006/OMS";

[WebMethod]
public String DeliverXmsBatch(String packageXml)
{
    if (String.IsNullOrEmpty(packageXml))
    {
        throw new ArgumentNullException("packageXml", "packageXml can't be null or empty!");
    }
    String xmsDataTag = "xmsData";
    String xmsBatchTag = "xmsBatch";

    StringWriter responseStringWriter = new StringWriter();
    XmlWriter responseXmlWriter = CreateXmlWriter(responseStringWriter);

    Stack<String> stack = new Stack<String>();
    using (XmlReader reader = XmlReader.Create(new StringReader(packageXml)))
    {
        int messageCount = 0;
        responseXmlWriter.WriteStartElement("xmsResponses", m_sOmsNamespace);
        String nameSpace = String.Empty;

        while (!reader.EOF)
        {
            if (stack.Count == 0)
            {
                if (reader.IsStartElement() && reader.LocalName == xmsBatchTag)
                {
                    stack.Push(xmsBatchTag);
                    nameSpace = reader.NamespaceURI;
                }
            }
            else if (reader.IsStartElement() && stack.Peek() == xmsBatchTag)
            {
                if (reader.IsStartElement(xmsDataTag, nameSpace))
                {
                    String response = String.Empty;

                    if (++messageCount <= m_MaxBatchSize)
                    {
                        // Process this node and its subnodes.
                        response = SendOneXms(reader.ReadOuterXml(), true);
                    }
                    else
                    {
                        String xmsId = reader.GetAttribute("Id");

                        using (StringWriter stringWriter = new StringWriter(new StringBuilder()))
                        {
                            using (XmlTextWriter writer = new XmlTextWriter(stringWriter))
                            {
                                writer.WriteStartElement("xmsResponse");

                                if (!String.IsNullOrEmpty(xmsId))
                                {
                                    writer.WriteAttributeString("Id", xmsId);
                                }

                                String content = String.Format(
                                    "One batch can only contain {0} messages at maximum.", m_MaxBatchSize);
                                BuildError(writer, "perbatchmsglimit", true, content, "");

                                response = stringWriter.GetStringBuilder().ToString();
                            }
                        }

                        reader.ReadOuterXml(); //skip this node and its sub-nodes.
                    }

                    responseXmlWriter.WriteRaw(response);
                    continue;
                }
            }

            reader.Read();
        }
    }

    responseXmlWriter.WriteEndElement();
    responseXmlWriter.Flush();

    return responseStringWriter.ToString();
}

public string SendOneXms(string xmsData, bool batchMode)
{
    String xmsId = "0";
    StringWriter stringWriter = null;
    XmlTextWriter writer = null;

    try
    {
        XmlReader reader = XmlReader.Create(new StringReader(xmsData));
        stringWriter = new StringWriter(new StringBuilder());
        writer = new XmlTextWriter(stringWriter);
        writer.WriteStartElement("xmsResponse", batchMode ? "" : m_sOmsNamespace);
 
        // Update xmsId with your code (for example, reader.GetAttribute("Id")).

        if (!String.IsNullOrEmpty(xmsId))
        {
            writer.WriteAttributeString("Id", xmsId);
        }

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

        reader.Close();

        BuildError(writer, "ok", false /* success */, "", "");

        return stringWriter.GetStringBuilder().ToString();
    }

    catch (XmlException ex)
    {
        // Handle exceptions.
        String attrText = batchMode ? "Id=\"" + xmsId + "\"" : "xmlns=    
            \"https://schemas.microsoft.com/office/Outlook/2006/OMS\"";

        return "<?xml version=\"1.0\" encoding=\"utf-16\"?>"
           + " <xmsResponse " + attrText + ">"
           + "   <error code=\"others\" severity=\"failure\"> <content>" 
           + ex.Message + "</content> </error>" + "</xmsResponse>";
    }

    finally
    {
        if (writer != null)
            writer.Close();
        if (stringWriter != null)
            stringWriter.Close();
    }
}

packageXml

The packageXml string is designed to package a number of xmsData elements (text messages or multimedia messages) into one XML schema. The following example shows a packageXml string that contains two SMS-formatted messages.

Example packageXml string that contains two SMS-formatted messages

<?xml version="1.0" encoding="utf-8"?>
<xmsBatch client="Microsoft Windows SharePoint Service" xmlns="https://schemas.microsoft.com/office/Outlook/2006/OMS">
  <xmsData id="0">
    <user>
      <userId>ddguo</userId>
      <password />
      <customData />
    </user>
    <xmsHead>
      <requiredService>SMS_SENDER</requiredService>
      <sourceType>wssAlert</sourceType>
      <to>
        <recipient>13671121236</recipient>
      </to>
    </xmsHead>
    <xmsBody format="SMS">
      <content contentType="text/plain" contentId="1.txt@5ca13ed023024ed59cfae6c0e185a5db" contentLocation="1.txt">This is a testing message.</content>
    </xmsBody>
  </xmsData>
  <xmsData id="1">
    <user>
      <userId>ddguo</userId>
      <password />
      <customData />
    </user>
    <xmsHead>
      <requiredService>SMS_SENDER</requiredService>
      <sourceType>wssAlert</sourceType>
      <to>
        <recipient>13671121236</recipient>
      </to>
    </xmsHead>
    <xmsBody format="SMS">
      <content contentType="text/plain" contentId="1.txt@ecf25304326e497c8775a929a3178311" contentLocation="1.txt">This is a testing message.</content>
    </xmsBody>
  </xmsData>
</xmsBatch>

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. Applies only 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. Applies only to MMS messages.
MIDI audio format	Audio/mid	MIDI format. Base64 encoded. Applies only to MMS messages.
AMR sound format	Audio/AMR	AMR format, single channel, 8K Hz. Base64 encoded. Applies only 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 and xmsResponses

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.

DeliverXmsBatch() returns an XML-formatted string named xmsResponses that contains one or more error xmsResponse elements, for each and every xmsData element delivery attempt in this batch.

The error element has two child elements: content, which is a string that contains a description or parameters of the error, and recipientList, which is a string that contains a semicolon–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 that notifies the user that the message has not been delivered.

The following are examples of xmsResponse strings.

Example xmsReponse string that indicates that the message was sent successfully

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

Example xmsResponses string returned by DeliverXmsBatch()

<?xml version="1.0" encoding="utf-8"?>
<xmsResponses xmlns="https://schemas.microsoft.com/office/Outlook/2006/OMS">
    <xmsResponse id="0">
        <error code="ok" severity="neutral" />
        <error code="serviceupdate" severity="neutral">
            <content>2008-08-28T08:59:10Z</content>
        </error>
    </xmsResponse>
    <xmsResponse id="1">
        <error code="ok" severity="neutral" />
        <error code="serviceupdate" severity="neutral">
            <content>2008-08-28T08:59:11Z</content>
        </error>
    </xmsResponse>
</xmsResponses>

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(), DeliverXmsBatch(), 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 Multipurpose Internet Mail Extensions (MIME) formatted SMTP e-mail message with an OMS-defined content class. The OMS Web service then sends the e-mail messages to a user-designated e-mail address. When Outlook 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 that contain 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 that the user provides 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 a multipart/alternative content-type and provide an HTML view of the message body.

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

From: "Mobile Inbound Agent" incomingmessage@example-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 an incoming MMS message packaged as an e-mail message

From: "Mobile Inbound Agent" incomingmessage@example-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 multipart message in MIME format.