VcardReader Class

Definition

Namespace: DataStandardizer.File.vCard

Reads vCard data (RFC 6350) into the card object model. A stream can hold many cards.

Syntax

public sealed class VcardReader : IDisposable, IAsyncDisposable

The data is read with a VcardContentLineReader, so the same options and rules apply to its content lines. On netstandard1.1 there are no asynchronous members, no file-path constructors, and the class doesn’t implement IAsyncDisposable.

Constructors

Constructor Notes
VcardReader(Stream vcardStream) Read as UTF-8. The stream is left open.
VcardReader(Stream vcardStream, VcardOptions options)  
VcardReader(string vcardFilePath) Opens the file for asynchronous I/O, and closes it when disposed, even before the first read.
VcardReader(string vcardFilePath, VcardOptions options)  
VcardReader(TextReader reader) The text reader is left open.
VcardReader(TextReader reader, VcardOptions options) options.Encoding must be null.

Properties

Each throws ObjectDisposedException once the reader is disposed.

Property Type Notes
CardsRead long The cards read so far, including any that failed a conformance check.
LinesRead long The logical lines read so far.
PhysicalLinesRead long The physical lines read so far.

Methods

Method Notes
ReadCard() The next card, or null at the end of the data.
ReadCards() The remaining cards, read as the sequence is enumerated.
ReadCardAsync(CancellationToken) Reports problems in the data through the task.
ReadCardsAsync(CancellationToken) The remaining cards as an IAsyncEnumerable<VcardCard>.
Dispose(), DisposeAsync() May be called more than once.

Errors

vCard 4.0, 3.0 and 2.1 are read, and one stream can hold any of them. A vCard 3.0 or 2.1 card is checked by the rules of its version, then converted to the canonical form of the model; see Versions and canonical forms. The card an AGENT of a 2.1 card holds, on the lines after it, is read with it. Any other VERSION throws VcardFileException as soon as it is read.

Problem What happens
A line that isn’t valid; a BEGIN or END that isn’t paired; a nested BEGIN; a VERSION other than 4.0, 3.0 or 2.1; data with no card VcardFileException, and the reader can’t continue.
A problem found in a card once it has been read, which the options don’t accept, including a card with no VERSION or with two VcardFileException, with the card index and the property in Data. Reading can continue with the next card.

Each card is checked as VcardCard.Validate does, and for the structure of its BEGIN, VERSION and END lines. The accommodations are AllowMissingRequiredProperties, AllowCardinalityViolations, AllowInvalidValues and AcceptLegacySyntax on VcardOptions. No option accepts a card with no VERSION or with two, or a vCard 4.0 card whose VERSION isn’t immediately after BEGIN:VCARD (RFC 6350 §3.3 and §6.7.9, RFC 2426 §5); the DiagnosticKind is then InvalidStructure.

An asynchronous read is canceled only when the token passed to it is canceled, whatever token the OperationCanceledException carries, or if it carries none. The task is then canceled. An OperationCanceledException from the text reader or stream while that token isn’t canceled faults the task, as any other failure of the source does. Either way, the reader can’t continue: later reads throw InvalidOperationException. During ReadCardsAsync, awaiting MoveNextAsync throws either one, but its task is canceled for both on every target, as an async iterator’s always is for an OperationCanceledException. Check the token to tell which it was.

Only one read may be in progress at a time.

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.