Información general sobre el desarrollo de dispositivos de mensajería móvil

Artículo
09/24/2014

Última modificación: miércoles, 14 de abril de 2010

Hace referencia a: SharePoint Foundation 2010

En este tema se proporciona información general sobre cómo agregar funcionalidad de mensajería para móviles a un proyecto de desarrollo de Microsoft SharePoint Foundation usando las API de mensajería para móviles del kit de desarrollo de software (SDK) de SharePoint Foundation. Con fines prácticos, estas API pueden dividirse en dos grupos amplios: las que admiten mensajes del servicio de mensajes cortos (SMS) (también llamada "mensajes de texto") usando el protocolo de comunicación Office Mobile Service (OMS) y las que le permiten crear compatibilidad con otros protocolos de estructura de comunicación o mensajes. En la mayoría de los escenarios de desarrollo, el remitente de los mensajes es la aplicación web de SharePoint Foundation en lugar de un usuario específico, por lo que la implementación de SharePoint Foundation necesitará tener una cuenta con una compañía proveedora de servicios de mensajería móvil (MSP) que admita el protocolo de comunicación que usa la solución.

El protocolo Office Mobile Service (OMS) es un protocolo de comunicación que proporciona una implementación de los protocolos de estructura del mensaje de SMS y sistema de mensajería multimedia (MMS). OMS requiere el protocolo SOAP para el acceso al servicio web. Las API que admiten OMS que se describen en Soluciones de mensajería OMS-SMS a continuación están diseñadas para mensajería SMS. Todas las clases o miembros que encuentre en el espacio de nombres Microsoft.SharePoint.MobileMessage y que tengan "MMS" en el nombre, o que solo tengan sentido en el contexto de mensajería MMS, son para uso interno únicamente y no deben llamarse desde el código. Para desarrollar soluciones de mensajería que no usen OMS como protocolo de comunicación o que use OMS para mensajes MMS, use el nivel de API más abstracto que se describe en Desarrollo de otros protocolos a continuación.

Soluciones de mensajería OMS-SMS

SharePoint Foundation proporciona varias API que realizan todas las llamadas al método web OMS, y todo el análisis y escritura de XML, por el usuario. El código simplemente llama a las API mediante la sintaxis orientada a objetos familiar.

Creación de una cuenta MSP para una aplicación web

Cada aplicación web de SharePoint Foundation, incluida la aplicación web de Administración central, puede tener una cuenta con un proveedor de servicio de mensajería móvil (MSP). Normalmente, estas cuentas las establece un administrador de la granja de servidores en la parte Administración de aplicaciones de la aplicación Administración central. No obstante, es posible crear una cuenta mediante programación y asignarla a una aplicación web. En primer lugar, llame a un constructor SPMobileMessagingAccount() que no requiera un parámetro SPMobileMessageServiceProvider. A continuación, llame al método UpdateSmsAccount(SPMobileMessagingAccount) para asignar la cuenta a una aplicación web. En el siguiente fragmento, webApp es una referencia a un objeto SPWebApplication. (Vea Obtención de referencias a sitios, aplicaciones web y otros objetos clave para obtener información sobre cómo obtener una referencia a dicho objeto.) El fragmento supone que el archivo tiene instrucciones using para Microsoft.SharePoint y System.Security. Tenga en cuenta que la llamada a UpdateSmsAccount(SPMobileMessagingAccount) se pasa como parte de un delegado anónimo al método RunWithElevatedPrivileges(SPSecurity.CodeToRunElevated).

SecureString password = new SecureString();
password.AppendChar(‘a’);
password.AppendChar(‘Z’);
password.AppendChar(‘3’);
password.AppendChar(‘&’);

SPMobileMessagingAccount account = new SPMobileMessagingAccount("Contoso Messaging",
                                                                "https://contoso.com/services/mobilemessages",
                                                                 "BobG",
                                                                 password);

SPSecurity.RunWithElevatedPrivileges(delegate() {webApp.UpdateSmsAccount(account);
                                                 webApp.Update();});

Dim password As New SecureString()
        password.AppendChar("a")
        password.AppendChar("z")
        password.AppendChar("3")
        password.AppendChar("&")

        Dim account As New SPMobileMessagingAccount("Contoso Messaging", "https://contoso.com/services/mobilemessages", "BobG", password)


        SPSecurity.RunWithElevatedPrivileges(Sub()
                                                 webApp.UpdateSmsAccount(account)
                                                 webApp.Update()
                                             End Sub)

Una vez que se haya asignado una cuenta con el MSP a la aplicación web, el código puede comenzar a usar la propiedad OutboundSmsServiceAccount como referencia al objeto de cuenta de la aplicación web.

Creación de un objeto de servicio web

Cuando tiene un SPMobileMessagingAccount, el código puede usarlo para crear un objeto SPMobileMessageWebService que contenga los métodos para enviar mensajes SMS. Cada vez que se obtiene una referencia a un objeto SPMobileMessagingAccount persistente, recomendamos comprobar siempre que no es null y que su propiedad IsValidAccount() es true. El fragmento siguiente ilustra cómo crear un objeto de servicio web. webApp es una referencia a un objeto SPWebApplication.

SPMobileMessagingAccount account = webApp.OutboundSmsServiceAccount;
if (account == null || !account.IsValidAccount())
{
    throw new SPException("The account passed in is invalid.");
}
else
{
    SPMobileMessageWebService messagingWebService = new SPMobileMessageWebService(account);
}

Dim account As SPMobileMessagingAccount = webApp.OutboundSmsServiceAccount
If account Is Nothing OrElse (Not account.IsValidAccount()) Then
    Throw New SPException("The account passed in is invalid.")
Else
    Dim messagingWebService As New SPMobileMessageWebService(account)
End If

Creación y envío de un mensaje móvil

Las dos tareas críticas siguientes son crear y enviar el mensaje.

Creación de un mensaje

Con un objeto SPMobileMessageWebService el código puede llamar a los métodos web OMS del servicio mediante los métodos del objeto como proxies. El más importante de éstos, naturalmente, es el método SendMessage(String). No obstante, para poder llamarlo, primero el código debe crear el mensaje. Hay tres métodos para hacerlo.

El código puede llamar al método BuildSmsMessage(SPMobileMessagingAccount, String, String) estático y pasarle parámetros para la cuenta del remitente, un destinatario y el texto del mensaje. Ésta es la forma más simple pero menos flexible.
El código puede llamar a una de las sobrecargas de SetTextContent(). En este caso, primero deberá construir el SPMobileMessageSmsBuilder y agregar destinatarios con llamadas del método AddRecipient(String) y, además, convertir el mensaje del objeto SPMobileSmsMessage que crea SetTextContent() al XML de mensaje adecuado del protocolo OMS. Esta forma de crear el mensaje le da la opción de tener varios destinatarios. También le permite establecer un límite de número de páginas secundarias inferior al que impone el proveedor del servicio.(ContentParts) en que el mensaje se divide si el texto del mensaje excede el límite de caracteres impuesto por el servicio.
El código puede crear una transacción de creación de mensajes. Dicha transacción consta de lo siguiente:
1. Una llamada de StartTextMessage()
2. Una o varias llamadas de AddChunk(String)
3. Una llamada de una de las sobrecargas de EndTextMessage()
Esta forma de crear el mensaje incluye todas las opciones, y complicaciones, del método anterior, pero, además, proporciona un mayor control sobre la forma en que se puede dividir el mensaje en páginas y en opciones adicionales, como la opción de agregar números de página.

Independientemente del método usado, si un mensaje excede el límite de caracteres que estableció el proveedor del servicio, el algoritmo de creación del mensaje intentará dividir el mensaje en varios mensajes separando el texto en fragmentos. Un fragmento de texto es una serie de caracteres que deben permanecer juntos en el mismo mensaje, si es posible. Esto hará que la serie de mensajes resultantes sea más coherente que si el mensaje primario se dividiera en partes iguales pero de forma arbitraria. Si un fragmento específico excede el límite de caracteres, se dividirá de todos modos. Solo el tercer método para crear un mensaje permite al código tener cierto control sobre la forma en que el mensaje se divide en fragmentos. El siguiente fragmento de código ilustra el tercer método. Tenga en cuenta lo siguiente sobre este ejemplo:

account es una referencia a un objeto SPMobileMessagingAccount.
Aunque solo hay una llamada a AddRecipient(String), puede llamarse varias veces para enviar el mismo mensaje a varios destinatarios, hasta el límite impuesto por el MSP.
SplitLongMessage se define en el siguiente bloque de código a continuación.
message es un objeto String que contiene el mensaje.
Una vez finalizada la transacción de creación de un mensaje, el objeto SPMobileMessageSmsBuilder contiene el mensaje en su propiedad Message.

SPMobileMessageSmsBuilder smsBuilder = new SPMobileMessageSmsBuilder(account);
smsBuilder.AddRecipient(mobile_telephone_number);

// Begin the message building transaction
smsBuilder.StartTextMessage();

// Add the message text, split as needed into chunks.
List<StringBuilder> messageParts = SplitLongMessage(message)
foreach (StringBuilder chunk in messageParts)
{
    smsBuilder.AddChunk(chunk.ToString());
}

// Finish the transaction
smsBuilder.EndTextMessage();

// At this point, the smsBuilder.Message property holds the message as an SPMobileSmsMessage object.

Dim smsBuilder As New SPMobileMessageSmsBuilder(account)
smsBuilder.AddRecipient(mobile_telephone_number)

' Begin the message building transaction
smsBuilder.StartTextMessage()

' Add the message text, split as needed into chunks.
Dim messageParts As List(Of StringBuilder) = SplitLongMessage(message)
For Each chunk As StringBuilder In messageParts
    smsBuilder.AddChunk(chunk.ToString())
Next

' Finish the transaction
smsBuilder.EndTextMessage()

' At this point, the smsBuilder.Message property holds the message as an SPMobileSmsMessage object

El método SplitLongMessage implementa un algoritmo simple para garantizar que ningún fragmento del mensaje exceda el límite de 133 caracteres (byte único) para cada fragmento de un mensaje SMS concatenado, a veces llamado "mensaje SMS largo". Asimismo, garantiza que las divisiones siempre se realicen en espacio en blanco, para que ninguna palabra quede dividida entre diferentes partes del mensaje. Se necesitaría un algoritmo más complejo si la solución de mensajería para móviles no puede asumir que todos los caracteres del mensaje serán de byte único.

public static List<StringBuilder> SplitLongMessage(String message)
{
    // Split the original message at white space.
    String[] words = message.Split(null);

    List<StringBuilder> chunks = new List<StringBuilder>();
    StringBuilder latestChunk = new StringBuilder(132);

    // Reconstruct the message in chunks of up to 133 characters.
    foreach (String word in words)
    {
        if (word.Length + latestChunk.Length <= 132) //Not 133 because a space will be added
        {
            latestChunk.Append(word + " "); // Add back the white space
        }
        else
        {
            // Add a copy of the chunk to the list
            chunks.Add(new StringBuilder(latestChunk.ToString()));

            // Empty out latest chunk so the next one can be started
            latestChunk.Remove(0, latestChunk.Length);

            // The word that exceeded the limit becomes the first word of the next chunk
            latestChunk.Append(word + " ");
        }
    }

    // Add the last short chunk
    if (latestChunk.Length > 0)
    {
        chunks.Add(latestChunk);
    }

    return chunks;
}

Public Shared Function SplitLongMessage(ByVal message As String) As List(Of StringBuilder)
    ' Split the original message at white space.
    Dim words() As String = message.Split(Nothing)

    Dim chunks As New List(Of StringBuilder)()
    Dim latestChunk As New StringBuilder(132)

    ' Reconstruct the message in chunks of up to 133 characters.
    For Each word As String In words
        If word.Length + latestChunk.Length <= 132 Then 'Not 133 because a space will be added
            latestChunk.Append(word & " ") ' Add back the white space
        Else
            ' Add a copy of the chunk to the list
            chunks.Add(New StringBuilder(latestChunk.ToString()))

            ' Empty out latest chunk so the next one can be started
            latestChunk.Remove(0, latestChunk.Length)

            ' The word that exceeded the limit becomes the first word of the next chunk
            latestChunk.Append(word & " ")
        End If
    Next word

    ' Add the last short chunk
    If latestChunk.Length > 0 Then
        chunks.Add(latestChunk)
    End If

    Return chunks
End Function

Sea que el objeto SPMobileSmsMessage (al que se hace referencia en la propiedad SPMobileMessageBuilder.Message) se cree con una llamada de SetTextContent() o mediante una transacción de creación de mensaje, el código debe convertir dicho objeto al XML de mensaje de formato OMS adecuado. Esto se hace mediante una llamada del método GetMessageXml(). Este paso de escritura de XML adicional no es necesario si el mensaje se crea mediante una llamada del método BuildSmsMessage(SPMobileMessagingAccount, String, String), ya que devuelve el XML del mensaje.

String messageXml = smsBuilder.GetMessageXml();

Dim messageXml As String = smsBuilder.GetMessageXml()

Envío de un mensaje

Un mensaje se envía pasando el XML del mensaje completo conforme a OMS al método SendMessage(String) de un objeto SPMobileMessageWebService. Vea Creación de un objeto de servicio web más arriba para obtener información sobre cómo crear un objeto. En el siguiente fragmento, messagingWebService es un objeto SPMobileMessageWebService y messageXml es el mensaje completo conforme a OMS.

SPMobileMessageDeliveryReport report = messagingWebService.SendMessage(messageXml);

Dim report As SPMobileMessageDeliveryReport = messagingWebService.SendMessage(messageXml)

El informe que devuelve SendMessage(String) contiene información acerca de si el mensaje se envió correctamente y, en caso contrario, por qué se produjo un error. Recomendamos incluir código que procese el informe, registre los mensajes enviados correctamente y responda a los errores. Para obtener información sobre la estructura del informe, vea SPMobileMessageDeliveryReport.

Envío de mensajes por lotes

Si la solución usa el método de envío por lotes, el código deberá almacenar los mensajes que se creen entre trabajos por lotes en algún tipo de estructura de cola que se pueda vaciar cuando se envía el lote, como List<T><SPMobileSmsMessage>. El trabajo por lotes comienza con la creación de un objeto SPMobileMessageBatchPackage al que se agrega cada objeto de mensaje. A continuación, el paquete se pasa al método BatchSendMessages(SPMobileMessageBatchPackage).

En el fragmento siguiente, messageCollection es un objeto List<T><SPMobileSmsMessage> y messagingWebService es un objeto SPMobileMessageWebService. Vea Creación de un objeto de servicio web más arriba para obtener información sobre cómo crear este tipo de objeto.

SPMobileMessageBatchPackage package = new SPMobileMessageBatchPackage();

foreach (SPMobileSmsMessage message in messageCollection)
{
    package.AddMessage(message);
}

List<SPMobileMessageDeliveryReport> reports = messagingWebService.BatchSendMessages(package);

Dim package As New SPMobileMessageBatchPackage()

For Each message As SPMobileSmsMessage In messageCollection
    package.AddMessage(message)
Next message

Dim reports As List(Of SPMobileMessageDeliveryReport) = messagingWebService.BatchSendMessages(package)

Tenga en cuenta que no es necesario convertir explícitamente los objetos SPMobileSmsMessage que están en el paquete a mensajes XML conforme a OMS. El paquete devuelve el XML del trabajo por lotes entero en su propiedad Xml. Este XML envía el método BatchSendMessages(SPMobileMessageBatchPackage) al servicio web de mensajería.

Recomendamos incluir código que procese la lista de informes devuelta por el método BatchSendMessages(SPMobileMessageBatchPackage), que registre los mensajes enviados correctamente y que responda a los errores.

Otros métodos de servicio web

La clase SPMobileMessageWebService tiene otros dos métodos: GetUserInfo(String) y GetServiceInfo(), que actúan como proxies para los métodos web OMS GetUserInfo y GetServiceInfo, respectivamente.

Desarrollo de otros protocolos

Microsoft no admite la derivación de ninguna de las clases de Microsoft.SharePoint.MobileMessage para crear una solución de mensajería para móviles que no use el protocolo OMS. Si desea que la solución funcione con este tipo de MSP que no usa OMS, considere crear un servicio web que actúe como capa intermedia entre las API de mensajería para móviles de SharePoint Foundation y el MSP que usa otro protocolo. El servicio aceptaría mensajes de protocolo OMS de SharePoint Foundation y las transformaría en mensajes adecuados para el MSP que usa el otro protocolo.

Compartir a través de