app-sms.tex

asterisk 是一个很有知名度开源软件

   Retry time for motx call
   Default 1
   --motx-retries
   Retries for motx call
   Default 10
   --mttx-channel
   Specify the channel for mttx calls
   Default is Local/ and the queue name without -X suffix
   --mtttx-callerid
   Specify the callerid for mttx calls
   May include X to use sub address based on queue name or may be full
   number
   Default is 080058752X0
   --mttx-wait
   Wait time for mttx call
   Default 10
   --mttx-delay
   Retry time for mttx call
   Default 30
   --mttx-retries
   Retries for mttx call
   Default 100
   --default-sub-address
   The default sub address assumed (e.g. for X in CLI and dialled numbers
   as above) when none added (-X) to queue
   Default 9
   --no-dial
   -x
   Create queue, but do not dial to send message
   --no-wait
   Do not wait if a call appears to be in progress
   This could have a small window where a message is queued but not
   sent, so regular calls to smsq should be done to pick up any missed
   messages
   --concurrent
   How many concurrent calls to allow (per queue), default 1
   --mr
   -n
   Message reference
   --pid
   -p
   Protocol ID
   --dcs
   Data coding scheme
   --udh
   Specific hex string of user data header specified (not including the
   initial length byte)
   May be a blank string to indicate header is included in the user data
   already but user data header indication to be set.
   --srr
   Status report requested
   --rp
   Return path requested
   --vp
   Specify validity period (seconds)
   --scts
   Specify timestamp (YYYY-MM-DDTHH:MM:SS)
   --spool-dir
   Spool dir (in which sms and outgoing are found)
   Default /var/spool/asterisk
\end{verbatim}

   Other arguments starting '-' or '\verb!--!' are invalid and will cause an
   error. Any trailing arguments are processed as follows:-

\begin{itemize}

     \item If the message is mobile originating and no destination address
       has been specified, then the first argument is assumed to be a
       destination address

     \item If the message is mobile terminating and no destination address
       has been specified, then the first argument is assumed to be the
       queue name

     \item If there is no user data, or user data file specified, then any
       following arguments are assumed to be the message, which are
       concatenated.

     \item If no user data is specified, then no message is sent. However,
       unless \verb!--no-dial! is specified, smsq checks for pending messages
       and generates an outgoing anyway
\end{itemize}


   Note that when smsq attempts to make a file in
   \path{/var/spool/asterisk/outgoing}, it checks if there is already a call
   queued for that queue. It will try several filenames, up to the
   \verb!--concurrent! setting. If these files exist, then this means Asterisk
   is already queued to send all messages for that queue, and so Asterisk
   should pick up the message just queued. However, this alone could
   create a race condition, so if the files exist then smsq will wait up
   to 3 seconds to confirm it still exists or if the queued messages have
   been sent already. The \verb!--no-wait! turns off this behaviour. Basically,
   this means that if you have a lot of messages to send all at once,
   Asterisk will not make unlimited concurrent calls to the same message
   centre or device for the same queue. This is because it is generally
   more efficient to make one call and send all of the messages one after
   the other.

   smsq can be used with no arguments, or with a queue name only, and it
   will check for any pending messages and cause an outgoing if there are
   any. It only sets up one outgoing call at a time based on the first
   queued message it finds. A outgoing call will normally send all queued
   messages for that queue. One way to use smsq would be to run with no
   queue name (so any queue) every minute or every few seconds to send
   pending message. This is not normally necessary unless \verb!--no-dial! is
   selected. Note that smsq does only check motx or mttx depending on the
   options selected, so it would need to be called twice as a general
   check.

   UTF-8 is used to parse command line arguments for user data, and is
   the default when reading a file. If an invalid UTF-8 sequence is
   found, it is treated as UCS-1 data (i.e, as is).
   The \verb!--process! option causes smsq to scan the specified queue (default
   is mtrx) for messages (matching the queue specified, or any if queue
   not specified) and run a command and delete the file. The command is
   run with a number of environment variables set as follows. Note that
   these are unset if not needed and not just taken from the calling
   environment. This allows simple processing of incoming messages
\begin{verbatim}
   $queue
   Set if a queue specified
   $?srr
   srr is set (to blank) if srr defined and has value 1.
   $?rp
   rp is set (to blank) if rp defined and has value 1.
   $ud
   User data, UTF-8 encoding, including any control characters, but with
   nulls stripped out
   Useful for the content of emails, for example, as it includes any
   newlines, etc.
   $ude
   User data, escaped UTF-8, including all characters, but control
   characters \n, \r, \t, \f, \xxx and \ is escaped as \\
   Useful guaranteed one line printable text, so useful in Subject lines
   of emails, etc
   $ud8
   Hex UCS-1 coding of user data (2 hex digits per character)
   Present only if all user data is in range U+0000 to U+00FF
   $ud16
   Hex UCS-2 coding of user data (4 hex digits per character)
   other
   Other fields set using their field name, e.g. mr, pid, dcs, etc. udh
   is a hex byte string
\end{verbatim}

\section{File formats}

   By default all queues are held in a director \path{/var/spool/asterisk/sms}.
   Within this directory are sub directories mtrx, mttx, morx, motx which
   hold the received messages and the messages ready to send. Also,
   \path{/var/log/asterisk/sms} is a log file of all messages handled.

   The file name in each queue directory starts with the queue parameter
   to SMS which is normally the CLI used for an outgoing message or the
   called number on an incoming message, and may have -X (X being sub
   address) appended. If no queue ID is known, then 0 is used by smsq by
   default. After this is a dot, and then any text. Files are scanned for
   matching queue ID and a dot at the start. This means temporary files
   being created can be given a different name not starting with a queue
   (we recommend a . on the start of the file name for temp files).
   Files in these queues are in the form of a simple text file where each
   line starts with a keyword and an = and then data. udh and ud have
   options for hex encoding, see below.

   UTF-8. The user data (ud) field is treated as being UTF-8 encoded
   unless the DCS is specified indicating 8 bit format. If 8 bit format
   is specified then the user data is sent as is.
   The keywords are as follows:
\begin{verbatim}
   oa Originating address
   The phone number from which the message came
   Present on mobile terminated messages and is the CLI for morx messages
   da
   Destination Address
   The phone number to which the message is sent
   Present on mobile originated messages
   scts
   The service centre time stamp
   Format YYYY-MM-DDTHH:MM:SS
   Present on mobile terminated messages
   pid
   One byte decimal protocol ID
   See GSM specs for more details
   Normally 0 or absent
   dcs
   One byte decimal data coding scheme
   If omitted, a sensible default is used (see below)
   See GSM specs for more details
   mr
   One byte decimal message reference
   Present on mobile originated messages, added by default if absent
   srr
   0 or 1 for status report request
   Does not work in UK yet, not implemented in app_sms yet
   rp
   0 or 1 return path
   See GSM specs for details
   vp
   Validity period in seconds
   Does not work in UK yet
   udh
   Hex string of user data header prepended to the SMS contents,
   excluding initial length byte.
   Consistent with ud, this is specified as udh# rather than udh=
   If blank, this means that the udhi flag will be set but any user data
   header must be in the ud field
   ud
   User data, may be text, or hex, see below
\end{verbatim}

   udh is specified as as udh\# followed by hex (2 hex digits per byte).
   If present, then the user data header indicator bit is set, and the
   length plus the user data header is added to the start of the user
   data, with padding if necessary (to septet boundary in 7 bit format).
   User data can hold an USC character codes U+0000 to U+FFFF. Any other
   characters are coded as U+FEFF

   ud can be specified as ud= followed by UTF-8 encoded text if it
   contains no control characters, i.e. only (U+0020 to U+FFFF). Any
   invalid UTF-8 sequences are treated as is (U+0080-U+00FF).

   ud can also be specified as ud\# followed by hex (2 hex digits per
   byte) containing characters U+0000 to U+00FF only.

   ud can also be specified as ud\#\# followed by hex (4 hex digits per
   byte) containing UCS-2 characters.

   When written by app\_sms (e.g. incoming messages), the file is written
   with ud= if it can be (no control characters). If it cannot, the a
   comment line ;ud= is used to show the user data for human readability
   and ud\# or ud\#\# is used.

\section{Delivery reports}

   The SMS specification allows for delivery reports. These are requested
   using the srr bit. However, as these do not work in the UK yet they
   are not fully implemented in this application. If anyone has a telco
   that does implement these, please let me know. BT in the UK have a non
   standard way to do this by starting the message with *0\#, and so this
   application may have a UK specific bodge in the near future to handle
   these.

   The main changes that are proposed for delivery report handling are :

\begin{itemize}
     \item New queues for sent messages, one file for each destination
       address and message reference.

     \item New field in message format, user reference, allowing applications
       to tie up their original message with a report.

     \item Handling of the delivery confirmation/rejection and connecting to
       the outgoing message - the received message file would then have
       fields for the original outgoing message and user reference
       allowing applications to handle confirmations better.
\end{itemize}