.. _gammu-smsbackup:

SMS Backup Format
=================

The SMS backup format is text file encoded in current encoding of platform
where Gammu is running.

This file use ini file syntax, see :ref:`ini`.

Sections
--------

The file consists of sections, whose name starts with ``SMSBackup``. When
creating the backup file, three digits are appended to this text defining
order. While reading the backup, any part after ``SMSBackup`` text is ignored
and everything which begins with this is processed. So you can as well give
the section name ``SMSBackupFoo`` and it will be processed.

The number of messages in backup file is currently limited by
:c:data:`GSM_BACKUP_MAX_SMS` (100000 at time of writing this document).

``SMSBackup`` section
+++++++++++++++++++++

Each section interprets one physical SMS message (eg. one message part in case
of multipart messages).

Decoded text
~~~~~~~~~~~~

For SMS backups created by Gammu, there is a decoded text as a comment just
after the section name:

.. code-block:: ini

    [SMSBackup001]
    ; This is message text

The text can be split to more lines if it is too long or of original message
included new lines.

.. note::

    This is easiest way to get message text, however also the least reliable
    one, because it is stored in the comments in the file.

Variables
~~~~~~~~~

The following variables can be defined for each SMS:

``SMSC``
    Text representation of SMSC number, not used by Gammu if ``SMSCUnicode``
    exists.
``SMSCUnicode``
    Hex encoded UCS-2 string with SMSC number.
``Class``
    Message class.
``Sent``
    Timestamp, when message has been sent.
``PDU``
    Message type, one of:

    * ``Deliver`` - received message
    * ``Submit`` - message to send
    * ``Status_Report`` - message to send with delivery report
``DateTime``
    Timestamp of message (sent or received).
``RejectDuplicates``
    Whether receiver should reject duplicates.
``ReplaceMessage``
    ID of message to replace.
``MessageReference``
    Message reference number as generated by network.
``State``
    State of the message:

    * ``Read``
    * ``UnRead``
    * ``Sent``
    * ``UnSent``
``Number``
    Recipient number.
``Name``
    Name of the message.
``Length``
    Length of message text.
``Coding``
    Coding of the message:

    * ``8bit`` - binary message
    * ``Default`` - GSM encoding, up to 160 chars in message
    * ``Unicode`` - Unicode encoding, up to 70 chars in message
``Text00`` ... ``TextNN``
    Numbered parts of the message payload.
``Folder``
    ID of folder where the message was saved.
``UDH``
    User defined header of the message.


Example
-------

The backup of message can look like following:

.. code-block:: ini

    [SMSBackup000]
    #ABCDEFGHIJKLMNOPQRSTUVWXYZ
    #
    SMSC = "+4540590000"
    SMSCUnicode = 002B0034003500340030003500390030003000300030
    Sent = 20021201T025023
    State = UnRead
    Number = "+4522706947"
    NumberUnicode = 002B0034003500320032003700300036003900340037
    Name = ""
    NameUnicode =
    Text00 = 004100420043004400450046004700480049004A004B004C004D004E004F0050005100520053005400550056005700580059005A000A
    Coding = Default
    Folder = 1
    Length = 27
    Class = -1
    ReplySMSC = False
    RejectDuplicates = True
    ReplaceMessage = 0
    MessageReference = 0