How can we help?

AxSms.SmppServer

Introduction

Skip to properties and methods

The SmppServer object can be used to accept incoming SMPP connections, effectively setting up you own SMSC. The SMPP protocol supports sending and receive SMS messages using only an internet connection. It’s primarily used for high volumes / high performance applications.

The SmppServer implementation is completely asynchronous for maximum performance. After starting the SmppServer a separate thread will accept incoming connections on the specified port. For each incoming connection a dedicated worker thread will be started to handle the client connection, this is the SmppSession object. The session objects are used to exchange SMS messages with connected clients.

Send and receive SMS messages from multiple clients using SmppServer

Send and receive SMS messages to/from multiple clients simultaneously using the SmppServer object 

Set objSmppServer = CreateObject("AxSms.SmppServer")   ' Create the SMPP server object
Set objConstants = CreateObject("AxSms.Constants")   ' Create the SMS constants object

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

' Set a logfile and start the server on both IPv6 and IPv4
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775, objConstants.SMPP_IPVERSION_BOTH
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error while starting SMPP server: " & _
    objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
WScript.Echo "SMPP server started..."

While objSmppServer.IsStarted
  Set objSmppSession = objSmppServer.GetFirstSession
  While objSmppServer.LastError = 0
    ' Accept all sessions that request a bind
    If objSmppSession.ConnectionState = objConstants.SMPP_SESSIONSTATE_BINDING Then
      WScript.Echo "Client IP: " & objSmppSession.Ip & ":" & objSmppSession.Port
      WScript.Echo "SystemId: " & objSmppSession.SystemId
      WScript.Echo "AddressRange: " & objSmppSession.AddressRange
      objSmppSession.LogFile = objSmppSession.SystemId & ".log"
      objSmppSession.RespondToBind objConstants.SMPP_ESME_ROK
    End If    
    
    If objSmppSession.ConnectionState = objConstants.SMPP_SESSIONSTATE_BOUND_TRX Then
      ' Receive incoming messages
      Set objMessage = objSmppSession.ReceiveSubmitSms
      While objSmppSession.LastError = 0
        WScript.Echo "Receive SMS from: " & objSmppSession.SystemId & "; to: " & _
          objMessage.ToAddress & "; suggested reference: " & objMessage.Reference
        
        ' Accept the incoming message with the suggested message reference
        objSmppSession.RespondToSubmitSms objMessage
        If objSmppSession.LastError <> 0 Then
          WScript.Echo "Error while responding: " & _
            objSmppSession.GetErrorDescription(objSmppSession.LastError)
          WScript.Quit 1
        End If
        
        ' Send a successful delivery report for the incoming message
        objMessage.SmppStatus = objConstants.SMPP_MESSAGESTATE_DELIVERED
        objSmppSession.DeliverReport objMessage
        If objSmppSession.LastError <> 0 Then
          WScript.Echo "Error while sending delivery report: " & _
            objSmppSession.GetErrorDescription(objSmppSession.LastError)
          WScript.Quit 1
        End If
        
        Set objMessage = objSmppSession.ReceiveSubmitSms
      WEnd

      ' Deliver a new message to the client
      Set objMessage = CreateObject("AxSms.Message")
      objMessage.ToAddress = "+31122334455"
      objMessage.FromAddress = "+35544332211"
      objMessage.Body = "Hello from the Auron Gateway !"
      objMessage.UserTag = 1 ' To identify this message when the client responds
      objSmppSession.DeliverSms objMessage
      If objSmppSession.LastError <> 0 Then
        WScript.Echo "Error while delivering: " & _
          objSmppSession.GetErrorDescription(objSmppSession.LastError)
        WScript.Quit 1
      End If
      
      ' Check if the client accepted any messages
      Set objMessage = objSmppSession.ReceiveDeliverResponse
      While objSmppSession.LastError = 0
        WScript.Echo "Response: " & objMessage.SmppCommandStatus & _
          " for UserTag: " & objMessage.UserTag
        Set objMessage = objSmppSession.ReceiveDeliverResponse
      WEnd
    End If
    
    Set objSmppSession = objSmppServer.GetNextSession
  WEnd

  objSmppServer.Sleep 1000
WEnd

objSmppServer.Stop
How to run this example

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
CertificateStore String Read/Write The certificate store used to find/search certificates
ListenIpv4 String Read/Write The IP address to listen on
ListenIpv6 String Read/Write The IPv6 address to listen on
IsStarted Boolean Read Whether the SMPP server is started and running
LastReference Number Read/Write The last suggested message reference
MaxClosedSessions Number Read/Write The maximum number of closed sessions to keep

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
Start Starts the SMPP server
Stop Stops the SMPP server
GetFirstSession Get first connected client session
GetNextSession Get next connected client session
GetSession Get the specified, connected, session
GetClosedSession Get a recently closed session
FindFirstMyServerCertificate Find first server certificate in ‘My’ store
FindNextMyServerCertificate Find next server certificate in ‘My’ store
FindFirstLocalIpAddress Find first local IP address
FindNextLocalIpAddress Find next local IP address

Version property

Return the version number of the SMS Component

Example: 

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

Build property

Return the build number of the SMS Component.

Example: 

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

Module property

Return the module name of the SMS Component.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")
WScript.Echo "SMS Component Version " & objSmppServer.Version & "; Build " & _
  objSmppServer.Build & "; Module " & objSmppServer.Module
WScript.Echo "License Status: " & objSmppServer.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 objSmppServer = CreateObject("AxSms.SmppServer")   ' Create new instance
WScript.Echo "License Status: " & objSmppServer.LicenseStatus
WScript.Echo "License Key: " & objSmppServer.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 objSmppServer = CreateObject("AxSms.SmppServer")   ' Create new instance
objSmppServer.LicenseKey = "XXXXX-XXXXX-XXXXX"         ' Assign your license key 
WScript.Echo "LicenseKey: " & objSmppServer.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 objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
    objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

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 objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
    objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

CertificateStore property

Set this property to the certificate store that should be searched when finding a security certificate. The SMPP Server always searches in the ‘My’ location for certificates that have a ‘Server’ purpose. The MMC (Microsoft Management Console) snap-in will have the ‘My’ location listed as ‘Personal’.

This property is used when searching for available certificates as well as when starting a secure SMPP Server connection.

Set to one of the constants found here.

By default this is set to search in the current user store.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
objSmppServer.CertificateStore = objConstants.SMPP_CERTIFICATESTORE_CURRENTUSER
WScript.Echo objSmppServer.FindFirstMyServerCertificate
While objSmppServer.LastError = 0
  WScript.Echo objSmppServer.FindNextMyServerCertificate
Wend
...

ListenIpv4 property

Set this property to the IP address the SMPP Server should listen on. Leave it empty to listen on ‘any’ (all) IPv4 addresses on the server.

This property is useful on servers with multiple network adapters as well as in testing and development situations. For instance: to prevent a connection from a remote PC set this property to ‘127.0.0.1’.

By default this property is set to an empty string.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
' Only accept local connections
objSmppServer.ListenIpv4 = "127.0.0.1"
objSmppServer.ListenIpv6 = "::1"
objSmppServer.Start 2775, objConstants.SMPP_IPVERSION_BOTH
...

ListenIpv6 property

Set this property to the IP address the SMPP Server should listen on. Leave it empty to listen on ‘any’ (all) IPv6 addresses on the server.

This property is useful on servers with multiple network adapters as well as in testing and development situations. For instance: to prevent a connection from a remote PC set this property to ‘::1’.

By default this property is set to an empty string.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
' Only accept local connections
objSmppServer.ListenIpv4 = "127.0.0.1"
objSmppServer.ListenIpv6 = "::1"
objSmppServer.Start 2775, objConstants.SMPP_IPVERSION_BOTH
...

IsStarted property

If the SMPP server is started and running this property returns ‘True’. If the server is stopped or not started yet, this property returns ‘False’.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
...
WScript.Echo "SMPP server started: " & objSmppServer.IsStarted
...

LastReference property

Every time a client submits a message to the SMPP server the SMPP server suggests message reference to return to the client. This message reference is an 8 digit hexadecimal number that is incremented for every message.

The message reference should uniquely identify an SMS message on the server.

When the message is received through the ReceiveSubmitSms method the suggested message reference is already set in the Reference property. This property can changed to suggest a different reference. The reference will be effective when calling RespondToSubmitSms.

Use this property to set a reference offset before starting or restarting the server to make sure no duplicate message references are issued. Store it regularly to keep track of the current last used message reference.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.LastReference = lLastReference + lRestartOffset
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
    objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

MaxClosedSessions property

After a SmppSession is closed a reference is kept in the closed sessions list. Recently closed sessions can be accessed using GetClosedSession.

By default this value is set to 100.

Example: 

Set objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.LastReference = lLastReference + lRestartOffset
objSmppServer.MaxClosedSessions = 1000
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
    objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

Clear method

This method resets all properties to their default values.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")
....
objSmppServer.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 (‘SmppServer’) 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 objSmppServer = CreateObject("AxSms.SmppServer ")  ' Create new instance
objSmppServer.LicenseKey = "XXXXX-XXXXX-XXXXX"
objSmppServer.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 objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
  objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

Sleep method

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

Parameters:

  • Milliseconds to sleep

Return value:

Always 0.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")
....
objSmppServer.Sleep 1000
...

Start method

Start the SMPP server on the specified port. A dedicated thread will be started in the background which listens on the specified port for incoming connections.

The server can be started, listening on IPv6, IPv4 or both. The both option is implemented as ‘dual stack’ which means that both an IPv4 and IPv6 socket are created. Use these constants to select the IP Version.

By default the server will listen on all IPv4 or IPv6 network adapters / IP addresses. Use either ListenIpv4 or ListenIpv6 to listen on a specific adapter / IP address.

The server can be started in secure mode by specifying the name of a server certificate. If no certificate is specified or if an empty string is specified the server will not be secured.

When started in secure mode the SMPP Server will only accept secure (TLS/SSL) connections. If a certificate is specified the server will search the ‘My’ (Personal) location in either the local machine or the current user store for the certificate. The certificate needs to have the ‘server’ purpose assigned to it. Access to the local machine store will need administrator privileges. The CertificateStore property determines if the ‘My’ store of the current user or the ‘My’ store of the local machine is searched.

For each connection an SmppSession object will be created. Use the GetFirstSession and GetNextSession methods to access these session and interact with them.

Parameters:

  • Port number
  • (Optional) IP version
  • (Optional) Certificate

Return value:

Always 0.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775, objConstants.SMPP_IPVERSION_6, "gateway.auronsoftware.com"
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
  objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

Stop method

Stop the SMPP server.

Parameters:

  • The error code

Return value:

The error string.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
...
objSmppServer.Logfile = "server.log"
objSmppServer.Start 2775
If objSmppServer.LastError <> 0 Then
  WScript.Echo "Error: " & objSmppServer.LastError & "," & _
  objSmppServer.GetErrorDescription(objSmppServer.LastError)
  WScript.Quit 1
End If
...
objSmppServer.Stop

GetFirstSession method

This method returns the first connected session object. If no clients are connected nothing is returned and the LastError property is set.

Parameters:

  • None

Return value:

An SmppSession object.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")
Set objConstants = CreateObject("AxSms.Constants")
...
Set objSmppSession = objSmppServer.GetFirstSession
While objSmppServer.LastError = 0
  If objSmppSession.ConnectionState = objConstants.SMPP_SESSIONSTATE_BINDING Then
    WScript.Echo "Client Ip: " & objSmppSession.Ip & ":" & objSmppSession.Port
    WScript.Echo "SystemId: " & objSmppSession.SystemId      
    WScript.Echo "AddressRange: " & objSmppSession.AddressRange
    objSmppSession.LogFile = objSmppSession.SystemId & ".log"
    objSmppSession.RespondToBind objConstants.SMPP_ESME_ROK
  End If    
  ...
  Set objSmppSession = objSmppServer.GetNextSession
WEnd
...

GetNextSession method

This method returns the next connected session object. If no clients are connected nothing is returned and the LastError property is set.

Parameters:

  • None

Return value:

Always 0.

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")
Set objConstants = CreateObject("AxSms.Constants")
...
Set objSmppSession = objSmppServer.GetFirstSession
While objSmppServer.LastError = 0
  If objSmppSession.ConnectionState = objConstants.SMPP_SESSIONSTATE_BINDING Then
    WScript.Echo "Client Ip: " & objSmppSession.Ip & ":" & objSmppSession.Port
    WScript.Echo "SystemId: " & objSmppSession.SystemId      
    WScript.Echo "AddressRange: " & objSmppSession.AddressRange
    objSmppSession.LogFile = objSmppSession.SystemId & ".log"
    objSmppSession.RespondToBind objConstants.SMPP_ESME_ROK
  End If    
  ...
  Set objSmppSession = objSmppServer.GetNextSession
WEnd
...

GetSession method

This method returns the specified session object. If the specified session is no longer connected the LastError property is set.

Parameters:

Return value:

The specified session

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")
...
Sub DeliverSms(SessionId, objSms)
  Set objSession = objSmppServer.GetSession(SessionId)
  If objSession.LastError <> 0 Then
    objSession.DeliverSms objSms
  End If
End Sub
...

GetClosedSession method

This method returns a recently closed session. If no closed sessions are available the LastError property is set.

The MaxClosedSessions property determines how many closed sessions are kept.

Parameters:

  • None

Return value:

A SmppSession object.

Example:

Set objSmppSession = objSmppServer.GetClosedSession
While objSmppServer.LastError = 0
  WScript.Echo "Session closed: " & objSmppSession.SystemId
			
  WScript.Echo "Not responded:  "
  Set objMessage = objSmppSession.FetchNotResponded
  While objSmppSession.LastError = 0
    WScript.Echo "Usertag: " & objMessage.Usertag & "; SequenceNumber: " & _
      objMessage.SmppSequenceNumber	
    Set objMessage = objSmppSession.FetchNotResponded
  WEnd

  WScript.Echo "Not delivered (seq is 0):  "
  Set objMessage = objSmppSession.FetchNotDelivered
  While objSmppSession.LastError = 0
    WScript.Echo "Usertag: " & objMessage.Usertag & "; SequenceNumber: " & _
      objMessage.SmppSequenceNumber	
    Set objMessage = objSmppSession.FetchNotDelivered
  WEnd
	
  Set objSmppSession = objSmppServer.GetClosedSession
WEnd

FindFirstMyServerCertificate method

This method returns the first server certificate found in the ‘My’ store. If no certificate could be found or if the store cannot be openened LastError property is set.

A server certificate is a certificate that has ‘Server’ set as one of its purposes. The ‘My’ store will be labeled ‘Personal’ in the MMC (Microsoft Management Console) ‘Certificates’ plugin.

The CertificateStore property determines if the ‘My’ store of the current user or the ‘My’ store of the local machine is searched.

Parameters:

  • None

Return value:

The name of the certificate

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
objSmppServer.CertificateStore = objConstants.SMPP_CERTIFICATESTORE_CURRENTUSER
WScript.Echo objSmppServer.FindFirstMyServerCertificate
While objSmppServer.LastError = 0
  WScript.Echo objSmppServer.FindNextMyServerCertificate
Wend
...

FindNextMyServerCertificate method

This method returns the next server certificate found in the ‘My’ store. If no certificate could be found or if the store cannot be openened LastError property is set.

A server certificate is a certificate that has ‘Server’ set as one of its purposes. The ‘My’ store will be labeled ‘Personal’ in the MMC (Microsoft Management Console) ‘Certificates’ plugin.

The CertificateStore property determines if the ‘My’ store of the current user or the ‘My’ store of the local machine is searched.

Parameters:

  • None

Return value:

The name of the certificate

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
objSmppServer.CertificateStore = objConstants.SMPP_CERTIFICATESTORE_CURRENTUSER
WScript.Echo objSmppServer.FindFirstMyServerCertificate
While objSmppServer.LastError = 0
  WScript.Echo objSmppServer.FindNextMyServerCertificate
Wend
...

FindFirstLocalIpAddress method

This method returns the first local IP address. If local IP addresses cannot not be found the LastError property is set.

Use these constants to select the IP Version to browse.

Parameters:

  • IP Version

Return value:

The IP address

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
WScript.Echo objSmppServer.FindFirstLocalIpAddress(objConstants.SMPP_IPVERSION_4)
While objSmppServer.LastError = 0
  WScript.Echo objSmppServer.FindNextLocalIpAddress
Wend
...

FindNextLocalIpAddress method

This method returns the next local IP address. If no more local IP addresses can be found the LastError property is set.

Use these constants to select the IP Version to browse.

Parameters:

  • none

Return value:

The IP address

Example:

Set objSmppServer = CreateObject("AxSms.SmppServer")  
Set objConstants = CreateObject("AxSms.Constants")  
...
WScript.Echo objSmppServer.FindFirstLocalIpAddress(objConstants.SMPP_IPVERSION_4)
While objSmppServer.LastError = 0
  WScript.Echo objSmppServer.FindNextLocalIpAddress
Wend
...