Introduction To Application Programming With SMS

Microsoft Corporation

October 2002

Applies to:
    Pocket PC 2002 Phone Edition
    Microsoft® eMbedded Visual Tools

Summary: Learn how to Send SMS messages from your eMbedded Visual Basic applications. Take advantage of Pocket PC 2002 Phone Edition's robust support for SMS (Short Message Service) when you build your applications.

Introapp.exe)

Contents

SMS and Pocket PC Phone Edition
SMS-Enabled Applications
Sending SMS Sample
Code Walkthrough
Conclusion

SMS and Pocket PC Phone Edition

Short Message Service is a standard for sending short alpha-numeric messages (max 160 characters) between mobile phones in Global System for Mobile Communications networks (GSM). It works much like paging, but with text, and most phones today have support for SMS.

A key aspect of SMS is that messages are sent through the mobile network operator's network instantly, without the need to manually connect to an Internet Service Provider—SMS messages are instantly delivered while e-mails need to be retrieved from a mail server by the receiver. Also, if the receiver is not online—if the phone is turned off—the SMS message is stored at the operator and forwarded when the phone is turned back on.

On Pocket PC 2002 Phone Edition devices, you can manage SMS messages much in the same way that you manage e-mail messages. The SMS Messaging component is integrated with the standard Inbox application, allowing you to send and receive messages in the same way you send and receive e-mails. You can even forward and reply to e-mails as SMS messages, and vice versa.

SMS-Enabled Applications

Many business scenarios involve notifications of some sort, and SMS is a great way to implement notifications for a variety of business events. It could be a salesman that notifies a service engineer of a customer in need of service, a service engineer notifying an executive of an important business event at the customer, or an executive informing all staff related to the customer about new customer handling routines.

Another interesting use of SMS is to enable mobile commerce (m-commerce), as SMS is often used for handling payment transactions. To get you started, we will show you how to send SMS messages from your Pocket PC 2002 Phone Edition device in the following example.

Sending SMS Sample

A simple form using Microsoft® eMbedded Visual Basic®:

Figure 1. SMS Sample application

In this form, you can enter an international mobile phone number and a text message. When you hit the Send button, the message is sent—as simple as that!

Code Walkthrough

Let's look at the core of the code for sending SMS messages. First of all, you need to declare a number of Microsoft Windows® APIs:

• One for opening the SMS Messaging component

• One for sending SMS messages

• And one for closing the SMS Messaging component:

  Public Declare Function SmsOpen Lib "SMS" (ByVal ptsMessageProtocol
    As String, ByVal dwMessageModes As Long, ByRef psmshHandle As
    Long, ByRef phMessageAvailableEvent As Long) As Long
  
  Public Declare Function SmsSendMessage Lib "SMS" (ByVal smshHandle
    As Long, ByVal psmsaSMSCAddress As Long, ByVal
    psmsaDestinationAddress As String, ByVal pstValidityPeriod As
    Long, ByVal pbData As String, ByVal dwDataSize As Long, ByVal
    pbProviderSpecificData As String, ByVal dwProviderSpecificDataSize
    As Long, ByVal smsdeDataEncoding As Long, ByVal dwOptions As Long,
    ByRef psmsmidMessageID As Long) As Long
  
  Public Declare Function SmsClose Lib "SMS" (ByVal smshHandle As
    Long) As Long
  

  You also need some API constants declared for the different APIs:

  Public Const SMS_MSGTYPE_TEXT = "Microsoft Text SMS Protocol"
  Public Const SMS_MODE_SEND = 2            ' Open in send mode
  Public Const SMSDE_GSM = 1                ' Use standard GSM
    encoding
  Public Const SMSAT_INTERNATIONAL = 1      ' International number
    format
  Public Const PS_MESSAGE_OPTION_NONE = 0   ' No message options
  Public Const PS_MESSAGE_CLASS0 = 0        ' Send immediately
  Public Const PSRO_NONE = 0                ' No replacements
  Public Const SMS_OPTION_DELIVERY_NONE = 0 ' No delivery options
  

  The following is the complete code to send an SMS message:

  Public Sub SendSMS(ByVal Number As String, ByVal Message As String)
  
    Dim SMSHandle As Long
    Dim SMSEvent As Long
    Dim SMSAddress As String
    Dim SMSProvider As String
  
    ' Open SMS Messaging Component
    Call SmsOpen(SMS_MSGTYPE_TEXT, SMS_MODE_SEND, SMSHandle, SMSEvent)
  
    ' Set Address structure (UDT as string)
    SMSAddress = LongToBytes(SMSAT_INTERNATIONAL) & Number
  
    ' Set Provider structure (UDT as string)
    SMSProvider = LongToBytes(PS_MESSAGE_OPTION_NONE) & _
                  LongToBytes(PS_MESSAGE_CLASS0) & _
                  LongToBytes(PSRO_NONE)
  
    ' Send message
    If 0 = SmsSendMessage(SMSHandle, 0, SMSAddress, 0, Message, _
           LenB(Message), SMSProvider, 12, SMSDE_GSM, _
           SMS_OPTION_DELIVERY_NONE, 0) Then
      MsgBox "Message sent!", vbInformation, App.Title
    Else
      MsgBox "Could not send message!", vbCritical, App.Title
    End If
  
    ' Close SMS Messaging Component
    Call SmsClose(SMSHandle)
  
  End Sub
  

First, the SMS Messaging component is opened (SmsOpen) and its handle is stored (SMSHandle). This handle is needed to call other SMS APIs.

A number of structures or UDTs (User Defined Types) need to be prepared for thecall to SmsSendMessage. Since eMbedded Visual Basic lacks support for UDTs, simple strings are used to emulate a structure.

The first is a structure containing the address of the SMS message. The address structure contains an indicator of what kind of number is supplied (in this case an international number) and the number itself.

The next structure contains various options regarding the service provider. The first part of the structure indicates that no special options are selected, and the second part indicates that the message should be sent immediately.

The last part states that no replacement should be made.

In the call to send the message (SmsSendMessage), the prepared structures are supplied, the message text and a number of options. Finally, the handle is closed (SmsClose).

For a complete example, see this article's sample code. Also, you can read more about this technique in Antonio Paneiro's article, UDTs (User Defined Types) with VBCE.

Conclusion

SMS is great for small and instant text notifications. And with the support in Pocket PC 2002 Phone Edition, you will be able to make your applications "SMS aware." With the sample code from this example, you have most of what you need to get going. If you accept that the mobile world, in terms of communication mechanisms and protocols, is more about "both/and" rather than "or/else," you pragmatically can use each option when suitable.