Reading a VCard - george-haddad/cardme GitHub Wiki

VCards can be read in 2 ways

1. From a file (.vcf)
2. From a Java String object

CardMe uses the VCardEngine class to read files and Strings. Mainly using the parse() method. You may either provide the parse method with a Java File object (or an array of File objects) or a Java String object (or an array of String objects) and these objects will be read and parsed into a VCard.

File objects will be read from the file and parsed, while String objects are just parsed immediately. The VCardEngine accepts arrays of File or String as a convenience for users who know that their VCards are all of one type and want a quick and easy way to get back the results. The result will be an array of VCard objects in the order they were given in.

Any errors that occur while parsing the files will be embedded in the VCard object and can be accessed through VCard's hasErrors() and getErrors() methods. The errors are tracked on a per-VCard basis so you would have to iterate through your VCards and check if each one has errors or not.

There are 2 advanced options that can be set on the VCardEngine for reading:

1. Set Compatibility Mode
2. Set Forced Charset

1. Set Compatibility Mode

This method sets the VCardEngine's compatibility mode to use when parsing VCards. By default it will use RFC2426 mode unless it changes. This method can be invoked multiple times in order to change the mode.

2. Set Forced Charset

This method allows you to control the charset that VCardEngine will read Quoted-Printable strings in. Normally when a type's encoding is marked as QUOTED-PRINTABLE it is usually followed by a CHARSET parameter (if not then system default is assumed). So when decoding a quoted-printable string we do so with either the charset provided or the system charset if one is not provided. The forced charset option overrides the previous and will always decode the quoted-printable string using the specified charset.

Read 1 VCard from File

File vcardFile = new File("/home/george/john.vcf");
VCardEngine vcardEngine = new VCardEngine();
VCard vcard = vcardEngine.parse(vcardFile)

Read 1 VCard from String

VCardEngine vcardEngine = new VCardEngine();
VCard vcard = vcardEngine.parse("BEGIN:VCARD\nVERSION:3.0\nN:Doe;John;;;\nFN:John Doe\nEND:VCARD");

Read Many VCards from File

File[] vcardFiles = new File[5];
//Assume array is filled with meaningful paths to .vcf files
VCardEngine vcardEngine = new VCardEngine();
VCard[] vcards = vcardEngine.parse(vcardFiles);

Read Many VCards from String

String[] vcardStrings = new String[5];
//Assume array is filled with meaningful vcards
VCardEngine vcardEngine = new VCardEngine();
VCard[] vcards = vcardEngine.parse(vcardStrings);

Read Multiple VCards in 1 File/String

File bigVCardFile = new File("/home/george/big_list.vcf");
VCardEngine vcardEngine = new VCardEngine();
List<VCard> vcardsList = vcardEngine.parseMultiple(bigVCardFile);

Read VCards With Advanced Modes

VCardEngine vcardEngine = new VCardEngine();
vcardEngine.setCompatibilityMode(CompatibilityMode.RFC2426);
vcardEngine.setForcedCharset("UTF-8");
vcardEngine.parse(new File("/home/george/john.vcf"));

Read VCards & Check For Errors

File vcardFile = new File("/home/george/john.vcf");
VCardEngine vcardEngine = new VCardEngine();
VCard vcard = vcardEngine.parse(vcardFile)
if(vcard.hasErrors()) {
   List<VCardError> errors = vcard.getErrors();
   for(int j = 0; j < errors.size(); j++) {
	System.out.println(errors.get(j).getErrorMessage());
	System.out.println(errors.get(j).getSeverity());
	System.out.println(StringUtil.formatException(errors.get(j).getError()));
   }
}