public void SerializeVcf(Stream stream,
VCdVersion version = DEFAULT_VERSION,
ITimeZoneIDConverter?tzConverter = null,
VcfOptions options = VcfOptions.Default,
bool leaveStreamOpen = false)
=> VCard.SerializeVcf(stream, this, version, tzConverter, options, leaveStreamOpen);
public static void SerializeVcf(
this IEnumerable <VCard?> vCards,
Stream stream,
VCdVersion version = VCard.DEFAULT_VERSION,
VcfOptions options = VcfOptions.Default,
bool leaveStreamOpen = false)
=> VCard.SerializeVcf(stream, vCards, version, options: options, leaveStreamOpen: leaveStreamOpen);
/// <summary>
/// Serialisiert <paramref name="vCards"/> als einen <see cref="string"/>, der den Inhalt einer VCF-Datei darstellt.
/// </summary>
///
/// <param name="vCards">Die zu serialisierenden <see cref="VCard"/>-Objekte. Die Sammlung darf leer sein und <c>null</c>-Werte
/// enthalten.</param>
/// <param name="version">Die vCard-Version, die für die Serialisierung verwendet wird.</param>
/// <param name="tzConverter">Ein Objekt, das <see cref="ITimeZoneIDConverter"/> implementiert, um beim Schreiben von vCard 2.1 oder
/// vCard 3.0 Zeitzonennamen aus der "IANA time zone database" in UTC-Offsets umwandeln zu können, oder <c>null</c>, um
/// auf eine Umwandlung zu verzichten.</param>
/// <param name="options">Optionen für das Serialisieren. Die Flags können
/// kombiniert werden.</param>
///
/// <returns><paramref name="vCards"/>, serialisiert als <see cref="string"/>, der den Inhalt einer VCF-Datei darstellt.</returns>
///
/// <remarks>
/// <note type="caution">
/// Obwohl die Methode selbst threadsafe ist, sind es die an die Methode übergebenen
/// <see cref="VCard"/>-Objekte nicht. Sperren Sie den lesenden und schreibenden Zugriff auf diese
/// <see cref="VCard"/>-Objekte während der Ausführung dieser Methode!
/// </note>
/// <note type="tip">
/// Sie können der Methode auch ein einzelnes <see cref="VCard"/>-Objekt übergeben, da die <see cref="VCard"/>-Klasse
/// <see cref="IEnumerable{T}">IEnumerable<VCard></see> explizit implementiert.
/// </note>
///
/// <para>Die Methode serialisiert möglicherweise mehr
/// vCards, als sich ursprünglich Elemente in <paramref name="vCards"/> befanden. Dies geschieht, wenn eine
/// vCard 4.0 serialisiert wird und sich
/// in den Eigenschaften <see cref="VCard.Members"/> oder <see cref="VCard.Relations"/> eines <see cref="VCard"/>-Objekts
/// weitere <see cref="VCard"/>-Objekte in Form von <see cref="RelationVCardProperty"/>-Objekten befanden.
/// Diese <see cref="VCard"/>-Objekte werden von der Methode an <paramref name="vCards"/> angefügt.
/// </para>
///
/// <para>Ebenso verhält sich die Methode, wenn eine vCard 2.1 oder 3.0 mit der Option <see cref="VcfOptions.IncludeAgentAsSeparateVCard"/>
/// serialisiert wird und wenn sich in der Eigenschaft <see cref="VCard.Relations"/> eines <see cref="VCard"/>-Objekts ein
/// <see cref="RelationVCardProperty"/>-Objekt befindet, auf dessen <see cref="ParameterSection"/> in der Eigenschaft <see cref="ParameterSection.RelationType"/>
/// das Flag <see cref="RelationTypes.Agent"/> gesetzt ist.
/// </para>
///
/// <para>
/// Wenn eine vCard 4.0 serialisiert wird, ruft die Methode <see cref="VCard.Dereference(IEnumerable{VCard?})"/> auf bevor sie erfolgreich
/// zurückkehrt. Im Fall, dass die Methode eine Ausnahme wirft, ist dies nicht garantiert.
/// </para>
///
/// </remarks>
///
///
/// <seealso cref="ITimeZoneIDConverter"/>
///
/// <exception cref="ArgumentNullException"><paramref name="vCards"/> ist <c>null</c>.</exception>
/// <exception cref="ArgumentException"><paramref name="version"/> hat einen nichtdefinierten Wert.</exception>
/// <exception cref="OutOfMemoryException">Es ist nicht genug Speicher vorhanden.</exception>
public static string ToVcfString(
IEnumerable <VCard?> vCards,
VCdVersion version = VCard.DEFAULT_VERSION,
ITimeZoneIDConverter?tzConverter = null,
VcfOptions options = VcfOptions.Default)
{
if (vCards is null)
{
throw new ArgumentNullException(nameof(vCards));
}
using var stream = new MemoryStream();
VCard.SerializeVcf(stream, vCards, version, tzConverter, options, leaveStreamOpen: true);
stream.Position = 0;
using var reader = new StreamReader(stream, Encoding.UTF8);
return(reader.ReadToEnd());
}
