VcardCard Class

Definition

Namespace: DataStandardizer.File.vCard

A vCard: an open list of properties, with typed accessors that don’t depend on the version the card was read from. See The common model and the versioned interfaces.

Syntax

public sealed partial class VcardCard : IVcard40Card, IVcard30Card, IVcard21Card

Constructors

Constructor Notes
VcardCard() A card with no properties. It needs at least one FN to conform to RFC 6350.

Properties

Property Type Notes
Properties IList<VcardContentLine> Every property in order, including unknown and X- properties, whether or not its value is valid. It can be changed. It doesn’t hold BEGIN, VERSION or END.
SourceVersion VcardVersion? The version the card was read from. null if it was built in code, or is a card held in an AGENT that was read with no VERSION.
Kind VcardKind What the card represents. With no KIND it is Individual, as RFC 6350 §6.1.4 says. RFC 6473 adds Application and RFC 6869 adds Device.
KindText string? The value of KIND as written, which holds any value that RFC 6350 and its extensions don’t define.
ExtensionProperties IReadOnlyList<VcardProperty<string>> The properties RFC 6350 and its extensions don’t define. Each value is as it appears in the content line.
Agents IReadOnlyList<VcardAgent> The RELATED properties with TYPE=agent, each a card, a URI or text. See VcardAgent.

Properties with at most one instance

Each is null if the card has none with a valid value. The setters replace every instance, including alternatives with the same ALTID, in the place of the first.

Property Name Value type Setter
Name N VcardName SetName(value), SetName(value, parameters)
Birthday BDAY VcardTypedValue (date-and-or-time or text) SetBirthday(value), SetBirthday(value, parameters)
Anniversary ANNIVERSARY VcardTypedValue (date-and-or-time or text) SetAnniversary(value), SetAnniversary(value, parameters)
Gender GENDER VcardGender SetGender(value), SetGender(value, parameters)
ProductId PRODID string SetProductId(value)
Revision REV VcardTimestamp SetRevision(value)
Uid UID VcardTypedValue (URI or text) SetUid(value)
BirthPlace BIRTHPLACE (RFC 6474 §2.1) VcardTypedValue (text or URI) SetBirthPlace(value), SetBirthPlace(value, parameters)
DeathPlace DEATHPLACE (RFC 6474 §2.2) VcardTypedValue (text or URI) SetDeathPlace(value), SetDeathPlace(value, parameters)
DeathDate DEATHDATE (RFC 6474 §2.3) VcardTypedValue (date-and-or-time or text) SetDeathDate(value), SetDeathDate(value, parameters)
Created CREATED (RFC 9554 §3.1) VcardTimestamp SetCreated(value)
DefaultLanguage LANGUAGE (RFC 9554 §3.3) Bcp47LanguageTag SetDefaultLanguage(value)
Mailer MAILER (RFC 2426 §3.3.3) string SetMailer(value)
Classification CLASS (RFC 2426 §3.7.1) string SetClassification(value)
SourceName NAME (RFC 2426 §5) string SetSourceName(value)
Profile PROFILE (RFC 2426 §5) string SetProfile(value)

SetKind takes a VcardKind, or the text of a value that RFC 6350 and its extensions don’t define. A value that isn’t initialised throws ArgumentException, and leaves the card as it was.

A setter throws InvalidOperationException if an instance has DERIVED=true, since RFC 9554 §4.4 says a client “MUST NOT update the property”. Remove it first to work the value out again. SetName also puts the components of RFC 9554 in the older components, as Addresses.Add does; see The common model and the versioned interfaces. Name leaves an instance with PHONETIC for last.

Properties with any number of instances

Each is a VcardPropertyList, a live view of Properties.

Property Name Value type
CalendarAccessUris CAPURI (RFC 2739 §2.3.3) Uri
Sources SOURCE Uri
Xml XML string
FormattedNames FN string
Nicknames NICKNAME IReadOnlyList<string>
Photos PHOTO VcardMediaUri
Addresses ADR VcardAddress
Telephones TEL VcardTypedValue (text or URI)
Emails EMAIL string
InstantMessaging IMPP Uri
Languages LANG Bcp47LanguageTag
TimeZones TZ VcardTypedValue (text, URI or UTC offset)
GeoLocations GEO Uri
Titles TITLE string
Roles ROLE string
Logos LOGO VcardMediaUri
Organizations ORG VcardOrganization
Members MEMBER Uri
Related RELATED VcardTypedValue (URI or text)
Categories CATEGORIES IReadOnlyList<string>
Notes NOTE string
Sounds SOUND VcardMediaUri
ClientPidMaps CLIENTPIDMAP VcardClientPidMap
Urls URL Uri
Keys KEY VcardTypedValue (URI or text)
FreeBusyUrls FBURL Uri
CalendarAddressUris CALADRURI Uri
CalendarUris CALURI Uri
Expertise EXPERTISE (RFC 6715 §2.1) string
Hobbies HOBBY (RFC 6715 §2.2) string
Interests INTEREST (RFC 6715 §2.3) string
OrganizationDirectories ORG-DIRECTORY (RFC 6715 §2.4) Uri
ContactUris CONTACT-URI (RFC 8605 §2.1) Uri
GrammaticalGenders GRAMGENDER (RFC 9554 §3.2) string: animate, common, feminine, inanimate, masculine, neuter, or a token
Pronouns PRONOUNS (RFC 9554 §3.4) string
SocialProfiles SOCIALPROFILE (RFC 9554 §3.5) VcardTypedValue (URI or text)

The typed members leave out a property whose value isn’t valid, which AllowInvalidValues lets a reader accept, and one with a CALSCALE other than gregorian, which RFC 6350 §5.8 says to ignore. Both stay in Properties.

System.Uri can’t hold more than 65519 characters on .NET Framework, so a member that gives a Uri, or a VcardTypedValue that holds one, leaves out a longer URI on every runtime, and adding one throws ArgumentException. It stays in Properties, and is read and written as usual. Photos, Logos and Sounds give a VcardMediaUri, which holds a URI of any length, such as the data: URI of a large photo.

Methods

Method Notes
AddAgent(card), AddAgent(uri) Adds a RELATED with TYPE=agent. A card is held as a copy, in the text of the property.
RemoveAgents() Removes every RELATED with TYPE=agent, and gives how many there were.
AsVersion21() The card as an IVcard21Card. It is this object, so a change through either is a change to both.
AsVersion30() The card as an IVcard30Card. It is this object, so a change through either is a change to both.
AsVersion40() The card as an IVcard40Card. It is this object, so a change through either is a change to both.
GetProperties(string name) The instances of a property, whether or not their values are valid.
GetPreferred(string name) The first instance with the lowest PREF; an instance without it is least preferred (RFC 6350 §5.3). null if there are none.
GetAlternatives(string name) The instances grouped by ALTID, in the order each group first appears (RFC 6350 §5.4). An instance without it is a group of its own.
GetDuplicatePropertyIds() The instances that have the same valid PROP-ID as another of the same name, as groups. RFC 9554 §4.7 leaves what to do about them to the application, so Validate() doesn’t report them.
RemoveProperties(string name) Removes every instance, and gives how many.
AddExtensionProperty(string name, string value) Adds a property that RFC 6350 and its extensions don’t define. There is an overload with parameters.
ResolveMembers(IEnumerable<VcardCard> cards) The cards of a set that the MEMBER properties link to by UID. One that doesn’t resolve, such as a mailto URI, is left out.
FindByUid(IEnumerable<VcardCard> cards, string uid) Static. The first card with a UID, compared as RFC 6350 §7.1.1 says. null if there is none.
Validate() Every VcardDiagnostic, without throwing for a problem in the card. An exception from a CharsetResolver of the caller’s isn’t caught.
Validate(version) What VcardWriter checks for that WriteVersion, including what the version can’t hold, as Lossy items.

Applies to

Targets netstandard1.1, netstandard2.0, netstandard2.1, and net10.0.

See also


This site uses Just the Docs, a documentation theme for Jekyll.