Managing Business Cards (vCard, jCard, hCard, xCard)

The core components of the IT Hit business card library are ICard2, ICard3 and ICard4 interfaces that represent a business card in vCard v2.1, vCard v3.0 and vCard v4.0 formats. They provide a high-level access to business card properties and property parameters.

Similarly to ICard2, ICard3 and ICard4 interfaces many interfaces of business card library end with 2, 3 and 4 meaning they correspond with v2.1, v3.0 or v4.0 standards. Further, we will use 'X' instead of an interface version to refer to all 3 interfaces or members.

Creating a Business Card

To create a new business card use the CreateCardX methods in a CardFactory class, that creates a business card implementing ICardX interface:

ICard4 card = CardFactory.CreateCard4("IT Hit, Ltd");

IEmail4 email1 = card.Emails.CreateItem();
email1.Text = "info@ithit.com";
email1.PreferenceLevel = 1;
card.Emails.Add(email1); 

IEmail4 email2 = card.Emails.CreateItem();
email2.Text = "sales@ithit.com";
card.Emails.Add(email2);

string strCard = new vFormatter().Serialize(card);

Most properties in the business card can be present more than once and are derived from ICardPropertyList<T> interface or interfaced derived from it, such as ITextPropertyList<T>. You will use the ICardPropertyList<T>.CreateItem() method to create new properties and Add method to add it to the list.

Serializing Business Cards

To serialize a business card object to a string or stream use the vFormatter.Serialize() method:

ICard4 card = CardFactory.CreateCard4("My Corp");
IAddress4 adr = card.Addresses.CreateItem();
adr.Street = new[] { "1 Greentree" };
adr.Locality = new[] { "Sydnay" };
adr.Region = new[] { "New South Wales" };
adr.Country = new[] { "Australia" };
adr.PostalCode = new[] { "12345" };
adr.PreferenceLevel = 1;
adr.Types = new AddressType[] { AddressType.Work, AddressType.Postal };
card.Addresses.Add(adr);
string sCard = new vFormatter().Serialize(card);

To serialize/deserialize to/from iCalendar and vCard formats you will use the vFormatter class. For jCalendar/jCard you will use the jFormatter. For hCalendar/hCard - hFormatter . For xCalendar/xCard - xFormatter.

Deserializing Business Cards

To deserialize a business card from string or stream use the vFormatter.Deserialize() method. A string or stream passed as a parameter to this method can contain more than one business card object, so the deserialization methods return a list of business cards:

string sCards = File.ReadAllText("C:\\Card.vcf");
IEnumerable<ICard2> cards = new vFormatter().Deserialize(sCards).Cast<ICard2>();
foreach (ICard2 card2 in cards)
{
      Console.Write(card2.Version);

      ICard3 card3 = card2 as ICard3;
      Console.WriteLine(string.Join(" ", card3.Name.FamilyNames));
      Console.WriteLine(string.Join(" ", card3.Name.GivenNames));
}

Detecting vCard Version

You can find vCard version during deserialization. You can either try to cast ICard2 to ICard3 / ICard4 interfaces (all vCards support ICard2 interface) or to read the ICollabObject.Version property:

string strCards = File.ReadAllText("C:\\Card.vcf");
ICard2 card = (ICard2)new vFormatter().Deserialize(strCards).FirstOrDefault();

Console.WriteLine("Version stored in business card: " + card.Version.Text);

if (card is ICard4)
{
    Console.WriteLine("This is a business card v4.0");
}
else if (card is ICard3)
{
    Console.WriteLine("This is a business card v3.0");
}
else
{
    Console.WriteLine("This is a business card v2.1");
}

Next Article:

Accessing Raw Calendar and Business Card Data