# Card Conversion

VisualCard not only parses the standard VCard contacts, but it also supports conversion from different contact formats to their VCard 3.0 counterparts by parsing these formats and forming a VCard 3.0 representation to be parsed by VisualCard. The below supported types are as follows:

* Android `contacts2.db` from the contacts provider
* MeCard string used to generate QR codes

## Android `contacts2.db`

Using the `contacts2.db` file found in the contact provider's data files found under `/data/data/android.providers.contacts/databases`, you can convert this file to be parsable by VisualCard's VCard 3.0 parser.

You can invoke `GetContactsFromDb()` from the `AndroidContactsDb` class, provided that you provide a path to this file on your local computer's drive.

{% hint style="warning" %}
In the first glance, this sounds easy. However, you need to know how to obtain the `contacts2.db` file from the contacts provider, which is only possible by rooting your Android device.

If your ROM provides ADB root shell, like [LineageOS](https://lineageos.org/) and the like, you can connect your phone to your computer and install [platform-tools](https://developer.android.com/tools/releases/platform-tools) to install ADB.

If the file is not there in the above path, you may need to look for this file name under the user's data folder, such as `/data/user/0/com.android.providers.contacts/databases/contacts2.db` for most devices.

Furthermore, some stock ROMs, like Motorola, might store their contacts in `/data/user/0/com.motorola.blur.providers.contacts/databases/contacts2.db` instead.

After installing ADB to your PATH, run the following commands:

```shell-session
$ adb root
$ adb pull /data/data/android.providers.contacts/databases/contacts2.db path/to/contacts2.db
```

{% endhint %}

{% hint style="danger" %}
**Be cautious, because rooting will cause your warranty to be void. Latest devices also need to have their bootloader (a program responsible for starting Android) unlocked (OEM unlocking) before rooting process succeeds.**

***Unlocking the bootloader may cause your user data to be wiped.***

***In some cases, your device might fail to boot to Android if done incorrectly.***
{% endhint %}

`GetContactsFromDb()` returns a list of parsed vCard card instance classes. Below is an example of how to parse vCard contacts from Android's `contacts2.db`:

```csharp
// If you already have contacts2.db somewhere in your computer
Card[] contactsSpecific = AndroidContactsDb.GetContactsFromDb(args[0]);

// If you're running rooted Android and you need to parse from the system path
Card[] contactsSystem = AndroidContactsDb.GetContactsFromDb();
```

Below are the supported contact elements for the conversion (found under the `vnd.android.cursor.item` group):

| Android             | VCard 3.0                                   |
| ------------------- | ------------------------------------------- |
| `name`              | <p><code>N</code></p><p><code>FN</code></p> |
| `phone_v2`          | `TEL`                                       |
| `nickname`          | `NICKNAME`                                  |
| `email_v2`          | `EMAIL`                                     |
| `postal-address_v2` | `ADR`                                       |
| `im`                | `X-[AOL\|MSN\|QQ\|...]`                     |
| `organization`      | `ORG`                                       |
| `website`           | `URL`                                       |
| `sip_address`       | `IMPP`                                      |
| `note`              | `NOTE`                                      |
| `photo`             | `PHOTO`                                     |

{% hint style="danger" %}
Unless you implement some kind of root checker in your application and have a reason to parse contacts the root way, we advice you to use built-in Android functions within your code using [ContactsContract.Contacts](https://learn.microsoft.com/en-us/dotnet/api/android.provider.contactscontract.contacts).
{% endhint %}

{% hint style="danger" %}
This conversion is one-way, meaning that you can't generate `contacts2.db` due to how different Android versions use this database. We don't plan to implement a function that lets you generate `contacts2.db`.
{% endhint %}

## MeCard strings

MeCard is commonly used for scannable contacts, usually generated by the QR code generators. This is typically used so that smartphone owners can easily scan the contact's QR code to add the contact to the phone. This is faster than a person manually typing their phone number and their details on a pen and a paper.

In order to parse MeCard strings, you'll have to use the `GetContactsFromMeCardString()` function found in the `MeCard` class. Like the above converter, you can get contact information on a vCard class instantly.

This converter supports about anything a MeCard contact can have. Here are the supported types:

| MeCard     | VCard 3.0           |
| ---------- | ------------------- |
| `ADR`      | `ADR`               |
| `BDAY`     | `BDAY`              |
| `EMAIL`    | `EMAIL`             |
| `N`        | `N`                 |
| `NICKNAME` | `NICKNAME`          |
| `NOTE`     | `NOTE`              |
| `SOUND`    | `X-VISUALCARD-KANA` |
| `TEL`      | `TEL`               |
| `TEL-AV`   | `TEL;TYPE=VIDEO`    |
| `URL`      | `URL`               |

{% hint style="info" %}
`SOUND` on MeCard is defined in Japanese phonebooks as:

*Designates a text string to be set as the kana name in the phonebook.*

As there is no native equivalent of **Kana Name** in any of the vCard specifications, such as `KANA:[...]`, you can access this value after the conversion using the `X-VISUALCARD-KANA` property.
{% endhint %}

In addition to this, you can convert vCard instances that VisualCard uses to MeCard strings so that your QR code generator can easily make use of it to generate codes that can be scanned using your phone and other devices that support QR code scanning. Usually, modern devices come with QR scanning function within the device's `Camera` application.

To convert deserialized vCard instances to MeCard strings, you can use the `SaveCardToMeCardString()` function, passing it that instance. You can parse it with compatibility mode turned on, causing the converter to exclude the following properties that some older phonebooks that understand MeCard don't recognize:

* `TEL-AV`
* `NOTE`
* `URL`
* `NICKNAME`
