How can we help?

AxSms.Gsm


Introduction

Skip to properties and methods

The GSM protocol object is able to connect to most GSM modem devices. Either through the TAPI (Windows Telephony API), directly through the COM interface or through an IP connection. The GSM protocol only uses ‘AT’ commands to communicate with the device and send and receive messages.

In addition to sending and receiving SMS messages it’s possible to send and receive custom commands. This could be used to, for instance, send a custom initialization string to the GSM modem before usage.

Send SMS using GSM modem

This sample will send out a single SMS messaging use the first TAPI device that’s connected to the PC.

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create GSM protocol object
Set objMessage = CreateObject("AxSms.Message")         ' Create SMS message object

' Show version information
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
  objGsm.Build & "; Module " & objGsm.Module
WScript.Echo License Status: " & objGsm.LicenseStatus & vbCrLf

objGsm.Logfile = "log.txt"                             ' Keep a session log

' Open the first connected device
sDevName = objGsm.FindFirstDevice
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If

' Compose an SMS message
objMessage.ToAddress = "+31122334455"
objMessage.Body = "This is a short text message"

' Send an SMS message through the connected GSM modem device
objGsm.SendSms objMessage
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  objGsm.Close
  WScript.Quit 1
End If

' Make sure to close the device to allow other applications to access it.
objGsm.Close
WScript.Echo "Done !"

Receive SMS using GSM modem

Read all SMS messages and status reports that are already on the SIM and leave them on the SIM card

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create GSM protocol object
Set objConst = CreateObject("AxSms.Constants")         ' Create global constants object
Set objMessage = CreateObject("AxSms.Message")         ' Create SMS message object

' Show version information
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
  objGsm.Build & "; Module " & objGsm.Module
WScript.Echo "License Status: " & objGsm.LicenseStatus & vbCrLf

objGsm.Logfile = "log.txt"                             ' Keep a session log

' Open the first connected device
sDevName = objGsm.FindFirstDevice
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)    
  WScript.Quit 1
End If

' Receive messages from the SIM card and leave them on the SIM card
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  objGsm.Close
  WScript.Quit 1
End If

' Show all SMS messages
Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend

' Show all status reports
Set objReport = objGsm.GetFirstReport
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objReport.FromAddress & _
    "; reference: " & objReport.Reference
  Set objReport = objGsm.GetNextReport
Wend

' Make sure to close the device to allow other applications to access it.
objGsm.Close
WScript.Echo "Done !"

Using application ports

An SMS message can specify an application port. The usage of application ports is very much like the usage of ports in the IP based protocols. If a message specifies it’s application ports it will specify both a source port as well as a destination port. The source port specifies which application sent the message. The destination port specifies to which application the message was intended.

An example of the use of application ports is the WAP Push message. A WAP Push message is a binary message which will push an URL to the MT. A WAP Push message will always be sent to application port 2948 where the Push application can pick-up the message and present it to the user.

Sending a message using an application port is just a matter of specifying the port(s) in either the ‘ToAddress’ of the message or the ‘FromAddress’ or both. For example, to send a message to “+31623350000” on port number “1000” use this:


Set objMessage = CreateObject("AxSms.Message")
...
objMessage.ToAddress = "31623350000:1000"

In this example the source port will be ‘0’. To also specify the source port use this:


Set objMessage = CreateObject("AxSms.Message")
...
objMessage.ToAddress = "31623350000:1000"
objMessage.FromAddress = ":1000"

To control the way message that are sent to a specific port are received you can use the property ‘ExtractApplicationPort’

When this property is set to ‘True’ application port specifying UDH headers will be extracted from the SMS message and the application ports will be appended to the ‘FromAddress’ and the ‘ToAddress’ respectively. When this property is set to ‘False’ the application port specifying UDH headers will be ignored.

If the ‘ExtractApplicationPort’ property is set to true application ports will be properly extracted for 16 bit port headers as well as 8 bit port headers. When sending messages to a specific application port the 16 bit headers will always be used.

Using national language shift tables

The national language shift tables are an extension to the GSM 03.38 standard that introduces different language character sets.

This means that for those languages that are present in the national language shift tables you can send SMS messages without using the Unicode character set. A single part Unicode message can only use 70 characters while a single part SMS that uses the national language shift tables can contain up to 152 characters. Or 155 when only the locking shift table is used.

Send an SMS using the national language shift table by simply setting the LanguageLockingShift and the LanguageSingleShift properties.


Set objMessage = CreateObject("AxSms.Message")
Set objConstants = CreateObject("AxSms.Constants")
...
objMessage.LanguageLockingShift = objConstants.LANGUAGE_LOCKINGSHIFT_HINDI
objMessage.LanguageSingleShift = objConstants.LANGUAGE_SINGLESHIFT_HINDI
objMessage.Body = "नमस्ते दुनिया!"

To control the way that messages with the language shift tables are received please look at the ExtractLanguageShift property.

Properties and Methods

Property Type Read/Write Description
Version String Read Version number of the SMS Component
Build String Read Build number of the SMS Component
Module String Read Module name of the SMS Component
LicenseStatus String Read License Status
LicenseKey String Read/Write License Key
LastError Number Read Result of the last called method
LogFile String Read/Write The path to a logfile which can be used for troubleshooting
Manufacturer String Read The manufacturer of the open device
Model String Read The model of the open device
SerialNr String Read The serial number of the open device
Revision String Read The revision number of the open device
IsOpen Boolean Read Whether a connection to a GSM device is currently open.
TcpMode Integer Read/Write The TCP mode when connecting to the GSM device using TCP/IP
OverrideFeatureCheck Boolean Read/Write Assume without verification that sending and receiving is supported
AssembleMultipart Boolean Read/Write Whether multipart messages should be automatically assembled
ExtractApplicationPort Boolean Read/Write Whether the application port is extracted from the message
ExtractLanguageShift Boolean Read/Write Whether language shift should be applied
MessageMode Number Read/Write Whether the modem should be used in Text mode or PDU mode
PreferredSmsc String Read/Write Set the preferred SMSC
PrefixSmscMode Number Read/Write Whether or not to include the SMSC prefix in PDU’s
SendEnabled Boolean Read Whether the GSM modem is able to send SMS messages
ReceiveEnabled Boolean Read Whether the GSM modem is able to receive SMS messages
ReportEnabled Boolean Read Whether the GSM modem is able to receive delivery reports
WaitForNetwork Boolean Read/Write Whether to wait for the device to register to a GSM network on open
NetworkTimeout Number Read/Write Timeout in milliseconds for registering on a GSM network
CommandTimeout Number Read/Write Timeout in milliseconds for sending commands to the device
InterCommandDelay Number Read/Write Time in milliseconds between sending commands to the device
InterCharacterDelay Number Read/Write Time in milliseconds between sending characters to the device

Method Description
Clear Reset all properties to their default values
SaveLicenseKey Save the License Key in the registry
GetErrorDescription Get the description of the given error
Sleep Sleep for the specified number of milliseconds
FindFirstDevice Find the first connected Windows telephony device
FindNextDevice Find the next connected Windows telephony device
FindFirstPort Find the first COM port on this PC
FindNextPort Find the next COM port on this PC
Open Open a Windows telephony device, COM port op TCP/IP connection
Close Close the device
ResetCom Reset COM status
SendCommand Send a custom command to the connected device
ReadResponse Read a string from the connected device
SendSms Send an SMS Message
Receive Receive SMS messages and status reports
DeleteSms Delete an SMS message
DeleteReport Delete a GsmDeliveryReport
GetFirstSms Get the first received SMS message
GetNextSms Get the next received SMS message
GetFirstReport Get the first received status report
GetNextReport Get the next received status report

Version property

Return the version number of the SMS Component

Example:

Set objGsm = CreateObject("AxSms.Gsm")
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
  objGsm.Build & "; Module " & objGsm.Module
WScript.Echo "License Status: " & objGsm.LicenseStatus & vbCrLf
...

Build property

Return the build number of the SMS Component.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
objGsm.Build & "; Module " & objGsm.Module
WScript.Echo "License Status: " & objGsm.LicenseStatus & vbCrLf
...

Module property

Return the module name of the SMS Component.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
objGsm.Build & "; Module " & objGsm.Module
WScript.Echo "License Status: " & objGsm.LicenseStatus & vbCrLf
...

LicenseStatus property

The status of your license. In case you have not licensed the product, the property holds the trial expiration date. For details, see Product Activation.

Example:

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create new instance
WScript.Echo "License Status: " & objGsm.LicenseStatus
WScript.Echo "License Key: " & objGsm.LicenseKey

LicenseKey property

A license key is required to unlock this component after the trial period has expired. Assign the LicenseKey property every time a new instance of this component is created (see code below). Alternatively, the LicenseKey property can be set automatically. This requires the license key to be stored in the registry. For details, see Product Activation.

Example:

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create new instance
objGsm.LicenseKey = "XXXXX-XXXXX-XXXXX"                ' Assign your license key 
WScript.Echo "LicenseKey: " & objGsm.LicenseKey

LastError property

Completion code of the last called method. To find the error description of a given error code, go to the online error codes codes page.

Example:

Set objGsm = CreateObject("AxSms.Gsm")  
...  
Set objMessage = CreateObject("AxSms.Message")
objMessage.ToAddress = "+31611223344"
objMessage.Body = "Short text message"
objGsm.SendSms objMessage
WScript.Echo "SendSms result:" &  objGsm.LastError ' Is message sent ?  
...

LogFile property

By default, LogFile holds an empty string and nothing is logged. If a valid file name is assigned to it, the SMS Component will write debug information to this file. Output data is written at the end of the file, the file is not cleared.

Example:

Set objGsm = CreateObject("AxSms.Gsm")   
objGsm.LogFile = "C:\temp\log.txt"
...
Set objMessage = CreateObject("AxSms.Message")
objMessage.ToAddress = "+31611223344"
objMessage.Body = "Short text message"  
objGsm.SendSms objMessage
...

Manufacturer property

After opening a GSM device this property will return the manufacturer of the GSM device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
sDevName = objGsm.FindFirstDevice
WScript.Echo "Opening: " & sDevName
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If

WScript.Echo "Manufacturer: " & objGsm.Manufacturer
WScript.Echo "Model: " & objGsm.Model
WScript.Echo "Revision: " & objGsm.Revision
WScript.Echo "SerialNr: " & objGsm.SerialNr
...

Model property

After opening a GSM device this property will return the model of the GSM device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
sDevName = objGsm.FindFirstDevice
WScript.Echo "Opening: " & sDevName
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If

WScript.Echo "Manufacturer: " & objGsm.Manufacturer
WScript.Echo "Model: " & objGsm.Model
WScript.Echo "Revision: " & objGsm.Revision
WScript.Echo "SerialNr: " & objGsm.SerialNr
...

SerialNr property

After opening a GSM device this property will return the serial number of the GSM device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
sDevName = objGsm.FindFirstDevice
WScript.Echo "Opening: " & sDevName
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If

WScript.Echo "Manufacturer: " & objGsm.Manufacturer
WScript.Echo "Model: " & objGsm.Model
WScript.Echo "Revision: " & objGsm.Revision
WScript.Echo "SerialNr: " & objGsm.SerialNr
...

Revision property

After opening a GSM device this property will return the revision number of the GSM device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
sDevName = objGsm.FindFirstDevice
WScript.Echo "Opening: " & sDevName
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If

WScript.Echo "Manufacturer: " & objGsm.Manufacturer
WScript.Echo "Model: " & objGsm.Model
WScript.Echo "Revision: " & objGsm.Revision
WScript.Echo "SerialNr: " & objGsm.SerialNr
...

IsOpen property

Returns true if this instance of the GSM object is currently connected to a GSM device.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
sDevName = objGsm.FindFirstDevice
WScript.Echo "Opening: " & sDevName
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If

WScript.Echo "Connection is open: " & objGsm.IsOpen
...

TcpMode property

This property sets the connection characteristics when connecting using TCP/IP. Use one of
these constants.

By default this property is set to GSM_TCPMODE_TELNET_WITH_COMCONTROL.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConstants = CreateObject("AxSms.Constants")
...
objGsm.TcpMode = objConstants.GSM_TCPMODE_RAW
objGsm.Open "192.168.1.29:2001"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If
...

OverrideFeatureCheck property

Overrides the GSM component feature check when opening the GSM device.

This property is useful when a GSM device does not correctly reports about its ability to send or receive SMS messages.

By default this property is set to false.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConstants = CreateObject("AxSms.Constants")
...
objGsm.OverrideFeatureCheck = True
objGsm.TcpMode = objConstants.GSM_TCPMODE_RAW
objGsm.Open "192.168.1.29:2001"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit
End If
...

AssembleMultipart property

Set this property to true to have the SMS Component automatically assemble multipart messages on receiving them. If this property is set to false the SMS Component will return all of the individual parts on receiving a multipart message.

By default this property is set to true.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.AssembleMultipart = false
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If

Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend
...

ExtractApplicationPort property

This property will only affect incoming SMS messages that contain an application port specifier. An SMS can contain an application port if it is meant to target a specific application. For example a WAP Push message will always have destination port 2948 to target the WAP Push application specifically.

If this property is set to ‘True’ the SMS Component will interpret the application port by appending the source port to the ‘FromAddress’ property and the destination port to the ‘ToAddress’ property separated by a colon character (‘:’). The SMS Component will remove the application port header from the SMS.

If this property is set to ‘False’ the SMS Component will not interpret the application port and leave the application port header in place. The application ports will not be added to the ‘FromAddress’ and ‘ToAddress’ properties.

By default this property is set to true.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.ExtractApplicationPort = False
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If

Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend
...

ExtractLanguageShift property

This property controls if the language shift tables should be applied. This only applies when receiving SMS messages that include a national language shift user data header (UDH).

With this property set to True the UDH is extracted and the appropriate national language tables are used automatically.

If this property is set to False the message the UDH is left in place and the message will be HEX formatted.

To send SMS messages using one of the language shift tables use the LanguageLockingShift and the LanguageSingleShift properties.

By default this property is set to true.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.ExtractLanguageShift = False
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If

Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Language locking shift: " & objMessage.LanguageLockingShift
  WScript.Echo "Language single shift: " & objMessage.LanguageSingleShift
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend
...

MessageMode property

Most modems are able to send and receive SMS messages in either Text mode or PDU mode. In PDU mode all SMS Messaging features are available, in Text mode only a subset of the features are available. Some older or specific GSM modems only
support Text mode. Set this value to one of these constants.

By default this value is set to ‘GSM_MESSAGEFORMAT_AUTO’.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConst = CreateObject("AxSms.Constants")
Set objMessage = CreateObject("AxSms.Message")
...
objGsm.MessageMode = objConst.GSM_MESSAGEFORMAT_TEXT
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
objMessage.ToAddress = "+31611223344"
objMessage.Body = "I'm texting through the Auron SMS Component !"  
objGsm.SendSms(objMessage)
...

PreferredSmsc property

Use this property to set the preferred SMSC address. The SMSC address should be specified as an international number, including ‘+’.

The preferred SMSC should be set before calling the Open method.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConst = CreateObject("AxSms.Constants")
Set objMessage = CreateObject("AxSms.Message")
...
objGsm.PreferredSmsc = "+316540881000"
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
objMessage.ToAddress = "+31611223344"
objMessage.Body = "I'm texting through the Auron SMS Component !"  
objGsm.SendSms(objMessage)
...

PrefixSmscMode property

The prefix SMSC mode. Some GSM modems or older mobile phones don’t support prefixing SMSC information in sending and/or receiving messages. Set this value to one of these constants.

By default this value is set to ‘GSM_SMSPREFIX_AUTO’.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConst = CreateObject("AxSms.Constants")
Set objMessage = CreateObject("AxSms.Message")
...
objGsm.PrefixSmscMode = objConst.GSM_SMSPREFIX_DISABLED
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
objMessage.ToAddress = "+31611223344"
objMessage.Body = "I'm texting through the Auron SMS Component !"  
objGsm.SendSms(objMessage)
...

SendEnabled property

If the GSM modem is able to send SMS messages this property will return ‘True’.

Example:

Set objGsm = CreateObject("AxSms.Gsm")   
...
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If            
...
WScript.Echo "Modem capabilities:"
WScript.Echo "Receiving: " & objGsm.ReceiveEnabled
WScript.Echo "Sending: " & objGsm.SendEnabled
WScript.Echo "Delivery reports: " & objGsm.ReportEnabled
...

ReceiveEnabled property

If the GSM modem is able to receive SMS messages this property will return ‘True’.

Example:

Set objGsm = CreateObject("AxSms.Gsm")   
...
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If            
...
WScript.Echo "Modem capabilities:"
WScript.Echo "Receiving: " & objGsm.ReceiveEnabled
WScript.Echo "Sending: " & objGsm.SendEnabled
WScript.Echo "Delivery reports: " & objGsm.ReportEnabled
...

ReportEnabled property

If the GSM modem is able to receive delivery (status) reports this property will return ‘True’.

Example:

Set objGsm = CreateObject("AxSms.Gsm")   
...
objGsm.Open "COM1"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If            
...
WScript.Echo "Modem capabilities:"
WScript.Echo "Receiving: " & objGsm.ReceiveEnabled
WScript.Echo "Sending: " & objGsm.SendEnabled
WScript.Echo "Delivery reports: " & objGsm.ReportEnabled
...

WaitForNetwork property

This property specifies whether or not to wait for the device to register to a GSM network on calling the Open method.

After inserting the SIM card or switching on the power supply the device may require a couple of seconds to register to the GSM network. It is generally good practice to wait for this before continuing since sending out SMS messages before the device is registered on a network may result in an error.

De default value for this property is ‘true’. Use the NetworkTimeout property to set maximum amount of time to wait.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.WaitForNetwork = true
objGsm.NetworkTimeout = 30000
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

NetworkTimeout property

This property specifies the maximum number of milliseconds to wait for the device to register to a GSM network on calling the Open method.

After inserting the SIM card or switching on the power supply the device may require a couple of seconds to register to the GSM network. It is generally good practice to wait for this before continuing since sending out SMS messages before the device is registered on a network may result in an error.

The default setting is 20000 milliseconds. Use the WaitForNetwork property to enable or disable waiting for registration.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.WaitForNetwork = true
objGsm.NetworkTimeout = 30000
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

CommandTimeout property

This controls the default timeout used for sending commands to the GSM device. For instance, the Open method sends a number of commands to the GSM device to make sure the device is in the correct state when the open function returns. This timeout controls how much time the Gsm object wait for a response from the device on each of these commands.

If the device does not respond within this timeout the operation has failed and LastError will be set to an error code.

The default setting is 10000 milliseconds (10 seconds).

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.NetworkTimeout = 30000
objGsm.CommandTimeout = 1000
objGsm.InterCommandDelay = 1000
objGsm.InterCharacterDelay = 100  
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

InterCommandDelay property

Some devices have trouble communicating at full speed and may need additional time between commands to process the commands properly. This property will support these devices by adding a set number of milliseconds of ‘sleep’ in between individual commands that are send to the device.

The default setting is 0 milliseconds (no delay).

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.NetworkTimeout = 30000
objGsm.InterCommandDelay = 1000
objGsm.InterCharacterDelay = 100  
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

InterCharacterDelay property

Some devices have trouble communicating at full speed and may need additional time between characters to process commands properly. This property will support these devices by adding a set number of milliseconds of ‘sleep’ in between individual characters that are send to the device.

The default setting is 0 milliseconds (no delay).

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.NetworkTimeout = 30000
objGsm.InterCommandDelay = 1000
objGsm.InterCharacterDelay = 100
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

Clear method

This method resets all properties to their default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
....
objGsm.Clear
...

SaveLicenseKey method

Description:

Use SaveLicenseKey to store the license key permanently in the registry. When a license key is saved, it is restored automatically every time a new instance of the object (‘Gsm’) is created. It is not recommended to save the license key if you distribute the component with your own software, because the key can be easily used by others.

Parameters:

  • None.

Return value:

Always 0. Check LastError property to see if the method was completed successfully.

Example:

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create new instance
objGsm.LicenseKey = "XXXXX-XXXXX-XXXXX"
objGsm.SaveLicenseKey                                     ' Save license key to registry

For more information, see Product Activation.

GetErrorDescription method

GetErrorDescription provides the error description of a given error code.

Parameters:

  • The error code

Return value:

The error string.

Example:

Set objGsm = CreateObject("AxSms.Gsm")   
objGsm.LogFile = "C:\temp\log.txt"
...
Set objMessage = CreateObject("AxSms.Message")
objMessage.ToAddress = "+31611223344"
objMessage.Body = "Short text message"  
objGsm.SendSms objMessage
WScript.Echo "SendSms result: " & objGsm.LastError & ", " & _
  objGsm.GetErrorDescription(objGsm.LastError)

Sleep method

This method suspends the current thread for the specified number of milliseconds.

Parameters:

  • Milliseconds to sleep

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
....
objGsm.Sleep 1000
...

FindFirstDevice method

This method finds the first of the connected Windows telephony devices. Use this in combination with FindNextDevice to get a list of connected telephony devices.

Parameters:

  • None

Return value:

The name of the first connected Windows telephony device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
WScript.Echo "Connected devices: "
sDevName = objGsm.FindFirstDevice
While objGsm.LastError = 0
  WScript.Echo sDevName
  sDevName = objGsm.FindNextDevice
WEnd

FindNextDevice method

This method find the next of the connected Windows telephony devices. Use this in combination with FindFirstDevice to get a list of connected telephony devices.

Parameters:

  • None

Return value:

The name of the next connected Windows telephony device

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
WScript.Echo "Connected devices: "
sDevName = objGsm.FindFirstDevice
While objGsm.LastError = 0
  WScript.Echo sDevName
  sDevName = objGsm.FindNextDevice
WEnd

FindFirstPort method

This method finds the first COM port on this PC. Use this in combination with FindNextPort to get a list of COM ports on the PC.

Parameters:

  • None

Return value:

The name of the first COM port on this PC

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
WScript.Echo "Available COM ports: "
sPortName = objGsm.FindFirstPort
While objGsm.LastError = 0
  WScript.Echo sPortName
  sPortName = objGsm.FindNextPort
WEnd

FindNextPort method

This method find the next COM port on this PC. Use this in combination with FindFirstPort to get a list of COM ports on the PC.

Parameters:

  • None

Return value:

The name of the next COM port on this PC

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
WScript.Echo "Available COM ports: "
sPortName = objGsm.FindFirstPort
While objGsm.LastError = 0
  WScript.Echo sPortName
  sPortName = objGsm.FindNextPort
WEnd

Open method

This method opens the specified Windows telephony device (TAPI), COM port or TCP/IP connection. COM ports should be specified as ‘COMn’ where n is the number. Windows telephony devices should be specified by using the full name. A TCP/IP connection should be specified as <host>:<port>. Some examples:

  • Using hostname: myipgsm:2001
  • Using IPv4: 192.168.1.15:2001
  • Using IPv6: [fd30::1:ff4e:3e:9:e]:2001

Parameters:

  • Name of the COM port, Telephony device or TCP/IP connection
  • (Optional) PIN number or an empty string
  • (Optional) Baudrate option, can be one of these constants. Only applied with COM connections

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

Close method

Closes any open device handles.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Open "COM2", "0000"
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
objGsm.Close

ResetCom method

Resets the COM status by clearing the transmit / receive queues and blinking DTR and RTS pins.

This action can sometimes fix connection connection problems on devices that use hardware flow control.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Open "COM2", "0000"
...
objGsm.ResetCom
objGsm.SendCommand("AT+CSQ", 2000)
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
objGsm.Close

SendCommand method

With this method you can send a custom command to the connected device.

Parameters:

  • Command to send to the device

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.SendCommand "ATI"
sResp = objGsm.ReadResponse(1000)
While sResp <> "OK"
  WScript.Echo "  " & sResp
  sResp = objGsm.ReadResponse(1000)
WEnd

ReadResponse method

With this method you can read data from a connected device

Parameters:

  • (Optional) Timeout

Return value:

Data from the connected device or an empty string is no data is available

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.SendCommand "ATI"
sResp = objGsm.ReadResponse(1000)
While sResp <> "OK"
  WScript.Echo "  " & sResp
  sResp = objGsm.ReadResponse(1000)
WEnd

SendSms method

This method sends an SMS message through the connected device.

Parameters:

  • The Message object
  • (Optional) Multipart flag, can be one of these constants
  • (Optional) Timeout in seconds

Return value:

The message reference(s). If it’s a multipart message the references of the individual parts are comma separated.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objMessage = CreateObject("AxSms.Message")
...
objGsm.SendSms objMessage
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  objGsm.Close
  WScript.Quit 1
End If

Receive method

This method receives SMS messages and status reports from the connected device. After calling this method use GetFirstSms/GetNextSms and GetFirstReport/GetNextReport to get the Message and GsmDeliveryReport objects.

Parameters:

  • Message status, can be one of these constants
  • (Optional) Whether or not to delete messages after receiving them
  • (Optional) Which storage type to use, can be one of these constants
  • (Optional) Receive timeout

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objConst = CreateObject("AxSms.Constants")
...
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...

DeleteSms method

Use this method to delete SMS messages. The message will be removed from the storage it was retrieved from.

Parameters:

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objMessage = objGsm.GetFirstSms
...
While objGsm.LastError = 0
  If objMessage.FromAddress = "+31122334455" Then
    objGms.DeleteSms objMessage
  Else
    WScript.Echo "Received from: " & objMessage.FromAddress    
    WScript.Echo objMessage.Body
  End If
  Set objMessage = objGsm.GetNextSms
Wend
...

DeleteReport method

Use this method to delete delivery reports. The delivery report will be removed from the storage it was retrieved from.

Parameters:

Return value:

Always 0.

Example:

Set objGsm = CreateObject("AxSms.Gsm")
Set objReport = objGsm.GetFirstReport
...
While objGsm.LastError = 0
  If objReport.Reference <> "1" Then
    objGms.DeleteReport objReport
  Else
    WScript.Echo "Received reference: " & objReport.Reference    
    WScript.Echo objReport.Body
  End If
  Set objReport = objGsm.GetNextReport
Wend
...

GetFirstSms method

This method gets the first SMS message that was received through the Receive method.

Parameters:

  • None

Return value:

An SMS message

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend

GetNextSms method

This method gets the next SMS message that was received through the Receive method.

Parameters:

  • None

Return value:

An SMS message

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...
Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend

GetFirstReport method

This method gets the first delivery report that was received through the Receive method.

Parameters:

  • None

Return value:

A GSM delivery report

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If
...            
Set objReport = objGsm.GetFirstReport
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objReport.FromAddress & _
    "; reference: " & objReport.Reference
  Set objReport = objGsm.GetNextReport
WEnd

GetNextReport method

This method gets the next delivery report that was received through the Receive method.

Parameters:

  • None

Return value:

A GSM delivery report

Example:

Set objGsm = CreateObject("AxSms.Gsm")
...
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If            
...
Set objReport = objGsm.GetFirstReport
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objReport.FromAddress & _
    "; reference: " & objReport.Reference
  Set objReport = objGsm.GetNextReport
WEnd

The GSM protocol object is able to connect to most GSM modem devices. Either through the TAPI (Windows Telephony API), directly through the COM interface or through an IP connection. The GSM protocol only uses ‘AT’ commands to communicate with the device and send and receive messages.

In addition to sending and receiving SMS messages it’s possible to send and receive custom commands. This could be used to, for instance, send a custom initialization string to the GSM modem before usage.

Send SMS using GSM modem

This sample will send out a single SMS messaging use the first TAPI device that’s connected to the PC.

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create GSM protocol object
Set objMessage = CreateObject("AxSms.Message")         ' Create SMS message object

' Show version information
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
  objGsm.Build & "; Module " & objGsm.Module
WScript.Echo License Status: " & objGsm.LicenseStatus & vbCrLf

objGsm.Logfile = "log.txt"                             ' Keep a session log

' Open the first connected device
sDevName = objGsm.FindFirstDevice
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  WScript.Quit 1
End If

' Compose an SMS message
objMessage.ToAddress = "+31122334455"
objMessage.Body = "This is a short text message"

' Send an SMS message through the connected GSM modem device
objGsm.SendSms objMessage
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  objGsm.Close
  WScript.Quit 1
End If

' Make sure to close the device to allow other applications to access it.
objGsm.Close
WScript.Echo "Done !"

Receive SMS using GSM modem

Read all SMS messages and status reports that are already on the SIM and leave them on the SIM card

Set objGsm = CreateObject("AxSms.Gsm")                 ' Create GSM protocol object
Set objConst = CreateObject("AxSms.Constants")         ' Create global constants object
Set objMessage = CreateObject("AxSms.Message")         ' Create SMS message object

' Show version information
WScript.Echo "SMS Component Version " & objGsm.Version & "; Build " & _
  objGsm.Build & "; Module " & objGsm.Module
WScript.Echo "License Status: " & objGsm.LicenseStatus & vbCrLf

objGsm.Logfile = "log.txt"                             ' Keep a session log

' Open the first connected device
sDevName = objGsm.FindFirstDevice
objGsm.Open sDevName
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)    
  WScript.Quit 1
End If

' Receive messages from the SIM card and leave them on the SIM card
objGsm.Receive objConst.GSM_MESSAGESTATE_RECEIVED_READ
If objGsm.LastError <> 0 Then
  WScript.Echo "Error: " & objGsm.GetErrorDescription(objGsm.LastError)
  objGsm.Close
  WScript.Quit 1
End If

' Show all SMS messages
Set objMessage = objGsm.GetFirstSms
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objMessage.FromAddress
  WScript.Echo objMessage.Body
  Set objMessage = objGsm.GetNextSms
Wend

' Show all status reports
Set objReport = objGsm.GetFirstReport
While objGsm.LastError = 0
  WScript.Echo "Received from: " & objReport.FromAddress & _
    "; reference: " & objReport.Reference
  Set objReport = objGsm.GetNextReport
Wend

' Make sure to close the device to allow other applications to access it.
objGsm.Close
WScript.Echo "Done !"

Using application ports

An SMS message can specify an application port. The usage of application ports is very much like the usage of ports in the IP based protocols. If a message specifies it’s application ports it will specify both a source port as well as a destination port. The source port specifies which application sent the message. The destination port specifies to which application the message was intended.

An example of the use of application ports is the WAP Push message. A WAP Push message is a binary message which will push an URL to the MT. A WAP Push message will always be sent to application port 2948 where the Push application can pick-up the message and present it to the user.

Sending a message using an application port is just a matter of specifying the port(s) in either the ‘ToAddress’ of the message or the ‘FromAddress’ or both. For example, to send a message to “+31623350000” on port number “1000” use this:


Set objMessage = CreateObject("AxSms.Message")
...
objMessage.ToAddress = "31623350000:1000"

In this example the source port will be ‘0’. To also specify the source port use this:


Set objMessage = CreateObject("AxSms.Message")
...
objMessage.ToAddress = "31623350000:1000"
objMessage.FromAddress = ":1000"

To control the way message that are sent to a specific port are received you can use the property ‘ExtractApplicationPort’

When this property is set to ‘True’ application port specifying UDH headers will be extracted from the SMS message and the application ports will be appended to the ‘FromAddress’ and the ‘ToAddress’ respectively. When this property is set to ‘False’ the application port specifying UDH headers will be ignored.

If the ‘ExtractApplicationPort’ property is set to true application ports will be properly extracted for 16 bit port headers as well as 8 bit port headers. When sending messages to a specific application port the 16 bit headers will always be used.

Using national language shift tables

The national language shift tables are an extension to the GSM 03.38 standard that introduces different language character sets.

This means that for those languages that are present in the national language shift tables you can send SMS messages without using the Unicode character set. A single part Unicode message can only use 70 characters while a single part SMS that uses the national language shift tables can contain up to 152 characters. Or 155 when only the locking shift table is used.

Send an SMS using the national language shift table by simply setting the LanguageLockingShift and the LanguageSingleShift properties.


Set objMessage = CreateObject("AxSms.Message")
Set objConstants = CreateObject("AxSms.Constants")
...
objMessage.LanguageLockingShift = objConstants.LANGUAGE_LOCKINGSHIFT_HINDI
objMessage.LanguageSingleShift = objConstants.LANGUAGE_SINGLESHIFT_HINDI
objMessage.Body = "नमस्ते दुनिया!"

To control the way that messages with the language shift tables are received please look at the ExtractLanguageShift property.