Class IptcData
Parsed IPTC-IIM datasets (IPTC-IIM 4.2), as news agencies, stock libraries and Lightroom write them next to XMP, with typed getters for the common ones. Shaped like ExifData: an unedited block writes back byte for byte; after an edit it is rebuilt in record and dataset order, record 1 first, with the coded character set (1:90) set to UTF-8 whenever a value is not plain ASCII.
public sealed class IptcData- Inheritance
-
IptcData
- Inherited Members
Examples
using Raster photo = Raster.Load("sideways.jpg");
IptcData iptc = photo.Metadata.Iptc ?? new IptcData();
iptc.Headline = "Harbour at dawn";
iptc.Keywords = [.. iptc.Keywords, "harbour", "Bergen"];
// Any dataset by its key; Add appends to the repeatable ones.
iptc.Set(IptcKey.City, "Bergen");
// Text that is not ASCII sets the coded character set (1:90) to UTF-8, so other programs read it right.
iptc.Caption = "Fishing boats at Bryggen, Bergen — first light";
foreach (IptcEntry entry in iptc.Entries)
{
Console.WriteLine($"{entry.Key} {entry.AsString()}");
}
// JPEG saves it in its Photoshop resource block (APP13), with the digest Photoshop and Lightroom check.
photo.Metadata.Iptc = iptc;
photo.Save("captioned.jpg");Constructors
IptcData()
Creates an empty block, to fill with Set(IptcKey, string) and Add(IptcKey, string).
public IptcData()Properties
Bylines
Gets or sets the creators (2:80), in order. Setting an empty list removes them.
public IReadOnlyList<string> Bylines { get; set; }Property Value
Exceptions
- ArgumentException
A name set is longer than 32 bytes in UTF-8.
Caption
public string? Caption { get; set; }Property Value
Exceptions
- ArgumentException
The value set is longer than 2,000 bytes in UTF-8.
Copyright
public string? Copyright { get; set; }Property Value
Exceptions
- ArgumentException
The value set is longer than 128 bytes in UTF-8.
Credit
public string? Credit { get; set; }Property Value
Exceptions
- ArgumentException
The value set is longer than 32 bytes in UTF-8.
DateCreated
Gets or sets when the content was created, from the date (2:55) and time (2:60): midnight UTC when there is no valid time, and null when there is no valid date. Setting writes both (CCYYMMDD and HHMMSS±HHMM); setting null removes both.
public DateTimeOffset? DateCreated { get; set; }Property Value
Entries
Gets every dataset in the order stored.
public IReadOnlyList<IptcEntry> Entries { get; }Property Value
Headline
public string? Headline { get; set; }Property Value
Exceptions
- ArgumentException
The value set is longer than 256 bytes in UTF-8.
IsDamaged
Gets whether the block was damaged when read: a dataset running past the end, bytes that are not datasets, or more data than allowed. What could be read is available; the original bytes are written back unless the block is edited.
public bool IsDamaged { get; }Property Value
IsUtf8
Gets whether text is UTF-8: the coded character set (1:90) is ESC % G.
public bool IsUtf8 { get; }Property Value
Keywords
Gets or sets the keywords (2:25), in order. Setting an empty list removes them.
public IReadOnlyList<string> Keywords { get; set; }Property Value
Exceptions
- ArgumentException
A keyword set is longer than 64 bytes in UTF-8.
Warnings
Gets what was wrong with the block when read (damage, values longer than the specification allows), as sentences.
public IReadOnlyList<string> Warnings { get; }Property Value
Methods
Add(IptcKey, string)
Adds one more value to a repeatable dataset, such as a keyword.
public void Add(IptcKey key, string value)Parameters
keyIptcKeyThe record and dataset.
valuestringThe text, stored as UTF-8 (with 1:90 set to UTF-8 when it is not ASCII).
Exceptions
- ArgumentException
The dataset is not repeatable (IsRepeatable), or the value is longer than MaxLength in UTF-8.
Copy()
Returns an independent copy.
public IptcData Copy()Returns
- IptcData
The copy.
Get(IptcKey)
Returns the first value of key as text, or null.
public string? Get(IptcKey key)Parameters
keyIptcKeyThe record and dataset.
Returns
- string
The text.
GetAll(IptcKey)
Returns every value of key as text, in order.
public IReadOnlyList<string> GetAll(IptcKey key)Parameters
keyIptcKeyThe record and dataset.
Returns
- IReadOnlyList<string>
The values; empty when there are none.
Parse(ReadOnlySpan<byte>, SafetyLimits?)
Reads IPTC-IIM datasets: tag markers 0x1C, each with a record, a dataset, a length and the value. Never throws: a block that runs past its end or past MaxMetadataBytes keeps what was read and is marked damaged.
public static IptcData Parse(ReadOnlySpan<byte> iim, SafetyLimits? limits = null)Parameters
iimReadOnlySpan<byte>The datasets, without any Photoshop resource wrapper.
limitsSafetyLimitsThe limits whose MaxMetadataBytes caps the values copied. Defaults to Default.
Returns
Examples
// IPTC datasets from somewhere other than an image file, with a cap on the bytes of values read.
IptcData iptc = IptcData.Parse(iim.Span, SafetyLimits.Default with { MaxMetadataBytes = 64 * 1024 });
Console.WriteLine($"{iptc.Get(IptcKey.ObjectName)}: {iptc.Entries.Count} datasets, damaged: {iptc.IsDamaged}");Remove(IptcKey)
Removes every value of key.
public bool Remove(IptcKey key)Parameters
keyIptcKeyThe record and dataset.
Returns
- bool
Whether there was any.
Set(IptcKey, string)
Replaces every value of key with one value.
public void Set(IptcKey key, string value)Parameters
keyIptcKeyThe record and dataset.
valuestringThe text, stored as UTF-8 (with 1:90 set to UTF-8 when it is not ASCII).
Exceptions
- ArgumentException
The value is longer than MaxLength in UTF-8; long text belongs in XMP. Or the key is the coded character set, which Egami keeps.
ToBytes()
Returns the datasets as stored in a file: the original bytes when unedited, otherwise rebuilt.
public ReadOnlyMemory<byte> ToBytes()Returns
- ReadOnlyMemory<byte>
The bytes.
TryGet(IptcKey, out IptcEntry?)
Returns the entry for the first dataset with key, if the block has one.
public bool TryGet(IptcKey key, out IptcEntry? entry)Parameters
Returns
- bool
Whether the block has the dataset.