::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    smsExtractor.py     |   Version 1.3     |   FreeBSD License |   2022-06-21
    James Hendrie       |   hendrie.james@gmail.com
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

    1.  Description
    2.  Requirements / Restrictions
    3.  Installation / Uninstallation
    4.  Usage
    5.  Examples
    6.  Links



----------------------------------------
    1.  Description
----------------------------------------

    smsExtractor is a Python script that will extract SMS and MMS messages from
    one or more given XML files generated by the program 'SMS Backup & Restore',
    an Android app written by Ritesh Sahu.  His program can be found at:

    (Google Play store)
    http://play.google.com/store/apps/details?id=com.riteshsahu.SMSBackupRestore

    (Developer's site)
    http://android.riteshsahu.com/apps/sms-backup-restore

    When run, this script will create a directory named after the file being
    processed (mmsFile will yield mmsFile.d, for instance), after which it will
    extract all of the text messages, as well as a few different types of MMS
    file; specifically images (jpg, png, gif) and video (3gp).

    The text files will be placed into a 'messages' subdirectory with each phone
    number having its own conversation file.  The MMS files are all dumped into
    the 'files' subdirectory.



----------------------------------------
    2.  Requirements / Restrictions
----------------------------------------

    You're going to need Python version 3 for this to run.  It was written for
    and tested on Python version 3.4.3.

    Also, as mentioned above, the files being processed need to have been
    generated by the program 'SMS Backup & Restore'.  While the script might
    work with files generated elsewhere, it has not been tested with anything
    else and was not designed with anything else in mind.



----------------------------------------
    3.  Installation / Uninstallation
----------------------------------------

    From inside the directory to which you've extracted the archive's contents
    (same directory as this README file), run 'make install' using root
    privileges to install the program.  To uninstall, do the same except issue
    'make uninstall' as the command.


----------------------------------------
    4.  Usage
----------------------------------------

    Usage:  smsExtractor OPTION or FILE
    
    Options:
        -h or --help:       Print help text
        -V or --version:    Print version and author info
        -s or --subdirs:    Write files to each contact's own subdirectory
        -f or --force:      Write into extant files, overwrite files that exist
        -m or --multiple:   Write messages to multiple (individual) files



----------------------------------------
    5.  Examples
----------------------------------------

smsExtractor smsbackup01.xml
    Extracts the contents of smsbackup01.xml into directory 'smsbackup01.xml.d'.

smsExtractor smsbackup02.xml mmsbackup01.xml
    Similar to the above, except it extracts the contents of both files, each
    into their own directory.

smsExtractor *.xml
    I think you get the picture.


----------------------------------------
    6.  Links
----------------------------------------

    Project page:
        https://github.com/jahendrie/smsExtractor

    Programs page (personal site):
        http://www.someplacedumb.net/content/progs

    SMS Backup & Restore:
        http://android.riteshsahu.com/apps/sms-backup-restore