Contacts: the vCard typed view, Outlook contacts, and MS-OXVCARD

Three pieces, each usable alone:

• VCardView (RecursiveAI.OneMail.Calendar.VCard, package .Calendar): typed, read-only accessors over a VCARD component. Nothing is copied out of the tree; the bytes stay in the component, so a card written back untouched is byte-identical.
• MapiContact and MapiDistributionList (RecursiveAI.OneMail.Contacts): typed views over the property bag of an IPM.Contact or IPM.DistList message. They also hang off the shared view as MapiMailItem.Contact / .DistributionList.
• ContactToVCardConverter and VCardToContactConverter (RecursiveAI.OneMail.Conversion.OxVCard): MS-OXVCARD in both directions, as IItemConversion with a loss report (docs/conversion.md). Family names in the report: mapi for contact properties, vcard for card properties.

The vCard typed view

VCardView reads vCard 2.1, 3.0 and 4.0 alike. Accessors for a property that may repeat return every occurrence in file order (Names, Titles, Roles, Notes, Organizations, Birthdays, Anniversaries); the singular ones (Name, Note, Birthday) are the first.

• Typed values (VCardTyped): Value, Types (bare 2.1 parameters and TYPE= merged), Pref, AltId, Pid, Language, ValueType, Label, HasType(word). Used by Emails, Phones, Addresses, Urls, Impps, Related, Languages, TimeZones.
• Media (VCardMedia): PHOTO, LOGO, SOUND, KEY. IsInline, Uri, MediaType; Data is decoded the first time it is read, not at parse time. Base64 is read leniently: surplus or missing = padding is accepted, a character outside the alphabet makes Data null (the raw value is still on the property). A data: URI is inline.
• Dates: Birthday, Anniversary are VCardDate (year, month, day and optional time, each possibly absent: --0412, 1980-03). A VALUE=text date, or free text, is returned by BirthdayText / AnniversaryText and Birthday is null. RevisionTime is the REV instant.
• Others: Gender (sex and identity text), Geos (3.0 lat;lon, 4.0 geo: URI), Kind, Members, Extensions (X- properties, name and value), GetText(property) and Unescape(text) for a property the view has no accessor for.
• Text unescaping. In 3.0 and 4.0 a backslash before any character other than \\ \; \, n N is dropped and the character kept; 2.1 uses \\ and \; only and keeps everything else (ambiguity CV1). The content-line layer is unchanged: the raw value always keeps every backslash.

The Outlook contact view

MapiContact(MapiMessage) reads the properties of MS-OXOCNTC. Strings that are absent and strings that are empty both read as null.

Birthday and anniversary are dates. Outlook writes two properties: PidTagBirthday at 11:59 UTC of the date, and PidLidBirthdayLocal at 0:00 of the date. The local one is preferred; with only the first, the UTC date is taken. (A reader that shows the instant in a time zone west of UTC shows the evening before; that is the reader's choice, not a different date.)

MapiDistributionList(MapiMessage) reads PidLidDistributionListName and the members. When PidLidDistributionListStream (0x8064) is present it is the list of members (MS-OXOCNTC 2.2.2.1); otherwise the multi-valued PidLidDistributionListMembers (0x8055) with the one-off entries (0x8054) are used. A member is a DistributionListMember: Kind (OneOff, Contact for a wrapped entry ID of a contact slot, or a list), DisplayName, AddressType, Address, SmtpAddress, ContactSlot. A malformed entry is skipped, never thrown.

Contact to vCard (ContactToVCardConverter)

Options: Version (3.0 default, as MS-OXVCARD specifies; 4.0), IncludePhoto (true).

Text is escaped for 3.0/4.0 and a CR LF becomes \n. Every property of the source is either written or in the report. Codes:

vCard to contact (VCardToContactConverter)

The result is an IPM.Contact message; PidTagMessageClass, PidTagSensitivity (CLASS, default 0) and the derived properties of the next section are always set. The rules follow the examples of MS-OXVCARD 2.1.3 literally:

• TEL: every rule that matches fires. TYPE=VOICE,MSG,WORK fills Business and Other; a fax alone fills Primary Fax; pref fills Primary; no type fills Other. The second work (home) number goes to Business2 (Home2).
• ADR: with no recognised type, Business and Other; postal, dom, intl, parcel fill Other. pref sets PidLidPostalAddressId. A fourth address is AdditionalValueNotMapped; the extended-address part is merged into the street (AddressExtendedMerged).
• EMAIL: the first three fill the email slots (PidLidEmail1..3); more are AdditionalValueNotMapped.
• BDAY: PidTagBirthday is the date at 11:59 UTC, PidLidBirthdayLocal the date at 0:00 (TimeOfDayDropped when the card had a time). A partial date is PartialDate and not stored; X-MS-ANNIVERSARY and 4.0 ANNIVERSARY likewise.
• N components written as lists are stored as the comma-joined text; several organisation units are joined with ", " (OrgUnitsMerged).
• PHOTO: inline data of a supported type becomes the contact photo attachment; a URI is PhotoNotInline. KEY that is not X.509 is KeyNotX509.
• Properties with no home (UID, GEO, TZ, LANG, IMPP beyond the first, ...) are NoContactMapping; VERSION, PRODID and MAILER are VCardBookkeeping.

Derived on import (never a loss): PidTagSubject, PidTagNormalizedSubject, PidTagConversationTopic (copies of the display name), PidTagDisplayName when the card has no FN (composed from N), PidLidEmailNDisplayName and the formatted addresses, the mailing-address copy (PidTagPostalAddress, 0x3A26-0x3A2B), PidLidFileUnder / PidLidFileUnderId, PidTagMessageClass, and flags.

Fidelity

• Contact → vCard → contact: each mapped property comes back equal, or the report names it. "Equal" is the exact property value; what the check does not count as a loss is the derived set above.
• vCard → contact → vCard: the contact is stable on a second round; the first differs from the source only in the derived additions (an FN composed from N) and in what the report lists.

Checks

tools/contacts holds them; nothing there ships in a package.

Results are in compatibility.md. The fuzz target is vcard-view (a vCard, or a damaged contact or list, through the view and both conversions; the vCard written must parse again).