VisualCard - Manual
ProjectsWebsiteBlog

Card Conversion

Converting your cards

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.

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 and the like, you can connect your phone to your computer and install 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:

$ adb root
$ adb pull /data/data/android.providers.contacts/databases/contacts2.db path/to/contacts2.db

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.

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:

// 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):

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.

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.

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:

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.

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

Last updated