FolkerKinzel.VCards 1.4.2

FolkerKinzel.VCards

Full featured .NET-API to work with vCard files (*.vcf).

It enables you

• to load vcf files from the file system and to save them there,
• to serialize vcf files from and to Streams and
• to convert vCard files, that match the vCard-versions 2.1, 3.0 and 4.0, to each other.

Overview

How errors are handled

Parse errors are silently ignored.

The same is for errors, that occur serializing the vCard: Because of the different vCard-standards are not completely compliant, incompliant data is silently ignored when converting from one vCard-Standard to another. To minimize the data loss, the API tries to preserve incompliant data using well-known Non-Standard-Properties. The usage of such Non-Standard-Properties can be controlled via options (VcfOptions).

The data model explained

The data model used by this API is aligned to the vCard 4.0 standard (RFC6350). This means, every read vCard of version 2.1 and 3.0 is internally converted to vCard 4.0. When saved and serialized, they are converted back.

Class VCardProperty<T>

The data model of the class VCard based on classes, that are derived from VCardProperty<T>.

VCardProperty<T> exposes the following data:

public abstract class VCardProperty<T>
{
    public string? Group { get; set; }

    public ParameterSection Parameters { get; }

    public virtual T Value { get; protected set; }
}

This reflects the structure of a data row in a *.vcf-file:

group1.TEL;TYPE=home,voice;VALUE=uri:tel:+49-123-4567

In this example corresponds

• group1 to VCardProperty<T>.Group,
• TEL;TYPE=home,voice;VALUE=uri to VCardProperty<T>.Parameters and
• tel:+49-123-4567 to VCardProperty<T>.Value.

Naming Conventions

Most properties of class VCard are collections. It has to do with, that many properties are allowed to have more than one instance per vCard (e.g. phone numbers, e-mail addresses). Such properties are named in Plural.</para>

A special feature are properties whose name ends with "Views": These are properties, which actually is only one instance per vCard allowed, but vCard 4.0 enables you to have different versions of that single instance (e.g. in different languages). You must set the same AltID parameter on each of these versions.