# 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

***

## <mark style="color:$primary;">Android</mark> <mark style="color:$primary;"></mark><mark style="color:$primary;">`contacts2.db`</mark>

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.

<details>

<summary>Getting a list of contacts</summary>

You can invoke `GetContactsFromDb()` from the `AndroidContactsDb` class by providing it a path to this file on your local computer's drive.

`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();
```

{% 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 %}

</details>

<details>

<summary>Supported contact elements for conversion</summary>

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" %}
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 %}

</details>

***

## <mark style="color:$primary;">MeCard strings</mark>

MeCard is commonly used for scannable contacts, usually generated with 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 pen and paper.

<details>

<summary>Obtaining vCard contacts from MeCard strings</summary>

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.

</details>

<details>

<summary>Supported contact elements for conversion</summary>

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 %}

</details>

<details>

<summary>Converting vCard instances to MeCard strings</summary>

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.

{% hint style="info" %}
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`
  {% endhint %}

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aptivi.gitbook.io/aptivi/visualcard-manual/usage/extra-features/card-conversion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.