|
Deutsch | English
SMS |
|
|
![[BAI]](/images/bai.white.gif)
![[Dot]](/images/dotw.gif)
![[Dot]](/images/dot.gif)
Manual
![[Valid XHTML 1.0!]](/images/vxhtml10.png){kind=small}
![[Valid CSS!]](/images/vcss.png){kind=small}
|
Home | Features | Manual | History | FAQ | Download | Order | References | Links | CLU | Imprint ![[HR]](/images/hr.gif){kind=small}
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 |
[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 721 9109550 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. This parameter has only sense if you send messages
to multiple recipients. Running in server mode this parameter is ignored.
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 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.
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 (GSM).
[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.
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]
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 funktion strftime.
See also Deferred sending and validity period.
[nur in der registrierten Version]
User=
Specifies an optional userid for use with Remote-CAPI (intern).
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 that 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 an ISDN-router for usage with a RemoteCAPI (BINTEC extensions).
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)
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 in your computer you specify here to which adapter
the definition belongs.
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 (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)
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.
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 or X.31). 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.
MsgDelay=<n>
Specifies a count of seconds (for example 0.2) to wait between sending two messages within one single connection
(normally not required).
MSN=24
Specifies the phone number of the ISDN adapter (if you are using CAPI 2.0). Here you have to enter
the number of the line to which the ISDN adapter is connected. Using a PBX this is the internal
number. 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 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,
and may not be set for Siemens E10, Siemens S10, Nokia DataCard, Nokia CardPhone or Nokia Data Suite.
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=2662
Using the RemoteCAPI (BINTEC extensions) this specifies the port on which a ISDN-router listens
for RemoteCAPI calls.
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).
RtsCts=true
Specifies to use the hardware flow control.
SetMsn=
Specifies an (AT-) command to set the MSN, CallingPartyNumber. If this command and a MSN 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.
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)
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.
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.
User= 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 chapter [BLACKLIST] you can specify the following keywords. Every keyword has to be entered in an own line.
Phone= This parameter can be defined multiple times. Each time this parameter appears it will specify a phone number to which no messages should be sent. If the specified number ends with a '&' this will be a prefix. That means that all numbers will be blocked which starts with the specified sequence. The numbers have to be specified in that format that would be sent to the provider, so you have to notice possible transformations (see parameter PREFIX).
The chapter [SSL] can be used for an optional integration of OpenSSL (mostly not required). The following parameters can be used:
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.
CertFile=
Specifies the file name of your own certificate.
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).
KeyFile=
Specifies the file name of your own private key (to your certificate CertFile).
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:
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.
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).
The parameter Address can be specified multiple times. If the first address is not reachable the next
one will be tried.
AddrNpi=9
Specifies the NumberingPlanIdentitcator. This parameter is only required for use with large accounts with UCP
or SMPP. Please ask your provider for the value.
AddrTon=0
Specifies the TypeOfNumber. This parameter is only required for use with large accounts with UCP
or SMPP. Please ask your provider for the value.
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.
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.
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.
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.
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. The value for that parameter has to be higher then the value for
ProtocolTimeout
(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.
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 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).
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.
MaxThroughput=
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).
MessageMode=
Specifies for SMPP 3.4 the message mode (between 1 and 3) or for UCP 4.0
whether the message should be treated as a 'single shot' message (0 or 1).
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 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/
(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, 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.
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 zero) and <c> the phone number.
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),
MM1 (Multimedia Messaging protocol 1),
MM7 (Multimedia Messaging protocol 7), EAIF (External Application Interface; Nokia), DTMF,
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 specify SMPP[Transceiver] to force a connection to the SMSC with a BIND_TRANSCEIVER instead of a BIND_TRANSMITTER or BIND_RECEIVER (olnl required in special cases, when the SMSC does not accept anything else).
For the protocol CIMD you can specify SMPP[USSD] to use a connection to a USSD.
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).
SaveToAdcSubdir=true
Specifies that incoming messages should be saved into a subdirectory for the
destination address.
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.
Stopbits=1
Specifies the count of stopbits (1 or 2). If this parameter
isn't specified the value from sendxms.cfg will be used.
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).
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).
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.
URI=
Specifies the URI for a HTTP Post Request (for example for MM1, MM7, EAIF).
For incoming connections the URI 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.
VASID=
Identifier of the VASP for the MMS Relay/Server.
VASPID=
Identifier of the originationg application.
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.
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!!!!
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:
For every character you have to enter one line with three hex codes, separated by commas.
The first code specifies the code of the character to translate, the second the code used
by the provider for that character and the third the code to translate back a received
character.
The code used by the provider can consist of multiple Hex character pairs. If these pairs
are delimited by a slash (/) this indicates that the original character will be coded
with multiple characters (Escape sequences; for Example the extended GSM character set).
If there is no slash contained the original character will be described by multiple
characters (but will still be only one character; for example CIMD character coding).
Use the files gsm.ctt and cimd.ctt (included in the standard installation) as an example.
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).
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.
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 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 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]
Count=0
Phone=491711234567
DCS=240
Split=10
LocalId=wobo
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) | |
| MM1 | StatusCode | StatusText |
| MM7 | StatusCode | StatusText |
| EAIF | StatusCode | StatusText |
| status report | ||
| Protocol | addCodes | addInfo |
| GSM | TP-Status | TP-Service-Center-Time-Stamp; TP-Discharge-Time |
| CIMD | status code (061) | discharge time (063) |
| SMPP | message_status; Error_code | done_date |
| OIS | SM status; delivery failure reason | completition/intermediate time |
| UCP | Dst; Rsn | |
| MM1 | 'DeliveryReport' or 'ReadReply': (Read)Status; StatusExtension | |
| MM7 | 'DeliveryReport' or 'ReadReply': MMStatus; MMStatusExtension | |
| EAIF | 'DeliveryReport' or 'ReadReply': (Read)Status; StatusExtension | |
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).
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.
MessageMode=
Specifies for SMPP 3.4 the message 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.
MSN=
Specifies the 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.
PID=
Specifies the ProtocolIdentifier (decimal)(see also GSM 03.40).
ReplyPathRequest=1
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=1
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).
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.
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 wuth an escape sequenz like '\t', '\n', '\r' or '\\'.
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 (and MyODBC) and which could be easily adapted to other database systems.
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 and 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);
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 will be called (1 = message sent successfully, 2 = message received successfully, 3 = message status received, 4 = message deleted, 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>). 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). */
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 ch=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 -XHANDLE=-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) |
| CHGPWD | to change the session password (UCP function 60) |
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 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.
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> | < <msgFile> | -f<msgFile>}]
options are (case sensitive):
| -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)) |
| -m<MSN> | specifies the 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 to use (default is sendxms.pid) |
| -q<n> | start SendXMS as a server and check queue every <n> seconds |
| -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) |
| -XChargedParty=<cp> | indication which party should be charged for the MMS (None, Sender, recipient, Both, ThirdParty |
| -XChargedPartyID=<cp> | specifies the address of a third party which is expected to pay for the MMS |
| -XDCS=<dcs> | specifies the DataCodingScheme to use (see GSM 03.40; do not use with -Z or -C) |
| -XDistribution=<di> | specifies the DistributionIndicator (true or false; only MMS) |
| -XMessageMode=<mm> | specifies the message mode (SMPP 3.4, 0-3) or the parameter SingleShot (UCP 4.0, 0-1) |
| -XPID=<pid> | specifies the ProtocolIdentifier to use (see GSM 03.40; can be used for replacing messages) |
| -XReplaceIfPresent=1 | specifies that an old message to the same destination should be replaced (nur SMPP) |
| -XServiceCode=<sc> | specifies the ServiceCode for the MMS |
| -XServiceDesc=<sd> | specifies the service description to use (0-99; only CIMD) |
| -XServiceType=<st> | indicates the service_type associated with the message (only SMPP) |
| -XTariffClass=<tc> | specifies the tariff class (CIMD, 0-99) or billingIdentifier (UCP 4.0) to use |