====== Intro ======
After Upgrading my mobile from SailfishOS 3.3.??? to 4.1.??? it figured out, that I've missed a backup with the OS tools. I've had only a backup of the filesystem.
Restoring most of the relevant information was simple. So it was no problem to get my Phonecalls, Messages and also Notes back.
Only two things didn't work. Contacts and Calendar. Allthough I can ignore my Calendar for the moment, also my contacts went away due to the fact, that there was a DB Schema change.

Luckily it was possible to start an emulator with OS 3.2.??? and restore the contacts within that emulator *but*,
all tryes to restore the data with Backuptools on that emulator or CalDav syncing or vcardconverter on OS level failed. For whatever reason it was not possible to restore that data.

====== Solution ======
My Solution here is to restore the data with a python script, exporting it from the Sqlite database to .vcf (vCard File).

**This only works for DB Structures of SailfishOS and was especially tested with DBs of OS version 3.2.X and 3.3.X**

<WRAP center round info 20%>
**Version 0.7 is the latest one.**
</WRAP>


===== Implementation =====
^function^implemented^
|Full Name|{{:icons8-haekchen-128.png?nolink&30|}}|
|First Name|{{:icons8-haekchen-128.png?nolink&30|}}|
|Last Name|{{:icons8-haekchen-128.png?nolink&30|}}|
|voice number|{{:icons8-haekchen-128.png?nolink&30|}}|
|fax number|{{:icons8-haekchen-128.png?nolink&30|}}|
|sms number|{{:icons8-haekchen-128.png?nolink&30|}}|
|e-mail addresses|{{:icons8-haekchen-128.png?nolink&30|}}|
|Organization name|{{:icons8-haekchen-128.png?nolink&30|}}|
|Organization parameters|{{:icons8-haekchen-128.png?nolink&30|}}|
|picture / foto|{{:icons8-haekchen-128.png?nolink&30|}}|
|address|{{:icons8-haekchen-128.png?nolink&30|}}|
|birthday|{{:icons8-loeschen-128.png?nolink&30|}}|
|URL|{{:icons8-loeschen-128.png?nolink&30|}}|
|Notes|{{:icons8-loeschen-128.png?nolink&30|}}|

===== Requirements =====
Install following Python Modules from PyPi
  * vObject
  * sqlite3
  * uuid

===== execution Notes =====
<code | Help>$ ./ContactRestore.py --help
usage: ContactRestore.py [-h] --db DB --output OUTPUT [--outsinglefile OUTSINGLEFILE] [--avatars AVATARS] [--debug]
                         [--version]

Restore SailfishOS 3 Contacts

optional arguments:
  -h, --help            show this help message and exit
  --db DB, -d DB        Sqlite3 Database file usually /home/{nemo,defaultuser}/.local/share/system/Contacts/qtcontacts-
                        sqlite/contacts.db
  --output OUTPUT, -o OUTPUT
                        Output directory for vcf files.'
  --outsinglefile OUTSINGLEFILE, -f OUTSINGLEFILE
                        If specefied, a file with that name is created under specified path, contianing all VCard
                        entrie. E.G. your address book
  --avatars AVATARS, -a AVATARS
                        Avatar directory. If present otherwise we skip this block of avatars, means, no avatars at all
  --debug               debugging output to identify problems
  --version             show program's version number and exit

This script was written to restore SailfishOS 3 contacts as VCF files. To see additional information, visit:
https://wiki.siningsoft.de/doku.php?id=sailfishos:projects:sailfish_contacts_rescue</code>

<code | Execution>
$ ./ContactRestore.py -d Testdata/contacts_with-Phone-Mobile-Fax-Pager-Assistent-Addresses.db -o Testdata/Output/
exporting SiSo Emulator to file Testdata/Output//SiSo_Emulator.vcf
exporting TestUserFirstName TestUserLastName to file Testdata/Output//TestUserFirstName_TestUserLastName.vcf
exporting 2nd Test *FN* User *LN* to file Testdata/Output//2nd_Test_*FN*_User_*LN*.vcf
exporting Phone Test to file Testdata/Output//Phone_Test.vcf
exporting Ludowig Adressuser to file Testdata/Output//Ludowig_Adressuser.vcf
</code>
====== Database ======
===== Schema ====
{{ :sailfishos:projects:contacts_os3-2_shema.png?nolink&400 |}}

===== table descriptions =====

==== Addresses ====
==== subTypes ====
The database is missing a table with subTypes to identify entries in Addresses.
To have a reference, here is a list of Types

^subType^vCard/vobject parameter^SailfishOS Contact label^
|Null|personal|Personal Address|
|0| |parcel|
|1|cell|Cell Phone|
|2|fax|Fax|
|3|pager|Pager|
|6|video|Video|
|10|??|Assistent|



==== PhoneNumbers ====
The Phonenumbers are listed in table **PhoneNumbers** with details from table **Details**.
Most interesting here is the type of number. Which is stored in table **PhoneNumbers** column **subTypes**.

Here is an example:

^detailId^contactId^phoneNumber^subTypes^normalizedNumber^detailId^contactId^detail^detailUri^linkedDetailUris^contexts^accessConstraints^provenance^modifiable^nonexportable^
|10|3|01719994445|1|19994445|10|3|PhoneNumber|NULL|NULL|Home|0|NULL|NULL|NULL|		
|11|3|040111222334|NULL|11222334|11|3|PhoneNumber|NULL|NULL|Home|0|NULL|NULL|NULL|		
|12|3|01720004443|1|20004443|12|3|PhoneNumber|NULL|NULL|Work|0|NULL|NULL|NULL|		
|13|3|040111222333|NULL|11222333|13|3|PhoneNumber|NULL|NULL|Work|0|NULL|NULL|NULL|		
|14|3|040111222335|2|11222335|14|3|PhoneNumber|NULL|NULL|Work|0|NULL|NULL|NULL|		

==== subTypes ====
The database is missing a table with subTypes to identify entries in PhoneNumbers for example.
To have a reference, here is a list of Types

^subType^vCard/vobject parameter^SailfishOS Contact label^
|Null|voice|Voice Phone|
|1|cell|Cell Phone|
|2|fax|Fax|
|3|pager|Pager|
|6|video|Video|
|10|??|Assistent|

Definition from RFC:
<WRAP center round box 60%>

   +-----------+-------------------------------------------------------+
   | Value     | Description                                           |
   +-----------+-------------------------------------------------------+
   | text      | Indicates that the telephone number supports text     |
   |           | messages (SMS).                                       |
   | voice     | Indicates a voice telephone number.                   |
   | fax       | Indicates a facsimile telephone number.               |
   | cell      | Indicates a cellular or mobile telephone number.      |
   | video     | Indicates a video conferencing telephone number.      |
   | pager     | Indicates a paging device telephone number.           |
   | textphone | Indicates a telecommunication device for people with  |
   |           | hearing or speech difficulties.                       |
   +-----------+-------------------------------------------------------+

      The default type is "voice".
</WRAP>


====== VCARD ======
Allthough it wasn't specified by python vobject lets assume we've to use VCard specification by RFC6350.

====== external Links ======
  * great Fileformat description: https://de.wikipedia.org/wiki/VCard
  * FileFormatdescription: https://docs.fileformat.com/email/vcf/#vcf-30-example
  * Python vobject: http://eventable.github.io/vobject/
  * vobject Code documentation: http://vobject.skyhouseconsulting.com/epydoc/
  * https://datatracker.ietf.org/doc/html/rfc6350

====== ToDo ======
  - fotos
  - birthday
  - missing parameters for names
  - URL with parameters

====== source ======
The sourcecode is located under [[svn://svn.siningsoft.de/Sailfish_Contacts_Restore]].
A free read access via svn will follow. If you're interested in submitting code as part of the development, a read/write access could be requested via [[sailfish@siningsoft.de]]

{{url>https://svn.siningsoft.de/listing.php?repname=Sailfish_Contacts_Restore noborder}}