ProjectsWebsiteBlog

Card Parts

How do the card parts work in VisualCard?

Normally, cards in VisualCard have two types of parts that define a contact:

  • Strings (GetString())

  • Array of parts (GetPartsArray())

In the current version of VisualCard, the following parts are supported:

Key
Type
2.1
3.0
4.0
5.0

KIND

String

●

●

N

Array

●

●

●

●

FN

String

●

●

●

●

TEL

String

●

●

●

●

ADR

Array

●

●

●

●

EMAIL

String

●

●

●

●

ORG

Array

●

●

●

●

TITLE

String

●

●

●

●

URL

String

●

●

●

●

NOTE

String

●

●

●

●

PHOTO

Array

●

●

●

●

LOGO

Array

●

●

●

●

SOUND

Array

●

●

●

●

REV

Array

●

●

●

●

NICKNAME

String

●

●

●

BDAY

Array

●

●

●

●

MAILER

String

●

●

●

ROLE

String

●

●

●

●

CATEGORIES

Array

●

●

●

●

PRODID

String

●

●

●

SORT-STRING

String

●

●

TZ

String

●

●

●

●

GEO

String

●

●

●

●

IMPP

String

●

●

●

SOURCE

String

●

●

●

●

XML

Array

●

FBURL

String

●

●

CALURI

String

●

●

CALADRURI

String

●

●

X-NAME

Array

●

●

●

●

AGENT

Array

●

●

●

ANNIVERSARY

Array

●

●

GENDER

Array

●

●

LANG

String

●

●

KEY

Array

●

●

●

●

LABEL

String

●

●

●

CLASS

String

●

●

UID

String

●

●

●

CONTACT-URI

String

●

●

MEMBER

String

●

RELATED

String

●

CLIENTPIDMAP

Array

●

NAME

String

●

PROFILE

String

●

EXPERTISE

String

●

●

HOBBY

String

●

●

INTEREST

String

●

●

ORG-DIRECTORY

String

●

●

The following base types by all the properties that can be put into arrays are supported:

  • HOME, WORK, and PREF

  • X-nonstandard and IANA types

  • Extra types supported by some properties, such as ADR and TEL

Here are the extra types that the following properties support:

Property
Types

TEL

TEXT, VOICE, FAX, CELL, VIDEO, PAGER, TEXTPHONE, ISDN, CAR, MODEM, BBS, MSG, PREF, TLX, MMS

ADR

DOM, INTL, PARCEL, POSTAL

LABEL

DOM, INTL, PARCEL, POSTAL

EMAIL

AOL, APPLELINK, ATTMAIL, CIS, EWORLD, INTERNET, IBMMAIL, MCIMAIL, POWERSHARE, PRODIGY, TLX, X400, CELL

PHOTO

JPG, GIF, CGM, WMF, BMP,MET, PMB, DIB, PICT, TIFF, PS, PDF, JPEG, MPEG, MPEG2, AVI, QTIME, PNG, WEBP

LOGO

JPG, GIF, CGM, WMF, BMP, MET, PMB, DIB, PICT, TIFF, PS, PDF, JPEG, MPEG, MPEG2, AVI, QTIME, PNG, WEBP

SOUND

MP3, WAVE, PCM, AIFF, AAC

IMPP

SIP

The below sections describe how exactly to parse all the supported types.

You can access all extra X-named and IANA properties by calling GetPartsArray, passing it the ExtraInfo type as a generic type argument.

Strings

Strings in vCard and VisualCard are the simplest of the types that allow you to input just text that represent that property. The above table shows all the properties, and those that are listed as a String, such as CLASS, can be get as a string using a function called GetString(). You can also get a dictionary of a list of parsed strings using the Strings property.

This function returns one of the following strings:

  • An empty string

    • If the string is not supported in the contact's vCard version.

    • If the string is not defined in the contact's vCard instance.

    • If the string is explicitly blank.

  • "individual"

    • If the string is not defined in the contact's vCard 4.0 or 5.0 kind.

    • If the string is explicitly "individual" in the contact's vCard 4.0 or 5.0 kind.

  • A string value

    • If the string is defined, supported, and is not empty.

You can easily access the card kind using the CardKindStr property from a card instance. It's also available as an enumeration value via the CardKind property.

When using the above function, it returns an instance of ValueInfo<string> that contains the following properties:

  • Property: An instance of PropertyInfo that shows you a dissection of raw prefix, group, and values. It contains the following properties:

    • Arguments: An array of parsed ArgumentInfo instances that contains the following properties and functions:

      • Key: Argument key name

      • Values: An array of a tuple that describes the value case sensitivity and the unquoted value

      • AllValues: An array of unquoted values

      • MatchValue(): A function that lets you match a value

    • Value: Raw value, as it appears on a vCard representation

    • Prefix: Raw prefix, as it appears on a vCard representation

    • Group: Raw group, as it appears on a vCard representation

    • NestedGroups: Nested groups separated by a dot

  • AltId: Alternative ID. If it's not specified, it returns -1.

  • ElementTypes: Card element type (home, work, ...)

  • ValueType: Value type (usually set by VALUE=)

  • Group: Property group

  • NestedGroups: Nested groups for a property (separated by a dot)

  • Value: A string value

  • IsPreferred: Is this part preferred?

You can also use the following functions:

  • HasType(): Checks to see if this value has a specific type

Array of Parts

Parts that can be more than one part (i.e. can be put to an array and can exist more than once per vCard instance) exist in vCard. The above table shows all the properties that are listed as an Array. If they are listed as such, like TEL, you can get it using GetPartsArray(). You can also get a dictionary of a list of parsed parts array lists using the PartsArray property.

GetPartsArray() is a generic method. This means that you can specify one of the Info classes, as long as it represents a valid class that points to a valid part, such as TelephoneInfo. In this case, you'll have to call it like this:

// Either
Contact.GetPartsArray<TelephoneInfo>()

// or
Contact.GetPartsArray<TelephoneInfo>(PartsArrayEnum.Telephone)

You can directly get a value of a property without having to cast the resultant part to the correct part info class. The same base properties also apply to the normal Parts.

You can also get any parts array as a base, though you can't call the non-parameterized function against the base part, BaseCardPartInfo. You'll also have to cast the resultant part if you need to access something other than the base properties as mentioned above.

Contact.GetPartsArray<BaseCardPartInfo>(PartsArrayEnum.Telephone)

This function returns one of the following:

  • An empty array

    • If the parts array is not supported in the contact's vCard version

    • If the parts array is not defined in the contact's vCard instance

  • An array of parts

    • If the part is supported and defined in the contact's vCard instance

Any attempt to specify an incorrect type or enumeration in the second overload of GetPartsArray, such as Contact.GetPartsArray<AddressInfo>(PartsArrayEnum.Telephone), will throw an exception. However, it doesn't throw an exception in case BaseCardPartInfo is specified.

For preferred parts, their value of the IsPreferred property is true, assuming that the PREF type exists in such parts.

Getting a Blob Stream

Image parts, icon parts, sound parts, and key parts in a vCard instance allow you to get a blob stream from the encoded data that allows you to represent the actual data decoded from the BASE64 encoding as a blob. VisualCard exposes this feature to allow you to perform various operations on them, such as displaying contact pictures, saving sound parts as sound files, etc.

You can make use of this feature by invoking the GetBlobData() function from the VcardParserTools class.

This feature doesn't support non-blob values, such as an HTTPS URL to a logo file.

Nested cards

Sometimes, you may come across a vCard file that consists of multiple nested vCards. This, accompanied with the UID property, can be connected so that you can make relationships with cards. You can easily access all children cards within a property in your Card instance using a property called NestedCards. You can easily access the UID of a card via a UniqueId property.

When no UID property is specified in the vCard file, it's empty, so it's assumed to have no relationship with any card. Even if they have no UID, they can be nested.

Last updated