diff options
Diffstat (limited to 'docs/manual/smsd')
| -rw-r--r-- | docs/manual/smsd/backends.rst | 20 | ||||
| -rw-r--r-- | docs/manual/smsd/code.rst | 201 | ||||
| -rw-r--r-- | docs/manual/smsd/config.rst | 828 | ||||
| -rw-r--r-- | docs/manual/smsd/dbi.rst | 78 | ||||
| -rw-r--r-- | docs/manual/smsd/files.rst | 81 | ||||
| -rw-r--r-- | docs/manual/smsd/index.rst | 15 | ||||
| -rw-r--r-- | docs/manual/smsd/inject.rst | 113 | ||||
| -rw-r--r-- | docs/manual/smsd/manual.rst | 9 | ||||
| -rw-r--r-- | docs/manual/smsd/monitor.rst | 63 | ||||
| -rw-r--r-- | docs/manual/smsd/mysql.rst | 94 | ||||
| -rw-r--r-- | docs/manual/smsd/null.rst | 25 | ||||
| -rw-r--r-- | docs/manual/smsd/odbc.rst | 90 | ||||
| -rw-r--r-- | docs/manual/smsd/overview.rst | 81 | ||||
| -rw-r--r-- | docs/manual/smsd/pgsql.rst | 58 | ||||
| -rw-r--r-- | docs/manual/smsd/run.rst | 168 | ||||
| -rw-r--r-- | docs/manual/smsd/smsd-interactions.dia | 949 | ||||
| -rw-r--r-- | docs/manual/smsd/smsd-interactions.png | bin | 0 -> 29711 bytes | |||
| -rw-r--r-- | docs/manual/smsd/smsd.rst | 271 | ||||
| -rw-r--r-- | docs/manual/smsd/sql.rst | 469 | ||||
| -rw-r--r-- | docs/manual/smsd/tables.rst | 625 | ||||
| -rw-r--r-- | docs/manual/smsd/usage.rst | 61 |
21 files changed, 4299 insertions, 0 deletions
diff --git a/docs/manual/smsd/backends.rst b/docs/manual/smsd/backends.rst new file mode 100644 index 0000000..80cd67b --- /dev/null +++ b/docs/manual/smsd/backends.rst @@ -0,0 +1,20 @@ +.. _smsd_services: + +Backend services +---------------- + +The backend service is used to store messages (both incoming and queue of +outgoing ones). + +.. toctree:: + :maxdepth: 2 + + files + sql + mysql + pgsql + dbi + odbc + null + tables + diff --git a/docs/manual/smsd/code.rst b/docs/manual/smsd/code.rst new file mode 100644 index 0000000..93128bc --- /dev/null +++ b/docs/manual/smsd/code.rst @@ -0,0 +1,201 @@ +Developer documentation +======================= + +Backend services +---------------- + +The backend service is responsible for storing received messages and giving +the SMSD core messages to send. It is solely up to them how the message will +be stored, for example currently Gammu includes backends to store messages on +filesystem (:ref:`gammu-smsd-files`), various databases (:ref:`gammu-smsd-mysql`, +:ref:`gammu-smsd-pgsql`, :ref:`gammu-smsd-dbi`) or backend which does not store anything +at all (:ref:`gammu-smsd-null`). + + +Backend interface ++++++++++++++++++ + +Each backend service needs to support several operations, which are exported +in ``GSM_SMSDService`` structure: + +.. c:function:: GSM_Error GSM_SMSDService::Init (GSM_SMSDConfig *Config) + + Initializes internal state, connect to backend storage. + + :param Config: Pointer to SMSD configuration data + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::Free (GSM_SMSDConfig *Config) + + Freeing internal data, disconnect from backend storage. + + :param Config: Pointer to SMSD configuration data + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::InitAfterConnect (GSM_SMSDConfig *Config) + + Optional hook called after SMSD is connected to phone, can be used for storing information about phone in backend. + + :param Config: Pointer to SMSD configuration data + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::SaveInboxSMS (GSM_MultiSMSMessage *sms, GSM_SMSDConfig *Config, char **Locations) + + Saves message into inbox. + + :param sms: Message data to save + :param Config: Pointer to SMSD configuration data + :param Locations: Newly allocation pointer to string with IDs identifying saved messages. + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::FindOutboxSMS (GSM_MultiSMSMessage *sms, GSM_SMSDConfig *Config, char *ID) + + Finds message in outbox suitable for sending. + + :param sms: Found outbox message will be stored here + :param Config: Pointer to SMSD configuration data + :param ID: Identification of found message will be stored here, this + should be unique for different message, so that repeated attempts to + send same message can be detected by SMSD core. Empty string avoids + this check. + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::MoveSMS (GSM_MultiSMSMessage *sms, GSM_SMSDConfig *Config, char *ID, gboolean alwaysDelete, gboolean sent) + + Moves sent message from outbox to sent items. + + :param sms: Message which should be moved, backend usually can get it by ID as well. + :param Config: Pointer to SMSD configuration data. + :param ID: Identification of message to be moved. + :param alwaysDelete: Whether to delete message from outbox even if moving fails. + :param sent: Whether message was sent (``TRUE``) or there was a failure (``FALSE``). + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::CreateOutboxSMS (GSM_MultiSMSMessage *sms, GSM_SMSDConfig *Config, char *NewID) + + Saves message into outbox queue. + + :param sms: Message data to save + :param Config: Pointer to SMSD configuration data + :param NewID: ID of created message will be stored here. + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::AddSentSMSInfo (GSM_MultiSMSMessage *sms, GSM_SMSDConfig *Config, char *ID, int Part, GSM_SMSDSendingError err, int TPMR) + + Logs information about sent message (eg. delivery report). + + :param sms: Message which should be moved, backend usually can get it by ID as well. + :param Config: Pointer to SMSD configuration data + :param ID: Identification of message to be marked. + :param Part: Part of the message which is being processed. + :param err: Status of sending message. + :param TPMR: Message reference if available (:term:`TPMR`). + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::RefreshSendStatus (GSM_SMSDConfig *Config, char *ID) + + Updates sending status in service backend. + + :param Config: Pointer to SMSD configuration data + :param ID: Identification of message to be marked. + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::RefreshPhoneStatus (GSM_SMSDConfig *Config) + + Updates information about phone in database (network status, battery, etc.). + + :param Config: Pointer to SMSD configuration data + :return: Error code. + +.. c:function:: GSM_Error GSM_SMSDService::ReadConfiguration (GSM_SMSDConfig *Config) + + Reads configuration specific for this backend. + + :param Config: Pointer to SMSD configuration data + :return: Error code. + +Message ID +++++++++++ + +You might have noticed that message ID is often used in the API. The primary +reason for this is that it is usually easier for backend to handle message +just by it's internal identification instead of handling message data from +:c:type:`GSM_MultiSMSMessage`. + +If the backend does not use any IDs internally, it really does not have to +provide them, with only exception of :c:func:`GSM_SMSDService::FindOutboxSMS`, +where ID is used for detection of repeated sending of same message. + +The lifetime of ID for sent message: + + * :c:func:`GSM_SMSDService::CreateOutboxSMS` or direct manipulation + with backend storage creates new ID + * :c:func:`GSM_SMSDService::FindOutboxSMS` returns ID of message to + process + * :c:func:`GSM_SMSDService::AddSentSMSInfo` and + :c:func:`GSM_SMSDService::RefreshSendStatus` are then notified using + this ID about sending of the message + * :c:func:`GSM_SMSDService::MoveSMS` then moves the message based on + ID to sent items + +The lifetime of ID for incoming messages: + + * :c:func:`GSM_SMSDService::SaveInboxSMS` generates the message + * :ref:`gammu-smsd-run` uses this ID + +Message Sending Workflow +------------------------ + +.. graphviz:: + + digraph smsdsending { + "new message" [shape=box]; + "message in storage" [shape=box]; + "message sent" [shape=box]; + "error sending message" [shape=box]; + "new message" -> "manually created SMS"; + "new message" -> "CreateOutboxSMS"; + "manually created SMS" -> "message in storage"; + "CreateOutboxSMS" -> "message in storage" + "message in storage" -> "FindOutboxSMS"; + "FindOutboxSMS" -> "AddSentSMSInfo(ERROR)" [label="Error", style=dotted]; + "FindOutboxSMS" -> "check duplicates"; + "check duplicates" -> "AddSentSMSInfo(ERROR)" [label="Too many retries", style=dotted]; + "check duplicates" -> "GSM_SendSMS"; + "GSM_SendSMS" -> "RefreshSendStatus"; + "GSM_SendSMS" -> "AddSentSMSInfo(ERROR)" [label="Error", style=dotted]; + "RefreshSendStatus" -> "RefreshSendStatus" [label="Sending"]; + "RefreshSendStatus" -> "AddSentSMSInfo(ERROR)" [label="Timeout", style=dotted]; + "RefreshSendStatus" -> "AddSentSMSInfo(OK)"; + "AddSentSMSInfo(OK)" -> "MoveSMS(noforce, OK)"; + "MoveSMS(noforce, OK)" -> "MoveSMS(force, ERR)" [label="Error", style=dotted]; + "AddSentSMSInfo(OK)" -> "MoveSMS(force, ERR)" [label="Error", style=dotted]; + "AddSentSMSInfo(ERROR)" -> "MoveSMS(force, ERR)"; + "MoveSMS(noforce, OK)" -> "message sent"; + "MoveSMS(force, ERR)" -> "error sending message"; + } + +Message Receiving Workflow +-------------------------- + +.. graphviz:: + + digraph smsdreceiving { + "received message" [shape=box]; + "ignored message" [shape=box]; + "failed message" [shape=box]; + "waiting message" [shape=box]; + "processed message" [shape=box]; + "received message" -> "GSM_GetNextSMS"; + "GSM_GetNextSMS" -> "SMSD_ValidMessage"; + "SMSD_ValidMessage" -> "GSM_LinkSMS"; + "SMSD_ValidMessage" -> "ignored message" [label="Not valid", style=dotted]; + "GSM_LinkSMS" -> "SMSD_CheckMultipart"; + "SMSD_CheckMultipart" -> "SaveInboxSMS"; + "SMSD_CheckMultipart" -> "waiting message" [label="Not all parts", style=dotted]; + "SaveInboxSMS" -> "SMSD_RunOnReceive" [label="Locations are passed here"]; + "SaveInboxSMS" -> "failed message" [label="Error", style=dotted]; + "SMSD_RunOnReceive" -> "GSM_DeleteSMS"; + "GSM_DeleteSMS" -> "processed message" + "GSM_DeleteSMS" -> "failed message" [label="Error", style=dotted]; + } diff --git a/docs/manual/smsd/config.rst b/docs/manual/smsd/config.rst new file mode 100644 index 0000000..7ab7f5f --- /dev/null +++ b/docs/manual/smsd/config.rst @@ -0,0 +1,828 @@ +.. _gammu-smsdrc: + +SMSD Configuration File +======================= + +Description +----------- + +gammu-smsd reads configuration from a config file. It's location can be +specified on command line, otherwise default path ``/etc/gammu-smsdrc`` +is used. + +This file use ini file syntax, see :ref:`ini`. + +Configuration file of gammu-smsd consists of at least two sections - +:config:section:`[gammu]` and :config:section:`[smsd]`. For :ref:`gammu-smsd-sql` +you can also use :config:section:`[sql]` and :config:section:`[tables]`. + +The :config:section:`[gammu]` section is configuration of a phone connection +and is same as described in :ref:`gammurc` with the only exception that +:config:option:`LogFile` is ignored and common logging for gammu library and +SMS daemon is used. However the :config:option:`LogFormat` directive still +configures how much messages gammu emits. + +.. config:section:: [smsd] + + The :config:section:`[smsd]` section configures SMS daemon itself, which are described in + following subsections. First general parameters of SMS daemon are listed and + then specific parameters for storage backends. + +.. config:section:: [include_numbers] + + List of numbers from which accept messages, see :ref:`message_filtering`. + +.. config:section:: [exclude_numbers] + + List of numbers from which reject messages, see :ref:`message_filtering`. + +.. config:section:: [include_smsc] + + List of SMSC numbers from which accept messages, see :ref:`message_filtering`. + +.. config:section:: [exclude_smsc] + + List of SMSC numbers from which reject messages, see :ref:`message_filtering`. + +.. config:section:: [sql] + + Configure SQL queries used by :ref:`gammu-smsd-sql`, you usually don't have to modify them. + + .. seealso:: :ref:`Configurable queries` + +.. config:section:: [tables] + + Configure SQL table names used by :ref:`gammu-smsd-sql`, you usually don't have to modify them. + + .. seealso:: :ref:`Configurable tables` + +General parameters of SMS daemon +-------------------------------- + +.. config:option:: Service + + SMSD service to use, one of following choices: + + ``FILES`` + Stores messages in files, see :ref:`gammu-smsd-files` for details. + ``NULL`` + Does not store messages at all, see :ref:`gammu-smsd-null` for details. + ``SQL`` + Stores messages in SQL database, see :ref:`gammu-smsd-sql` for details, + choose database type to use by :config:option:`Driver`. + + .. versionadded:: 1.28.93 + ``MYSQL`` + .. deprecated:: 1.28.93 + + Use :config:option:`Service` = ``SQL`` and :config:option:`Driver` = ``native_mysql`` instead. + + Compatibility option for older configuration files, stores messages in + MySQL database, see :ref:`gammu-smsd-mysql` for details. + + ``PGSQL`` + .. deprecated:: 1.28.93 + + Use :config:option:`Service` = ``SQL`` and :config:option:`Driver` = ``native_pgsql`` instead. + + Compatibility option for older configuration files, stores messages in + PostgreSQL database, see :ref:`gammu-smsd-pgsql` for details. + + ``DBI`` + .. deprecated:: 1.28.93 + + Use :config:option:`Service` = ``SQL`` and :config:option:`Driver` = DBI driver instead. + + Compatibility option for older configuration files, stores messages in + any database supported by libdbi, see :ref:`gammu-smsd-dbi` for details. + + .. note:: + + Availability of backends depends on platform and compile time configuration. + +.. config:option:: PIN + + PIN for SIM card. This is optional, but you should set it if your phone after + power on requires PIN. + +.. config:option:: NetworkCode + + Network personalisation password. This is optional, but some phones require it + after power on. + +.. config:option:: PhoneCode + + Phone lock password. This is optional, but some phones require it after power + on. + +.. config:option:: LogFile + + File where SMSD actions are being logged. You can also use special value + ``syslog`` which will send all messages to syslog daemon. On Windows another + special value ``eventlog`` exists, which will send logs to Windows Event Log. + + If you run SMSD as a system daemon (or service), it is recommended to use + absolute path to log file as startup directory might be different than you + expect. + + Default is to provide no logging. + + .. note:: + + For logging to Windows Event Log, it is recommended to install Event Log + source by invoking :option:`gammu-smsd -e` (this is automatically done during + installation of Gammu). + +.. config:option:: LogFacility + + Facility to use on logging backends which support it (currently only + syslog). One of following chouces: + + * ``DAEMON`` (default) + * ``USER`` + * ``LOCAL0`` + * ``LOCAL1`` + * ``LOCAL2`` + * ``LOCAL3`` + * ``LOCAL4`` + * ``LOCAL5`` + * ``LOCAL6`` + * ``LOCAL7`` + + .. versionadded:: 1.30.91 + +.. config:option:: DebugLevel + + Debug level for SMSD. The integer value should be sum of all flags you + want to enable. + + 1 + enables basic debugging information + 2 + enables logging of SQL queries of service backends + 4 + enables logging of gammu debug information + + Generally to get as much debug information as possible, use 255. + + Default is 0, what should mean no extra information. + +.. config:option:: CommTimeout + + How many seconds should SMSD wait after there is no message in outbox + before scanning it again. + + Default is 30. + +.. config:option:: SendTimeout + + Shows how many seconds SMSD should wait for network answer during sending + sms. If nothing happen during this time, sms will be resent. + + Default is 30. + +.. config:option:: MaxRetries + + How many times will SMSD try to resend message if sending fails. This + is tracked per message and currently supported only with SQL backends. + + Default is 1. + +.. config:option:: ReceiveFrequency + + The number of seconds between testing for received SMSes, when the phone is + busy sending SMSes. Normally a test for received SMSes is done every + :config:option:`CommTimeout` seconds and after each sent SMS. + + Default is 15. + +.. config:option:: StatusFrequency + + The number of seconds between refreshing phone status (battery, signal) stored + in shared memory and possibly in service backends. Use 0 to disable. + + You might want to increase this for higher throughput. + + Default is 60. + +.. config:option:: LoopSleep + + The number of seconds how long will SMSD sleep before checking for some + activity. Please note that setting this to higher value than 1 will have + effects to other time based configurations, because they will be effectively + rounded to multiply of this value. + + Setting this to 0 disables sleeping. Please note this might cause Gammu to + consume quite a lot of CPU power as it will effectively do busy loop. + + This sleep is utilized only if the main loop (sending and receiving + messages) takes less than defined time. For example if you set LoopSleep to + 5 seconds and sending messages take 10 seconds, no sleep will be done in + the iteration which is sending messages. Also the sleep time is lowered by + the already processed time. + + Default is 1. + +.. config:option:: MultipartTimeout + + The number of seconds how long will SMSD wait for all parts of multipart + message. If all parts won't arrive in time, parts will be processed as separate + messages. + + Default is 600 (10 minutes). + +.. config:option:: CheckSecurity + + Whether to check if phone wants to enter PIN. + + Default is 1 (enabled). + +.. config:option:: HangupCalls + + .. versionadded:: 1.34.0 + + Whether to automatically hangup any incoming calls. + + Default is 0 (disabled). + +.. config:option:: CheckBattery + + Whether to check phone battery state periodically. + + Default is 1 (enabled). + +.. config:option:: CheckSignal + + Whether to check signal level periodically. + + Default is 1 (enabled). + +.. config:option:: CheckNetwork + + .. versionadded:: 1.37.90 + + Whether to check network status periodically. + + If phone is reported to be not on the network, SMSD + tries to power it on. + + Default is 1 (enabled). + +.. config:option:: ResetFrequency + + The number of seconds between performing a preventive soft reset in order to + minimize the cases of hanging phones e.g. Nokia 5110 will sometimes freeze to + a state when only after unmounting the battery the phone will be functional + again. + + Default is 0 (not used). + +.. config:option:: HardResetFrequency + + .. versionadded:: 1.28.92 + + .. warning:: + + For some phones hard reset means deleting all data in it. Use + :config:option:`ResetFrequency` instead, unless you know what you are + doing. + + The number of seconds between performing a preventive hard reset in order to + minimize the cases of hanging phones. + + Default is 0 (not used). + +.. config:option:: DeliveryReport + + Whether delivery reports should be used, one of ``no``, ``log``, ``sms``. + + ``log`` + one line log entry, + ``sms`` + store in inbox as a received SMS + ``no`` + no delivery reports + + Default is ``no``. + +.. config:option:: DeliveryReportDelay + + Delay in seconds how long is still delivery report considered valid. This + depends on brokenness of your network (delivery report should have same + timestamp as sent message). Increase this if delivery reports are not paired + with sent messages. + + Default is 600 (10 minutes). + +.. config:option:: PhoneID + + String with info about phone used for sending/receiving. This can be useful if + you want to run several SMS daemons (see :ref:`smsd-multi`). + + When you set PhoneID, all messages (including injected ones) will be marked + by this string (stored as SenderID in the database) and it allows more SMS + daemons to share a single database. + + SMSD daemon will in such case send :ref:`outbox` messages only with + matching or empty SenderID. + + This option has actually no effect with :ref:`gammu-smsd-files`. + +.. config:option:: SMSC + + .. versionadded:: 1.36.2 + + SMSC number to use for sending messages if not specified in the message + (see options of :ref:`gammu-smsd-inject`). + + In most cases you don't need this settings as Gammu tries to read correct + SMSC from phone, but sometimes this fails (try :option:`gammu getsmsc`). + +.. config:option:: RunOnReceive + + Executes a program after receiving message. + + This parameter is executed through shell, so you might need to escape some + special characters and you can include any number of parameters. Additionally + parameters with identifiers of received messages are appended to the command + line. The identifiers depend on used service backend, typically it is ID of + inserted row for database backends or file name for file based backends. + + Gammu SMSD waits for the script to terminate. If you make some time consuming + there, it will make SMSD not receive new messages. However to limit breakage + from this situation, the waiting time is limited to two minutes. After this + time SMSD will continue in normal operation and might execute your script + again. + + The process has available lot of information about received message in + environment, check :ref:`gammu-smsd-run` for more details. + +.. config:option:: RunOnFailure + + .. versionadded:: 1.28.93 + + Executes a program on failure. + + This can be used to proactively react on some failures or to interactively + detect failure of sending message. + + The program will receive optional parameter, which can currently be either + ``INIT`` (meaning failure during phone initialization) or message ID, + which would indicate error while sending the message. + + .. note:: The environment with message (as is in :config:option:`RunOnReceive`) is not passed to the command. + +.. config:option:: RunOnSent + + .. versionadded:: 1.36.4 + + Executes a program after sending message. + + The program will receive optional parameter a message ID and environment + with message details as described in :ref:`gammu-smsd-run`. + +.. config:option:: RunOnIncomingCall + + .. versionadded:: 1.38.5 + + Executes a program after cancelling incoming call. + + The program will receive a parameter with a phone number of the call. + This requires :config:option:`HangupCalls` to be enabled. + +.. config:option:: IncludeNumbersFile + + File with list of numbers which are accepted by SMSD. The file contains one + number per line, blank lines are ignored. The file is read at startup and is + reread only when configuration is being reread. See Message filtering for + details. + +.. config:option:: ExcludeNumbersFile + + File with list of numbers which are not accepted by SMSD. The file contains + one number per line, blank lines are ignored. The file is read at startup and + is reread only when configuration is being reread. See Message filtering for + details. + +.. config:option:: IncludeSMSCFile + + File with list of SMSC numbers which are accepted by SMSD. The file contains + one number per line, blank lines are ignored. The file is read at startup and + is reread only when configuration is being reread. See Message filtering for + details. + +.. config:option:: ExcludeSMSCFile + + File with list of SMSC numbers which are not accepted by SMSD. The file + contains one number per line, blank lines are ignored. The file is read at + startup and is reread only when configuration is being reread. See Message + filtering for details. + +.. config:option:: BackendRetries + + How many times will SMSD backend retry operation. + + The implementation on different backends is different, for database backends + it generally means how many times it will try to reconnect to the server. + + Default is 10. + +.. config:option:: Send + + .. versionadded:: 1.28.91 + + Whether to enable sending of messages. + + Default is True. + +.. config:option:: Receive + + .. versionadded:: 1.28.91 + + Whether to enable receiving of messages. + + Default is True. + + +Database backends options +------------------------- + +All DBI, ODBC, MYSQL and PGSQL backends (see :ref:`gammu-smsd-mysql`, +:ref:`gammu-smsd-odbc`, :ref:`gammu-smsd-pgsql`, :ref:`gammu-smsd-dbi` for +their documentation) supports same options for configuring connection to a +database: + +.. config:option:: User + + User name used for connection to a database. + +.. config:option:: Password + + Password used for connection to a database. + +.. config:option:: Host + + Database server address. It can also contain port or socket path after + semicolon, for example ``localhost:/path/to/socket`` or + ``192.168.1.1:8000``. + + For ODBC this is used as Data source name. + + .. note:: + + Some database servers differentiate usage of ``localhost`` (to use + local socket) and ``127.0.0.1`` (to use locat TCP/IP connection). + Please make sure your SMSD settings match the database server ones. + + .. versionadded:: 1.28.92 + +.. config:option:: PC + + .. deprecated:: 1.28.92 + + Please use :config:option:`Host` instead. + + Synonym for :config:option:`Host`, kept for backwards compatibility. + +.. config:option:: Database + + Name of database (or schema) to use and where SMSD can find it's tables. + + Please note that you should create tables in this database before using + gammu-smsd. SQL files for creating needed tables are included in + documentation for individual database backends: :ref:`gammu-smsd-mysql`, + :ref:`gammu-smsd-odbc`, :ref:`gammu-smsd-pgsql`, :ref:`gammu-smsd-dbi` + +.. config:option:: SkipSMSCNumber + + When you send sms from some SMS centers you can have delivery reports from + other SMSC number. You can set here number of this SMSC used by you and Gammu + will not check it's number during assigning reports to sent SMS. + +.. config:option:: Driver + + SQL driver to use, Gammu supports several native drivers and generic + interface using ODBC and DBI. Availability of the backends depends on + compile time options. + + Available drivers: + + ``odbc`` + + Connects to the database using ODBC, see :ref:`gammu-smsd-odbc`. + + ``native_mysql`` + + Stores messages in MySQL database, see :ref:`gammu-smsd-mysql` for + details. + + ``native_pgsql`` + + Stores messages in PostgreSQL database, see :ref:`gammu-smsd-pgsql` for + details. + + ``db2``, ``firebird``, ``freetds``, ``ingres``, ``msql``, ``mysql``, ``oracle``, ``pgsql``, ``sqlite``, ``sqlite3`` + + Stores messages using DBI library in given backend. You need to have + installed appropriate DBI driver to make it work. See + :ref:`gammu-smsd-dbi` for details. + +.. config:option:: SQL + + SQL dialect to use. This is specially useful with :ref:`gammu-smsd-odbc` where SMSD + does not know which server it is actually talking to. + + Possible values: + + * ``mysql`` - MySQL + * ``pgsql`` - PostgreSQL + * ``sqlite`` - SQLite + * ``mssql`` - Microsoft SQL Server + * ``sybase`` - Sybase + * ``access`` - Microsoft Access + * ``oracle`` - Oracle + * ``odbc`` - Generic ODBC + + .. versionadded:: 1.28.93 + + .. seealso:: You can also completely customize SQL queries used as described in :ref:`SQL Queries`. + +.. config:option:: DriversPath + + Path, where DBI drivers are stored, this usually does not have to be set if + you have properly installed drivers. + +.. config:option:: DBDir + + Database directory for some (currently only sqlite) DBI drivers. Set here path + where sqlite database files are stored. + +Files backend options ++++++++++++++++++++++ + +The FILES backend accepts following configuration options. See +:ref:`gammu-smsd-files` for more detailed service backend description. Please note +that all path should contain trailing path separator (/ on Unix systems): + +.. config:option:: InboxPath + + Where the received SMSes are stored. + + Default is current directory. + +.. config:option:: OutboxPath + + Where SMSes to be sent should be placed. + + Default is current directory. + +.. config:option:: SentSMSPath + + Where the transmitted SMSes are placed, if same as :config:option:`OutboxPath` transmitted + messages are deleted. + + Default is to delete transmitted messages. + +.. config:option:: ErrorSMSPath + + Where SMSes with error in transmission is placed. + + Default is same as :config:option:`SentSMSPath`. + +.. config:option:: InboxFormat + + The format in which the SMS will be stored: ``detail``, ``unicode``, ``standard``. + + ``detail`` + format used for message backup by :ref:`gammu`, see :ref:`gammu-smsbackup`. + ``unicode`` + message text stored in unicode (UTF-16) + ``standard`` + message text stored in system charset + + The ``standard`` and ``unicode`` settings do not apply for 8-bit messages, which + are always written raw as they are received with extension .bin. + + Default is ``unicode``. + + .. note:: + + In ``detail`` format, all message parts are stored into signle file, + for all others each message part is saved separately. + +.. config:option:: OutboxFormat + + The format in which messages created by :ref:`gammu-smsd-inject` will be stored, + it accepts same values as InboxFormat. + + Default is ``detail`` if Gammu is compiled in with backup functions, ``unicode`` + otherwise. + +.. config:option:: TransmitFormat + + The format for transmitting the SMS: ``auto``, ``unicode``, ``7bit``. + + This option is used only if :config:option:`OutboxFormat` is not set to + ``detail``. In such case encoding specified in the message is used (you can + specify it to :ref:`gammu-smsd-inject`). + + Default is ``auto``. + +.. _message_filtering: + +Message filtering +----------------- + +SMSD allows one to process only limited subset of incoming messages. You can define +filters for sender number in :config:section:`[include_numbers]` and +:config:section:`[exclude_numbers]` sections or using +:config:option:`IncludeNumbersFile` and :config:option:`ExcludeNumbersFile` +directives. + +If :config:section:`[include_numbers]` section exists, all values (keys are +ignored) from it are used as allowed phone numbers and no other message is +processed. On the other side, in :config:section:`[exclude_numbers]` you can +specify numbers which you want to skip. + +Lists from both sources are merged together. If there is any number in include +list, only include list is used and only messages in this list are being +accepted. If include list is empty, exclude list can be used to ignore +messages from some numbers. If both lists are empty, all messages are +accepted. + +Similar filtering rules can be used for SMSC number filtering, they just use +different set of configuration options - :config:section:`[include_smsc]` and +:config:section:`[exclude_smsc]` sections or :config:option:`IncludeSMSCFile` +and :config:option:`ExcludeSMSCFile` directives. + +Examples +-------- + +There is more complete example available in Gammu documentation. Please note +that for simplicity following examples do not include :config:section:`[gammu]` +section, you can look into :ref:`gammurc` for some examples how it can look like. + +Files service ++++++++++++++ + +SMSD configuration file for FILES backend could look like: + +.. code-block:: ini + + [smsd] + Service = files + PIN = 1234 + LogFile = syslog + InboxPath = /var/spool/sms/inbox/ + OutboxPath = /var/spool/sms/outbox/ + SentSMSPath = /var/spool/sms/sent/ + ErrorSMSPath = /var/spool/sms/error/ + +MySQL service ++++++++++++++ + +If you want to use MYSQL backend, you will need something like this: + +.. code-block:: ini + + [smsd] + Service = sql + Driver = native_mysql + PIN = 1234 + LogFile = syslog + User = smsd + Password = smsd + PC = localhost + Database = smsd + +DBI service using SQLite +++++++++++++++++++++++++ + +For :ref:`gammu-smsd-dbi` backend, in this particular case SQLite: + +.. code-block:: ini + + [smsd] + Service = sql + Driver = sqlite3 + DBDir = /var/lib/sqlite3 + Database = smsd.db + +ODBC service using MySQL +++++++++++++++++++++++++ + +For :ref:`gammu-smsd-odbc` backend, in this particular case using DSN ``smsd`` server: + +.. code-block:: ini + + [smsd] + Service = sql + Driver = odbc + Host = smsd + +The DSN definition (in :file:`~/.odbc.ini` on UNIX) for using MySQL server would look like: + +.. code-block:: ini + + [smsd] + Description = MySQL + Driver = MySQL + Server = 127.0.0.1 + Database = smsd + Port = + Socket = + Option = + Stmt = + + [smsdsuse] + Driver = MySQL ODBC 3.51.27r695 Driver + DATABASE = smsd + SERVER = 127.0.0.1 + + +Numbers filtering ++++++++++++++++++ + +Process only messages from 123456 number: + +.. code-block:: ini + + [include_numbers] + number1 = 123456 + +Do not process messages from evil number 666: + +.. code-block:: ini + + [exclude_numbers] + number1 = 666 + +Debugging ++++++++++ + +Enabling debugging: + +.. code-block:: ini + + [smsd] + debuglevel = 255 + logfile = smsd.log + +.. _smsd-multi: + +Multiple modems ++++++++++++++++ + +You can run any number of SMSD instances and they can even share same backend +database. For routing the messages, you need to set different +:config:option:`PhoneID` for each instance and set ``SenderID`` column in +:ref:`outbox` table. + +Following example shows configuration for two modems, but you can have any +number of SMSD instances. The only limitation is performance of your hardware, +especially if all modems are connected using USB. + +Configuration for first SMSD: + +.. code-block:: ini + + [gammu] + device = /dev/ttyACM0 + connection = at + + [smsd] + Service = sql + Driver = native_mysql + PIN = 1234 + LogFile = syslog + User = smsd + Password = smsd + PC = localhost + Database = smsd + PhoneID = first + +Configuration for second SMSD: + +.. code-block:: ini + + [gammu] + device = /dev/ttyACM1 + connection = at + + [smsd] + Service = sql + Driver = native_mysql + PIN = 1234 + LogFile = syslog + User = smsd + Password = smsd + PC = localhost + Database = smsd + PhoneID = second + +You can then start two separate instances of SMSD: + +.. code-block:: sh + + gammu-smsd -c /path/to/first-smsdrc + gammu-smsd -c /path/to/second-smsdrc diff --git a/docs/manual/smsd/dbi.rst b/docs/manual/smsd/dbi.rst new file mode 100644 index 0000000..d9f30ad --- /dev/null +++ b/docs/manual/smsd/dbi.rst @@ -0,0 +1,78 @@ +.. _gammu-smsd-dbi: + +DBI Backend +=========== + +Description +----------- + +DBI backend stores all data in any database supported by `libdbi`_, which +parameters are defined by configuration (see :ref:`gammu-smsdrc` for description of +configuration options). + +For tables description see :ref:`gammu-smsd-tables`. + +This backend is based on :ref:`gammu-smsd-sql`. + +.. note:: + + The DBI driver is currently not supported on Windows because libdbi + library does not support this platform. + + +Configuration +------------- + +Before running :ref:`gammu-smsd` you need to create necessary tables in the +database. You can use examples given in database specific backends parts of +this manual to do that. + +The configuration file then can look like: + +.. code-block:: ini + + [smsd] + service = sql + driver = DBI_DRIVER + host = localhost + +.. seealso:: :ref:`gammu-smsdrc` + +Supported drivers +----------------- + +For complete list of drivers for `libdbi`_ see `libdbi-drivers`_ project. The +drivers for example include: + +* ``sqlite3`` - for SQLite 3 +* ``mysql`` - for MySQL +* ``pgsql`` - for PostgeSQL +* ``freetds`` - for MS SQL Server or Sybase + +.. _libdbi: http://libdbi.sourceforge.net/ +.. _libdbi-drivers: http://libdbi-drivers.sourceforge.net/ + +.. _sqlite-create: + +Creating tables for SQLite +-------------------------- + +SQL script for creating tables in SQLite database: + +.. literalinclude:: ../../sql/sqlite.sql + :language: sql + +.. note:: + + You can find the script in :file:`docs/sql/sqlite.sql` as well. There are + also scripts for other databases in same folder. + +Upgrading tables +---------------- + +The easiest way to upgrade database structure is to backup old one and start +with creating new one based on example above. + +For upgrading existing database, you can use changes described in +:ref:`smsd-tables-history` and then manually update ``Version`` field in +``gammu`` table. diff --git a/docs/manual/smsd/files.rst b/docs/manual/smsd/files.rst new file mode 100644 index 0000000..6e204f5 --- /dev/null +++ b/docs/manual/smsd/files.rst @@ -0,0 +1,81 @@ +.. _gammu-smsd-files: + +Files backend +============= + +Description +----------- + +FILES backend stores all data on a filesystem in folders defined by +configuration (see :ref:`gammu-smsdrc` for description of configuration options). + +Receiving of messages +--------------------- + +Received messages are stored in a folder defined by configuration. The +filename will be ``IN<date>_<time>_<serial>_<sender>_<sequence>.<ext>``, +for example ``IN20021130_021531_00_+45409000931640979_00.txt``. + +Explanation of fields: + +``<date>`` + date in format ``YYYYMMDD`` +``<time>`` + time in format ``HHMMSS`` +``<sender>`` + sender number +``<serial>`` + order of a message (in case more messages were received at same time), in format ``NN`` +``<sequence>`` + part of the message for multipart messages, in format ``NN`` +``<ext>`` + ``txt`` for text message, 8-bit messages are stored with ``bin`` extension, ``smsbackup`` for :ref:`gammu-smsbackup` + +The content of the file is content of the message and the format is defined by +configuration directive :config:option:`InboxFormat` (see :ref:`gammu-smsdrc`). + +Transmitting of messages +------------------------ + +Transmitted messages are read from a folder defined by configuration. The +filename should be one of the following formats: + +- ``OUT<recipient>.<ext>`` +- ``OUT<priority>_<recipient>_<serial>.<ext>`` +- ``OUT<priority><date>_<time>_<serial>_<recipient>_<note>.<ext>`` + +Explanation of fields: + +``<recipient>`` + recipient number where to send message +``<priority>`` + an alphabetic character (A-Z) A = highest priority +``<ext>`` + ``txt`` for normal text SMS, ``smsbackup`` for :ref:`gammu-smsbackup` +``<note>`` + any arbitrary text which is ignored + +For text messages, you can additionally append flags to extension: + + ``d`` + delivery report requested + ``f`` + flash SMS + ``b`` + WAP bookmark as name,URL + +Other fields are same as for received messages. + +For example OUTG20040620_193810_123_+4512345678_xpq.txtdf is a flash text SMS +requesting delivery reports. + +SMSes will be transmitted sequentially based on the file name. The contents of +the file is the SMS to be transmitted (in Unicode or standard character set). + +The contents of the file is the SMS to be transmitted (in Unicode or standard +character set), for WAP bookmarks it is split on as Name,URL, for text +messages whole file content is used. + +Please note that if file is not in Unicode, encoding is detected based on +locales, which do not have to be configured if SMSD is running from init +script. If this is your case, please add locales definition to init script. diff --git a/docs/manual/smsd/index.rst b/docs/manual/smsd/index.rst new file mode 100644 index 0000000..36c9b2c --- /dev/null +++ b/docs/manual/smsd/index.rst @@ -0,0 +1,15 @@ +.. _smsd: + +SMS Daemon +========== + +.. toctree:: + :maxdepth: 2 + + overview + usage + manual + config + run + backends + code diff --git a/docs/manual/smsd/inject.rst b/docs/manual/smsd/inject.rst new file mode 100644 index 0000000..0c35191 --- /dev/null +++ b/docs/manual/smsd/inject.rst @@ -0,0 +1,113 @@ +.. _gammu-smsd-inject: + +gammu-smsd-inject +================= + +.. program:: gammu-smsd-inject + +Synopsis +-------- + +.. code-block:: text + + gammu-smsd-inject [OPTION]... MESSAGETYPE RECIPIENT [MESSAGE_PARAMETER]... + +Description +----------- + +This manual page documents briefly the :program:`gammu-smsd-inject` command. + +:program:`gammu-smsd-inject` is a program that enqueues message in Gammu SMS +Daemon, which will be later sent by the daemon using connected GSM modem. + +Support for this program depends on features available in currently used SMSD +service backend, however currently it is supported by all of them. + +Program accepts following options (please note that long options might be not +accepted on some platforms): + +.. option:: -h, --help + + Shows help. + +.. option:: -v, --version + + Shows version information and compiled in features. + +.. option:: -c, --config=file + + Configuration file to use, default is /etc/gammu-smsdrc, on Windows there + is no default and configuration file path has to be always specified. + +.. option:: -l, --use-log + + Use logging as configured in config file. + +.. option:: -L, --no-use-log + + Do not use logging as configured in config file (default). + +For description of message types and their parameters, please check documentation +for :option:`gammu savesms`. + +.. _smsd-inject-examples: + +Examples +-------- + +To check it out, you need to have configuration file for SMSD, see +:ref:`gammu-smsdrc` for more details about it. + +Inject text message up to standard 160 chars: + +.. code-block:: sh + + echo "All your base are belong to us" | gammu-smsd-inject TEXT 123456 + +or + +.. code-block:: sh + + gammu-smsd-inject TEXT 123456 -text "All your base are belong to us" + +Inject unicode text message: + +.. code-block:: sh + + gammu-smsd-inject TEXT 123456 -unicode -text "ZkouÅ¡ka sirén" + +Inject long text message: + +.. code-block:: sh + + echo "All your base are belong to us" | gammu-smsd-inject TEXT 123456 -len 400 + +or + +.. code-block:: sh + + gammu-smsd-inject TEXT 123456 -len 400 -text "All your base are belong to us" + +or + +.. code-block:: sh + + gammu-smsd-inject EMS 123456 -text "All your base are belong to us" + +Inject some funky message with predefined sound and animation from 2 bitmaps: + +.. code-block:: sh + + gammu-smsd-inject EMS 123456 -text "Greetings" -defsound 1 -text "from Gammu" -tone10 axelf.txt -animation 2 file1.bmp file2.bmp + +Inject protected message with ringtone: + +.. code-block:: sh + + gammu-smsd-inject EMS 123456 -protected 2 -variablebitmaplong ala.bmp -toneSElong axelf.txt -toneSE ring.txt + +Inject USSD query: + +.. code-block:: sh + + gammu-smsd-inject USSD '*101#' diff --git a/docs/manual/smsd/manual.rst b/docs/manual/smsd/manual.rst new file mode 100644 index 0000000..a413fff --- /dev/null +++ b/docs/manual/smsd/manual.rst @@ -0,0 +1,9 @@ +Program Manuals +=============== + +.. toctree:: + :maxdepth: 2 + + smsd + inject + monitor diff --git a/docs/manual/smsd/monitor.rst b/docs/manual/smsd/monitor.rst new file mode 100644 index 0000000..906692f --- /dev/null +++ b/docs/manual/smsd/monitor.rst @@ -0,0 +1,63 @@ +.. _gammu-smsd-monitor: + +gammu-smsd-monitor +================== + +.. program:: gammu-smsd-monitor + +Synopsis +-------- + +.. code-block:: text + + gammu-smsd-monitor [OPTION]... + +Description +----------- + +This manual page documents briefly the :program:`gammu-smsd-monitor` command. + +:program:`gammu-smsd-monitor` is a program that monitors state of Gammu SMS +Daemon. It periodically displays information about phone and number of +processed messages. + +Program accepts following options (please note that long options might be not +accepted on some platforms): + +.. option:: -h, --help + + Shows help. + +.. option:: -v, --version + + Shows version information and compiled in features. + +.. option:: -c, --config=file + + Configuration file to use, default is /etc/gammu-smsdrc, on Windows there + is no default and configuration file path has to be always specified. + +.. option:: -n, --loops=count + + Number of loops, by default monitor loops infinitely. + +.. option:: -d, --delay=seconds + + Delay between polling SMSD state, default is 20 seconds. + +.. option:: -C, --csv + + Print output in comma separated values format: + + .. code-block:: text + + client;phone ID;IMEI;sent;received;failed;battery;signal + +.. option:: -l, --use-log + + Use logging as configured in config file. + +.. option:: -L, --no-use-log + + Do not use logging as configured in config file (default). + diff --git a/docs/manual/smsd/mysql.rst b/docs/manual/smsd/mysql.rst new file mode 100644 index 0000000..19b59bf --- /dev/null +++ b/docs/manual/smsd/mysql.rst @@ -0,0 +1,94 @@ +.. _gammu-smsd-mysql: + +MySQL Backend +============= + +Description +----------- + +MYSQL backend stores all data in a `MySQL`_ database server, which parameters are +defined by configuration (see :ref:`gammu-smsdrc` for description of configuration +options). + +For tables description see :ref:`gammu-smsd-tables`. + +This backend is based on :ref:`gammu-smsd-sql`. + +Configuration +------------- + +Before running :ref:`gammu-smsd` you need to create necessary tables in the +database, which is described below. + +The configuration file then can look like: + +.. code-block:: ini + + [smsd] + service = sql + driver = native_mysql + host = localhost + +.. seealso:: :ref:`gammu-smsdrc` + +Privileges +---------- + +The user accessing the database does not need much privileges, the following +privileges should be enough: + +.. code-block:: sql + + GRANT USAGE ON *.* TO 'smsd'@'localhost' IDENTIFIED BY 'password'; + + GRANT SELECT, INSERT, UPDATE, DELETE ON `smsd`.* TO 'smsd'@'localhost'; + + CREATE DATABASE smsd; + +.. note:: + + For creating the SQL tables you need more privileges, especially for + creating triggers, which are used for some functionality. + +.. _MySQL: https://www.mysql.com/ + +.. _mysql-create: + +Creating tables for MySQL +------------------------- + +Depending on MySQL version and settings please choose best fitting +script to create tables: + +* :file:`mysql-strict.sql` can be used in strict mode, but requires MySQL 5.6.5 + or newer +* :file:`mysql.sql` supports all MySQL versions, but requires neither of + `NO_ZERO_DATE`, `ANSI` or `STRICT` modes to be set in the server + +SQL script :file:`mysql.sql` for creating tables in MySQL database: + +.. literalinclude:: ../../sql/mysql.sql + :language: mysql + +.. note:: + + You can find the script in :file:`docs/sql/mysql.sql` as well. + +SQL script :file:`mysql-strict.sql` for creating tables in MySQL database: + +.. literalinclude:: ../../sql/mysql-strict.sql + :language: mysql + +.. note:: + + You can find the script in :file:`docs/sql/mysql-strict.sql` as well. + +Upgrading tables +---------------- + +The easiest way to upgrade database structure is to backup old one and start +with creating new one based on example above. + +For upgrading existing database, you can use changes described in +:ref:`smsd-tables-history` and then manually update ``Version`` field in +``gammu`` table. diff --git a/docs/manual/smsd/null.rst b/docs/manual/smsd/null.rst new file mode 100644 index 0000000..585d650 --- /dev/null +++ b/docs/manual/smsd/null.rst @@ -0,0 +1,25 @@ +.. _gammu-smsd-null: + +Null Backend +============ + +Description +----------- + +NULL backend does not store data at all. It could be useful in case you +don't want to store messages at all and you want to process then in +:config:option:`RunOnReceive` handler. + +Configuration +------------- + +The configuration file then can look like: + +.. code-block:: ini + + [smsd] + Service = null + RunOnReceive = /usr/local/bin/process-sms + +.. seealso:: :ref:`gammu-smsdrc` + diff --git a/docs/manual/smsd/odbc.rst b/docs/manual/smsd/odbc.rst new file mode 100644 index 0000000..d32e41f --- /dev/null +++ b/docs/manual/smsd/odbc.rst @@ -0,0 +1,90 @@ +.. _gammu-smsd-odbc: + +ODBC Backend +============ + +Description +----------- + +.. versionadded:: 1.29.92 + +ODBC backend stores all data in any database supported by `ODBC`_, which +parameters are defined by configuration (see :ref:`gammu-smsdrc` for description of +configuration options). + +For tables description see :ref:`gammu-smsd-tables`. + +This backend is based on :ref:`gammu-smsd-sql`. + +Supported drivers +----------------- + +On Microsoft Windows, Gammu uses native ODBC, on other platforms, `unixODBC`_ +can be used. + +.. _ODBC: https://en.wikipedia.org/wiki/Open_Database_Connectivity +.. _unixODBC: http://www.unixodbc.org/ + +Limitations +----------- + +Due to limits of the ODBC interface, Gammu can not reliably detect which SQL +engine it is connected to. + +In most cases this can be solved by setting :config:option:`SQL` setting to +correct dialect. + +If that fails, you can also tweak the SQL queries to work in used SQL server, +see :ref:`SQL Queries` for more details. Still you should set +:config:option:`SQL` to closest matching SQL dialect. + +Configuration +------------- + +Before running :ref:`gammu-smsd` you need to create necessary tables in the +database. You can use examples given in database specific backends parts of +this manual to do that. + +You specify data source name (DSN) as :config:option:`Host` in +:ref:`gammu-smsdrc`. The data source is configured depending on your platform. + +.. note:: + + Please remember that SMSD might be running in different context than your + user (separate account on Linux or as as service on Windows), so the ODBC + DSN needs to be configured as system wide in this case (system DSN on + Windows or in global configuration on Linux). + +On Microsoft Windows, you can find instructions on Microsoft website: +https://support.microsoft.com/kb/305599 + +For unixODBC this is documented in the user manual: +http://www.unixodbc.org/doc/UserManual/ + +Creating tables +--------------- + +Prior to starting SMSD you have to create tables it will use. Gammu ships SQL +scripts for several databases to do that: + +* :ref:`mysql-create` +* :ref:`pgsql-create` +* :ref:`sqlite-create` + + +Example +------- + +Example configuration: + +.. code-block:: ini + + [smsd] + service = sql + driver = odbc + host = dsn_of_your_database + sql = sql_variant_to_use + user = username + password = password + +.. seealso:: :ref:`gammu-smsdrc` diff --git a/docs/manual/smsd/overview.rst b/docs/manual/smsd/overview.rst new file mode 100644 index 0000000..bfc167f --- /dev/null +++ b/docs/manual/smsd/overview.rst @@ -0,0 +1,81 @@ +Overview +======== + +Gammu SMS Daemon is a program that periodically scans GSM modem for received +messages, stores them in defined storage and also sends messages enqueued in +this storage. + +Overall schema +-------------- + +The interactions of SMS Daemon and related components can be seen on following +picture. + +.. graphviz:: + + digraph smsdinteractions { + "gammu-smsd-inject" [shape=box]; + "gammu-smsd" [shape=box]; + "Run on receive" [shape=box, style=dotted]; + "GSM modem" [shape=box, style=dashed]; + "gammu-smsd-monitor" [shape=box]; + "Service\nstorage" [shape=doublecircle]; + "Kalkun" [shape=box, style=dotted]; + "gammu-smsd" -> "GSM modem" [label="Outgoing"]; + "GSM modem" -> "gammu-smsd" [label="Incoming"]; + "gammu-smsd" -> "Service\nstorage" [label="Save"]; + "Service\nstorage" -> "gammu-smsd" [label="Read"]; + "gammu-smsd" -> "Run on receive" [label="Execute"]; + "Service\nstorage" -> "Run on receive" [label="Read"]; + "Kalkun" -> "Service\nstorage" [label="Inject"]; + "Service\nstorage" -> "Kalkun" [label="Read"]; + "gammu-smsd-inject" -> "Service\nstorage" [label="Inject"]; + "gammu-smsd" -> "gammu-smsd-monitor" [label="Monitor"]; + } + +SMSD operation +-------------- + +The SMSD operation consist of several steps. + +.. graphviz:: + + digraph smsloop { + start[shape="box", style=rounded, label="Startup"]; + end[shape="box", style=rounded, label="Termination"]; + connected[shape="diamond", style="", label="Phone connected?"]; + connect[label="Connect to phone"]; + security[label="Check for security code"]; + receive[label="Receive messages"]; + reset[label="Reset phone if needed"]; + send[label="Send messages"]; + status[label="Check phone status"]; + sleep[label="Sleep"]; + shutdown[shape="diamond", style="", label="Shutdown requested?"]; + + start -> connected; + connected -> connect [label="No"]; + connected -> security [label="Yes"]; + connect -> security; + security -> receive; + receive -> reset; + reset -> send; + send -> status; + status -> sleep; + sleep -> shutdown; + + shutdown -> connected [label="No"]; + shutdown -> end [label="Yes"]; + } + +1. Process command line options. +2. Configure backend service. +3. Main loop is executed until it is signalled to be terminated. + 1. Try to connect to phone if not connected. + 2. Check for security code if configured (configured by :config:option:`CheckSecurity`). + 3. Check for received messages (frequency configured by :config:option:`ReceiveFrequency`). + 4. Check for reset of the phone if configured (frequency configured by :config:option:`ResetFrequency`). + 5. Check for messages to send (frequency configured by :config:option:`CommTimeout`). + 6. Check phone status (frequency configured by :config:option:`StatusFrequency`). + 7. Sleep for defined time (:config:option:`LoopSleep`). +4. Backend service is freed. diff --git a/docs/manual/smsd/pgsql.rst b/docs/manual/smsd/pgsql.rst new file mode 100644 index 0000000..eb55b62 --- /dev/null +++ b/docs/manual/smsd/pgsql.rst @@ -0,0 +1,58 @@ +.. _gammu-smsd-pgsql: + +PostgreSQL Backend +================== + +Description +----------- + +PGSQL backend stores all data in a `PostgreSQL`_ database server, which +parameters are defined by configuration (see :ref:`gammu-smsdrc` for description of +configuration options). + +For tables description see :ref:`gammu-smsd-tables`. + +This backend is based on :ref:`gammu-smsd-sql`. + +.. _PostgreSQL: https://www.postgresql.org/ + +Configuration +------------- + +Before running :ref:`gammu-smsd` you need to create necessary tables in the +database, which is described below. + +The configuration file then can look like: + +.. code-block:: ini + + [smsd] + service = sql + driver = native_pgsql + host = localhost + +.. seealso:: :ref:`gammu-smsdrc` + +.. _pgsql-create: + +Creating tables for PostgreSQL +------------------------------ + +SQL script for creating tables in PostgreSQL database: + +.. literalinclude:: ../../sql/pgsql.sql + :language: sql + +.. note:: + + You can find the script in :file:`docs/sql/pgsql.sql` as well. + +Upgrading tables +---------------- + +The easiest way to upgrade database structure is to backup old one and start +with creating new one based on example above. + +For upgrading existing database, you can use changes described in +:ref:`smsd-tables-history` and then manually update ``Version`` field in +``gammu`` table. diff --git a/docs/manual/smsd/run.rst b/docs/manual/smsd/run.rst new file mode 100644 index 0000000..7fcd913 --- /dev/null +++ b/docs/manual/smsd/run.rst @@ -0,0 +1,168 @@ +.. _gammu-smsd-run: + +RunOnReceive Directive +====================== + +Description +----------- + +Gammu SMSD can be configured by :config:option:`RunOnReceive` directive (see +:ref:`gammu-smsdrc` for details) to run defined program after receiving +every message. It can receive single message or more messages, which are parts +of one multipart message. + +This parameter is executed through shell, so you might need to escape some +special characters and you can include any number of parameters. Additionally +parameters with identifiers of received messages are appended to the command +line. The identifiers depend on used service backend, typically it is ID of +inserted row for database backends or file name for file based backends. + +Gammu SMSD waits for the script to terminate. If you make some time consuming +there, it will make SMSD not receive new messages. However to limit breakage +from this situation, the waiting time is limited to two minutes. After this +time SMSD will continue in normal operation and might execute your script +again. + +.. note:: + + All input and output file descriptors are closed when this program is + invoked, so you have to ensure to open files on your own. + +Environment +----------- + +.. versionadded:: 1.28.0 + +Program is executed with environment which contains lot of information about +the message. You can use it together with NULL service (see +:ref:`gammu-smsd-null`) to implement completely own processing of messages. + +Global variables +++++++++++++++++ + +.. envvar:: SMS_MESSAGES + + Number of physical messages received. + +.. envvar:: DECODED_PARTS + + Number of decoded message parts. + +.. envvar:: PHONE_ID + + .. versionadded:: 1.38.2 + + Value of :config:option:`PhoneID`. Useful when running multiple instances + (see :ref:`smsd-multi`). + +Per message variables ++++++++++++++++++++++ + +The variables further described as ``SMS_1_...`` are generated for each physical +message, where 1 is replaced by current number of message. + +.. envvar:: SMS_1_CLASS + + Class of message. + +.. envvar:: SMS_1_NUMBER + + Sender number. + +.. envvar:: SMS_1_TEXT + + Message text. Text is not available for 8-bit binary messages. + +.. envvar:: SMS_1_REFERENCE + + .. versionadded:: 1.38.5 + + Message Reference. If delivery status received, this variable contains TPMR of original message + +Per part variables +++++++++++++++++++ + +The variables further described as ``DECODED_1_...`` are generated for each message +part, where 1 is replaced by current number of part. Set are only those +variables whose content is present in the message. + +.. envvar:: DECODED_1_TEXT + + Decoded long message text. + +.. envvar:: DECODED_1_MMS_SENDER + + Sender of MMS indication message. + +.. envvar:: DECODED_1_MMS_TITLE + + title of MMS indication message. + +.. envvar:: DECODED_1_MMS_ADDRESS + + Address (URL) of MMS from MMS indication message. + +.. envvar:: DECODED_1_MMS_SIZE + + Size of MMS as specified in MMS indication message. + + +Examples +-------- + +Activating RunOnReceive ++++++++++++++++++++++++ + +To activate this feature you need to set :config:option:`RunOnReceive` in +the :ref:`gammu-smsdrc`. + +.. code-block:: ini + + [smsd] + RunOnReceive = /path/to/script.sh + +Processing messages from the files backend +++++++++++++++++++++++++++++++++++++++++++ + +Following script (if used as :config:option:`RunOnReceive` handler) passes +message data to other program. This works only with the :ref:`gammu-smsd-files`. + +.. literalinclude:: ../../../contrib/smsd-scripts/receive-files + :language: sh + +Invoking commands based on message text ++++++++++++++++++++++++++++++++++++++++ + +Following script (if used as :config:option:`RunOnReceive` handler) executes +given programs based on message text. + +.. literalinclude:: ../../../contrib/smsd-scripts/sms-commands + :language: sh + +Passing message text to program ++++++++++++++++++++++++++++++++ + +Following script (if used as :config:option:`RunOnReceive` handler) passes +message text and sender to external program. + +.. literalinclude:: ../../../contrib/smsd-scripts/receive-exec + :language: sh + +Passing MMS indication parameters to external program ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Following script (if used as :config:option:`RunOnReceive` handler) will write +information about each received MMS indication to the log file. Just replace +echo command with your own program to do custom processing. + +.. literalinclude:: ../../../contrib/smsd-scripts/receive-mms + :language: sh + +Processing message text in Python ++++++++++++++++++++++++++++++++++ + +Following script (if used as :config:option:`RunOnReceive` handler) written +in Python will concatenate all text from received message: + +.. literalinclude:: ../../../contrib/smsd-scripts/receive-python + :language: python diff --git a/docs/manual/smsd/smsd-interactions.dia b/docs/manual/smsd/smsd-interactions.dia new file mode 100644 index 0000000..87f2ef8 --- /dev/null +++ b/docs/manual/smsd/smsd-interactions.dia @@ -0,0 +1,949 @@ +<?xml version="1.0" encoding="UTF-8"?> +<dia:diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/"> + <dia:diagramdata> + <dia:attribute name="background"> + <dia:color val="#ffffff"/> + </dia:attribute> + <dia:attribute name="pagebreak"> + <dia:color val="#000099"/> + </dia:attribute> + <dia:attribute name="paper"> + <dia:composite type="paper"> + <dia:attribute name="name"> + <dia:string>#A4#</dia:string> + </dia:attribute> + <dia:attribute name="tmargin"> + <dia:real val="2.8222000598907471"/> + </dia:attribute> + <dia:attribute name="bmargin"> + <dia:real val="2.8222000598907471"/> + </dia:attribute> + <dia:attribute name="lmargin"> + <dia:real val="2.8222000598907471"/> + </dia:attribute> + <dia:attribute name="rmargin"> + <dia:real val="2.8222000598907471"/> + </dia:attribute> + <dia:attribute name="is_portrait"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="scaling"> + <dia:real val="1"/> + </dia:attribute> + <dia:attribute name="fitto"> + <dia:boolean val="false"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="grid"> + <dia:composite type="grid"> + <dia:attribute name="width_x"> + <dia:real val="1"/> + </dia:attribute> + <dia:attribute name="width_y"> + <dia:real val="1"/> + </dia:attribute> + <dia:attribute name="visible_x"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="visible_y"> + <dia:int val="1"/> + </dia:attribute> + <dia:composite type="color"/> + </dia:composite> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#d8e5e5"/> + </dia:attribute> + <dia:attribute name="guides"> + <dia:composite type="guides"> + <dia:attribute name="hguides"/> + <dia:attribute name="vguides"/> + </dia:composite> + </dia:attribute> + </dia:diagramdata> + <dia:layer name="PozadÃ" visible="true" active="true"> + <dia:object type="Sybase - Stable Queue" version="1" id="O0"> + <dia:attribute name="obj_pos"> + <dia:point val="20,15"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="19.95,14.95;25.0955,20.8179"/> + </dia:attribute> + <dia:attribute name="meta"> + <dia:composite type="dict"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="20,15"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="5.045454545454545"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="3.9642857142857149"/> + </dia:attribute> + <dia:attribute name="line_width"> + <dia:real val="0.10000000000000001"/> + </dia:attribute> + <dia:attribute name="line_colour"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="fill_colour"> + <dia:color val="#ffffff"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="line_style"> + <dia:enum val="0"/> + <dia:real val="1"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.10000000000000001"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Service storage +(eg. database)#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="22.5227,19.7445"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="flip_horizontal"> + <dia:boolean val="false"/> + </dia:attribute> + <dia:attribute name="flip_vertical"> + <dia:boolean val="false"/> + </dia:attribute> + <dia:attribute name="subscale"> + <dia:real val="1"/> + </dia:attribute> + </dia:object> + <dia:object type="Flowchart - Box" version="0" id="O1"> + <dia:attribute name="obj_pos"> + <dia:point val="33,7"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="32.95,6.95;41.05,11.05"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="33,7"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="8"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="4"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#gammu-smsd-inject#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="37,9.18"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + </dia:object> + <dia:object type="Flowchart - Box" version="0" id="O2"> + <dia:attribute name="obj_pos"> + <dia:point val="4,15"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="3.95,14.95;12.05,19.05"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="4,15"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="8"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="4"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#gammu-smsd#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="8,17.18"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + </dia:object> + <dia:object type="Flowchart - Box" version="0" id="O3"> + <dia:attribute name="obj_pos"> + <dia:point val="4,7"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="3.95,6.95;12.05,11.05"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="4,7"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="8"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="4"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#gammu-smsd-monitor#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="8,9.18"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + </dia:object> + <dia:object type="Flowchart - Box" version="0" id="O4"> + <dia:attribute name="obj_pos"> + <dia:point val="33,15"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="32.95,14.95;41.05,19.05"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="33,15"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="8"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="4"/> + </dia:attribute> + <dia:attribute name="border_width"> + <dia:real val="0.10000000149011612"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="line_style"> + <dia:enum val="4"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Kalkun +web frontend#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="37,16.78"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O5"> + <dia:attribute name="obj_pos"> + <dia:point val="8,11"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="7.6382,10.95;8.3618,15.05"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="8,11"/> + <dia:point val="8,15"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="start_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="start_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="start_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O3" connection="13"/> + <dia:connection handle="1" to="O2" connection="2"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O6"> + <dia:attribute name="obj_pos"> + <dia:point val="33,18"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="24.95,17.6382;33.05,18.3618"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="33,18"/> + <dia:point val="25,18"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="start_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="start_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="start_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O4" connection="9"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O7"> + <dia:attribute name="obj_pos"> + <dia:point val="12,16"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="11.95,15.6382;20.0637,16.3618"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="12,16"/> + <dia:point val="19.9519,16"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="end_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="end_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="end_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O8"> + <dia:attribute name="obj_pos"> + <dia:point val="33,9"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="23.907,8.93066;33.0693,15.0693"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="33,9"/> + <dia:point val="24,15"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="end_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="end_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="end_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O1" connection="7"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O9"> + <dia:attribute name="obj_pos"> + <dia:point val="25,15"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="25,14.42;25,15.1375"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>##</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="25,15"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="0"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="3"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O10"> + <dia:attribute name="obj_pos"> + <dia:point val="27,11"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="24.6887,10.2412;29.3113,11.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Inject messages +to send#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="27,10.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O11"> + <dia:attribute name="obj_pos"> + <dia:point val="15.976,16"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="13.9485,15.2412;18.0035,16.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Save received +messages#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="15.976,15.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O7" connection="0"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O12"> + <dia:attribute name="obj_pos"> + <dia:point val="15.976,18"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="13.6648,17.2413;18.2873,18.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Read messages +to send#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="15.976,17.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O16" connection="0"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O13"> + <dia:attribute name="obj_pos"> + <dia:point val="9,13"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="8.1475,12.2412;9.8525,13.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Read +status#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="9,12.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O14"> + <dia:attribute name="obj_pos"> + <dia:point val="29,16"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="26.6887,15.2412;31.3113,16.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Inject messages +to send#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="29,15.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O17" connection="0"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O15"> + <dia:attribute name="obj_pos"> + <dia:point val="29,18"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="26.9387,17.2413;31.0613,18.7587"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Read received +messages#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="29,17.8212"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O6" connection="0"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O16"> + <dia:attribute name="obj_pos"> + <dia:point val="12,18"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="11.95,17.6382;20.0019,18.3618"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="12,18"/> + <dia:point val="19.9519,18"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="start_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="start_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="start_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O2" connection="10"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O17"> + <dia:attribute name="obj_pos"> + <dia:point val="33,16"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="24.8882,15.6382;33.05,16.3618"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="33,16"/> + <dia:point val="25,16"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="end_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="end_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="end_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O4" connection="5"/> + </dia:connections> + </dia:object> + <dia:object type="Flowchart - Box" version="0" id="O18"> + <dia:attribute name="obj_pos"> + <dia:point val="4,23"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="3.95,22.95;12.05,27.05"/> + </dia:attribute> + <dia:attribute name="elem_corner"> + <dia:point val="4,23"/> + </dia:attribute> + <dia:attribute name="elem_width"> + <dia:real val="8"/> + </dia:attribute> + <dia:attribute name="elem_height"> + <dia:real val="4"/> + </dia:attribute> + <dia:attribute name="border_width"> + <dia:real val="0.10000000149011612"/> + </dia:attribute> + <dia:attribute name="show_background"> + <dia:boolean val="true"/> + </dia:attribute> + <dia:attribute name="line_style"> + <dia:enum val="1"/> + </dia:attribute> + <dia:attribute name="dashlength"> + <dia:real val="0.29999999999999999"/> + </dia:attribute> + <dia:attribute name="padding"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#GSM +modem#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="8,24.78"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O19"> + <dia:attribute name="obj_pos"> + <dia:point val="6,19"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="5.6382,18.95;6.3618,23.1118"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="6,19"/> + <dia:point val="6,23"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="end_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="end_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="end_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O2" connection="12"/> + <dia:connection handle="1" to="O18" connection="1"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Line" version="0" id="O20"> + <dia:attribute name="obj_pos"> + <dia:point val="10,23"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="9.6382,18.8882;10.3618,23.05"/> + </dia:attribute> + <dia:attribute name="conn_endpoints"> + <dia:point val="10,23"/> + <dia:point val="10,19"/> + </dia:attribute> + <dia:attribute name="numcp"> + <dia:int val="1"/> + </dia:attribute> + <dia:attribute name="end_arrow"> + <dia:enum val="22"/> + </dia:attribute> + <dia:attribute name="end_arrow_length"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:attribute name="end_arrow_width"> + <dia:real val="0.5"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O18" connection="3"/> + <dia:connection handle="1" to="O2" connection="14"/> + </dia:connections> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O21"> + <dia:attribute name="obj_pos"> + <dia:point val="12,21"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="10.5412,20.2143;13.4767,21.7857"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Incoming +messages#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="12,20.8123"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O22"> + <dia:attribute name="obj_pos"> + <dia:point val="4,21"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="2.54125,20.2143;5.47669,21.7857"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>#Outgoing +messages#</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="4,20.8123"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="1"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="2"/> + </dia:attribute> + </dia:object> + <dia:object type="Standard - Text" version="1" id="O23"> + <dia:attribute name="obj_pos"> + <dia:point val="37,17"/> + </dia:attribute> + <dia:attribute name="obj_bb"> + <dia:rectangle val="37,16.42;37,17.1375"/> + </dia:attribute> + <dia:attribute name="text"> + <dia:composite type="text"> + <dia:attribute name="string"> + <dia:string>##</dia:string> + </dia:attribute> + <dia:attribute name="font"> + <dia:font family="sans" style="0" name="Helvetica"/> + </dia:attribute> + <dia:attribute name="height"> + <dia:real val="0.80000000000000004"/> + </dia:attribute> + <dia:attribute name="pos"> + <dia:point val="37,17"/> + </dia:attribute> + <dia:attribute name="color"> + <dia:color val="#000000"/> + </dia:attribute> + <dia:attribute name="alignment"> + <dia:enum val="0"/> + </dia:attribute> + </dia:composite> + </dia:attribute> + <dia:attribute name="valign"> + <dia:enum val="3"/> + </dia:attribute> + <dia:connections> + <dia:connection handle="0" to="O4" connection="16"/> + </dia:connections> + </dia:object> + </dia:layer> +</dia:diagram> diff --git a/docs/manual/smsd/smsd-interactions.png b/docs/manual/smsd/smsd-interactions.png Binary files differnew file mode 100644 index 0000000..250af4a --- /dev/null +++ b/docs/manual/smsd/smsd-interactions.png diff --git a/docs/manual/smsd/smsd.rst b/docs/manual/smsd/smsd.rst new file mode 100644 index 0000000..6314add --- /dev/null +++ b/docs/manual/smsd/smsd.rst @@ -0,0 +1,271 @@ +.. _gammu-smsd: + +gammu-smsd +========== + +.. program:: gammu-smsd + +Synopsis +-------- + +.. code-block:: text + + gammu-smsd [OPTION]... + + +Description +----------- + +This manual page documents briefly the :program:`gammu-smsd` command. + +:program:`gammu-smsd` is a program that periodically scans GSM modem for +received messages, stores them in defined storage and also sends messages +enqueued in this storage. + +The daemon can reload configuration file after sending hangup signal (SIGHUP) +and properly terminates itself on SIGINT and SIGTERM. + +Program accepts following options (please note that long options might be not +accepted on some platforms): + +.. option:: -h, --help + + Shows help. + +.. option:: -v, --version + + Shows version information and compiled in features. + +.. option:: -c, --config=file + + Configuration file to use, default is /etc/gammu-smsdrc, on Windows there + is no default and configuration file path has to be always specified. + + If you run SMSD as a system daemon (or service), it is recommended to use + absolute path to configuration file as startup directory might be + different than you expect. + + See :ref:`gammu-smsdrc` for configuration file documentation. + +.. option:: -p, --pid=file + + Lock file for storing pid, empty for no locking. Not supported on Windows. + +.. option:: -U, --user=user + + Drop daemon privileges to chosen user after starting. + +.. option:: -G, --group=group + + Drop daemon privileges to chosen group after starting. + +.. option:: -d, --daemon + + Daemonize program on startup. Not supported on Windows. + +.. option:: -i, --install-service + + Installs SMSD as a Windows service. + +.. option:: -u, --uninstall-service + + Uninstalls SMSD as a Windows service. + +.. option:: -s, --start-service + + Starts SMSD Windows service. + +.. option:: -k, --stop-service + + Stops SMSD Windows service. + +.. option:: -f, --max-failures=count + + Terminate after defined number of failures. Use 0 to not terminate (this is default). + +.. option:: -X, --suicide=seconds + + Kills itself after number of seconds. + +.. option:: -S, --run-service + + Runs pogram as SMSD Windows service. This should not be used manually, but + only Windows Service manager should use this command. + +.. option:: -n, --service-name=name + + Defines name of a Windows service. Each service requires an unique name, + so if you want to run several SMSD instances, you have to name each + service differently. Default is "GammuSMSD". + +.. option:: -l, --use-log + + Use logging as configured in config file (default). + +.. option:: -L, --no-use-log + + Do not use logging as configured in config file. + +.. option:: -e, --install-event-log + + Installs Windows EventLog description to registry. + + .. versionadded:: 1.31.90 + +.. option:: -E, --uninstall-event-log + + Uninstalls Windows EventLog description to registry. + + .. versionadded:: 1.31.90 + +.. _gammu-smsd-signals: + +Signals +------- + +SMSD can be controlled using following POSIX signals (if your platform supports this): + +SIGHUP + Reload configuration and reconnect to phone. +SIGINT, SIGTERM + Gracefully shutdown the daemon. +SIGALRM + Used internally for :option:`gammu-smsd -X` +SIGUSR1 + Suspends SMSD operation, closing connection to phone and database. +SIGUSR2 + Resumes SMSD operation (after previous suspend). + +.. versionchanged:: 1.22.91 + Added support for SIGHUP. +.. versionchanged:: 1.22.95 + Added support for SIGALRM. +.. versionchanged:: 1.31.90 + Added support for SIGUSR1 and SIGUSR2. + +Examples +-------- + +Linux/Unix Examples ++++++++++++++++++++ + +Start SMSD as a daemon on Linux: + +.. code-block:: sh + + gammu-smsd --config /etc/gammu-smsdrc --pid /var/run/gammu-smsd.pid --daemon + +Start SMSD as a daemon on Linux with reduced privileges: + +.. code-block:: sh + + gammu-smsd --config /etc/gammu-smsdrc --pid /var/run/gammu-smsd.pid --daemon --user gammu --group gammu + +SMSD as a system wide daemon +++++++++++++++++++++++++++++ + +To use SMSD as a daemon, you might want to use init script which is shipped +with Gammu in contrib/init directory. It is not installed by default, either +install it manually or check INSTALL file for instructions. + +Under Windows 7 you might need to disable UAC (user account control) before +you will be able to install SMSD service. + +Windows Service Examples +++++++++++++++++++++++++ + +Install Gammu SMSD Windows service: + +.. code-block:: sh + + gammu-smsd.exe -c c:\Gammu\smsdrc -i + +Install two instances of SMSD Windows service: + +.. code-block:: sh + + gammu-smsd.exe -c c:\Gammu\smsdrc-1 -n Gammu-first-phone -i + + gammu-smsd.exe -c c:\Gammu\smsdrc-2 -n Gammu-second-phone -i + +To uninstall a Windows service: + +.. code-block:: sh + + gammu-smsd.exe -u + +Troubleshooting Windows Service ++++++++++++++++++++++++++++++++ + +If Gammu fails to start as a Windows service (you will usually get "Error +1053: The service did not respond to the start or control request in a timely +fashion"), first check your SMSD logs. If they do not contain any useful hint, +try starting SMSD manually with exactly same parameters as you installed the +service (without -i). + +For example the command line can look like: + +.. code-block:: sh + + gammu-smsd.exe -c smsdrc + +You now should be able to get errors from SMSD even if it fails to start as a +service. + +.. _gammu-smsd-suspend: + +Invoking Gammu and suspending SMSD +++++++++++++++++++++++++++++++++++ + +As you can not run Gammu and Gammu SMSD at same time on signle device, you can +workaround this limitation by suspending SMSD temporarily using `SIGUSR1` and +`SIGUSR2` signals (see also :ref:`gammu-smsd-signals`): + +.. code-block:: sh + + SMSD_PID=`pidof gammu-smsd` + if [ -z "$SMSD_PID" ] ; then + echo "Failed to figure out SMSD PID!" + else + kill -SIGUSR1 $SMSD_PID + gammu identify + kill -SIGUSR2 $SMSD_PID + fi + +Or even create a `gammu-safe` script: + +.. code-block:: sh + #!/bin/bash + SMSD_PID=`pidof gammu-smsd` + if [ -z "$SMSD_PID" ] ; then + gammu $@ + else + tty=$(lsof |grep -E "gammu-sms\s+$SMSD_PID\s+.*/dev/tty*"|awk {'print $NF'}) + kill -SIGUSR1 $SMSD_PID + while test "$(fuser $ttyfuser $tty 2> /dev/null|xargs)" = $SMSD_PID + do + sleep 1 + done + sleep 1 + gammu $@ + kill -SIGUSR2 $SMSD_PID + while test "$(fuser $ttyfuser $tty 2> /dev/null|xargs)" != $SMSD_PID + do + sleep 1 + done + sleep 1 + fi + + +Known Limitations +----------------- + +You can not use same phone by more programs in same time. However in case you +did not enable locking in :config:section:`[gammu]` section, it might be able +to start the communication with phone from more programs. In this case neither +of the programs will probably work, see :ref:`gammu-smsd-suspend` for +workaround. + +There is no way to detect that SMS message is reply to another by looking at +message headers. The only way to achieve this is to add some token to the +message and let the user include it in the message on reply. diff --git a/docs/manual/smsd/sql.rst b/docs/manual/smsd/sql.rst new file mode 100644 index 0000000..fd894e0 --- /dev/null +++ b/docs/manual/smsd/sql.rst @@ -0,0 +1,469 @@ +.. _gammu-smsd-sql: + +SQL Service +=========== + +Description +----------- + +SQL service stores all its data in database. It can use one of these SQL backends +(configuration option :config:option:`Driver` in smsd section): + +* ``native_mysql`` for :ref:`gammu-smsd-mysql` +* ``native_pgsql`` for :ref:`gammu-smsd-pgsql` +* ``odbc`` for :ref:`gammu-smsd-odbc` +* drivers supported by DBI for :ref:`gammu-smsd-dbi`, which include: + * ``sqlite3`` - for SQLite 3 + * ``mysql`` - for MySQL + * ``pgsql`` - for PostgeSQL + * ``freetds`` - for MS SQL Server or Sybase + +SQL connection parameters +------------------------- + +Common for all backends: + +* :config:option:`User` - user connecting to database +* :config:option:`Password` - password for connecting to database +* :config:option:`Host` - database host or data source name +* :config:option:`Database` - database name +* :config:option:`Driver` - ``native_mysql``, ``native_pgsql``, ``odbc`` or DBI one +* :config:option:`SQL` - SQL dialect to use + +Specific for DBI: + +* :config:option:`DriversPath` - path to DBI drivers +* :config:option:`DBDir` - sqlite/sqlite3 directory with database + +.. seealso:: The variables are fully described in :ref:`gammurc` documentation. + +.. _Configurable tables: + +Tables +------ + +.. versionadded:: 1.37.1 + +You can customize name of all tables in the :config:section:`[tables]`. The SQL +queries will reflect this, so it's enough to change table name in this section. + +.. config:option:: gammu + + Name of the :ref:`gammu-table` table. + +.. config:option:: inbox + + Name of the :ref:`inbox` table. + +.. config:option:: sentitems + + Name of the :ref:`sentitems` table. + +.. config:option:: outbox + + Name of the :ref:`outbox` table. + +.. config:option:: outbox_multipart + + Name of the :ref:`outbox_multipart` table. + +.. config:option:: phones + + Name of the :ref:`phones` table. + +You can change any table name using these: + +.. code-block:: ini + + [tables] + inbox = special_inbox + +.. _SQL Queries: + +SQL Queries +----------- + +Almost all queries are configurable. You can edit them in +:config:section:`[sql]` section. There are several variables used in SQL +queries. We can separate them into three groups: + +* phone specific, which can be used in every query, see :ref:`Phone Specific Parameters` +* SMS specific, which can be used in queries which works with SMS messages, see :ref:`SMS Specific Parameters` +* query specific, which are numeric and are specific only for given query (or set of queries), see :ref:`Configurable queries` + +.. _Phone Specific Parameters: + +Phone Specific Parameters ++++++++++++++++++++++++++ + +``%I`` + IMEI of phone +``%S`` + SIM IMSI +``%P`` + PHONE ID (hostname) +``%N`` + client name (eg. Gammu 1.12.3) +``%O`` + network code +``%M`` + network name + + +.. _SMS Specific Parameters: + +SMS Specific Parameters ++++++++++++++++++++++++ + +``%R`` + remote number [#f1]_ +``%C`` + delivery datetime +``%e`` + delivery status on receiving or status error on sending +``%t`` + message reference +``%d`` + receiving datetime for received sms +``%E`` + encoded text of SMS +``%c`` + SMS coding (ie 8bit or UnicodeNoCompression) +``%F`` + sms centre number +``%u`` + UDH header +``%x`` + class +``%T`` + decoded SMS text +``%A`` + CreatorID of SMS (sending sms) +``%V`` + relative validity + +.. [#f1] Sender number for received messages (insert to inbox or delivery notifications), destination otherwise. + +.. _Configurable queries: + +Configurable queries +-------------------- + +All configurable queries can be set in :config:section:`[sql]` section. Sequence of rows in selects are mandatory. + +All default queries noted here are noted for MySQL. Actual time and time addition +are selected for default queries during initialization. + +.. config:option:: delete_phone + + Deletes phone from database. + + Default value: + + .. code-block:: sql + + DELETE FROM phones WHERE IMEI = %I + +.. config:option:: insert_phone + + Inserts phone to database. + + Default value: + + .. code-block:: sql + + INSERT INTO phones (IMEI, ID, Send, Receive, InsertIntoDB, TimeOut, Client, Battery, Signal) + VALUES (%I, %P, %1, %2, NOW(), (NOW() + INTERVAL 10 SECOND) + 0, %N, -1, -1) + + Query specific parameters: + + ``%1`` + enable send (yes or no) - configuration option Send + ``%2`` + enable receive (yes or no) - configuration option Receive + +.. config:option:: save_inbox_sms_select + + Select message for update delivery status. + + Default value: + + .. code-block:: sql + + SELECT ID, Status, SendingDateTime, DeliveryDateTime, SMSCNumber FROM sentitems + WHERE DeliveryDateTime IS NULL AND SenderID = %P AND TPMR = %t AND DestinationNumber = %R + +.. config:option:: save_inbox_sms_update_delivered + + Update message delivery status if message was delivered. + + Default value: + + .. code-block:: sql + + UPDATE sentitems SET DeliveryDateTime = %C, Status = %1, StatusError = %e WHERE ID = %2 AND TPMR = %t + + Query specific parameters: + + ``%1`` + delivery status returned by GSM network + ``%2`` + ID of message + +.. config:option:: save_inbox_sms_update + + Update message if there is an delivery error. + + Default value: + + .. code-block:: sql + + UPDATE sentitems SET Status = %1, StatusError = %e WHERE ID = %2 AND TPMR = %t + + Query specific parameters: + + ``%1`` + delivery status returned by GSM network + ``%2`` + ID of message + +.. config:option:: save_inbox_sms_insert + + Insert received message. + + Default value: + + .. code-block:: sql + + INSERT INTO inbox (ReceivingDateTime, Text, SenderNumber, Coding, SMSCNumber, UDH, + Class, TextDecoded, RecipientID) VALUES (%d, %E, %R, %c, %F, %u, %x, %T, %P) + +.. config:option:: update_received + + Update statistics after receiving message. + + Default value: + + .. code-block:: sql + + UPDATE phones SET Received = Received + 1 WHERE IMEI = %I + +.. config:option:: refresh_send_status + + Update messages in outbox. + + Default value: + + .. code-block:: sql + + UPDATE outbox SET SendingTimeOut = (NOW() + INTERVAL 60 SECOND) + 0 + WHERE ID = %1 AND (SendingTimeOut < NOW() OR SendingTimeOut IS NULL) + + The default query calculates sending timeout based on :config:option:`LoopSleep` + value. + + Query specific parameters: + + ``%1`` + ID of message + +.. config:option:: find_outbox_sms_id + + Find sms messages for sending. + + Default value: + + .. code-block:: sql + + SELECT ID, InsertIntoDB, SendingDateTime, SenderID FROM outbox + WHERE SendingDateTime < NOW() AND SendingTimeOut < NOW() AND + SendBefore >= CURTIME() AND SendAfter <= CURTIME() AND + ( SenderID is NULL OR SenderID = '' OR SenderID = %P ) ORDER BY InsertIntoDB ASC LIMIT %1 + + Query specific parameters: + + ``%1`` + limit of sms messages sended in one walk in loop + +.. config:option:: find_outbox_body + + Select body of message. + + Default value: + + .. code-block:: sql + + SELECT Text, Coding, UDH, Class, TextDecoded, ID, DestinationNumber, MultiPart, + RelativeValidity, DeliveryReport, CreatorID FROM outbox WHERE ID=%1 + + Query specific parameters: + + ``%1`` + ID of message + +.. config:option:: find_outbox_multipart + + Select remaining parts of sms message. + + Default value: + + .. code-block:: sql + + SELECT Text, Coding, UDH, Class, TextDecoded, ID, SequencePosition + FROM outbox_multipart WHERE ID=%1 AND SequencePosition=%2 + + Query specific parameters: + + ``%1`` + ID of message + ``%2`` + Number of multipart message + +.. config:option:: delete_outbox + + Remove messages from outbox after threir successful send. + + Default value: + + .. code-block:: sql + + DELETE FROM outbox WHERE ID=%1 + + Query specific parameters: + + ``%1`` + ID of message + +.. config:option:: delete_outbox_multipart + + Remove messages from outbox_multipart after threir successful send. + + Default value: + + .. code-block:: sql + + DELETE FROM outbox_multipart WHERE ID=%1 + + Query specific parameters: + + ``%1`` + ID of message + +.. config:option:: create_outbox + + Create message (insert to outbox). + + Default value: + + .. code-block:: sql + + INSERT INTO outbox (CreatorID, SenderID, DeliveryReport, MultiPart, + InsertIntoDB, Text, DestinationNumber, RelativeValidity, Coding, UDH, Class, + TextDecoded) VALUES (%1, %P, %2, %3, NOW(), %E, %R, %V, %c, %u, %x, %T) + + Query specific parameters: + + ``%1`` + creator of message + ``%2`` + delivery status report - yes/default + ``%3`` + multipart - FALSE/TRUE + ``%4`` + Part (part number) + ``%5`` + ID of message + +.. config:option:: create_outbox_multipart + + Create message remaining parts. + + Default value: + + .. code-block:: sql + + INSERT INTO outbox_multipart (SequencePosition, Text, Coding, UDH, Class, + TextDecoded, ID) VALUES (%4, %E, %c, %u, %x, %T, %5) + + Query specific parameters: + + ``%1`` + creator of message + ``%2`` + delivery status report - yes/default + ``%3`` + multipart - FALSE/TRUE + ``%4`` + Part (part number) + ``%5`` + ID of message + +.. config:option:: add_sent_info + + Insert to sentitems. + + Default value: + + .. code-block:: sql + + INSERT INTO sentitems (CreatorID,ID,SequencePosition,Status,SendingDateTime, + SMSCNumber, TPMR, SenderID,Text,DestinationNumber,Coding,UDH,Class,TextDecoded, + InsertIntoDB,RelativeValidity) + VALUES (%A, %1, %2, %3, NOW(), %F, %4, %P, %E, %R, %c, %u, %x, %T, %5, %V) + + Query specific parameters: + + ``%1`` + ID of sms message + ``%2`` + part number (for multipart sms) + ``%3`` + message state (SendingError, Error, SendingOK, SendingOKNoReport) + ``%4`` + message reference (TPMR) + ``%5`` + time when inserted in db + +.. config:option:: update_sent + + Update sent statistics after sending message. + + Default value: + + .. code-block:: sql + + UPDATE phones SET Sent= Sent + 1 WHERE IMEI = %I + +.. config:option:: refresh_phone_status + + Update phone status (battery, signal). + + Default value: + + .. code-block:: sql + + UPDATE phones SET TimeOut= (NOW() + INTERVAL 10 SECOND) + 0, + Battery = %1, Signal = %2 WHERE IMEI = %I + + Query specific parameters: + + ``%1`` + battery percent + ``%2`` + signal percent + +.. config:option:: update_retries + + Update number of retries for outbox message. + + .. code-block:: sql + + UPDATE outbox SET SendngTimeOut = (NOW() + INTERVAL 600 SECOND) + 0, + Retries = %2 WHERE ID = %1 + + Query specific parameters: + + ``%1`` + message ID + ``%2`` + number of retries diff --git a/docs/manual/smsd/tables.rst b/docs/manual/smsd/tables.rst new file mode 100644 index 0000000..8b06e79 --- /dev/null +++ b/docs/manual/smsd/tables.rst @@ -0,0 +1,625 @@ +.. _gammu-smsd-tables: + +SMSD Database Structure +======================= + +The backends themselves are described in their sections, this document +describes general database structure and required tables. + +More SMS daemons can share single database. If you do not specify PhoneID in +their configuration, all are treated equally and you have no guarantee which +one sends outgoing message. If you configure PhoneID and use it when inserting +message to the ``outbox`` table (:ref:`gammu-smsd-inject` does this), each SMS +daemon will have separate outbox queue. See also :ref:`smsd-multi`. + +Receiving of messages +--------------------- + +Received messages are stored in :ref:`inbox` table. + +Transmitting of messages +------------------------ + +Transmitted messages are read from table :ref:`outbox` and possible subsequent parts +of the same message from :ref:`outbox_multipart`. + +Description of tables +--------------------- + +.. _gammu-table: + +gammu ++++++ + +Table holding single field ``Version`` - version of a database schema. See +:ref:`smsd-tables-history` for details what has changed. + +.. _inbox: + +inbox ++++++ + +Table where received messages will be stored. + +Fields description: + +``UpdatedInDB`` (timestamp) + when somebody (daemon, user, etc.) updated it + +``ReceivingDateTime`` (timestamp) + when SMS was received + +``Text`` (text) + encoded SMS text (for all SMS) + +``SenderNumber`` (varchar(20)) + decoded SMS sender number + +``Coding`` (enum('Default_No_Compression', 'Unicode_No_Compression', '8bit', 'Default_Compression', 'Unicode_Compression')) + SMS text coding + +``UDH`` (text) + encoded User Data Header text + +``SMSCNumber`` (varchar(20)) + decoded SMSC number + +``Class`` (integer) + SMS class or \-1 (0 is flash SMS, 1 is normal one, 127 is USSD) + +``TextDecoded`` (varchar(160)) + decoded SMS text (for Default Alphabet/Unicode SMS) + +``ID`` (integer unsigned) + SMS identificator (for using with external applications) + +``RecipientID`` (text) + which Gammu daemon has added it + +``Processed`` (enum('false', 'true')) + you can use for marking, whether SMS was processed or not + +``Status`` (integer) + Status of incoming message. Currently only used for + ``Class`` 127 (USSD) messages with following meaning: + + ``1`` + Unknown status. + ``2`` + No action is needed, maybe network initiated USSD. + ``3`` + Reply is expected. + ``4`` + USSD dialog terminated. + ``5`` + Another client replied. + ``6`` + Operation not supported. + ``7`` + Network timeout. + + .. versionadded:: 1.38.5 + +.. _outbox: + +outbox +++++++ + +Messages enqueued for sending should be placed in this table. If message +is multipart, subsequent parts are stored in table :ref:`outbox_multipart`. + +Fields description: + +``UpdatedInDB`` (timestamp) + when somebody (daemon, user, etc.) updated it + +``InsertIntoDB`` (timestamp) + when message was inserted into database + +``SendingDateTime`` (timestamp) + set it to some value, when want to force sending after some planned time + +``SendBefore`` (time) + Send message before specified time, can be used to limit messages from + being sent in night. Default value is 23:59:59 + + .. versionadded:: 1.29.90 + +``SendAfter`` (time) + Send message after specified time, can be used to limit messages from + being sent in night. Default value is 00:00:00 + + .. versionadded:: 1.29.90 + +``Text`` (text) + SMS text encoded using hex values in proper coding. If you want to use + TextDecoded field, keep this NULL (or empty). + +``DestinationNumber`` (varchar(20)) + recipient number + +``Coding`` (enum('Default_No_Compression', 'Unicode_No_Compression', '8bit', 'Default_Compression', 'Unicode_Compression')) + SMS text coding + +``UDH`` (text) + User Data Header encoded using hex values which will be used for constructing + the message. Without this, message will be sent as plain text. + +``Class`` (integer) + SMS class or \-1 (0 is normal SMS, 1 is flash one, 127 is USSD) + +``TextDecoded`` (varchar(160)) + SMS text in "human readable" form + +``ID`` (integer unsigned) + SMS/SMS sequence ID + + Please note that this number has to be unique also for sentitems table, so + reusing message IDs might not be a good idea. + +``MultiPart`` (enum('false','true')) + info, whether there are more SMS from this sequence in outbox_multipart + +``RelativeValidity`` (integer) + SMS relative validity like encoded using GSM specs + +``SenderID`` (text) + which SMSD instance should send this one sequence, see + :config:option:`PhoneID` and :ref:`smsd-multi`. If blank, first SMSD who + sees this message first will process it. + +``SendingTimeOut`` (timestamp) + used by SMSD instance for own targets + +``DeliveryReport`` (enum('default','yes','no')) + when default is used, Delivery Report is used or not according to SMSD instance settings; yes forces Delivery Report. + +``CreatorID`` (text) + identification of program created the message + +``Retries`` (integer) + number of attempted retries when sending this message + +``Priority`` (integer) + priority of message, messages with higher priority are processed first + +``Status`` (enum('SendingOK', 'SendingOKNoReport', 'SendingError', 'DeliveryOK', 'DeliveryFailed', 'DeliveryPending', 'DeliveryUnknown', 'Error', 'Reserved')) + Status of message sending. SendingError means that phone failed to send the + message, Error indicates some other error while processing message. + + ``SendingOK`` + Message has been sent, waiting for delivery report. + ``SendingOKNoReport`` + Message has been sent without asking for delivery report. + ``SendingError`` + Sending has failed. + ``DeliveryOK`` + Delivery report arrived and reported success. + ``DeliveryFailed`` + Delivery report arrived and reports failure. + ``DeliveryPending`` + Delivery report announced pending deliver. + ``DeliveryUnknown`` + Delivery report reported unknown status. + ``Error`` + Some other error happened during sending (usually bug in SMSD). + ``Reserved`` + Initial value, meaning the status has not been set. + + .. versionadded:: 1.38.5 + +``StatusCode`` (integer) + GSM status code + + .. versionadded:: 1.38.5 + +.. _outbox_multipart: + +outbox_multipart +++++++++++++++++ + +Data for outgoing multipart messages. + +Fields description: + +``ID`` (integer unsigned) + the same meaning as values in outbox table +``Text`` (text) + the same meaning as values in outbox table +``Coding`` (enum('Default_No_Compression', 'Unicode_No_Compression', '8bit', 'Default_Compression', 'Unicode_Compression')) + the same meaning as values in outbox table +``UDH`` (text) + the same meaning as values in outbox table +``Class`` (integer) + the same meaning as values in outbox table +``TextDecoded`` (varchar(160)) + the same meaning as values in outbox table +``ID`` (integer unsigned) + the same meaning as values in outbox table + +``SequencePosition`` (integer) + info, what is SMS number in SMS sequence (start at 2, first part is in :ref:`outbox` + table). + +``Status`` (enum('SendingOK', 'SendingOKNoReport', 'SendingError', 'DeliveryOK', 'DeliveryFailed', 'DeliveryPending', 'DeliveryUnknown', 'Error', 'Reserved')) + Status of message sending. SendingError means that phone failed to send the + message, Error indicates some other error while processing message. + + ``SendingOK`` + Message has been sent, waiting for delivery report. + ``SendingOKNoReport`` + Message has been sent without asking for delivery report. + ``SendingError`` + Sending has failed. + ``DeliveryOK`` + Delivery report arrived and reported success. + ``DeliveryFailed`` + Delivery report arrived and reports failure. + ``DeliveryPending`` + Delivery report announced pending deliver. + ``DeliveryUnknown`` + Delivery report reported unknown status. + ``Error`` + Some other error happened during sending (usually bug in SMSD). + ``Reserved`` + Initial value, meaning the status has not been set. + + .. versionadded:: 1.38.5 + +``StatusCode`` (integer) + GSM status code + + .. versionadded:: 1.38.5 + +.. _phones: + +phones +++++++ + +Information about connected phones. This table is periodically refreshed and +you can get information such as battery or signal level from here. + +Fields description: + +``ID`` (text) + PhoneID value + +``UpdatedInDB`` (timestamp) + when this record has been updated + +``InsertIntoDB`` (timestamp) + when this record has been created (when phone has been connected) + +``TimeOut`` (timestamp) + when this record expires + +``Send`` (boolean) + indicates whether SMSD is sending messages, depends on configuration directive :config:option:`Send` + +``Receive`` (boolean) + indicates whether SMSD is receiving messages, depends on configuration directive :config:option:`Receive` + +``IMEI`` (text) + IMEI of phone + +``IMSI`` (text) + SIM IMSI + +``Client`` (text) + client name, usually string Gammu with version + +``Battery`` (integer) + battery level in percent (or \-1 if unknown) + +``Signal`` (integer) + signal level in percent (or \-1 if unknown) + +``Sent`` (integer) + Number of sent SMS messages (SMSD does not reset this counter, so it might + overflow). + +``Received`` (integer) + Number of received SMS messages (SMSD does not reset this counter, so it might + overflow). + +.. _sentitems: + +sentitems ++++++++++ + +Log of sent messages (and unsent ones with error code). Also if delivery +reports are enabled, message state is updated after receiving delivery report. + +Fields description: + +``UpdatedInDB`` (timestamp) + when somebody (daemon, user, etc.) updated it + +``InsertIntoDB`` (timestamp) + when message was inserted into database + +``SendingDateTime`` (timestamp) + when message has been sent + +``DeliveryDateTime`` (timestamp) + Time of receiving delivery report (if it has been enabled). + +``Status`` (enum('SendingOK', 'SendingOKNoReport', 'SendingError', 'DeliveryOK', 'DeliveryFailed', 'DeliveryPending', 'DeliveryUnknown', 'Error')) + Status of message sending. SendingError means that phone failed to send the + message, Error indicates some other error while processing message. + + ``SendingOK`` + Message has been sent, waiting for delivery report. + ``SendingOKNoReport`` + Message has been sent without asking for delivery report. + ``SendingError`` + Sending has failed. + ``DeliveryOK`` + Delivery report arrived and reported success. + ``DeliveryFailed`` + Delivery report arrived and reports failure. + ``DeliveryPending`` + Delivery report announced pending deliver. + ``DeliveryUnknown`` + Delivery report reported unknown status. + ``Error`` + Some other error happened during sending (usually bug in SMSD). + +``StatusError`` (integer) + Status of delivery from delivery report message, codes are defined in GSM + specification 03.40 section 9.2.3.15 (TP-Status). + +``Text`` (text) + SMS text encoded using hex values + +``DestinationNumber`` (varchar(20)) + decoded destination number for SMS + +``Coding`` (enum('Default_No_Compression', 'Unicode_No_Compression', '8bit', 'Default_Compression', 'Unicode_Compression')) + SMS text coding + +``UDH`` (text) + User Data Header encoded using hex values + +``SMSCNumber`` (varchar(20)) + decoded number of SMSC, which sent SMS + +``Class`` (integer) + SMS class or \-1 (0 is normal SMS, 1 is flash one, 127 is USSD) + +``TextDecoded`` (varchar(160)) + SMS text in "human readable" form + +``ID`` (integer unsigned) + SMS ID + +``SenderID`` (text) + which SMSD instance sent this one sequence, see :config:option:`PhoneID` + +``SequencePosition`` (integer) + SMS number in SMS sequence + +``TPMR`` (integer) + Message Reference like in GSM specs + +``RelativeValidity`` (integer) + SMS relative validity like encoded using GSM specs + +``CreatorID`` (text) + copied from CreatorID from outbox table + +``StatusCode`` (integer) + GSM status code + + .. versionadded:: 1.38.5 + + +.. _smsd-tables-history: + +History of database structure +----------------------------- + +.. note:: + + Testing versions (see :ref:`versioning`) do not have to keep same table + structure as final releases. Below mentioned versions are for + informational purposes only, you should always use stable versions in + production environment. + +History of schema versions: + +17 + + * Added ``Status`` field to :ref:`outbox` and :ref:`outbox_multipart`. + * Added ``StatusCode`` field to :ref:`sentitems`, :ref:`outbox` and :ref:`outbox_multipart`. + * Added ``Status`` field to :ref:`inbox`. + + .. versionchanged:: 1.38.5 + +16 + + * Removed unused ``daemons``, ``pbk`` and ``pbk_groups`` tables. + * Added primary key to the ``gammu`` table. + * Added ``Priority`` field to the :ref:`outbox`. + * Added ``IMSI`` field to the :ref:`phones`. + + .. versionchanged:: 1.37.90 + +15 + + Added ``Retries`` field to the :ref:`outbox`. + + .. versionchanged:: 1.36.7 + +14 + + Added ``NetCode`` and ``NetName`` fields. + + .. versionchanged:: 1.34.0 + +13 + Added ``SendBefore`` and ``SendAfter`` fields. + + .. versionchanged:: 1.29.90 + + Also PostgreSQL fields are now case sensitive (same as other backends). + + .. versionchanged:: 1.29.93 +12 + the changes only affect MySQL structure changing default values for + timestamps from ``0000-00-00 00:00:00`` to ``CURRENT_TIMESTAMP()`` by + using triggers, to update to this version, just execute triggers + definition at the end of SQL file. + + .. versionchanged:: 1.28.94 +11 + all fields for storing message text are no longer limited to 160 chars, + but are arbitrary length text fields. + + .. versionchanged:: 1.25.92 +10 + ``DeliveryDateTime`` is now NULL when message is not delivered, added several + indexes + + .. versionchanged:: 1.22.95 +9 + added sent/received counters to phones table + + .. versionchanged:: 1.22.93 +8 + Signal and battery state are now stored in database. + + .. versionchanged:: 1.20.94 +7 + Added ``CreatorID`` to several tables. + + .. versionchanged:: 1.07.00 +6 + Many fields in outbox can now be NULL. + + .. versionchanged:: 1.06.00 +5 + Introduced daemons table and various other changes. + + .. versionchanged:: 1.03.00 +3 + Introduced phones table and various other changes. + + .. versionchanged:: 0.98.0 + + +Examples +-------- + +Creating tables ++++++++++++++++ + +SQL scripts to create all needed tables for most databases are included in +Gammu documentation (docs/sql). As well as some PHP scripts interacting with +the database. + +For example to create SQLite tables, issue following command: + +.. code-block:: sh + + sqlite3 smsd.db < docs/sql/sqlite.sql + +Injecting a message using SQL ++++++++++++++++++++++++++++++ + +To send a message, you can either use :ref:`gammu-smsd-inject`, which does all the +magic for you, or you can insert the message manually. The simplest example is +short text message: + +.. code-block:: sql + + INSERT INTO outbox ( + DestinationNumber, + TextDecoded, + CreatorID, + Coding + ) VALUES ( + '800123465', + 'This is a SQL test message', + 'Program', + 'Default_No_Compression' + ); + +Please note usage of ``TextDecoded`` field, for ``Text`` field, you would have +to hex encode the unicode text: + +.. code-block:: sql + + INSERT INTO outbox ( + DestinationNumber, + Text, + CreatorID, + Coding + ) VALUES ( + '800123465', + '005400680069007300200069007300200061002000530051004c002000740065007300740020006d006500730073006100670065', + 'Program', + 'Default_No_Compression' + ); + +Injecting long message using SQL +++++++++++++++++++++++++++++++++ + +Inserting multipart messages is a bit more tricky, you need to construct also +UDH header and store it hexadecimally written into UDH field. Unless you have a +good reason to do this manually, use :ref:`gammu-smsd-inject`, C library +(:c:func:`SMSD_InjectSMS`) or Python library +(:meth:`gammu.smsd.SMSD.InjectSMS`). + +For long text message, the UDH starts with ``050003`` followed by byte as a +message reference (you can put any hex value there, but it should be **different +for each message**, ``D3`` in following example), byte for number of messages +(``02`` in example, it should be unique for each message you send to same phone +number) and byte for number of current message (``01`` for first message, +``02`` for second, etc.). + +I most cases, the mutlipart message has to be class 1. + +For example long text message of two parts could look like following: + +.. code-block:: sql + + INSERT INTO outbox ( + CreatorID, + MultiPart, + DestinationNumber, + UDH, + TextDecoded, + Coding, + Class + ) VALUES ( + 'Gammu 1.23.91', + 'true', + '123465', + '050003D30201', + 'Mqukqirip ya konej eqniu rejropocejor hugiygydewl tfej nrupxujob xuemymiyliralj. Te tvyjuh qaxumur ibewfoiws zuucoz tdygu gelum L ejqigqesykl kya jdytbez', + 'Default_No_Compression', + 1 + ) + + INSERT INTO outbox_multipart ( + SequencePosition, + UDH, + Class, + TextDecoded, + ID, + Coding, + Class + ) VALUES ( + 2, + '050003D30202', + 'u xewz qisubevumxyzk ufuylehyzc. Nse xobq dfolizygqysj t bvowsyhyhyemim ovutpapeaempye giuuwbib.', + <ID_OF_INSERTED_RECORD_IN_OUBOX_TABLE>, + 'Default_No_Compression', + 1 + ) + +.. note:: + + Adding UDH means that you have less space for text, in above example you + can use only 153 characters in single message. diff --git a/docs/manual/smsd/usage.rst b/docs/manual/smsd/usage.rst new file mode 100644 index 0000000..44d28fc --- /dev/null +++ b/docs/manual/smsd/usage.rst @@ -0,0 +1,61 @@ +Usage +===== + +This chapter will describe basic ways of using SMSD. It's use is not limited +to these, but they can give you overview of SMSD abilities. + +Storing Messages in Backend +--------------------------- + +The standard mode of operating SMSD. You simply configure backend service, and +all received messages will end up in it and any message you put into outbox +storage will be sent. + +Creating Messages to Send +------------------------- + +Creating of messages to send heavily depends on service backend you use. Most +of them support :ref:`gammu-smsd-inject`, which can be used to construct +the message, or you can just insert message manually to the backend storage. + +Alternatively you can use :c:func:`SMSD_InjectSMS` (from C) or using +:meth:`gammu.smsd.SMSD.InjectSMS` (from Python). + +Notification about Received Messages +------------------------------------ + +Once SMSD receives message and stores it in backend service, it can invoke +your own program to do any message processing, see :ref:`gammu-smsd-run`. + +Monitoring SMSD Status +---------------------- + +You can use :ref:`gammu-smsd-monitor` to monitor status of SMSD. It uses +shared memory segment to get current status of running SMSD. + +Alternatively you can get the same functionality from libGammu using +:c:func:`SMSD_GetStatus` or python-gammu using +:meth:`gammu.smsd.SMSD.GetStatus`. + +.. _reporting-bugs-smsd: + +Reporting Bugs +-------------- + +Please report bugs to <https://github.com/gammu/gammu/issues>. + +Before reporting a bug, please enable verbose logging in SMSD configuration +by :config:option:`DebugLevel` and :config:option:`LogFile`: + +.. code-block:: ini + + [gammu] + connection = your connection setting + port = your port name + logformat = textalldate + + [smsd] + debuglevel = 255 + logfile = smsd.log + +and include this verbose log within bug report. |
