# HG changeset patch
# User Mychaela Falconia <falcon@freecalypso.org>
# Date 1613367610 0
# Node ID 54800d2f5752897b6e80f9b945837e5136b2dd19
# Parent  a008f7a4bddf456e1ac79010c0f1e67860dea0c6
doc/User-oriented-commands: SMS manipulation documented

diff -r a008f7a4bddf -r 54800d2f5752 doc/User-oriented-commands
--- a/doc/User-oriented-commands	Mon Feb 15 04:57:51 2021 +0000
+++ b/doc/User-oriented-commands	Mon Feb 15 05:40:10 2021 +0000
@@ -311,6 +311,51 @@
 Manipulating stored SMS
 =======================
 
+The fundamental operating model of all message stores for SMS (whether SIM or
+phone-based) is that received messages accumulate (and possibly sent ones too,
+if they are stored in this manner), the limited available memory fills up, and
+then the user needs to clean out the accumulated messages, preferably also
+archiving them by transferring to a larger computer for longer-term storage.
+Given this fundamental operating model, we only need to provide commands for
+dumping the content of the message store and for cleaning it out - there is no
+real need to implement commands for writing messages into the store.
+
+The extent of special support for the SIM SMS store in fc-simtool is rather
+minimal because it just so happened that we already have external tools that do
+a major part of the work.  Some phone firmwares, particularly that of the
+Pirelli DP-L10 phone currently used by the Mother, implement their on-the-phone
+SMS storage by a way of a file in their local flash file system whose binary
+format just happens to be exactly the same as the binary format of SIM-based
+EF_SMS if all 176-byte records are simply abutted together in the host-based
+binary representation.  A few release cycles ago we added a new utility named
+pcm-sms-decode to our FreeCalypso host tools suite; this utility reads a binary
+file in this "EF_SMS records concat" format and performs the quite involved job
+of fully decoding all messages into human-readable form.  Given that we have
+this external pcm-sms-decode utility, all we need to do in fc-simtool is save
+all records of EF_SMS into a single concatenated binary file, and let
+pcm-sms-decode do the rest.
+
+Our dedicated commands for working with the SIM SMS store are as follows:
+
+save-sms-bin host-filename
+
+This command saves the full content of EF_SMS in the named file in the host file
+system in binary format, suitable for further decoding with pcm-sms-decode.
+
+sms-erase-all
+
+This command erases every record entry in EF_SMS.
+
+sms-erase-one rec
+
+This command erases the specified individual record in EF_SMS.
+
+sms-erase-range start-rec end-rec
+
+This command erases the specified range of records in EF_SMS.  The starting
+record must be identified by number (SIM record numbers are 1-based); the
+ending record argument may be either as a number or the "end" keyword.
+
 Manipulating SMS profiles
 =========================