☰ Menu [BAI] BAI
[HR]
manual.svg

Böcherer Angewandte Informatik SendXMS® V11.03 Manual

Content

  1. Content
  2. Summary
  3. Licence
  4. Open Source/Third Party Software
  5. Installation
  6. Configuration
  7. Character Translation Tables
  8. Phone number format filters
  9. Voice messages
  10. Server mode
  11. ODBC interface
  12. Spool API
  13. SNMP
  14. Userexit
  15. VXMSC-Edition
  16. Deferred sending and validity period
  17. Choosing a desired function
  18. Calling syntax
  19. Integration into Email systems
  20. Integration into WWW servers
  21. Graphical user interface
  22. Voice Over IP (VoIP)
  23. X.25/X.31
  24. TCP/IP, SSL
  25. PPP
  26. Return codes
  27. SMS over HTTP
  28. MMS, Ringtones, Logos, WAP Push (OMA Provisioning, OMA DRM, OMA EMN, Bookmarks, MMS Notifications, ...)
  29. UCS-2
  30. Mobile Number Portability (MNP)
  31. Abbreviations
  32. Where can I get the newest version?
  33. Problems/Questions

Summary

SendXMS is the most powerful and scalable program to send and to receive short messages (SMS, EMS, MMS) to cellular phones or pagers using the protocols TAP, EMI/UCP (CMG), SMPP (Logica), CIMD (Nokia), OIS (SMS2000, SEMA), ES 201 912, OneAPI (GSMA) (SMS, MMS, Location, Capability, Payment), GSM, HTTP, MM1, MM7, MMS-F or EAIF (Nokia). SendXMS can also play/record voice messages.

SendXMS has (among others) the following topics:

  • support for MNP (Mobile Number Portability)
  • additional graphical Interface through Java front-end
  • available on many platforms
  • TAP protocol
  • AIM extensions for TAP
  • EMI/UCP (CMG) protocol
  • SMPP (Logica) protocol
  • OIS (SMS2000, SEMA) protocol
  • CIMD (Nokia) protocol
  • UAP (Huawei) protocol
  • SMS for ISDN (ETSI ES 201 912 (protocol 1 and 2); only using CAPI or VoIP)
  • Fixed network Multimedia Messaging Service (MMS-F)
  • support for MM1 (WAP 1.x and 2.0)
  • support for binary messages1)
  • support for UCS-2 (Unicode; multibyte characters) messages (including Emojis)
  • support for WAP Push1)
  • support for USSD1)
  • sending of DTMF sequences
  • GSM 07.05 (MO and MT; PDU mode)
  • receiving messages (GSM, ETSI ES 201 912, MM1, MMS-F and UUS; in Professional-Edition also with UCP, SMPP, OIS, CIMD, OneAPI, MM7, EAIF)
  • UUS (User-User-Signaling) with CAPI 2.0 (if supported by used CAPI and provider)
  • confirmed delivery
  • status request for submitted SMS1)
  • deletion of submitted but not already delivered SMS1)
  • immediate display of messages (Flash SMS) on the receiving phone possible
  • support for the feature Reply-Path-Request
  • support for long short-messages (disassemble/assemble of a message in up to 255 SMS)1)
  • deferred sending of messages1)
  • Blacklist (phone numbers to which no messages should be sent)1)
  • Allow- and Denylist (users which may (not) be allowed to use SendXMS)1)
  • VoIP support
  • CAPI 2.0 support
  • Remote CAPI support (AVM extension; CAPIoTCP) (also for Unix)
  • Remote CAPI support (Bintec extension) (also for Unix)
  • TAPI 2.0 support
  • playing/recording of voice messages
  • support for modems, ISDN-Terminal adapters and GSM cards/modems (connected via serial interface, USB or Ethernet)
  • definition of unlimited character translation tables possible
  • support for the extended GSM character set
  • conversion utility included to read .bmp, .png, .gif, .mng, .rtx, .rtttl, .imy, .htm, .mid, .smil and .xml (.xml in Professional-Edition and higher) files1)
  • support for messages with different priorities1)
  • support for (voice, fax, electronic mail and other) message waiting indications
  • support for EMS 4.x and 5.x (pictures, melodies, animations, ...); using EMS 5.x also coloured or polyphonic
  • support for SMIL
  • support for Smart Messaging (like ringing tones, operator logos, Business Cards), also for CDMA/TDMA1)
  • support for Nokia, EMS, Motorola and Sagem ringing tones1)
  • support for Siemens OTA Download Service1)
  • configurable for every provider using TAP, EMI/UCP, SMPP, CIMD, OIS, ES 201 912, MM1, MM7, MMS-F, EAIF or GSM 07.05.
  • preconfigured for many providers all over the world
  • message can be specified on the command line (batch-processing)
  • easy installation and configuration
  • easy integration into email-systems, WWW servers and/or SNMP management
  • device won't be locked between two dial-attempts
  • configurable for the most modems, ISDN-adapters and ISDN-Terminal adapters
  • charge information (CAPI)
  • evaluable return codes (error code or count of successfully processed messages)1)
  • phone book: using aliases instead of numbers1)
  • sending messages to multiple recipients even with different providers1)
  • sending messages to multiple recipients in one connection1)
  • event-logging in a file or with syslogd1)
  • configurable redial count1)
  • configurable redial delay between two dial-attempts1)
  • multiple modem-devices configurable (if one isn't available the next one is used)1)
  • multithreaded
  • format of incoming/outgoing numbers can be automatically changed using filters with regular expressions

The Server-Edition provides all features of the Standard-Edition and additionally the following features:

  • can be installed as a Windows service1)
  • an external program (also a batch/script file), a function within a SharedObject/DLL or a method within a Java class can automatically be launched when a message has been sent or received1)
  • messages can be spooled and sent in server mode with a minimum number of connections1)
  • White- and Blacklist (phone numbers to which messages can or can not be sent)1)
  • Allow- and Denylist (users which may (not) be allowed to use SendXMS)1)

The Professional-Edition provides all features of the Server-Edition and additionally the following features:

  • support for metrics (e.g. Prometheus)1)
  • support for SSL (OpenSSL required)1)
  • support for SMS over HTTP (e.g. Twitter)1)
  • support (SMS, MMS, Location, Capability, Payment) for OneAPI (GSMA)1)
  • support for SIP Extension for Instant Messaging (RFC3428)
  • support for MM71)
  • support for EAIF (Nokia)1)
  • support for asynchronous communication (windowing)1)
  • support for large accounts1)
  • support for permanent connections1)
  • support for KeepAlive (Enqire Link)1)
  • possibility to define times at which special messages (e.g. promotion) should not be submitted1)
  • compiler für Over The Air Settings (WAP/OMA Client Provisioning, OMA (SyncML) Device Management (Package#0), OMA Digital Rights Management (DRM) 1.0, OMA E-Mail Notification (EMN), MMS Notification, Service Indication (SI), Service Loading (SL), (Nokia/Sony Ericsson) OTA Service Settings, Bookmarks and SyncML Settings)1)
  • data throughput (per session) with X.25 or TCPIP more then 500 SMS/second possible, with GSM (per modem) up to 1200 SMS/hour and with X.31 (D-channel) up to 18000 SMS/hour.
  • receiving messages (GSM, UCP, SMPP, CIMD, OIS, ETSI ES 201 912, OneAPI, MM1, MM7, MMS-F, EAIF)1)
  • support for SNMPv2 traps1)
  • support for X.251)
  • support for X.311)
  • support for TCP/IP (IPv4 and IPv6)1)
  • support for UDP1)
  • support for SCTP1)
  • RFC1086 (TCP/IP-X.25 Bridge) support1)
  • priorisation of spool files possible
  • writing of statistic/billing data1)
  • spool API (per default spool files will be read/written to/from the filesystem; with this API you can redirect this for example to any database) 1)
  • implementation of Spool API via ODBC included (with examples for MySQL/MariaDB, PostgreSQL, Oracle and Microsoft SQL Server)1)

The VXMSC-Edition provides all features of the Professional-Edition and additionally the following features: and additionally:

  • functionality (conforming to the Professional-Edition) of a virtual SMSC/MMSC (VXMSC)1)
  • can be used as a XMS gateway1)
  • receiving/sending of XMS (per TCP) from/to any other program using UCP, SMPP, CIMD, OIS, MM7 or EAIF1)

1)only available with registered version

Licence

SendXMS can be tested for a period of 20 days without any charge. To use SendXMS after this period it has to be licenced. Every user has to agree to our Conditions of License and Use.

Open Source/Third Party Software

Depending on the configuration and the kind of usage it may be possible that SendXMS will also use Open Source/Third Party Software. Such Open Source/Third Party Software usually has its own copyrights and licence agreements, will usually be used as a shared library/DLL and usually does not need to be installed seperately. In the following, a (not necessarily complete) list of such software is listed (in alphabetic order):

Software URL Lizenz
Info-ZIP http://www.info-zip.org http://www.info-zip.org/pub/infozip/license.html
libiconv http://www.gnu.org/software/libiconv/ https://www.gnu.org/licenses/gpl-3.0.en.html
libmng http://www.libpng.org/pub/mng/ http://github.com/LuaDist/libmng/blob/master/LICENSE
libre http://creytiv.com/re.html http://opensource.org/licenses/bsd-license.php
libTomCrypt http://www.libtom.net/LibTomCrypt/ http://github.com/libtom/libtomcrypt/blob/develop/LICENSE
OpenSSL http://www.openssl.org/ http://www.apache.org/licenses/LICENSE-2.0.txt
OSHDLC http://github.com/bgb043/oshdlc https://www.gnu.org/licenses/gpl-3.0.en.html
prometheus-client-c https://github.com/digitalocean/prometheus-client-c http://www.apache.org/licenses/LICENSE-2.0
zlib http://zlib.net/ http://zlib.net/zlib_license.html

Installation

At first you have to download an installation archive for the operating system you want to use. Then just start the loaded archive (in case of Unix you maybe have to uncompress the loaded file using 'gunzip -N ...' or 'gzip -d ...' and to make it executable using 'chmod +x ...'). If Java has been installed on your system a Java installer with a graphical user interface or otherwise a console installer will be invoked. You can force the usage of one of these installation modes by running 'setup --java' or 'setup --console'. The installation program asks for the most recent parameters (to test SendXMS) and copies the required files into the destination directory.

After running setup you should edit the file sendxms.pro and delete all not required provider definitions.

Attention, before any automated call of SendXMS test whether the hang-up procedure (ESCAPE Sequence or dropping DTR) works with your local modem.

For the Unix versions the owner of the file sendxms must have enough rights to use the modem device and to create files (in the spool directory, lock directory, ...) and the Set-User-ID Bit should be set.

Configuration

Normally there is no more configuration required after running the setup program. In most cases you should now be able to send a message with a simple command like 'sendxms <phone> <msg>'. But with the configuration files and the command line parameter you have although the possibility to adapt SendXMS for optimal use in many different cases. All files have to be UTF-8 encoded!

To configure SendXMS, edit the file sendxms.cfg.

In the file sendxms.pro you can define the different providers (which provider uses TAP, UCP, ..., which phone numbers are to be used for them and what is the predial code for them).

Your personal phone book with aliases can be defined in the file sendxms.pbk.

Comments are always prefixed by ';'.

All configuration files will be searched by default in the directory in which the executable is located. This can be changed by specifying explicit a configuration file on the command line or by setting the environment variable SendXMS. In the latter case the value of this environment variable will be used as the search path for the configuration files.

sendxms.cfg

In this file you can configure SendXMS in the chapter [SendXMS]. In the chapter [Device] you can configure your communication interface (devices) and the in chapter [XMSGUI] the usage of the graphical front-end. The chapters [Allow] and [Deny] are used to define user access restrictions. The chapters [Whitelist] and [Blacklist] to specify numbers to which messages can or can not be sent. The chapter SetEnv can be used to optionally define or change environment variables for SendXMS processes. In the chapters [Audio Mime Types], [Image Mime Types] and [Video Mime Types] you can define file extensions for a corresponding MIME Type. Optionally you can also use the following chapters to configure
[SSL] the integration of OpenSSL,
[PPP] parameters for PPP connections,
[ODBC] the access data for usage of the integrated ODBC-Spool-API,
[SNMP] usage of SNMP traps
[Metrics] usage of metrics (e.g. Prometheus)
and [Java] parameters for using a Java VM (Java userexit)

In the registered version you can define as many devices as you want. In the connection phase SendXMS tries to use the first defined device. If this went wrong (device is locked) the next one is used. If no device can be used there will be a delay (RedialDelay) and then the whole will be repeated (RedialCount).

In the chapter [SendXMS] you can specify the following keywords to configure SendXMS. Every keyword has to be entered in an own line.

BinLocks=false
Specifies whether the lock file should be binary or ascii (only unix).

CachePhonebook=true
Specifies that the content of the phonebook file should be cached. This is not required for a 'standard' installation and makes only sense if the user is generating spool files himself and uses aliases (instead of a phone number) within these spool files (only in Professional-Edition or higher).

CountryCode=+49
Specifies the international country code (for example '+49' for Germany or '+1' for North America). If this parameter is not or wrong specified SendXMS will dial for national calls also the international prefix with the country code which won't work.

DontReassemble=true
Suppresses the reassembling of incoming long SMS (which are received in multiple parts).

EnableVersionCheck=true
Enables automatic checking for a newer SendXMS version. In case that a newer version is available this will be just be logged an automatic installation will not be initiated.

InternationalPrefix=00
Specifies a sequence of digits to substitute a '+'sign in front of a phone number and to identify international numbers (default: "00").

LocalIdDir=localids
Specifies a directory to store data for mapping LocalIds (assigned by the user) to MsgIds (assigned by the SMSC). This is only relevant if a status report will be requested for a message. In this case the MsgId will be stored together with the LocalId after the message has been sent. When a status report has been received the LocalId will be read using the received MsgId.

LockDir=/var/spool/uucp
Specifies the directory to look for and to generate a lock file (only unix).

LockFunction=
Specifies the system function (flock or fcntl for Linux, Unix and lockfile for Windows) to be used for file locking. The function flock is not on all platforms available and does not always work with network drives. If fcntl (or just nothing) has been specified SendXMS tries to recognize whether the used operating system is supporting Open file description locks and will use it (F_OFD_SETLK). In case that this recognition is not wanted or does not work you can enforce usage of Advisory record locking (F_SETLK) by specifying 'LockFunction=fcntl (arl)'.

LogFile=sendxms.log
Specifies a file in which all actions will be logged. If the file name contains $h or $d this placeholder will be replaced by the actual hour (yyyymmddhh) or the actual day (yyyymmdd). Additionally a symbolic link will be created (same name but without date) which will always point with a static name to the actual log file. Using LogFile=syslog the logging will be handled through the syslog daemon (Facility=LOG_DAEMON, Priority=LOG_INFO; important messages additionally with Priority=LOG_ALERT). With LogFile=/dev/null the logging can be suppressed. [only available in the registered version]

LogMsgText=false
Suppresses the logging of the text of the messages (default is logging on). [only available in the registered version]

LogLevel=255
This parameter can be used to define different levels of logging. The specified value will be treated as a bit field, with following used bits:

Bit0 informative messages (for example that a message has been received)
Bit1 Warnings (for example that the SMSC has overridden the validity period)
Bit2 Errors (for example that a provider can not be accessed)
Bit3 The text 'looking for messages on...' using a GSM device
Bit4 Keep alive messages

[only available in the registered version]

LongDistancePrefix=0
Specifies a digit (maybe multiple), which are required for making national long distance calls (if you for example want to dial the international number +49 123 4567890 from within Germany then the country code '+49' has to be substituted by the LongDistancePrefix 0).

MaxErrors=
Specifies the count of errors (not transmitted messages) to accept until SendXMS will be terminated. If this parameter isn't set or is set to 0 the program will not terminate after an error. Running in server mode this parameter will result in closing the actual connection/device.

MaxSplit=
Specifies the max. number of segments to use for a long (concatenated) SMS. This value can be individually overwritten for each message using the command line option -N (Split= in a spool file). If no value is specified neither in the cfg file, nor in the provider definition, nor for the message itself only one single SMS (one segment) per message will be sent.

MNP= (see also Mobile Number Portability (MNP))
Specifies a function within a dll or shared object, which will be used to check whether a recipients phone number has been ported to a different provider or not.

Phone=
Your own phone number, from which the message will be submitted.

Phonebook=
Specifies the phonebook file name to use (default is sendxms.pbk). This value can be overwritten using the command line option -b.

PidFile=
Specifies the pid file name to use (default is sendxms.pid). This value can be overwritten using the command line option -P.

Priority=-5
With this you can set the priority to execute SendXMS. The value has to be in the range from -15 (high priority) to 15 (low priority).

RcZeroIfOK=true
Specifies that the return code 0 should be used if one or messages have been successfully sent (Unix style). This should be used for example for usage within an email system. If this parameter isn't set the count of submitted messages will be returned.

ReceiveDir=received
Specifies the directory where received SMS's should be saved. [only available in the registered version]

RedialCount=3
Specifies the count of redial attempts (see RetryCount, too). [only available in the registered version]

RedialDelay=60
Specifies the count of seconds to wait between two dial attempts. While this time the modem will not be locked. [only available in the registered version]

RetryCount=3
Specifies the max. number of retries to send a message. Running in server mode this means how often the message will be left in the spool directory. In opposite to RedialCount this will take effect after every faulty transmission and not only if there is no available modem or the connection is not established. (after faulty transmission) [only available in the registered version]

RetryDelay=60
Specifies the count of seconds to wait between two send attempts. While this time the modem will not be locked. [only available in the registered version]

SentDir=unsent
Specifies a directory in which already sent messages are archived. [only available in the registered version]

SpoolDir=/var/spool/sendxms
Specifies the directory to spool messages. [only available in the registered version]

SpoolFilePrefix=
By default SendXMS generates spool files with a name like sms* and processes all available files in SPOOLDIR. But if this parameter is set the created spool files will get a name with the specified prefix and only files in SPOOLDIR with this prefix will be processed.

SpoolSort=
Specifies the order to process spool files. Using SpoolSort=Name will sort the spool files in alpabetical order (file name) and SpoolSort=Time will sort by the modification time (FIFO). In any other case the spool files will be processed in the given order by the file system.

StatisticDir=statistic
Specifies a directory in which statistic/billing data will be stored. The data will be stored in CSV format and so can be easily processed with database, spreadsheet or other software. The following data will be written:

  • date/time (e.g.: "2007-11-16, 10:42:07")
  • kind of the message (0=sent, 1=received, 2=error)
  • number of the recipient
  • number of the originator
  • segment number of a segmented message
  • count of required segments
  • DCS of the message
  • MessageClass of the message
  • TariffClass of the message
  • duration of the transmission in seconds (residence time of the message in SpoolDir)
  • indication whether the message has been rejected (by the Userexit) (1) or not (0)

[only available in the registered version]

TmpDir=tmp
Specifies a directory where temporary files should be stored.

Umask=0x12
Specifies a process specific umask (file mode creation mask). If this parameter is not specified the umask of the process environment will be used. [only Linux/Unix]

UnsentDir=unsent
Specifies a directory in which unsent messages are archived. [only available in the registered version]

TimeFormat=%Y.%m.%d %H:%M:%S
Defines the format used to specify time values (ValidityPeriod or DeferredDelivery). The syntax is equivalent to the format string of the C funktions strftime/strptime. See also Deferred sending and validity period. [nur in der registrierten Version]

UserExitVersion=
Specifies the version of the userexit prototype to use. If this parameter is not defined always the oldest available prototype will be used. If the calling convention of the userexit will be changed in a new SendXMS version this new one will be assigned a new version number. With this you can select which prototype should be used and it is not necessary to change your userexit if we add new parameters. In this manual only the actual version of the userexit will be described.

ATTENTION: Support for this parameter will be cancelled starting with the next major release.

In the chapter [XMSConv] you can specify the following keywords to configure the utility XMSConv. Every keyword has to be entered in an own line.

WapInitiatorUri=
Specifies a default value for the WSP parameter X-WAP-Initiator-URI. This parameter is only used by XMSConv to compile WAP Push messages (only in Professional-Edition or higher).

WapPushFlag=
Specifies a default value for the WSP parameter PushFlag. This parameter is only used by XMSConv to compile WAP Push messages (only in Professional-Edition or higher).

In the chapter [Device] you can specify the following keywords to configure your modem. Every keyword has to be entered in an own line. (Please check your modem description (if you have one) for the corresponding modem commands)

Address=
Specifies the IP-address of a device (e.g. ISDN device with RemoteCAPI, modem with AT-over-Ethernet, VoIP, ...).

AtOverEthernet=
Specifies that the device will be accessed over IP. Valid parameter values are TCP, UDP or Telnet.

Baud=4800
Specifies the baud rate (300, 600, 1200, 2400, 4800 or 9600). This value is only used if it isn't defined in sendxms.pro for the provider to be called. (not used with TAPI)

BC=
Using CAPI2.0 the value vor Bearer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation.

BChannelInfo=
Using a leased line with CAPI2.0 the operation parameters have to be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation.

Beep=AT#VTS=[960,0,6]
Specifies a command to generate a tone signal (recoding of a voice message with a voice modem). (not used with TAPI)

CalledPartyInFilter=
CalledPartyOutFilter=
CallingPartyInFilter=
CallingPartyOutFilter=
With this parameter you can define a filter (or a list of filters if it is defined multiple times) with which incoming/outgoing phone numbers can be filtered and transformed (in case of a match). E.g. it is possible to add/remove per device a trailing '0' in case that the used CAPI does indicate the number in a wrong format or to explicitly set TON/NPI (<ton>:<npi>:<msisdn>). Please see also Phone number format filters.

CapiConnectResponseDelay=0.5
Specifies a delay (in seconds) before an incomming call will be accepted/rejected (using a CAPI device). In normal case this delay is not required but for some (internal) S0 buses SendXMS is too fast. In such cases it is possible (if CapiConnectResponseDelay is not set) that other parallel connected ISDN devices will not recognize that an incoming call has already been accepted by SendXMS.

ConnectTimeout=40
Specifies the time (in seconds) to wait for a connection after the dial command.

Controller=1
If you are using multiple ISDN adapters (via CAPI) in your computer you specify here to which adapter the definition belongs. If you don't explicitly specify a controller all available controllers will be used.

Databits=8
Specifies the count of databits (7 or 8). This value is only used if it isn't defined in sendxms.pro for the provider to be called. (not used with TAPI)

Device=
Specifies the device to which your modem is connected. (Attention: on unix you have to take notice that the owner of the file sendxms is allowed to use the device).

If you are using CAPI 2.0 you have to specify the path to the CAPI-DLL/-Shared Object (Windows, Linux) or to the CAPI-device (Unix) here.

Using Windows SendXMS tries first to open the device exclusive. If this doesn't work (maybe because of RAS) the device is opened using the TAPI-interface. With this you have the ability to share the modem with other applications, but you can't use all features of SendXMS.

DeviceType=Modem
Specifies the kind of hardware to be used for communication (VoIP, Modem, Voice modem, GSM 07.05, CAPI 2.0, CAPI 2.0 (BINTEC), RFC1086 or SERIAL).

DialPrefix=ATDT0w
Specifies the command to dial a number.
Using the CAPI interface with a PBX you can specify here the number ti get a line (normally 0). (not used with TAPI)

DialSuffix=
For some modems/ISDN terminal adapters it is required to append some additional AT commands to the phone number. This commands can be defined here. This value is only used if it isn't defined in sendxms.pro for the provider to be called. (not used with TAPI)

Domain=bai.de
Using a Voip account the phone numbers have to be transformed to SIP addresses (e.g. 0123456789 to sip:0123456789@bai.de). By default the configured IP address of the used VoIP account will be used for that. In case that the parameter Domain is defined this value will be used instead.

DtmfTransfer=RTP
Using a VoIP account this parameter specifies the kind of signalling DTMF tones. Possible values are RTP (RFC 4733, inband), INFO (SIP INFO, out-of-band) or BOTH (RTP and INFO).

Escape=+++
Specifies the escape sequence to switch the modem from data to command mode. ATTENTION! The escape sequence is only used, if you explicitly specify it. If not specified the DTR signal will be dropped for one second. Define the escape sequence only if dropping DTR doesn't work.

Hangup=ATH
Specifies the command to hang up.

HexDigits=lower
Specifies the usage of lower case hex digits for sending binary messages (default is upper case hex digits).

HLC=
Using CAPI2.0 the value vor High Layer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation.

HttpAuthType=Basic
Specifies the type of HTTP authentication to use (Basic, Digest or None).

IMSI=
Specifies the IMSI of the used SIM card (for mapping between a provider definition and a GSM device).

Init=ATQ0E1V1L1
Specifies the initialisation command for your modem. You have to set your modem to:

  • echo on
  • answer on
  • answer as text

(not used with TAPI)

Init2=
Specifies a second initialisation command for your modem. (not used with TAPI)

KeepAlive=
Specifies the maximum count of seconds a GSM device may be inactive. If this limit has been reached the registration status is checked and if necessary the modem is reregistered to the GSM network (only in Professional-Edition or higher).

LineType=ANALOG
Specifies the type of line (ANALOG, ISDN, X.25, X.31, TCP, UDP, TLS or DTLS). This parameter can also be defined within a provider definition. SendXMS will automatically select a corresponding device for a selected provider.

LLC=
Using CAPI2.0 the value vor Low Layer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation.

MessageStorages=ME;SR
Specifies a comma separated list with message storages from which messages should be read (only GSM 07.05). In normal case messages will be read just from one single memory (SM or ME).

MsgDelay=<n>
Specifies a count of seconds (for example 0.2) to wait between sending two messages within one single connection (normally not required).

MsnIn=
This parameter can be specified multiple times. Each time this parameter specifies a local phone number (MSN) (using CAPI 2.0) for which incoming calls should be accepted (for receiving fixed line SMS, DTMF or UUS messages). If this parameter is not specified all calls are accepted (for fixed line SMS only calls from the SMSC).

MsnOut=
Specifies the phone number of the ISDN adapter (using CAPI 2.0 and only for outgoing connections). Using this parameter you can specify the (for a PBX the internal) number of the line to which the ISDN adapter is connected. If you specify no or a wrong number it is possible that you can't get any connection. This parameter can be overridden by the command line option -m.

Name=
Identifies a devices by a unique name. Using that name with the command line option -d a specific device can be preselected. This is only required if multiple devices are configured and the automatic device choice should be avoided.

RegisterNetwork=
Specifies the command to be used to register a GSM device to the network. This command is used if the device is not already registered when the device is opened or if the parameter KEEPALIVE is also defined and the device is no longer registered.

OriginatingAddress=01234..
Specifies the originating address (local number)(X.25; only in Professional-Edition).

PacketLen=128
Specifies the X.25 or X.31 packet length (default: 128).

Parity=NONE
Specifies the kind of parity (NONE, EVEN or ODD). This value is only used if it isn't defined in sendxms.pro for the provider to be called. This command will be executed after the standard initialisation. For some GSM cards it is necessary to specify a memory address (AT+CPMS="ME") what can be done with this parameter. (not used with TAPI)

Password=
Specifies an optional password for use with Remote-CAPI (intern).

PDUWithoutSCA=true
Some (very old) GSM modems require a PDU without the SCA (in contrast to GSM 07.05). This parameter is for example required for Siemens M1, Falcom A1 or Xircom CreditCard but not for newer devices.

Phone=
Specifies the line number of the corresponding modem or of the SIM used with the corresponding GSM module.

PlayDTMF=AT#VTS=
Specifies the command to play a DTMF sequence (only voice modem). (not used with TAPI)

PIN="1234"
Specifies the PIN for your SIM (GSM devices). If you are using a GSM card which doesn't require any PIN (AT+CPIN? doesn't work) you have to leave this blank. For some devices you have to enclose the PIN in quotes (") but be aware that this can result in errors with other devices.

PLMN=
Specifies the PLMN of a MM1 provider (for mapping between a provider definition and a GSM device).

Port=
Specifies an TCP/UDP port to be used with an IP address.

PowerOn=
Specifies a command to turn on a GSM device (Default: AT+CFUN=1).

PowerOff=
Specifies a command to turn on a GSM device (Default: AT+CFUN=0).

PppInit=
Specifies an additional initialization command for the modem to make a PPP connection. This command will be executed after the standard initialization.

PppMmsProfile=
Specifies the character sequence required to open a PPP connection using the MMS profile (using a GSM device). If this parameter is not specified SendXMS tried to determin it automatically or uses the default value *99***1#.

Provider=
For a GSM device you can define here a default provider name. Per default all messages which are received through a GSM device are stored in a subdirectory of SpoolDir which is named like the used SMSC address. If the parameter Provider has been defined for a GSM device this value is used instead of the SMSC address (this causes that all received messages are stored in one common directory).

PUK="1234"
Specifies the PUK for your SIM (GSM devices). If you are using a GSM card which doesn't require any PIN (AT+CPIN? doesn't work) you have to leave this blank. For some devices you have to enclose the PIN in quotes (") but be aware that this can result in errors with other devices.

Reset=ATZ
Specifies the command to reset your modem (normally ATZ).

RtpPorts=10000-10050
Using a VoIP account this parameter can be used to define a local port range for RTP/RTCP (per connection two ports are required). If the connection to a SIP server will be established through a NAT router the router must be configured so that these ports will be forwarded to SendXMS.

RtsCts=true
Specifies to use the hardware flow control.

SetMsnOut=
Specifies an (AT-) command to set the (outgoing MSN, CallingPartyNumber. If this command and a MsnOut has been specified the corresponding number will be selected through the given command befor a connection will be established. The MSN will be appended at the end of the given command or will replace the placeholder $msn.

SipAlwaysRegister=True
Using a VoIP account this parameter specifies that always (even just for outgoing connections) a registration will be used.

SipRegistrationInterval=300
Specifies the count of seconds after which a SIP registration will be renewd.

StartVoicemode=AT#CLS=8
Specifies the command to set a voice modem to voice mode. This is required for recording/playing voice messages. (not used with TAPI)

Stopbits=1
Specifies the count of stopbits (1 or 2). This value is only used if it isn't defined in sendxms.pro for the provider to be called. (not used with TAPI)

StopVoicemode=AT#CLS=0
Specifies the command to cancel voice mode (voice modem). (not used with TAPI)

StunRfc=3489
Specifies that the STUN server defined with StunServer will comply with RFC 3489 (and not to the newer RFC 5389).

StunServer=10.11.12.13 3478
Specifies the address (and port) of a STUN server. Using VoIP through a NAT router a STUN server will be required to find out the public IP address.

SuppressReinit=true
If this parameter is used, a device will only be initialised opening it the first time (only in server mode). With all subsequent openings communication will start immediately without any initialisation. So you can get a much better throughput. This parameter should only be used if it is sure, that no other application will access the device and maybe change the settings.

TEI=1
Specifies the TIE (Terminal Endpoint Identifier) to be used for a X.31 connection.

UseDChannel=true
Specifies that the D-channel should be used for a X.31-connection. If this parameter isn't set =1 a B-channel will be used.

UserId=
Specifies an optional userid for use with Remote-CAPI (intern).

VoiceCompression=ALAW
If this parameter is specified then recorded messages will be stored as WAV-files and you can play WAV-files if they use a supported format. Until know ALAW (ISDN in Europe) and ULAW (ISDN in USA) are supported (8kHz, 1 channel, 8 bit).

VoiceReceive=AT#VRX
Specifies the command for a voice modem to start voice receive mode (recording of voice messages). (not used with TAPI)

VoiceTransmit=AT#VTX
Specifies the command for a voice modem to start voice transmit mode (playing of voice messages). (not used with TAPI)

WaitAfterWrite=0.5
Specifies the count of seconds to wait after writing to the device (normally 0)

WindowSize=2
Specifies the X.25 window size (default: 7) or the B3 window size for use with X.31 (default: 2).

X31Channels=0,0,1,1,0,0
Specifies the X.31 channels to be used. You have to specify - speparated by commas -

  • lowest incoming channel
  • highest incoming channel
  • lowest two-way channel
  • highest two-way channel
  • lowest outgoing channel
  • highest outgoing channel

If this parameter isn't specified the default (0,0,1,1,0,0) will be used, what will work in most cases.

XonXoff=true
Specifies to use the software flow control.

In the chapter [XMSGUI] you can specify the following keywords. Every keyword has to be entered in an own line.

cfgEditable=true
Specifies whether an enduser of the graphical front-end may modify the configuration file sendxms.cfg (=true) or not (=false). Even if this parameter is set to true an enduser can only modify sendxms.cfg if he has write access to the file.

proEditable=true
Specifies whether an enduser of the graphical front-end may modify the provider definition file sendxms.pro (=true) or not (=false). Even if this parameter is set to true an enduser can only modify sendxms.pro if he has write access to the file.

showLogfile=false
Specifies whether an enduser of the graphical front-end may be able to display the logfile of SendXMS (=true) or not (=false). Even if this parameter is set to true an enduser is only able to display the logfile if he has read access to the logfile.

In the chapters [Allow] and [Deny] you can specify the following keywords. Every keyword has to be entered in an own line. Always only one of both lists will be used. If both are defined the ALLOW list will be used.

UserId=
This parameter can be defined multiple times. Each time this parameter appears it will specify a userid which may or may not use SendXMS. If the userid are specified in the chapter [ALLOW] only these users may use the program. If the users are specified in the chapter [DENY] all users except the specifies may use the program.

In the chapters [Whitelist] and [Blacklist] you can specify the following keywords. Every keyword has to be entered in an own line. If both lists are defined the Whitelist has preference.

Phone=
This parameter can be defined multiple times. Each time this parameter appears it will specify a phone number to which no messages could (Whitelist) or could not (Blacklist) be sent. If the specified number is ending with a '*' this will be a prefix. That means that all numbers starting with the specified sequence will be used.

The chapter [SSL] can be used for an optional integration of OpenSSL (mostly not required). The following parameters can be used:

AcceptSelfSignedCertificates=true
Specifies that also self signed certificates should be accepted.

CALocation=
Defines the location where the certificates (PEM coded) of trusted CAs are stored. This can be a path (ends with a /) or a file which could contain multiple certificates.

CertChainFile=
Specifies the name of a certificate chain file with your own certificate (PEM coded; the certificates must be sorted starting with your own certificate and ending at the highest level (root)).

CertFile=
Specifies the name of your own certificate file (PEM coded).

KeyFile=
Specifies the file name of your own private key (PEM coded) (to your certificate CertFile).

LibCrypto=
Can be used to specify the name (with or without a path) of the crypto library (default is libeay32.dll for Windows and libcrypto.so for other systems).

LibSsl=
Can be used to specify the name (with or without a path) of the SSL library (default is libssl32.dll for Windows and libssl.so for other systems).

Password=
Specifies the password (passphrase) of your own private key (KeyFile).

VerifyPeer=true
Specifies that for incoming SSL connections a certificate from the peer computer will be requested and verified.

The chapter [PPP] can be used to configure PPP connections (in most cases this is only required for MM1 connections). The following parameters can be used:

Chat=
Specifies the complete path to chat (only Unix/Linux). If this parameter is not specified the default PATH will be used.

IpUp=
Specifies an optional script/batch file (or executable), which will be executed after a PPP connection has been established. This file can be used for any special routing. The file will be executed wih the following parameters:

  • IP address to connect to (MMSC)
  • IP address of the local PPP interfaces
  • IP address of the remote PPP server

NoDefaultRoute=true
Using this parameter you can avoid that a default route will be set to the created PPP interface after a connection has been established (if not used all IP traffic will be routed - as long as the connection is open - over the PPP interface by default). If this parameter is used only the IP address of the SMSC/MMSC will be routed to the PPP interface. But for that it is required that SendXMS will be executed using a root account (or on Windows an administrator account).

Pppd=
Specifies the complete path to pppd (only Unix/Linux). If this parameter is not specified the default PATH will be used.

The chapter [ODBC] can optionally be used to configure access data for the integrated ODBC-Spool-API (mostly not required). The following parameters can be used:

DSN=
Specifies the DataSourceName of the ODBC connection to be used. The DSN has to be configured on system level (e.g. using Unix in /etc/unixODBC/odbc.ini).

UID=
Specifies the (ODBC) UserId to be used.

PASSWORD=
Specifies the (ODBC) Password to be used.

LibOdbc=
Specifies the name (with or without a path) of the ODBC library to be used (the default is libodbc32.dll for Windows and libodbc.so for Unix).

UseInternalSpoolApi=true
Forces to use the internal ODBC SpoolAPI Implementation.

The chapter [SNMP] can be used to configure the optional usage of SNMP (v2c) Traps (Notifications). The following parameters can be used:

Address=
Specifies the IP address of a SNMP daemon to receive the traps.

Community=
Specifies a Community String to use (default is public).

InitializeTrap=false
Disables the generation of a trap in case of (re-)initializing a SendXMS process.

KeepaliveTrap=false
Disables the generation of a trap in case of sending/receiving a KeepAlive.

PingDelay=
Specifies the delay(in seconds) between two subsequent Ping traps (default is 60).

PingTrap=false
Disables the generation of ping traps.

Port=
Specifies the (UDP) Port on which the SNMP daemon is listening for traps (default is 162).

ProcessTrap=false
Disables the generation of a trap in case of starting/ending a SendXMS process.

SessionTrap=false
Disables the generation of a trap in case of opening/closing a connection.

SourceAddress=
Specifies the outgoing IP address to use.

SourcePort=
Specifies the outgoing (UDP) port to use.

The chapter [Java] can be used for the optional configuration of a Java VM (for using a Java userexit). The following parameters can be used:

JniVersion=0x00010006
Specifies the JNI version (here 1.6) to use.

LibJvm=
Specifies the path to libjvm.so respectively jvm.dll (Java Virtual Machine).

VmOption=
Specifies an option (e.g. -D<name>=<value>) for starting the Java VM. This parameter can be specified multiple times.

In the chapters [Audio Mime Types], [Image Mime Types] and [Video Mime Types] you can define file extensions for a corresponding MIME Type, for example:

  
    [Audio Mime Types]
mid=audio/midi
midi=audio/midi
amr=audio/amr

sendxms.pro

In this file you can define different providers. Many providers are preconfigured and can be used without any changes. But all not required provider definitions should be deleted. For some providers there are multiple definitions (modem, ISDN, GSM) preconfigured, from which you should delete all not required or move the one you use to the top. For a provider definition you have to enter a chapter by entering a line of the form
[<provider>]
In every chapter you can specify the following parameters:
(for all UCP-providers you should set ModemInit in a way to force your modem to use V.42/LAPM)

AdcInFilter=
With this parameter you can define a filter (or a list of filters if it is defined multiple times) with which incoming phone numbers (destination address) can be filtered and transformed (in case of a match). Please see also Phone number format filters.

AdcOutFilter=
With this parameter you can define a filter (or a list of filters if it is defined multiple times) with which outgoing phone numbers (destination address) can be filtered and transformed (in case of a match). Please see also Phone number format filters.

Address=<ip-address>
This parameter specifies the IP address of a provider. In case of a TCP/IP connections you have to specify this parameter instead of Phone (see also Phone). Optionally you can also append a port number (separated by a space). This parameter can be specified multiple times. If the first address is not reachable the next one will be tried.

AddressRange=
Specifies the address range (only SMPP). Please ask your provider for the value.

APN=
Specifies the Access Point Name (MM1) for a MMS provider.

AutoAlert=<phone number>
This parameter is only used in server mode and if the server was started with the parameter -aRECEIVE to read incoming messages. In this case every time the server processes the queue for the corresponding provider the service computer is called and asked for incoming messages for the specified phone number (using a less queue delay with X.25/X.31 this can be very expensive). Using CIMD a phone number has to be specified, but this number isn't used. Using UCP the phone number can be specified in the form <pid>:<phone>.

AutoConnect=<n>
This parameter is only used in server mode and if the server was started with the parameter -aRECEIVE to read incoming messages. In this case every time the server processes the queue for the corresponding provider the service computer is automatically called and SendXMS waits the specified count of seconds for incoming messages. The difference to AutoAlert is that there is only traffic on the line if there are really messages waiting. In this case of a X.25/X.31 connection this will cause no additional costs.

B1Protocol=64K-HDLC
With this parameter you specify which B1 protocol (ISDN, physical layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminal adapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

64K-HDLC 64 kbit/s with HDLC framing
64K-TRANS 64 kbit/s bit-transparent operation with byte framing from the network
V.110-ASYNC V.110 asynchronous operation with start/stop byte framing
V.110-SYNC V.110 synchronous operation with HDLC framing
T.30-FAX3 T.30 modem for fax group 3
64K-INVERT 64 kbit/s inverted with HDLC framing
56K-TRANS 56 kbit/s bit-transparent operation with byte framing from the network
MODEM-NEGOTIATION Modem with full negotiation
MODEM-ASYNC Modem asynchronous operation with start/stop byte framing
MODEM-SYNC Modem synchronous operation with HDLC framing

B2Protocol=X.75-SLP
With this parameter you specify which B2 protocol (ISDN, data link layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminal adapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

X.75-SLP ISO 7776 (X.75 SLP)
TRANS Transparent
SDLC SDLC
LAPD-X.25 LAPD in accordance with Q.921 for D channel X.25
T.30-FAX3 T.30 for fax group 3
PPP Point-to-Point Protocol
IGNORE Transparent (ignoring framing errors of B1 protocol)
MODEM Modem with full negotiation
X.75-SLP-V.42 ISO 7776 (X.75 SLP) with V.42 bis compression
V.120-ASYNC V.120 asynchronous mode
V.120-ASYNC-V.42 V.120 asynchronous mode with V.42 bis compression
V.120-TRANS V.120 bit-transparent mode
LAPD LAPD in accordance with Q.921

B3Protocol=TRANS
With this parameter you specify which B3 protocol (ISDN, network layer) should be used. This is only required if the connection is established with CAPI and the provider doesn't support the default protocols. Using an ISDN terminal adapter you have to select the protocol with an AT command in MODEMINIT. Following selections are possible:

TRANS Transparent
T.90NL T.90NL with compatibility to T.70NL
X.25-DTE-DTE ISO 8202 (X.25 DTE-DTE)
X.25-DCE X.25 DCE
T.30-FAX3 T.30 for fax group 3
T.30-FAX3-EXT T.30 for fax group 3 extended
MODEM Modem

Baud=4800
Specifies the baud rate (300, 600, 1200, 2400, 4800 or 9600). If this parameter isn't specified the value from sendxms.cfg will be used.

BC=
Using CAPI2.0 the value vor Bearer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation. If this parameter isn't specified the value from sendxms.cfg will be used.

BDataLen=1024
Specifies the max. length of data blocks (CAPI; this is not the length of a message). The value has to be in the range between 128 and 2048.

ChargedParty=
With this parameter you can control which party should pay for a MMS (Sender, Recipient, Both or Neither).

ChargedPartyID=
Specifies the address of a third party which is expected to pay for the MMS.

CallUserData=
Specifies the CallUserData for a X.25/X.31 connection. It is possible to specify a max. of 16 bytes, each coded as two hex digits.

CIP=UNRESTRICTED-DIGITAL
With this parameter you can specify (normally not required) a CIP value (Compatibility Information Profile) for connections with CAPI. Using an ISDN terminal adapter you have to select the CIP value with an AT command in MODEMINIT. Following selections are possible:

SPEECH Speech
UNRESTRICTED-DIGITAL unrestricted digital information
RESTRICTED-DIGITAL restricted digital information
3.1KHZ-AUDIO 3.1 kHz audio
7KHZ-AUDIO 7 kHz audio
VIDEO Video
PACKET-MODE packet mode
56KBIT-RATE-ADAPTATION 56 kbit/s rate adaptation
UNRESTRICTED-DIGITAL-WITH-TONES unrestricted digital information with tones/announcements
TELEPHONY Telephony

Databits=8
Specifies the count of databits (7 or 8). If this parameter isn't specified the value from sendxms.cfg will be used.

DataOverVoip=True
Specifies that the corresponding provider is supporting data traffic (like 64 kHz using ISDN) over VoIP connections. Actually this feature is only supported by a few providers and may not work between different VoIP providers. If there is a hardware based solution available (e.g. a VoIP gateway with CAPI interface, ISDN PBX with CAPI- or VoIP interface, ...) this would be the better choice.

Device=
Here you can specify the name of a device (as defined in sendxms.cfg with the parameter Name) to force the usage of this device for that provider.

Detach=

Specifies that the given provider definition should be managed in a special way. Depending on the given parameter value an extra child process will be launched to make a permanent connection. Valid parameter values are:

Send A permanent connection for sending messages will be established (no incoming messages).
Receive A permanent connection for receiving messages will be established (no outgoing messages).
All A permanent connection for sending and receiving messages will be established.
Ignore This provider definition will only be used if it is explicitly specified on the command line (using -p). Otherwise (server mode without an explicit provider selection) this provider definition will be completely ignored.
AcceptXME (only with LineType=TCP) The programm will wait for incoming connections from a XMSC to the given address(es)/port(s). If applicable a XME session will be started.
AcceptVXMSC (only with VXMSC-Edition and LineType=TCP) The programm will wait for incoming connections from a XMS to the given address(es)/port(s). If applicable a VXMSC session will be started.

Receiving messages will only be possible if the server process will be started with the command line option -aRECEIVE.

DetachQueueDelay=
In case that an own child process will be launched for the given provider (see also Detach=) a different queueDelay can be given with this parameter. Per default the child process will be started with the same queueDelay (command line parameter -q<n>) as the calling server process.

DetachUserexit=
In case that an own child process will be launched for the given provider (see also Detach=) a different userexit can be given with this parameter. Per default the child process will be started with the same userexit (command line parameter -u) as the calling server process.

DialSuffix=
For some modems/ISDN terminal adapters it is required to append some additional AT commands to the phone number. This commands can be defined here. If this parameter isn't specified the value from sendxms.cfg will be used.

DirName=
Specifies a subdirectory (within ReceiveDir, SpoolDir, ...), which will be used instead of the provders name. With this option you can force that different provider definitions (with different names) will use the same spool directory.

DlrOnlyForFirstSegment=True
Using this parameter will cause that an optional Status Report Requests (for multipart messages) will only be requested for the first segment (for all segments else).

DoNotDisturbTime=
Using this parameter you can define times at which specific messages (e.g. advertisemnt) should not be sent. This parameter can be defined multiple times. This parameter will only be respected for messages with the (spool file) parameter DoNotDisturb=true set. Such messages will not be sent as long as the actual time is within one of the DoNotDisturbTime settings. The format to define such values is as follows:

<DoNotDisturbTime> ::= <start> "-" <end>

<start> ::= <date>"."<time>
<end> ::= <date>"."<time>

<date> ::= <week day> | <year><month><day>

<week day> ::= <every day> | <sunday> | <monday> | <tuesday> | <wednesday> | <thursday> | <friday> | <saturday>

<every day> ::= "*"
<sunday> ::= "0"
<monday> ::= "1"
<tuesday> ::= "2"
<wednesday> ::= "3"
<thursday> ::= "4"
<friday> ::= "5"
<saturday> ::= "6"

<year> ::= <digit><digit><digit><digit>
<month> ::= <digit><digit> ; 01-12
<day> ::= <digit><digit> ; 01-31

<time> ::= <hour><minute><second>

<hour> ::= <digit><digit> ; 00-24
<minute> ::= <digit><digit> ; 00-59
<second> ::= <digit><digit> ; 00-59

<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Example:
DoNotDisturbTime=*.000000-*.080000 ; every day between 00:00 and 08:00
DoNotDisturbTime=0.000000-0.240000 ; every Sunday (the whole day)
DoNotDisturbTime=20110101.000000-20110101.240000 ; New Year 2011 (the whole day)

(only Professional-Edition or higher)

DtmfDelay=
Specifies the length (in milliseconds) of a DTMF ton (only Protocol=DTMF).

DtmfGap=
Specifies the length (in milliseconds) of a gap between two DTMF tons (only Protocol=DTMF).

ErrorFilter=
Using a SMS over HTTP service provider you can define with this parameter a filter to recognize an error (filter does match) or success (filter does not match) by interpreting the (non standardized) response of the service provider. If for example the provider is sending the following response to a send request:
ERROR: invalid recipient
you can use the following filter to recognize the error:
MsgIdFilter=/^ERROR:(.*)/\1/
(see also Phone number format filters and SMS over HTTP).

HLC=
Using CAPI2.0 the value vor High Layer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation. If this parameter isn't specified the value from sendxms.cfg will be used.

KeepAlive=
Specifies the maximum count of seconds the connection can be inactive. If this limit has been reached a request will be started to check the validity of the connection and to disable any automatic hang-up (only in Professional-Edition and higher).

LineType=ANALOG
Specifies the connection type of the specified phone-number/address (for that provider) (ANALOG, ISDN, TCP, PPP_TCP, X.25 or X.31). This parameter can also be defined within a device definition. SendXMS will automatically select a corresponding device for a selected provider.

LLC=
Using CAPI2.0 the value vor Low Layer Capability can (normaly not required) be defined here (specifying single bytes in hex format (each byte coded with two hex digits). The coding scheme can be found in the CAPI documentation. If this parameter isn't specified the value from sendxms.cfg will be used.

MapUserValue=
Using this parameter you can map user specific parameters to provider specific protocol extensions. Some protocols provide specical parameter fields to support provider specific extensions. For example with SMPP (3.4 or above) the optional TLV parameters 0x1400 to 0x4000, with CIMD the tags 600 to 900 and with UCP (EMI) the XSer Type of services 0x0E to 0xFF can be used for provider specific extensions. If the service provider is supporting such an extension you can define this with this parameter so that the provider specific data can be exchanged (sending and/or receiving). For example you can define with MapUserValue=TariffOption|0x1500 for a SMPP account tha the content of the optional user specific spool file parameter TariffOption will be exchanged via the optional TLV parameter 0x1500. Using MM1, MM7 or EAIF you can specify additonal HTTP header parameters (e.g. MapUserValue=uaprofile|X-WAP-PROFILE to exchange an User Agent Profile). Using a SMS over HTTP provider you can also map the standard spool file parameters to the URI parameters reuqired from your service provider (only Professional-Edition and higher).

MaxAllowedConnections=
Specifies the max. count of incoming (simultaneously) connections allowed for the corresponding provider definition. Using this parameter you can limit the number of connections per client (provider definition) (only VXMSC-Edition and higher).

MaxMsg=
Specifies the max. count of messages which can be send in a single connection. If this parameter is specified the connection is cancelled after the corresponding count of messages is sent and if required a new connection will be established. This is necessary because some providers have a limit for sending multiple messages per connection. Running in server mode this parameter specifies the max. count of messages to process before the server continues to handle the next provider.

MaxSplit=
Specifies the max. number of segments to use for a long (concatenated) SMS. This value can be overwritten by using the parameter MaxSplit in a provider definition or individually for each message using the command line option -N (Split= in a spool file). If no value is specified neither in the cfg file, nor in the provider definition, nor for the message itself only one single SMS (one segment) per message will be sent.

MaxThroughput=
MaxThroughputIn=
MaxThroughputOut=
Specifies (optional) the maximum throughput for a specific provider. The value refers by default to the max. throughput per second. This can be changed by adding another interval separated by a slash (e.g.: MaxThroughput=100 indicates a max. throughput of 100 messages per second; MaxThroughput=1200/60 indicates a max. throughput of 1200 messages per minute).
MaxThroughput= limits the in- AND outgoing traffic to the given value. Using MaxThroughputIn= and MaxThroughputOut= these values can be specifies independently from each other.

MaxRecipients=
Specifies the max count of recipients (between 1 and 256) which could be used within one data packet. If more recipients are specified for a message, then multiple packets will be sent sequentially, each with as much recipients as allowed.

MessagingMode=
Specifies for SMPP 3.4 the messaging mode (between 1 and 3) or for UCP 4.0 whether the message should be treated as a 'single shot' message (0 or 1).

MM7Schema=
Specifies the schema to be used with MM7, e.g.:

http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-6-MM7-1-4

MNP= (see also Mobile Number Portability (MNP))
Specifies a porting identifier of the network. With this identifier - if you have defined a MNP function in the cfg file - SendXMS will test whether a recipients phone number (not an alias) has been ported. This parameter can be defined multiple times for a provider.

ModemInit=
Specifies an additional initialise command for the modem. This command is called after the initialise command defined in sendxms.cfg and doesn't substitute it. Commonly this command can be left blank. It is only needed, if you want to force your modem to use a specific protocol. For example you should use V.42/LAPM for providers using UCP.

MsgDelay=<n>
Specifies a count of seconds (for example 0.2) to wait between sending two messages within one single connection (normally not required).

MsgIdFilter=
Using a SMS over HTTP service provider you can define with this parameter a filter for extracting the given MsgId out of the (non standardized) response of the service provider. If for example the provider is sending the following response to a send request:

SUCCESS: SMS was scheduled for delivery (MessageIdentifier=30106CCE)

you can use the following filter to get the MsgId:

MsgIdFilter=/^SUCCESS: SMS was scheduled for delivery \(MessageIdentifier=([0-9,A-F]*)\)/\1/i

(see also Phone number format filters and SMS over HTTP).

MsgLen=
Specifies the max. length of a message (number of characters respectively number of seconds). If the protocol is SKYPER then this parameter is set automatically. In the unregistered version the max. length is limited to 60 characters or 5 seconds.

MsgType=
Specifies the kind of message: NUMERIC (only digits), ALPHANUMERIC (characters and digits) or TONE (no characters, only beeping). If the protocol is SKYPER then this parameter is set automatically. In case of Skyper the modem has to be configured for not filtering XON/XOFF characters.

MTBillingInterface=
Specifies whether and which interface for MT billing should be used. At the moment there are the choices 'IC3S' and 'Whatever Mobile'.
IC3S indicates that the T-Mobile Micropayment Platform will be used. The parameter forces that the field TariffClass (BillingIdentifier) should be parsed before sending a message and that the placeholders $y and $z should be replaced by the max. count of segments ($y) and the actual segment number ($y).
Whatever Mobile indicates that the MT billing interface of Whatever Mobile GmbH should be used. How the messages are billed can be specified with the parameter MTBillingMode.

MTBillingMode=
The given value controls how the messages will be billed: no billing at all (1), all segments will be billed (2), only the first segment will be billed (3) or no segments will be billed (4).

Network=
Specifies the network system (GSM, CDMA, TDMA, ...).

NoHttpAuthentication=true
In case that a UserId or a Password has been defined for a HTTP connection the Basic Access Authentication will be used by default. Because many providers of SMS over HTTP services do not support this authenticaton it can be turned of using this parameter (only in Professional-Edition and higher).

NoKeepAlive=
Specifies the maximum count of seconds the connection can be inactive. If this limit has been reached the connection will be closed. The value for that parameter has to be higher then the value for ProtocolTimeout (only in Professional-Edition and higher).

NotificationAddress=
Specifies the address to which the SMSC should send notifications [only UCP function 51; not with Standard-Edition].

NotificationPID=
Specifies the type of NotificationAddr [only UCP function 51; not with Standard-Edition].

Following values are defined for <n>:

0100 Mobile Station
0122 Fax Group 3
0131 X.400
0138 Menu over PSTN
0139 PC appl. over PSTN (E.164)
0339 PC appl. over X.25 (X.121)
0439 PC appl. over ISDN (E.164)
0539 PC appl. over TCP/IP

NotificationType=
Specifies which notifications should be sent [only UCP function 51, CIMD, SMPP and OIS].

Following values will be accepted for UCP, OIS and CIMD for <n>:

0 none (default value)
1 Delivery Notification (DN)
2 Non-delivery Notification (ND)
3 DN + ND
4 Buffered message notification (BN)
5 BN + DN
6 BN + ND
7 all

For SMPP 3.4 all values conforming to the protocol specification can be used.

NotifyURL=
Specifies an URL, which should be used by an OneAPI server to send notifications to.

OadcInFilter=
With this parameter you can define a filter (or a list of filters if it is defined multiple times) with which incoming phone numbers (originating address) can be filtered and transformed (in case of a match). Please see also Phone number format filters.

OadcOutFilter=
With this parameter you can define a filter (or a list of filters if it is defined multiple times) with which outgoing phone numbers (originating address) can be filtered and transformed (in case of a match). Please see also Phone number format filters.

OkFilter=
Using a SMS over HTTP service provider you can define with this parameter a filter to recognize the success (filter does match) or an error (filter does not match) by interpreting the (non standardized) response of the service provider. If for example the provider is sending the following response to a send request:

SUCCESS: SMS was scheduled for delivery (MessageIdentifier=30106CCE)

you can use the following filter to recognize the success:

MsgIdFilter=/^SUCCESS:(.*)/\1/

(see also Phone number format filters and SMS over HTTP).

OriginatingAddress=
Specifies the originating address (phone number) to use for that provider (only in Professional-Edition and higher and only if supported by the used provider and/or device).

Password=
For some providers a password (Authentication Code for UCP) is required, which you can specify here. Please ask your provider for the value.

Parity=NONE
Specifies the kind of parity (NONE, EVEN or ODD). If this parameter isn't specified the value from sendxms.cfg will be used.

Phone=
Specifies the phone number of the provider. If the last character of the number is a '&', this means that the specified number will be appended by the number of the recipient.
If you are using the GSM protocol you have to enter the SMSC-address in the form +<a><b><c>, where <a> is the country code (without zeros), <b> the area code (without zeros) and <c> the phone number. For many GSM modems it is also possible to just specify Phone=<SIM>. In this case the software tries to automatically read the SMSC address out of the modem.
This parameter can be defined multiple times.

Port=<n>
Specifies the (destination) port number to use for a TCP/IP connection.

PPPPhone=
Specifies a phone number to dial for opening a PPP connection. This parameter is only required in conjunction with LineType=PPP_TCP.

Prefix=
Specifies the predial code for the corresponding provider. With this prefix SendXMS tries to identify the provider to which the phone number of the recipient belongs. If Prefix=* is defined all numbers will be valid for that provider. This parameter can be defined multiple times.

Priority=
Defines a standard priority to use if no other priority is explicitly assigned to a message (-I).

Protocol=
Specifies the protocol (TAP (Telocator Alphanumeric Protocol), TAPAIM (TAP-protocol with AIM-extensions), UCP (Universal Computer Protocol; CMG), GSM (Global System for Mobile communication), UUS (User-User-Signaling), SMPP (Short Message Peer to Peer; Logica), CIMD (Computer Interface to Message Distribution; Nokia), OIS (Open Interface Specification; SMS2000 SEMA), ES201912_1, ES201912_2, HTTP (SMS over HTTP (proprietary)) see also SMS over HTTP), UAP (USSD Service Protocol; Huawei),, SIP_IM (SIP Instant Messaging; RFC3428), MM1 (Multimedia Messaging protocol 1), MM7 (Multimedia Messaging protocol 7), EAIF (External Application Interface; Nokia), ONEAPI_SMS, ONEAPI_MMS, ONEAPI_LOCATION, ONEAPI_CAPABILITY, ONEAPI_PAYMENT, DTMF, Voice, Skyper or CityRuf) which the provider uses. DTMF is for use with some pager services (only numeric messages) and can only be used with CAPI 2.0 or with a voice modem. UUS is an Euro-ISDN service (not supported in all countries) and can only be used with CAPI 2.0.

For the protocol UCP you can additionally select between different function codes for sending (UCP[01], UCP[30] or UCP[51]; using a large account you should use function 51). The functions 30 and 51 will additionally transmit the originator address (phone number) and a validity period (if defined). But these functions are not supported by all providers.

For the protocol SMPP (at least version 3.4) you can also use the additional parameter UseAlwaysTransceiver=True to force a connection to the SMSC with a BIND_TRANSCEIVER instead of a BIND_TRANSMITTER or BIND_RECEIVER (only required in special cases, if the SMSC does not accept anything else).

For the protocol CIMD you can specify CIMD[USSD] to use a connection to a USSDC.

For the protocol OIS you can additionally select between General Access (OIS) and Direct Access (OIS[Direct]).

For the protocol MM1 you can additionally select between MM1 over HTTP (MM1[HTTP] or just MM1) (MMS-F and WAP 2.0) and MM1 over WSP (MM1[WSP]) (WAP 1.x).

ProtocolVersion=
Is used to differ between different protocol versions (e.g. Protocol=CIMD, ProtocolVersion=2.0).

ProtocolTimeout=60
Specifies the time (in seconds) to wait for a response from the service computer. If this parameter isn't defined following default values will be used, which are higher then the protocol limits:

For X.25, X.31 and TCP/IP connections always 10 seconds, in other cases:

CIMD 30 seconds
ES201912_1 10 seconds
ES201912_2 10 seconds
GSM 160 seconds
OIS 30 seconds
SMPP 30 seconds
TAP 30 seconds
UCP 120 seconds

ReconnectDelay=<n>
Specifies a delay (in seconds) in which after a connection to this provider has been closed no new connection to the provider can be established (only in server mode).

SourceAddress=<w.x.y.z>
Specifies the source address to use for a TCP/IP connection.

SourcePort=<n>
Specifies the (source) port number to use for a TCP/IP connection.

SslCertChainFile=
Specifies the name of a certificate chain file with your own certificate (for the corresponding provider definition) (PEM coded; the certificates must be sorted starting with your own certificate and ending at the highest level (root)) and overwrites the value for CertChainFile in chapter [SSL] in sendxms.cfg.

SslCertFile=
Specifies the name of your own certificate file (for the corresponding provider definition) (PEM coded) and overwrites the value for CertFile in chapter [SSL] in sendxms.cfg.

SslKeyFile=
Specifies the file name of your own private key (PEM coded) (to your certificate SslCertFile) and overwrites the value for KeyFile in chapter [SSL] in sendxms.cfg.

SslPassword=
Specifies the password (passphrase) of your own private key (SslKeyFile) and overwrites the value for Password in chapter [SSL] in sendxms.cfg.

SslServerNameIndication=<domain>
Specifies the name of the domain (e.g.: smpp.sendxms.com) whose certificate the server should use. For servers hosting multiple domains under the same IP, this may be necessary to use the correct certificate.

Stopbits=1
Specifies the count of stopbits (1 or 2). If this parameter isn't specified the value from sendxms.cfg will be used.

SwapDlrAddresses=true
Specifies that the sender and recipient addresses should be swaped if a MM7 status report (DeliverReportReq) has been received. Some MMSCs already swap these addresses themselves, others not.

SystemDescription=
Specifies a system description (between 0 and 9; only for CIMD), which should be used by default.

SystemId=
Specifies the system id (only SMPP). Please ask your provider for the value.

SystemType=
Specifies the system type (only SMPP). Please ask your provider for the value.

TariffClass=
Specifies a tariff class (CIMD, between 0 and 99) or the billing identifier (UCP 4.0), which should be used by default.

ThrottledDelay=
Specifies a count of seconds to wait (no protocol activities) after a Throttled Error (only SMPP and UAP).

TimeOffset=
Specifies the offset (in minutes) between the local timezone and the timezone of the SMSC/MMSC. With this parameter the values for ValidityPeriod and DeferredDelivery are corrected (only UCP and CIMD; the other protocols support different timezones directly).

TransTable=tap.ctt
Specifies a character translation table (see also Character Translation Tables). For a SMS over HTTP provider you can specify with this parameter a special (URL) encoding (default is UTF-8).

UCP60Password=
If a UCP provider is using the password option (function 60) you have to define that parameter. Normally this is only required for large accounts. Additionally the parameter USEUCP60=true has to be defined (only Professional-Edition and higher).

URI=
Specifies the URI for a HTTP Post Request (for example for MM1, MM7, EAIF). For incoming connections the URI which the client requests has to use the format /SendXMS/<provider> (<provider> is the name of the used provider definition).

UseAimCharacterTranslation=true
Enables the usage of the extended character translation (only TAPAIM).

UseOtoA=true
Enables the usage of the OTOA parameter (only UCP). This parameter is required for international and alphanumeric originating addresses, but is not supported by all providers.

UserId=
For some providers (CIMD or UCP (function 60)) a UserID is required, which you can specify here. Please ask your provider for the value. Using UCP the userid can be specified in the form <opid>:<userid> (but also only <userid> possible).

UseUCP60=true
Specifies that a session has to be started (with UCP function 60) before SMS can be sent. Additionally the parameter UCP60Password should be defined (only Professional-Edition and higher).

VASID=
Value Added Service Identification (only Professional-Edition and higher).

VASPID=
Value Added Service Provider Identification (only Professional-Edition and higher).

WaitAfterConnect=
For some providers (using the UCP protocol) there must be a delay between the Connect message of the modem and the first outgoing message. This parameter specifies the duration in seconds of this delay. This seems only be necessary if your modem isn't set to V.42/LAPM. So the better way is to set in ModemInit (see below) such an AT command.

WindowSize=
Specifies the max. number of messages which can be sent without waiting for a response (default=1). Counterpart to the synchronous communication (waiting for a response after each submitted requested) this will result in a better performance (only Professional-Edition and higher).

WspEncodingVersion=1.3
Specifies a WSP Encoding-Version for usage with for example EAIF or MM1.

sendxms.pro example:

  
    [D1]
Phone=01712092522
Protocol=TAP
Prefix=+49171
MsgType=ALPHANUMERIC
MsgLen=160

sendxms.pbk

In this file you can enter a chapter for every in sendxms.pro defined provider with aliases. Every chapter starts with a line of the form:
[<provider>]
Every alias has to be entered in an own line and has to be of the form:

<alias>=<phone>

The phone book is only available in the registered version!!!!

sendxms.pbk example:

  
    [D1]
max=01711234567 ; Max Müller

Character Translation Tables

Due to the fact that every by SendXMS supported protocol uses its own character set and many providers modify these character sets SendXMS offers the possibility to define specific character translation tables for every provider. If for one provider no explicit table is specified a default table is used. To define a table for a provider you have to generate a file in the following format an specify this file within the provider definition in the parameter TransTable:
The default characters have to be specified in a table CharacterTable=00. The value 00 is a placeholder for the default GSM alphabet. Multiple tables with different values (language identifiers) can be specified (see 2GPP TS 23.038).
For each individual character a line with two comma-separated Hex codes will be specified. The first code (UCS-2) specifies the character to be translated. The second code specifies the value which is used by the provider for the character specified by the first code.
Because the GSM alphabet is uses just 7 bits only 128 characters can be coded. But via an extension mechanism some more important characters can be used (using such charaters will reduce the max. count of characters per SMS). For this at first a special character has to be defined using the parameter EscapeChar=1B (in this case the Escape character). The characters which should be coded with such an escape sequence have to be specified in a table ExtensionTable=00 using the same format as above.
Use the files ctt/gsm.ctt and ctt/cimd.ctt (included in the standard installation) as an example. But please don't change these files. If required copy the original file and modify this one.

Phone number format filters

Because of the fact that for some connections to a SMSC/MMSC you have to submit the phone numbers in a specific format (for example in international format, in international format but without any prefix or in national format) SendXMS offers the ability to define per provider different filters. By defining a filter multiple times within a provider definition you can build a list of filters which will be used in the given order until one filter definition matchs against the given number. You can define different filter(s) for destination numbers and/or the originating numbers (each for incoming and/or outgoing messages). With this it is for example possible to transform (if the SMSC requires that) an outgoing destination number automatically into international format without any leading prefix. for incoming messages you can for example define a filter which always puts a '+' in front of a destination number.

A filter has to be specified as a regular expression (POSIX 1003.2). A filter consists of two parts which are separated by a delimiter ('/'). The first part consist of the regular expression (RE). In case that this RE matches the data (destination or originating number), the data will be replaced by the expression in the second part of the filter. Within the second part you can specify any sequence of digits and/or a back reference. A back reference has to be specified in the form \<n> with <n> in the range of 1 to 9. The back reference \1 refers to the first part of the RE (first opening bracket). At the end of a filter definition the following modifiers can also be specified:

i Perform case-insensitive matching
g Perform a global match (find all matches rather than stopping after the first match)
m Perform multiline matching
c Continue with the next RE in list, even if actual one is matching

Some examples:


AdcOutFilter=/^(\+|00)([0-9]*)/\2/
AdcOutFilter=/^(0)([0-9]*)/49\2/

This filter checks before a message will be sent, whether the destination number has been specified in international format (+... or 00...) (first filter) or in national format (0...) (second filter). In case that the first filter matchs the number will be transformed (using \2) to an internatinal number without prefix (without + or 00). In case that the first filter does not match the second one will be used and in case that this one matchs (the number starts with 0) the starting '0' will be replaced with '49' (using 49\2).
+491711234567, 00491711234567 or 01711234567 will be transformed to 491711234567.
+123456789 will be transformed to 123456789.


AdcOutFilter=/^(\+49|0049|0)(164|168|1691)([0-9]*)/\3/

This filter checks before a message will be sent, whether the destination number uses one of the German region codes 0164, 0168 or 01691 (in international or national format). In case that the filter matchs the complete region code will be removed.
+491681234567 or 01681234567 will be transformed to 1234567.
+123456789 will keep unchanged.


AdcInFilter=/^(\+491|00491)([0-9]{5})(0*)/\2/

This filter will transform incoming destination numbers which starts with +491 or 00491, contain 5 additional digits and ends with any count of '0'. The result will just contain the 5 digits (short code).
+49112345000, 00491123450 or +49112345 will be transformed to 12345.
+112345000 will keep unchanged.


OadcOutFilter=/(^([0-9]{0,3}:){0,2})?((\+?[0-9]+)$|(([A-Z0-9]*)([^A-Z0-9]*)))/\1\4\6/ig

This filter will remove all non-alphanumeric characters from the source address. A leading + sign or explicitly specified TON/NPI values will be kept.

Voice messages

Additionally to the ability to communicate with cellular phones and pagers SendXMS can also communicate with "normal" phones. To use this feature you have to use a voice modem VoIP or CAPI 2.0. There are preconfigured entries in the provider file (sendxms.pro) to use voice messages. To play a voice message that message has to be in the native coding format of the corresponding device (this formats differ between different modem manufactures). To play voice messages in different formats you have to use conversion programs. Many such conversion programs are freely available (for example sox or mgetty+sendfax). To play a voice message you have to call SendXMS in the same way as if you send a text message, except that you have to explicitly specify the predefined provider VOICE:


sendxms -pVOICE 07246942484 -fvoice.dat

or


sendxms -pVOICE 07246942484 < voice.dat

In both cases the specified number will be called and the voice message stored in the file voice.dat will be played.

Using VoIP or CAPI 2.0 you can directly send WAV files if these are coded in aLaw or uLaw fomrat using 8 KhZ, 1 channel and 8 bit. Using any other device the meaage has to be coded the native format of the used device. The easiest way to record such a message is to use SendXMS itself with such a command:


sendxms -pVOICE 07246942484 -fvoice.dat -aRECEIVE

Server mode

In the registered version (Server-Edition or higher) of SendXMS is a server mode available (-q<n>). With this you can force a SendXMS-instance to run in the background and check the spool directory in regular periods. If there are messages to send they will be send all at once. If a server is running all other instances of SendXMS spool their messages, instead of sending them directly over the phone line. So you have the ability to collect messages and send them within one single connection and to save money. With additional parameters you can force SendXMS, whether a server is running or not, to spool the messages or to send them directly.

If you are using a GSM device or a large account you have the ability to receive and store (-aRECEIVE) SMSs and/or notifications (DLRs).

To spool messages you only have to call SendXMS or you can generate the spool files by yourself (ASCII format; while generating a spool file this should be locked exclusively). The spool files have to be placed in the directory <SPOOLDIR> (defined in sendxms.cfg). In that directory there has to be a subdirectory for every provider for which messages are spooled. the spool files have to be UTF-8 encoded and have to start with the following line
; encoding=UTF-8
Every spooled message has to be placed in a separate file. The following is a example for a spool file:


; encoding=UTF-8
[D1]
Phone=491711234567
XMS=This is a spool file.

The following key words will be interpreted (most of them are optional): Action=
Specifies the type of request. Possible values are SEND, DELETE, RECEIVE, QUERY (command line parameter -a).

AddCodes=
AddInfo=
AddCodes and AddInfo may contain additional protocol specific information and are set as follows:

negative response
Protocol addCodes addInfo
GSM error code "CME ERROR" or "CMS ERROR"
CIMD Error Code (900) Error Text (901)
SMPP Command Status
OIS result
UCP Ec (error code)
HTTP HTTP response code
OneAPI_SMS HTTP response code
MM1 StatusCode StatusText
MM7 StatusCode StatusText
EAIF StatusCode StatusText
OneAPI_MMS HTTP response code
status report
Protocol addCodes addInfo
GSM TP-Status TP-Service-Center-Time-Stamp; TP-Discharge-Time
CIMD status code (061); status error code (062) discharge time (063)
SMPP message_status; Error_code done_date
OIS SM status; delivery failure reason completition/intermediate time
UCP Dst; Rsn
OneAPI_SMS deliveryInfo
MM1 'DeliveryReport' or 'ReadReply': (Read)Status; StatusExtension
MM7 'DeliveryReport' or 'ReadReply': MMStatus; MMStatusExtension
EAIF 'DeliveryReport' or 'ReadReply': (Read)Status; StatusExtension
OneAPI_MMS deliveryInfo

AllowAdaptations=
Indicates if VASP allows adaptations of the content of a MMS (true or false).

ChargedParty=
An indication which party is expected to be charged for a MMS (Sender, Receiver, Both, Neither or ThirdParty).

ChargedPartyID=
The address of the third party which is expected to pay for the MMS.

Count=
Specifies the actual count of send attempts. If the message could not be sent this parameter is incremented until it reaches the maximum allowed value (RetryCount).

Date=
Specifies the ServiceCenterTimeStamp (e.g.: Tue, 09 Jan 2001 11:22:19 +0000).

DCS=
Specifies the DataCodingScheme (decimal)(see also GSM 03.38).

DeferredDelivery=
Specifies the time/date when the message should be delivered by the SMSC/MMSC (command line parameter -D). See also Deferred sending and validity period.

Device=
Specifies the device to use (command line parameter -d).

DistributionIndicator=
Indicates whether the content of a MMS can be redistributed (true or false).

DoNotDisturb=true
In case that DoNotDisturbTime parameter values are defined for the used provider definition these values have to be respected for the according message. So it it is for eample possible to prevent sending of advertisements at night. Such messages will be sent as soon as the actual time is not within any DoNotDisturbTime definition. (only in Professional-Edition or higher).

LocalId=
Specifies the userid of the originator (default) or an unique (local) id for the message (command line parameter -o). This parameter is different to the phone number which is displayed on the recipients phone and can be used for internal use.

MessagingMode=
Specifies for SMPP 3.4 the messaging mode (between 1 and 3) or for UCP 4.0 whether the message should be treated as a 'single shot' message (0 or 1).

MmsMessageClass=
Specifies for MMS the message class (X-Mms-Message-Class).

MsgId=
Specifies the msgId of the message (command line parameter -G). The msgID will be assigned by the SMSC/MMSC and is required for deleting a message or for querying the status.

MsnOut=
Specifies the (outgoing) MSN to use (command line parameter -m, only ISDN).

OriginatingAddress=
Specifies the originating address which will be displayed on the recipients phone (command line parameter -O).

Phone=
Specifies the recipients phone number. Using the Professional-Edition (or higher) this parameter can be specified multipe times. If multiple recipients are specified SendXMS will try (depending on the used protocol) to submit the message to as many recipients as possible at once. If this is not possible the message will be submitted multiple times (each time to as many recipients as possible).
For MMS message it is also possible to specify the additional fields To, Cc and Bcc (as a comma seperated list). But this will be just informative, the routing depends just on the field Phone.

PID=
Specifies the ProtocolIdentifier (e.g.: PID=0x40 for a Ping message or PID=0x5F for a Return Call Message; see also GSM 03.40).

ReplyPathRequest=true
Indicates that the parameter ReplyPathRequest should be used (command line parameter -R).

Priority=
Specifies the priority of the message (command line parameter -I)

ReplaceIfPresent=1
Specifies that an old message to the same destination address should be replaced (only SMPP).

ServiceCode=
Specifies the ServiceCode for a MMS.

ServiceDescription=
Specifies a value between 0 and 99, which can be used for billing (only CIMD).

ServiceType=
Indicates the service_type associated with the message (only SMPP).

Split=
Specifies the max. number of SMS the message should be split into (command line parameter -N). In special cases (e.g. in a userexit call) thi sparameter may also indicate that the given content is the n-th segment of a long SMS. In this case the parameter is given in the format x/y/z where x specifies th count of required segments, y specifies the number of the actual segment and z specifies a reference number (unique for all segments of a message).

StartTime=
Specifies the time/date when the message should be transferred to the SMSC/MMSC (command line parameter -S). See also Deferred sending and validity period.

StatusReportRequest=true
Indicates that the parameter StatusReportRequest should be used (command line parameter -F).

Subject=
Specifies the subject of a MMS (command line parameter -U).

TariffClass
Specifies a tariff class (CIMD, between 0 and 99) or the billing identifier (UCP 4.0).

Template=
Specifies the absolute path to a file containing the message content to be submitted. This may be usefull for message campaigns with always the same content to multiple thousand recipients. The content of the specified file will overwrite the content of the parameter XMS.
The content of the specified file has to be UTF-8 encoded.

TemplateSuffix=
TemplatePrefix=
Specifies the absolute path to a file containing the beginning/ending of the message text to be submitted. This may be usefull for message campaigns with always the same content to multiple thousand recipients. The content of the parameter XMS will be inserted between prefix and suffif. So you can create message campaigns (MMS) with messages containing always the same picture and/or video but different text.
The content of the specified file has to be UTF-8 encoded.

UDH=
Specifies (for SMS and EMS) the UserDataHeader (without length) (command line parameter -U). Only the fixed part od the UDH (the one which is repeated in every segment of a long message) should be specified. The UDH parts which belong only to one single segment (EMS) are specified in the message text within the tags <UDH>...</UDH> (you can easily generate such content using XMSConv).

UsedDevice=
Specifies the device (defined in sendxms.cfg) which has been used for the message.

UsedProtocol=
Specifies the protocol which has been used for the message.

UssdServiceCode=
Specifies an USSD Service Code (SMPP, CIMD and UAP; 0-255).

ValidityPeriod=
Specifies the time/date until which the message should be valid (command line parameter -V). See also Deferred sending and validity period.

XMS=
The message itself. the characters <TAB> (0x09), <LF> (0x0A), <CR> (0x0D) and <Backslash> (0x5C) have to be entered as an escape sequence like '\t', '\n', '\r' or '\\'.

Using ONEAPI Payment protocol you can also use the parameter names defined in the GSMA protocol definition as key words.

ODBC interface

Per default spool file will be written/searched by SendXMS within the file system. Independently from the below described spool API there exists, starting with the Professional-Edition, the possibility to exchange the spool files directly with a database system using the ODBC interface. For that you have to configure the access data for the database system to use in the .cfg file. (see also Configuration). Of Course the ODBC data source has also to be configured (and tested) on operating system level. Within the used database system you have to create a database with the required tables and stored procedures. After a successfull installation of SendXMS you will find the file spoolapi.mysql within the subdirectory (of the installation directory) samples which contains a database definition for usage with MySQL/MariaDB (and MyODBC) and which could be easily adapted to other database systems. Using Unix/Linux you should use unixODBC as the ODBC manager.

Spool-API

Per default spool file will be written/searched by SendXMS within the file system. Starting with the Professional-Edition there is also Spool API available with which this could be changed. So it is for example possible to communicate directly with any database. For this you have to provide a shared object (DLL) with some required functions. The name of this shared object (DLL) has to be specified within the used .cfg file using the parameter SpoolAPI (chapter [SendXMS]). If the specified file can not be loaded or if one (or more) functions could not be found) the default spool API (file system) will be used.

An implementation of the spool API has to be thread safe! Each function has to return 0 in case of a successfull execution. The initialization function of the spool API may return a pointer to any internal structure which will be used by SendXMS as a parameter for each other function call. With this structure you can avoid global variables.

The spool API uses a similar architecture as it is also used with the file system. So it will also be differentiated between SPOOLDIR, RECEIVEDIR, SENTDIR und UNSENTDIR. Whether this differentiation will really be done within the implementation does not matter.

The data transfer will take place in the standard spool file format (UTF-8 coded) (see also server mode). Whether the data will be stored in this or any other format doesn't matter.

Records have to be locked exclusively (per thread) to avoid multiple processing.

An implentation of the spool API has to provide the following functions:

#define XMS_SPOOLDIR 0     /* messages to send */
#define XMS_RECEIVEDIR 1 /* received messages */
#define XMS_UNSENTDIR 2 /* messages which couldn't be sent */
#define XMS_SENTDIR 3 /* already sent messages */

/* initialise the API; returns a pointer to any Userdata and the version of the implemented API */
int xmsSpoolApiInit (void **userdata, int *version);

/* release locks, memory, ... */
int xmsSpoolApiExit (void *userdata);

/* generate a list with keys of messages in the given dir; return -1 if the list is empty */
int xmsSpoolApiOpenMsgList (void *userdata, int dir, char *provider);

/* lock the next messages, allocate memory (sets *xmsLen to the size of the message) and return it; return -1 if no more messages are available */
int xmsSpoolApiGetNextMsg (void *userdata, int dir, char *provider, char *key, int maxKeyLen, char **xms, int *xmsLen);

/* free the memory allocated in xmsSpoolApiGetNextMsg (but do not release the lock!)*/
int xmsSpoolApiFreeMsg (char *xms);

/* free the previously generated list */
int xmsSpoolApiCloseMsgList (void *userdata, int dir, char *provider);

/* unlock the given record */
int xmsSpoolApiUnlock (void *userdata, int dir, char *provider, char *key);

/* insert a new record; returns the generated primary key */
int xmsSpoolApiInsert (void *userdata, int dir, char *provider, char *key, int maxKeyLen, char *xms, int xmsLen);

/* update the given record and unlocks it */
int xmsSpoolApiUpdate (void *userdata, int dir, char *provider, char *key, char *xms, int xmsLen);

/* delete the given record */
int xmsSpoolApiDelete (void *userdata, int dir, char *provider, char *key);

SNMP

Starting with the Professional-Edition you can configure SendXMS in that way that for special events SNMP traps (Notifications) will be sent to a SNMP daemon. A trap is an unconfirmed alarm to inform a management system automatically about a state change. For that SendXMS is using SNMPv2c. Traps are onnly supported using the Professional-Edition (or above) and will only be used if SendXMS is running in server mode (queue delay >= 0). Traps are supported for the fllowing events:

  • a SendXMS process has been started or ended
  • a SendXMS process has been (re-)initialized
  • a protocol session (e.g. SMPP) has been open or closed
  • a KeepAlive has been sent or received
  • Ping (periodical generation of a trap in fixed intervals)

The configuration of the SNMP traps will be done in the file sendxms.cfg in the chapter [SNMP]. If in this file a destination address/port has been defined all of these listed traps will be generated by default. But each kind of trap can be manually disabled by use of a corresponding parameter (e.g.: KeepaliveTrap=false). You can also define a Community to use and the interval between two ping traps (default is 60 seconds).

The traps generated by SendXMS may contain the following information:

  • the PID (ProcessID)
  • the actual time/date (GMT)
  • the name of the used provider definition
  • the used device

The corresponding MIB file (bai.mib) can be found within the subdirectory (of the installation directory) samples.

Userexit

With the parameter -u you can specify an userexit. This is a function within a shared object/DLL (recommended), an external program or batch/script file, which will always be called by SendXMS when a message has been sent or received, a message couldn't be sent (only if running in server mode), a connection has been opened or closed, .... With such an userexit you can for example integrate a database system, a network managemant system (for example using Net-SNMP), a billing system or something else.

If the userexit is an external program (an executable or a batch/script file) the userexit will be called with one single parameter. This parameter speciffies the cause, why the userexit has been called and will have one of the following values:

1 message successfully sent
2 message successfully received
3 message status (DLR) received
4 message deleted
8 MMS Notification Indication received
98 connection started
99 connection closed
100 program (re-)initialized
-1 message couldn't be sent
-2 hardware problem

Additionally the userexit can read the content of complete spool file via stdin (a pipe). The format of such a spool file is described in the chapter Server mode. The content of this format may be easily interpreted and contains all available information which can be used within the userexit in any kind.

The userexit may not make any output to stdout (also a pipe). If output is required you have to use stderr for that. A userexit should always terminate as sson as possible to avoid timeout problems in the connection to a SMSC. The return code of the userexit should be 0 to terminate the transaction correctly. If any value not equal 0 is returned the transaction will be aborted (a received message will not be saved and will not be deleted from the SMSC/MMSC). A return code < 0 will be translated into a default (protocol dependend) error code. A return code > 0 and ;lt; 256 will be interpreted as a UCP error code and will be translated into a corresponding protocol dependend error code. A return code > 255 will be interpreted as a protocol specific return code and this code minus 255 will be submitted to the communication partner.

The userexit can also be a (thread safe) function within a DLL or a so-library (shared object). For that you have to separate the name of the DLL/so-library from the name of the function by a masterspace (@) (-u<dll>@<function>; for a Java userexit -ujava@<class>@<function>). Such an userexit will not get the content of the spool file via a pipe but directly as a second calling parameter (as a string). The third parameter will specify the length of that string. The content of the spool file may not be changed. If changes are required these changes have to be returned (only key-value of the changed parameter) using the fourth parameter

A prototype for an userexit function in a shared object is:


int UserExit (int cause, char *xms, int xmsLen, char *changedXms);

Using Windows the function should be defined like:


Borland compiler:    int __stdcall __declspec(dllexport) UserExit (...)
MS-Compiler: extern "C" int __declspec(dllexport) __stdcall UserExit (...)

/* The MS compiler decorates the function. This results in using _UserExit@<n> to call this function (or using a def file which exports the function with a correct name). */

The Samples subdirectory contains some examples for a simple Userexit and also for a small programm to extract the attachments of a received MMS.

VXMSC-Edition

With the VXMSC-Edition it is possible to emulate a virtual SMSC/MMSC. At the moment the protocols UCP, SMPP, CIMD, OIS or TAP over TCP/IP are supported for that. Using for example a CISCO router it is also possible to use X.25, FrameRelay, ... The supported functionality is identical to that supported by the Professional-Edition. Using the VXMSC-Edition it is of course also possible to connect to a real SMSC/MMSC as a client (SME).

Incoming requests are spooled (RECEIVEDIR) by default as with all other editions, too. The required logic of the virtual XMSC (for example the functionality of a gateway) has to be implemented using an external program or (better) using an userexit. For the userexit (see Userexit) the following additionals cause codes are available:

6 message has been delivered
7 DeliverNotification has been delivered
129 SubmitRequest has been received (message should be submitted)
130 StatusReportRequest has been received (status report will be requested)
131 DeleteRequest has been received (existing SubmitRequest should be deleted)
133 StartSessionRequest has been received
134 StopSessionRequest has been received

For incoming SubmitRequests there is also the MsgId, which has been assigned by the VXMSC-Edition, specified in the variable localId.

When the userexit is called because of a connection has been opend or closed or a session has been started or stopped the fields adC and oAdC contain the IP address and port number (local and remote).

For a StartSessionRequest (UCP function 60, SMPP bind operation or CIMD function 1) the UserId of the SME will be assigned to the field localId and the password to addCodes.

Using SMPP the field addInfo contains also the value TRANSMITTER, RECEIVER or TRANSCEIVER, depending on the BIND request the SME has sent. The SME has to use the SYSTEMTYPE=SendXMS.

Using MM7/EAIF the URI the client requests has to use the format /SendXMS/<provider> (<provider> is the name of the used (by the VXMSC) provider definition). For incoming MM7/EAIF requests addInfo contains the VASPID and addCodes the VASID.

If the StartSessionRequest should be rejected the userexit has to return -1.

To accept incoming connections as a VXMSC you just have to specify the parameter Detach=AcceptVXMSC in the corresponding provider definition. This will cause SendXMS to listen on the given address(es)/port(s) for incoming connections and if applicable to start a VXMSC session. Alternatively incoming connectiosn can be accepted using tools like inetd or xinetd. This (inetd) will be configured in the file /etc/inetd.conf (and /etc/services) like:


vxmscd     stream     tcp     nowait     root       /usr/local/sendxms/sendxms /usr/local/sendxms/sendxms -pTEST -aRECEIVE -Q0 --HANDLE=-1

ATTENTION: in most cases it would be better to call a script from within inetd and the script has to call the above given command. In case that you are using any additional parameter specifying a file (userexit, .cfg filename, ...) you should use an absolute path.

Of course the specified provider TEST has to be defined in sendxms.pro with protocol UCP[51], SMPP, CIMD, OIS or TAP (do not specify DETACH).

To enable the VXMSC to deliver messages to a client application the messages have to be either spooled (using the command line) with the option -aDELIVER or you have to put the line ACTION=DELIVER into the generated spool files.

Deferred sending and validity period

SendXMS offers the possibility to send messages to a later time. You have to specify that time with a command line parameter (-S).

Another possibility is to send the message now, but to specify with the parameter -D the time at which the service computer should deliver the message.

With the parameter -V a validity period can be specified. If this parameter is specified, the message will be deleted if it couldn't be delivered within the specified period.

Each parameter has either to be specified as an offset to the actual time (seconds prefixed with a plus sign, e.g. -S+3600) or as an absolute time/date value (YYYYMMDDhhmmss (hh = hour, mm = minute, ss = second, DD = day, MM = month, YYYY = year), e.g. -V20080507170000)). These parameters are not supported by all protocols/providers.

Choosing a desired function

Additionally to sending messages SendXMS is also able to query the status of messages, to delete messages and to receive messages. This functionality depends on the used protocol (UCP, TAP, GSM, ...) and on the used provider. In most cases these functions are only available for cellular networks (GSM, TDMA, CDMA). It is also required that the used phone line supports CLI (Calling Line Identification).

You choose the desired function on the command line by adding the parameter -a<action>. If the parameter isn't specified the value for <action> will be set to SEND. Otherwise you can select between SEND, RECEICE, QUERY, DELETE and CHGPWD which have the following meanings:

SEND to send a message
QUERY to query the status of a former transmitted message
DELETE to delete a former transmitted but not already delivered message
RECEIVE to receive messages and/or notifications (DLRs) AND (in server mode) to send messages
CHGPWD to change the session password (UCP function 60)
CHGPWD to remove old files/messages from the spool directories (SpoolDir, ReceiveDir, SentDir, UnsentDir, StatisticDir, LocalIdDir, TmpDir). By default (without additional parameters) all files/messages older then 5 days will be removed. Using the parameter -q the count of days can be changed.
CLEANto delete old files from the spool directories (SpoolDir, ReceiveDir, SentDir, UnsentDir, StatisticDir, LocalIdDir, TmpDir). By default all files elder then 5 days will be deleted. Using the parameter -q the count of days can be changed. ATTENTION: a wrong configuration may result in an erased disk!

In every case the phone number of the recipient has to be specified (at least for the german provider D1 with the format 49171... (to query the status or to delete a message)). To delete a message you have also to enter the identification number/timestamp of the message (will be shown after the message has been transmitted). You can find some examples in the chapter Calling syntax.

To receive messages via fixedline SMS (or to receive UUS messages) one instance of SendXMS has to wait permanently for incoming calls from the SMS gateway. This instance should be started with the following command:
sendxms -p<provider> -aReceive
<provider> specifies the name of the corresponding provider definition (in sendxms.pro) of the used fixedline SMS Gateway. The started instance waits for and accepts incoming calls from any number defined in the provider definition. All other calls (from any other number) are ignored. If the messages should be received using the server mode of SendXMS it it enough to add the parameter Detach=Receive to the provider definition.

To receive MMS via MM7 or EAIF you have to give a port address to your MMSC provider on which SendXMS waits for incoming messages. This port has to be defined in an own provider definition sendxms.pro. Additionally you have to define the parameters Detach=AcceptXME, UserId=, Password= und URI=/SendXMS/<provider>.

Calling syntax

SendXMS will be executed as follows (in 95% just with 'sendxms <phone> <sms>'):

sendxms [options] {<phoneNo> | <alias> | -g<groupFile>} [{<message> | -f<msgFile>}]

options are (case sensitive; do not specify any delimiters between an option selector and an option value (e.g.: -aSend but not -a Send)):

-a<action> specifies the requested action (SEND, RECEIVE, QUERY, DELETE or CHGPWD)
-b<pbkFile> specifies the phone book file (sendxms.pbk)
-c<cfgFile> specifies the configuration file (sendxms.cfg)
-C<msgClass> message Class (SMS, EMS: 0-3; MMS: 128-131)
-d<device> preselect a specific device
-D<deliver time> specifies the time when the message should be delivered (from the service computer)
-f<msgFile> specifies the name of a file which contents will be send as the message
-F Status Report Request
-g<groupFile> specifies the name of a group file with recipient numbers
-G<msgId> specifies the MsgId which should be deleted or for which a status report should be queried
-h shows the help
-H shows the version of SendXMS
-i installs SendXMS (server mode) as a service (Windows only; in case that you are using any additional parameter specifying a file (userexit, .cfg filename, ...) name you should use an absolute path
-I<priority> specifies the priority of a message (0 (low) - 3 (high))
-l<spool file name> specifie the name of a spool file (including path), which should be processed/send (use '-' to read spool file from stdin)
-m<MSN> specifies the (outgoing) MSN to use (CAPI 2.0 only)
-M<SMS> specifies the message to send (required if the message starts with a '-')
-n start SendXMS standalone (even if there is a server running)
-N<n> split the specified message in up to <n> SMS (default: 1)
-o<local ID> sets the originating userid or a local messageId
-O<originatingAddress> sets the originating address of the message which will be shown to the recipient (only with Professional-Edition and if supported by the provider/device)
-p<provider> specifies the provider for the corresponding phone number
-P<pidFileName> specifies the pid file name to use (default is sendxms.pid)
-q<n> start SendXMS as a server and check queue every <n> seconds;
using this parameter together with -aCLEAN <n> will specify the minimal age (count of days) of files/message to be removed
-Q<n> start SendXMS as a VXMSC and check queue every <n> seconds
-r<proFile> specifies the provider definition file (sendxms.pro)
-R Reply Path Request (see GSM 03.40)
-s spool messages (even if there is no server running)
-S<start time> specifies the time when the message should be sent (from the local computer)
-u<userexit> specifies a shored object, a program or a batch/script file which will be launched when a message as been sent or received
-U<userdataheader/subject> for SMS and EMS: hex coded UserDataHeader (see GSM 03.40) without length; only that part of the UDH which is repeated in each segment of a long message
for MMS: subject
-v verbose, shows the communication with the device on the screen
-V<validity period> specifies the period until the message should be valid
-x uninstalls the service SendXMS (Windows only)
--ChargedParty=<cp> indication which party should be charged for the MMS (None, Sender, recipient, Both, ThirdParty
--ChargedPartyID=<cp> specifies the address of a third party which is expected to pay for the MMS
--DCS=<dcs> specifies the DataCodingScheme to use (see GSM 03.40; do not use with -Z or -C)
--Distribution=<di> specifies the DistributionIndicator (true or false; only MMS)
--MessagingMode=<mm> specifies the messaging mode (SMPP 3.4, 0-3) or the parameter SingleShot (UCP 4.0, 0-1)
--PID=<pid> specifies the ProtocolIdentifier to use (see GSM 03.40; can be used for replacing messages)
--ReplaceIfPresent=1 specifies that an old message to the same destination should be replaced (nur SMPP)
--ServiceCode=<sc> specifies the ServiceCode for the MMS
--ServiceDesc=<sd> specifies the service description to use (0-99; only CIMD)
--ServiceType=<st> indicates the service_type associated with the message (only SMPP)
--TariffClass=<tc> specifies the tariff class (CIMD, 0-99) or billingIdentifier (UCP 4.0) to use
--UssdServiceCode=<sc> specifies an USSD Service Code (SMPP, CIMD and UAP; 0-255)
-z<char encoding> specifies the character encoding used for the given message (either a wellknown single byte charset (like iso-8859-1), utf-8, utf-16 or hex (for hex coded message))
-Z<data coding> specifies the data coding of the outgoing message (GSM (7 bit; default), binary (8 bit) or ucs2/utf16)

Ex.: sendxms 0123456789 "I am testing SendXMS"

You have to specify at least one parameter - the phone number (without blanks; using SMPP or OIS the number (and the originating address (-O)) can be specified in the form <ton>:<npi>:<phone>) of the recipient or an alias (from the phone book). Alternatively the parameter -g can be used to specify the name of a file which contains multiple phone numbers. With such a file it is possible to send one messages to multiple recipients. The specified file must have the following format:


[<provider1>]
PHONE=<number1>
PHONE=<number2>
PHONE=<number3>
PHONE=<alias1>
PHONE=<alias2>

[<provider2>]
PHONE=<number4>

Enclosed in brackets ([]) you have to specify providers (which are defined in sendxms.pro), followed by multiple lines with phone numbers of recipients. Every line contains a phone number (PHONE=...) of a recipient (number or alias), which belongs to the corresponding provider and to which the message should be send in one connection. In the above example the message will be send to 5 recipients of <provider1> using the same connection. The message will also be send to one recipient of <provider2>.

Using SMPP as the transfer protocol it is also possible to send a message to a distribution list which is managed on the SMSC. In this case the name of this list has to be specified in the form 999:0:<distribution list name> (instead of a recipients phone number).

The second parameter is the message, enclosed by ' (ATTENTION: depending on the shell you are using some characters are substituted by the shell (for example '!') or you have to enclose the message by " instead of '). If you specify the message on the command line the message may not start with a minus (in that case the message has to be specified with the command line parameter -M). Alternatively you can specify the message by redirecting it from a file (< msgFile) or with the Parameter -f<msgFile>, where <msgFile> is the name of the file that will be send (at least the first n characters). If you specify only one parameter on the command line (the recipient), the message will be read from the console. If you want to send a message to a provider, which can't be identified by the predial code of the recipients phone number you have to specify the corresponding provider (as defined in sendxms.pro) with the parameter -p<provider>. For Example: you want to send a message to a Cityruf-pager. SendXMS can't recognise the provider (Cityruf), because the number has no predial code. That's why you have to specify -pCityruf.

Binary messages have to be entered hex coded. For every binary character you have to enter two characters (0-9 and A-F). The message "ABC" is hex coded "414243". For ringing tones or operator logos you have also to specify an hex coded UserDataHeader (without length) using the parameter -U. For a ringing tone you have for example to specify -U050415811581 (see GSM 03.40 and Narrowband Sockets Specification (Intel, Nokia)). Instead of the hex coded UserDataHeader you can also use one of these predefined values -URingTone, -UOperatorLogo, -UGroupLogo, -UPicture, -UvCard, -UvCalendar and -UWapOTA (if the receiver supports the Smart Messaging Specification).

To send EMS messages, the EMS specific UDH part (the one which is not repeated in every segment of a long message) has to be specified in the message text at the corresponding position within the tags <UDH>...</UDH>. If this UDH part contains any position information this will be ignored and recalculated by SendXMS. The easiest way to generate such messages is to use XMSConv.

If you start SendXMS with the parameter -q<n> SendXMS works as a server and checks every <n> seconds the spool directory (if no value for <n> is specified this means to check only one time and terminate). If there are spooled messages they will be sent with a minimum number of connections. If there are spooled messages they will be sent with a minimum number of connections. If there runs a server every new instance will be started in spool mode. This can be manipulated with the parameters -s (always spool) and -n (never spool).

The -z parameter specifies which charset is used tp specify the message. By default SendXMS uses the system charset. If the message is not entered in the standard charset then you have to specify this parameter.

Examples:

sendxms 0123456789 test
The message "test" will be sent to the specified number.

sendxms 0123456789 "<UDH>0A03001F40</UDH>This is a formatted EMS message"
The formatted message (underlined) will be sent to the specified number.

sendxms -pD1 -F 0123456789 "This is a test message"
The message "This is a test message" will be sent to the specified number using the provider D1. After transmitting the message the program waits for a confirmation which will indicate whether the message has been delivered to the recipient or has been stored on the service computer.

sendxms 0123456789 -fmsg.txt
sendxms 0123456789 -dModem1 < msg.txt
In both cases the content of the file msg.txt will be sent to the specified number. In the second case the device Modem1 (parameter NAME in chapter [Device] ins sendxms.cfg) is preselected.

sendxms -ggroup "Alert for all"
The message "Alert for all" will be sent to all numbers which are listed in the file group. The format of group file is:

  
   [D1]
PHONE=0170...
PHONE=0171...

[D2]
PHONE=0172...

[EPLUS]
PHONE=0177...
PHONE=0177...

sendxms -pVOICE 07246942484 < voice.dat
sendxms -pVOICE 07246942484 -fvoice.dat
A voice message (voice modem, VoIP or CAPI 2.0) will be send to the specified number. The file voice.dat has to contain the voice message in the native format for the used device.

sendxms -pUUS 1234567 "This is a test message"
The message "This is a test message" will be submitted to the phone number 1234567 via UUS (only with CAPI 2.0). This will only work if the service UUS is supported by the network provider and by both communication partners. The message will be submitted in the D-channel without any fee.

sendxms -pVOICE -aRECEIVE 07246942484 -fvoice.dat
The specified number will be called and a voice message will be stored in the native device format to the file voice.dat.

sendxms -aQUERY 0123456789 -G1141863480
The status of the message 1141863480 (this number has been shown after transmitting a message) for the phone number 0123456789 will be queried.

sendxms -aDELETE 0123456789 -G1141863480
The message 1141863480 for the phone number 0123456789 will be deleted (if the message has not already been delivered).

sendxms -q5
Starts SendXMS in server mode with a queue delay of 5 seconds.

sendxms -q5 -aRECEIVE
Starts SendXMS in server mode with a queue delay of 5 seconds. Additionally all defined GSM devices and providers for which the parameter AUTOALERT or AUTOCONNECT is defined are checked for incoming messages.

sendxms -aCHGPWD -pD1_X31 password
A connection to the provider will be established to change the password (UCP function 60).

Integration into email systems

Following .forward file should demonstrate how easy SendXMS can be integrated into an email system (Unix). You only have to generate a .forward file in your homedir with the following content:


\wobo, "| /usr/local/sendxms/forward.sms"

With this file all incoming emails will be forwarded to the userid wobo (here you have to enter your own userid, so that you have the same normal access to the emails as you will have without the .forward file) and the follwing script forward.sms will be called. This script sends a message (containing the originator and the subject of the email) to the specified phone number by SendXMS.


#! /bin/sh
egrep -ih '^From:|^Subject:' | /usr/local/sendxms/sendxms 0123456789 > /dev/null
exit 0

After a successfull SendXMS installation you can find an examaple Perl script in the samples sub directory which will forward (using a .forward file) all emails for a specific email account to the phone number specified in the Subject header. This variant of the script will always send the first 500 characters of mail with Content-Type text/plain and will automatically take care about the used character encoding.

An direct integration in sendmail is very easy, too. For this you have only to define in sendmail.cf a MTA (for example Msendxms, ...) and in 'Rule Set 0' a rule which defines under which conditions SendXMS or a script file - one like forward.sms - should be called.

Using Windows it is possible to be informed by SendXMS about incoming emails with the freeware product POSTIE or with the shareware mailer The Bat!.

Using the tool mail2sms you can convert a complete MIME mail into tiny text before sending it as a SMS.

Integration into WWW servers

SendXMS can easily be integrated into WWW servers. SendXMS will automatically recognise whether it is invoked from a http server and will handle some special actions in accordance to the environment. As an example for an integration into a http server you can use the Perl script (Perl5) sendxms.cgi. To install that example you only have to copy the files sendxms.cgi and sendxms.ini to the cgi-bin directory of the http server and to adapt the file sendxms.ini (path, language and configuration files). Maybe you have also have to change the path to your Perl interpreter in the first line of sendxms.cgi. Please remember that the userid under which the http-server is running requires access rights to SendXMS.

The script will be invoked by entering the following into the Address field of your browser:
http://<server>/cgi-bin/sendxms.cgi
or by making such a link in your own pages.

Graphical user interface

One optional part of SendXMS is a graphical user interface implemented in Java (requires Java Runtime Environment (JRE) (http://www.java.com/download/). To call that user interface you can use the included script or batch files (xmsgui). After the starting the user interface for the first time the most required input fields are displayed. Selecting the menu option "Settings/Expert mode" you can get more options. After entering a phone number, a message text and selecting the button 'Send' SendXMS will be launched and the output is displayed in an automatically selected page. Every sent message will be stored in a journal which you can use (journals context menu) to query a status report for a message or to delete a message.

Voice Over IP (VoIP)

Due to the increasing conversion from ISDN to VoIP connections, the sending of SMS via telephone connections is also affected. Using a VoIP connection SMS must be sent using 'SMS for fixed line' provider (in Germany, for example, Telekom or Anny Way). Using digital SMS protocols (TAP, UCP, ...) is (currently) no more possible via VoIP connections. But Voice and DTMF messages can still be used via VoIP.

In order to use a VoIP connection, you have to configure it as a device in the sendxms.cfg file. Therefor you have to configure a SIP server with the usual parameters. In general, the simplest method is to use a local (in the same subnet) existing PBX as a SIP proxy. Iin case that the (VoIP-) PBX system has an internal ISDN bus available, CAPI can also still be used to communicate with the PBX. In the case of a locally existing (and already configured) telephone system, no further measures are required otherwise.

Using an external SIP server, the firewall and/or the router may also need to be configured.

If a router with NAT (but without ALG) is used you have also to add a STUN server in the device definition (in sendxms.cfg) so that the external IP address can be determined. The router must be configured that way that the RTP/RTCP ports negotiated between SendXMS and the SIP server will be forwarded to SendXMS. In the provider definition (in sendxms.cfg) a specific port range can be forced (see also RtpPorts).

Beispiel (VoIP):

sendxms.cfg
[Device]
DeviceType=VOIP
Address=10.11.12.13 5060
User=<userid>
Password=<password>
;LineType=TCP
;RtpPorts=10000-10050
;SipAlwaysRegister=True
;DtmfTransfer=Rtp
;StunServer=stun1.l.google.com 19302
;StunRfc=3489

X.25/X.31

The SendXMS-Professional-Edition is also able to transmit messages via X.25 or X.31 (X.25 over ISDN). To use X.25 a TCP-X.25 bridge (a RFC1086 compliant or CISCO like) has to be used. To use X.31 you require a X.31 capable device and the special service X.31 from your telephone company (they will assign you a TEI). With this you only have to define a special provider in sendxms.pro and a device in sendxms.cfg (see below). All other handling is exactly as it is with a modem connection.

Example (X.25):

sendxms.cfg sendxms.pro
[Device]
DeviceType=RFC1086
LineType=X.25
Device=ex25.dll
ConnectTimeout=5
;PacketLen=2048
;WindowSize=7
OriginatingAddress=<local address>
[D1_X25]
Phone=012345....
LineType=X.25
;KeepAlive=300 ; for permanent connection
;Detach=ALL ; for permanent connection
;WindowSize=10 ; for asynchronous communication (windowing)
Protocol=UCP[51]
UseOtoA=true
Prefix=+49160|+49160
Prefix=+49170|+49170
Prefix=+49171|+49171
Prefix=+49175|+49175
MsgType=ALPHANUMERIC
MsgLen=160
UseUCP60=true ; only if function 60 is required
UCP60Password=<password> ; if the password option is used
UserId=<large account>

Example (X.31):

sendxms.cfg sendxms.pro
[Device]
DeviceType=CAPI 2.0
LineType=X.31
Device=capi2032.dll
ConnectTimeout=5
UseDChannel=true
TEI=1
X31Channels=0,0,1,1,0,0
MsnOut=25
[D1_X31]
Phone=012345....
LineType=X.31
Protocol=UCP[51]
UseOtoA=true
Prefix=+49160|+49160
Prefix=+49170|+49170
Prefix=+49171|+49171
Prefix=+49175|+49175
MsgType=ALPHANUMERIC
MsgLen=160
UseUCP60=true ; only if function 60 is required
UCP60Password=<password> ; if the password option is used
UserId=<large account>
;WindowSizw=10 ; for asynchronous communication (windowing)

TCP/IP, SSL

The SendXMS-Professional-Edition is also able to transmit messages via TCP/IP. To use TCP/IP connections you have to install and configure TCP/IP on your computer and to define a special provider in sendxms.pro with LINETYP=TCP (see below). You do not need to define any device to use TCP/IP connections. All other handling is exactly as it is with a modem connection. Incase of an installed OpenSSL package you can also use SSL connections. For that you just have to specify instead LineType=SSL of LineType=TCP. For more configuration settings for SSL connections see also Configuration

Example:

sendxms.pro
[D1_TCP]
Address=127.1.1.1 12345
LineType=TCP
;LineType=SSL ; for SSL connection
;KeepAlive=300 ; for permanent connection
;Detach=ALL ; for permanent connection
;WindowSize=10 ; for asynchronous communication (windowing)
Protocol=UCP[51]
UseOtoA=true
Prefix=+49160|+49160
Prefix=+49170|+49170
Prefix=+49171|+49171
Prefix=+49175|+49175
MsgType=ALPHANUMERIC
MsgLen=160
UseUCP60=true ; only if function 60 is required
UCP60Password=<password> ; if the password option is used
UserId=<large account>

PPP

In some cases (for example for Fixed network MMS) it is required to use a PPP connection. For this SendXMS is using functionallity of the used operating system (pppd and on Windows RasDial). Although this will happen transparently for the user we want to notice some special things.

Opening a PPP connection a default route will be set to the created PPP interface. This means that all IP traffic (of all applications and all useres) will be routed by default over that PPP interface as long as the connection is open. Because this is not very reasonable this can be suppressed by defining the parameter NoDefaultRoute=true (in the chapter [PPP] in the .cfg file). if this parameter is used SendXMS will try to set a required (and not more) route itself. But for this it is required that SendXMS will be used with privileged rights (it has to be run by root or (on Windows) by an administrator). Using Unix/Linux you also have to notice that pppd can only be used if SendXMS is running in the root account or if ths s-Bit is set for pppd.

Return codes

SendXMS returns the count of successfully processed messages (return code 0 means that SendXMS terminated normally but was not abel to send or receive any messages). If the return code is negative then this is an error code, which is described in the file sendxms.err. This feature is only available in the registered version. Be aware that some Unix shells return the return code as an 'unsigned byte'. Therefore the return code is in the range between 0 and 255, where all values above 127 are error codes.

If the parameter RCZEROIFOK=true is specified in sendxms.cfg SendXMS returns 0 if one ore more messages have been submitted. This is useful for usage within (for example) an email system.

SMS over HTTP

Although there is no standard available for SMS over HTTP (except OneAPI) many service providers are offering such services. Because of the missing standard every provider is using an own syntax, which are often similar but nevertheless not compatible. Thatswhy we've also decided to introduce our own syntax but with the difference that ours is configurable and thatswhy usable with a lot of proprietary services. But if possible we recommend to use any of the standard SMS protocols and noz to use such a service. Using our SMS over HTTP implementation it is (at the moment) only possible to send (and not to receive) messages. Obwohl (nach unserem Wissen) für den Versand von SMS über HTTP kein Standardprotokoll exist

If it is not possible to use any standard SMS protocol you just have to define a provider definition in your .pro file with Protocol=HTTP and LineType=TCP. Additionally you have to specify a URI for the used service with URI=... angeben. Using such a provider definition SendXMS will connect to the given address/port (Address=) and will use a GET request for sending a message. If your service provider requires a POST request this can be specified by using Protocol=HTTP[POST]. In this case a POST request with the Content-Type application/x-www-form-urlencoded will be sent. The character encodingwill always be UTF-8.

The several data fields for the SMS (recipient number, sending number, message text, ...) will be named by default in the same way as in a SendXMS spool file (see also Server mode). Because the chance that the provider is using the same parameter names as SendXMS is not very high the used names can adapted by using MapUserValue=.

Because the format of a response for SMS over HTTP is also not standardized the parameters OkFilter, ErrorFilter and MsgIdFilter can be used to define filters for identifying whether sending the message has been successfull or an error occured and for extracting the messageId (the service provider assigned to the message) out of the response (see also Phone number format filters).

The following are two examples for a provider definition for SMS over HTTP:


[smstrade]
ProtocolTimeout=5
Address=gateway.smstrade.de:80
LineType=TCP
Protocol=HTTP
URI=/
MsgLen=160
Password=xxx
TariffClass=basic
MapUserValue=XMS|message
MapUserValue=Password|key
MapUserValue=Phone|to
MapUserValue=OriginatingAddress|from
MapUserValue=ValidityPeriod|/dev/null
MapUserValue=DeferredDelivery|/dev/null
MapUserValue=TariffClass|route
NoHttpAuthentication=true
AdcOutFilter=/^(\+|00)([0-9]*)/\2/
AdcOutFilter=/^(0)([0-9]*)/49\2/
oAdcOutFilter=/^(\+|00)([0-9]*)/\2/
oAdcOutFilter=/^(0)([0-9]*)/49\2/
okFilter=/^100$/\1/


[Twitter]
ProtocolTimeout=5
Address=twitter.com 80
URI=/statuses/update.xml
LineType=TCP
Protocol=HTTP [POST]
MsgLen=140
UserId=xyz
Password=xyz
MapUserValue=XMS|status
MapUserValue=Phone|/dev/null
MapUserValue=OriginatingAddress|/dev/null
MapUserValue=DCS|/dev/null
MapUserValue=StatusReportRequest|/dev/null
MapUserValue=TariffClass|/dev/null
MapUserValue=ValidityPeriod|/dev/null
MapUserValue=DeferredDelivery|/dev/null
MapUserValue=UDH|/dev/null
ErrorFilter=#(.*)<error>(.*)</error>(.*)#\2#
OkFilter=#(.*)<status>(.*)</status>(.*)#\2#
MsgIdFilter=#<id>([0-9,A-F]*)</id>#\1#

MMS, Ringtones, Logos, WAP Push (OMA Provisioning, OMA DRM, OMA EMN, Bookmarks, MMS Notifications, ...)

To send MMS messages (MIME file (the ContentType has to be specified within the first line) with BASE64 encoded parts) or (in case of SMS/EMS) formatted text messages, WAP Push messages (Bookmarks, Browser Settings, SyncML Settings, ...), MMS notifications, ringing tones, operator logos, group graphics or picture messages (concerning to the Nokia Smart Messaging Specification) the data have to be entered in hex format. Because such data is often available in any other format the data has to be converted what can be done with the tool XMSConv (only in registered version). With this you have the ability to convert .bmp, .png, .gif, .mng, .htm, .xml, .smil, .imy, .mid, .rtx, .rtttl files. Only with EMS 5.x a logo may be coloured. In all other cases a logo/bitmaps have to be coded in black/white. Nokia logos must have a size of:

  • 72 x 14 (operator logo or group logo (CLI))
  • 78 x 21 (operator logo large)
  • 72 x 28 (picture message or screen saver)

EMS pictures must have a size of:

  • 8 x 8 (picture small)
  • 16 x 16 (picture large)
  • n x m, with (n, m > 0) and (for EMS4 (not EMS5): n * m / 8 <= 128) (picture variable)

An EMS animation consists of 4 pictures with a size of 8 x 8 or 16 x 16. A Nokia animation consists of up to 16 logos with one of the above sizes.

Using the Siemens OTA Download Service a bitmap or a midi file will be loaded onto the phone. The format depends on the downloaded phone model (e.g. a screen saver for a S45 should have a size of 101x64).

For WAP Push messages additional specific data (have a look to the WAP specifications) can be specified. For example for the WSP header fields PushFlag or X-Wap-Initiator-Uri you can define default values in the cfg file (chapter [XMSConv]) which can be overridden using the command line options --PushFlag or --InitiatorUri. For WAP/OMA Client Provisioning documents you can also select one of 4 security mechanisms (e.g.: --SEC=0 --IMSI=123456789012345; this means that the messages will be only valid on the phone with thespecified IMSI):

Here are some samples how to run it:

xmsconv -f<mms.smil> -FMMS -W<phone>
sends a MMS.

xmsconv -f<picture.gif> -FSMIL -M"Just a picture" -W<phone>
sends a MMS and creates a simple SMIL file (presentation) for that.

xmsconv -f<mms.smil> -FMMS -W<phone> -W-pt-com_mms
sends a MMS via the MMS-gateway of Deutsche Telekom.

xmsconv -f<logo.bmp> -UGROUPLOGO -FNOKIA -W<phone>
sends a group graphic in Nokia format.

xmsconv -f<logo.bmo> -m<mcc> -n<mnc> -UOPERATORLOGO -W<phone>
sends an operator logo in Nokia format.

xmsconv -f<logo.png> -UOPERATORLOGO -m262 -n1 -UOPERATORLOGO -W<phone>
sends an operator logo in Nokia format. Because the original graphic is a group graphic the type of graphic and the network code of the operator is explicitly specified on the command line.

xmsconv -f<picture.bmp> -M"this is a picture message" -UPICTURE -W-V+3600 -W<phone>
sends a picture message with the text "this is a picture message".

xmsconv -f<ringtone.rtx> -URINGTONE -FMOTOROLA -W<phone>
sends a ringtone in Motorola format.

xmsconv -f<bitmap.bmp> -FSIEMENS -W<phone>
sends a bitmap file via Siemens OTA download.

xmsconv -f<melody.mid> -FSIEMENS -W<phone>
sends a midi file via Siemens OTA download.

xmsconv -f<push.xml> -W<phone>
or
xmsconv -f<push.xml> -W<phone> --WapInitiatorUri=http://www.sendxms.com/ --WapPushFlag=3 --SEC=1 --USERPIN=1234
sends a WAP Push message. In the second example the WSP parameters X-Wap-Initiator-Uri (on some devices this will be shown as the originator of the message) and PushFlag will also be used. The file has to conform to the corresponding Document Type Definition (DTD), e.g.:


<?xml version="1.0"?>
<!DOCTYPE wap-provisioningdoc PUBLIC "-//WAPFORUM//DTD PROV 1.0//EN" "http://www.wapforum.org/DTD/prov.dtd">
<wap-provisioningdoc version="1.0">
 <characteristic type="PXLOGICAL">
  <parm name="PROXY-ID" value="PROXY"/>
  <parm name="NAME" value="Proxy"/>
  <characteristic type="PORT">
   <parm name="PORTNBR" value="8080"/>
  </characteristic>
  <characteristic type="PXPHYSICAL">
   <parm name="PXADDR" value="13.22.45.55"/>
   <parm name="PXADDRTYPE" value="IPV4"/>
   <parm name="TO-NAPID" value="Browsing_CSD"/>
  </characteristic>
 </characteristic>
 <characteristic type="NAPDEF">
  <parm name="NAPID" value="Browsing_CSD"/>
  <parm name="BEARER" value="GSM-CSD"/>
  <parm name="NAME" value="Browsing CSD"/>
  <parm name="NAP-ADDRESS" value="+5555555555"/>
  <parm name="NAP-ADDRTYPE" value="E164"/>
  <parm name="CALLTYPE" value="ANALOG-MODEM"/>
  <parm name="LINKSPEED" value="9600"/>
  <characteristic type="NAPAUTHINFO">
   <parm name="AUTHTYPE" value="PAP"/>
   <parm name="AUTHNAME" value="name2"/>
   <parm name="AUTHSECRET" value="password2"/>
  </characteristic>
 </characteristic>
 <characteristic type="APPLICATION">
  <parm name="APPID" value="w2"/>
  <parm name="TO-PROXY" value="PROXY" />
  <characteristic type="RESOURCE">
   <parm name="NAME" value="Bookmark Name"/>
   <parm name="URI" value="http://wap.com"/>
   <parm name="STARTPAGE"/>
  </characteristic>
 </characteristic>
</wap-provisioningdoc>

or


<?xml version="1.0"?>
<!DOCTYPE CHARACTERISTIC-LIST SYSTEM "file://c:/settingspush/settings.dtd" >
<CHARACTERISTIC-LIST>
 <CHARACTERISTIC TYPE="ADDRESS">
  <PARM NAME="BEARER" VALUE="GSM/CSD"/>
  <PARM NAME="PROXY" VALUE="123.45.123.67"/>
  <PARM NAME="CSD_DIALSTRING" VALUE="+4583572"/>
  <PARM NAME="PPP_AUTHTYPE" VALUE="PAP"/>
  <PARM NAME="PPP_AUTHNAME" VALUE="wapuser"/>
  <PARM NAME="PPP_AUTHSERCRET" VALUE="wappassw"/>
  <PARM NAME="CSD_CALLTYPE" VALUE="ANALOGUE"/>
  <PARM NAME="CSD_CALLSPEED" VALUE="AUTO"/>
 </CHARACTERISTIC>
 <CHARACTERISTIC TYPE="URL" VALUE="http://wap.dk"/>
 <CHARACTERISTIC TYPE="NAME">
  <PARM NAME="NAME" VALUE="ABC Service"/>
 </CHARACTERISTIC>
 <CHARACTERISTIC TYPE="BOOKMARK">
   <PARM NAME="NAME" VALUE="Wap"/>
   <PARM NAME="URL" VALUE="http://wap.dk"/>
 </CHARACTERISTIC>
</CHARACTERISTIC-LIST>

or


<?xml version="1.0"?>
<!DOCTYPE CHARACTERISTIC-LIST SYSTEM "file://c:/settingspush/settings.dtd" >
<CHARACTERISTIC-LIST>
 <CHARACTERISTIC TYPE="BOOKMARK">
  <PARM NAME="NAME" VALUE="Wap"/>
  <PARM NAME="URL" VALUE="http://wap.dk"/>
 </CHARACTERISTIC>
</CHARACTERISTIC-LIST>

or


<?xml version="1.0"?>
<!DOCTYPE si PUBLIC "-//WAPFORUM//DTD SI 1.0//EN" "http://www.wapforum.org/DTD/si.dtd">
<si>
 <indication href="http://www.yxz.com/email/123/abc.wml" created="1999-06-25T15:23:15Z" si-expires="2010-06-30T00:00:00Z">You have 4 new emails</indication>
</si>

or


<?xml version="1.0"?>
<!DOCTYPE sl PUBLIC "-//WAPFORUM//DTD SL 1.0//EN" "http://www.wapforum.org/DTD/sl.dtd">
<sl href="http://www.yxz.com/email/123/abc.wml" action="execute-low"></sl>

or


<?xml version="1.0"?>
<!DOCTYPE SyncSettings>
<SyncSettings>
 <Version>1.0</Version>
 <HostAddr>http://www.syncserver.com/sync</HostAddr>
 <Port>8080</Port>
 <RemoteDB>
  <CTType>text/x-vcard</CTType>
  <CTVer>2.1</CTVer>
  <URI>./Contacts?CLASS&EQ;PRIVATE</URI>
  <Name>Private Contact DB</Name>
  <Auth>
   <AuthScheme>1</AuthScheme>
   <Username>james</Username>
   <Cred>cHdk</Cred> <!-- Base64 coded 'pwd' -->
  </Auth>
 </RemoteDB>
 <RemoteDB>
  <CTType>text/x-vcalendar</CTType>
  <CTVer>1.0</CTVer>
  <URI>./Calendar</URI>
  <Name>Calendar DB</Name>
 </RemoteDB>
 <Name>PIM Service</Name>
 <Auth>
  <AuthLevel>2</AuthLevel>
  <AuthScheme>1</AuthScheme>
  <Username>james</Username>
  <Cred>Ym9uZA==</Cred> <!-- Base64 coded 'bond' -->
 </Auth>
 <Auth>
  <AuthLevel>1</AuthLevel>
  <AuthScheme>1</AuthScheme>
  <Username>bond</Username>
  <Cred>Ym9uZA==</Cred> <!-- Base64 coded 'bond' -->
 </Auth>
 <ConRef>
  <ConType>1</ConType>
  <RefID>My AP</RefID>
 </ConRef>
</SyncSettings>
</SyncSettings>

oder


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE o-ex:rights PUBLIC "-//OMA//DTD DRMREL 1.0//EN" "http://www.oma.org/dtd/dr">
<o-ex:rights xmlns:o-ex="http://odrl.net/1.1/ODRL-EX" xmlns:o-dd="http://odrl.net/1.1/ODRL-DD" xmlns:ds="http://www.w3.org/2000/09/xmldsig#/">
 <o-ex:context>
  <o-dd:version>1.0</o-dd:version>
 </o-ex:context>
 <o-ex:agreement>
  <o-ex:asset>
   <o-ex:context>
    <o-dd:uid>cid:4567829547@foo.com</o-dd:uid>
   </o-ex:context>
   <ds:KeyInfo>
    <ds:KeyValue>vUEwR8LzEJoeiC+dgT1mgg==</ds:KeyValue>
   </ds:KeyInfo>
  </o-ex:asset>
  <o-ex:permission>
   <o-dd:play/>
  </o-ex:permission>
 </o-ex:agreement>
</o-ex:rights>

or


<?xml version="1.0"?>
<!DOCTYPE emn PUBLIC "-//OMA/DTD EMN 1.0//EN" "http://www.openmobilealliance.com/tech/DTD/emn.dtd">
<emn mailbox="mailat:user@wapforum.org" timestamp="2006-04-16T06:40:00Z"/>

xmsconv -f<mms.ind> -UWapPush -W<phone>
Versendet eine MMS-Notification-Indication (SMS) als WAP-Push (informiert ein MMS-Gerät über eine abzuholende Nachricht). Die Datei muss einen gültigen MMS Header enthalten, z.B.:

xmsconv -f<mms.ind> -UWapPush -W<phone>
Sends a MMS-notification-indication (SMS) as a WAP Push (informs a MMS device about a new message to download). The file has to contain a valid MMS header, e.g.:


X-Mms-Message-Type: m-notification-ind
X-Mms-Transaction-Id: abcdef
X-Mms-Version: 1.0
From: +123456789/TYPE=PLMN
Subject: one more mms
X-Mms-Message-Class: Personal
X-Mms-Message-Size: 1234
X-Mms-Expiry: 86000; type=relative
X-Mms-Content-Location: http://www.xyz.com/m1.mms

xmsconv -f<oma_dm.xml> -W<phone>
Sends an OMA (SyncML) Device Management Initiation Package (Package#0) as a WAP Push (informs a device to start a Device Management Session). The file has to be of a format like:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE SyncML-DM-Notification SYSTEM "http://www.syncml.org/docs/syncml_dm_ddf_v11_20020213.dtd">
<SyncML_DM_Notification xmlns='SYNCML:SYNCML1.1'>
 <SyncHdr>
  <VerProto>DM/1.1</VerProto>
  <UiMode>not-specified</UiMode>    <!-- not-specified, background, informative or user-interaction -->
  <Initiator>server</Initiator>     <!-- client or server -->
  <SessionID>1</SessionID>
  <ServerIdentifier>http://www.syncml.org/mgmt-server</ServerIdentifier>
  <Password>password</Password>
  <Nonce>nonce</Nonce>
  <VendorSpecific></VendorSpecific> <!-- only hex digits allowed -->
 </SyncHdr>
</SyncML_DM_Notification>

UCS-2

SendXMS is also able to send messages with UCS-2 encoding (multibyte). Because each character requires in this case two bytes the maximum message size is limited to 70 characters per GSM message. To send an UCS-2 message you have to specify the command line option -Zucs2 and you also should specify the character set of the given message (you have to specify the message in any single byte character set (like iso-8859-7) or in UTF-8; this character set is then automatically translated to UCS-2):

sendxms -zutf8 -Zucs2 0123456789 "bla bla bla..."

Mobile Number Portability (MNP)

SendXMS already supports MNP since many years. You just have to specify the correct provider (network) each time you generate a message or a spool file.

But because the user normaly does not know whether a recipients phone number has been ported or not SendXMS now also has the ability to retrieve this information automatically. How MNP works in different countries differs in each case. In the file sendxms.cfg you can define with MNP= a function within a dll or a shared object which will be called by SendXMS if required. The function will be called with two parameters for a porting identifier of the network to which the number belongs and the recipients phone number. If the number has been ported to a different network the function should set the identifier variable to the corresponding value and should return 0. If the number has not been ported (belongs still (or again) to the original network) the function should return a value not equal 0.

If the identifier variable has been set and the function has returned 0 SendXMS will search in the pro file (by default sendxms.pro) for a provider definition with a corresponding MNP= definition. If the function has returned any value not equal to 0 or the identifier variable has been left blank SendXMS will continue in the normal way and will search for a provider using the PREFIX values.

A prototype for an mnp function in a shared object is:


int Mnp (char *id, char *adC);

Using Windows the function should be defined like:


Borland-Compiler:    int __stdcall __declspec(dllexport) Mnp (...)

MS-Compiler: extern "C" int __declspec(dllexport) __stdcall Mnp (...)

/* The MS compiler decorates the function. This results in using _Mnp@<n> to call this function (or using a def file which exports the function with a correct name). */

Abbreviations

3GPP
3rd Generation Partnership Project
AdC
ADdress Codes
AIM
Application Interface Module
ALG
Application Layer Gateway
API
Application Programming Interface
APN
Access Point Name
BAI
Böcherer Angewandte Informatik (Böcherer Applied Computer Sience)
CAPI
Common-ISDN-API
CDMA
Code Division Multiple Access
CIMD
Computer Interface to Message Distribution
CSD
Circuit Switched Data
CSV
Comma Separated Values
DCS
Data Coding Scheme
DLL
Dynamic Link Library
DM
Device Management
DRM
Digital Rights Management
DTLS
Datagram Transport Layer Security
DTMF
Dual Tone Multiplexed Frequency
EMI
External Machine Interface
EMN
E-Mail Notification
EMS
Enhanced Messaging Service
ETSI
European Telecommunications Standard Institute
FDMA
Frequency Division Multiple Access
GPRS
General Packet Radio Service
GSM
Global System for Mobile Communication
GSMA
GSM Association
HSCSD
High Speed Circuit Switched Data
HTTP
HyperText Transfer Protocol
IM
Instant Messaging
IMEI
International Mobile Equipment Identification
IMSI
International Mobile Subscriber Identification
IP
Internet Protocol
IPv4
Internet Protocol version 4
IPv6
Internet Protocol version 6
ISDN
Integrated Services Digital Network
JNI
Java Native Interface
JSON
JavaScript Object Notation
JVM
Java Virtual Machine
MCC
Mobile Country Code
MIB
Management Information Base
MIME
Multipurpose Internet Mail Extensions
MMS
Multimedia Messaging Service
MNC
Mobile Network Code
MNP
Mobile Number Portability
MO
Mobile Originated
MSISDN
Mobile Station ISDN number
MSN
Multiple Subscribe Number
MT
Mobile Terminated
MWI
Message Waiting Indicator
NAT
Network Address Translation
NPI
Numbering Plan Identification
NTP
Network Time Protocol
OAdC
Originator ADdress Code
ODBC
Open DataBase Connectivity
OIS
Open Interface Specification
OMA
Open Mobile Alliance
OTA
Over The Air
PIN
Personal Identification number
PLMN
Public Land Mobile Network
PPP
Point to Point Protocol
QoS
Quality of Service
RTCP
RealTime Control Protocol
RTP
RealTime Transport Protocol
SCTP
Stream Control Transmisson Protocol
SDP
Session Description Protocol
SMPP
Short Message Peer to Peer
SIM
Subscriber Identity Module
SIP
Session Initiation Protocol
SME
Short Message Entity
SMIL
Synchronized Multimedia Integration Language
SMS
Short Message Service
SMSC
Short Message Service Center
SMTP
Simple Mail Transport Protocol
SNMP
Simple Network Managemnet Protocol
SNTP
Simple Network Time Protocol
SO
Shared Object
SRTP
Secure RealTime Transport Protocol
SSL
Secure Socket Layer
STUN
Session Traversal Utilities for NAT
TAP
Telocator Alphanumeric Protocol
TAPI
Telephony API
TCP
Transmission Control Protocol
TDMA
Time Division Multiple Access
TLS
Transport Layer Security
TON
Type Of Number
UAP
Ussd service Protocol
UAPROFILE
User Agent Profile
UCP
Universal Computer Protocol
UCS
Unicode Standard
UDP
User Datagram Protocol
UMTS
Universal Mobile Telecommunication System
URI
Uniform Resource Identifier
USIM
Universal-SIM
USSD
Unstructured Supplementary Services Center
UUS
User-User-Signalling
VSMSC
Virtual Short Message Service Center
WAP
Wireless Application Protocol
wobo
WOlfgang BOecherer
VOIP
Voice Over IP
VXMSC
Virtual eXtended Message Service Center
XME
eXtended Message Entity
XML
eXtensible Markup Language
XMS
eXtended Messaging Service
XMSC
eXtended Message Service Center

Where can I get the newest version?

You can always get the newest version from www.sendxms.com.

Problems/Questions

Please send an email including the following information to support@sendxms.com:

  • error-/problem-description
  • hardcopy of the screen (command line (with the additional option -v) and error message)
  • your sendxms.cfg
  • your sendxms.pro
  • used operating system
  • used version of SendXMS