Class CapReader

Namespace

EncDotNet.S100.Datasets.Cap

Assembly

EncDotNet.S100.Datasets.Cap.dll

Reads CAP 1.2 marine weather warnings in the three forms the NWS and other alerting authorities publish (design note docs/design/weather-sources.md §6.1):

public static class CapReader

Inheritance

object

CapReader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

• CAP XML: one <alert> in the CAP 1.2 namespace (urn:oasis:names:tc:emergency:cap:1.2; 1.1 and 1.0 read the same).
• Atom: a feed whose entries each hold a whole <alert>, or, as api.weather.gov/alerts.atom writes them, carry the alert's fields as cap: elements of the entry itself (one info, one area), with the identifier in the entry's id, the headline in its title and the description in its summary.
• NWS GeoJSON: an alert feature, or a feature collection of them, as api.weather.gov/alerts returns them. The feature's geometry is the area's polygon; ends is Ends.

Elements are matched by local name, so a producer's namespace prefix doesn't matter. Unknown elements are ignored. A polygon or circle that can't be read is skipped rather than failing the file.

Fields

AtomNamespace

The Atom namespace.

public const string AtomNamespace = "http://www.w3.org/2005/Atom"

Field Value

string

Cap12Namespace

The CAP 1.2 XML namespace.

public const string Cap12Namespace = "urn:oasis:names:tc:emergency:cap:1.2"

Field Value

string

CapNamespacePrefix

The start every CAP namespace shares (1.0, 1.1 and 1.2).

public const string CapNamespacePrefix = "urn:oasis:names:tc:emergency:cap:"

Field Value

string

Methods

IsCapRoot(string, string, string)

Whether an XML root element (its namespace and local name, and the document's first characters) is CAP: an alert in a CAP namespace, or an Atom feed whose text declares the CAP namespace.

public static bool IsCapRoot(string namespaceUri, string localName, string documentPrefix)

Parameters

namespaceUri string

The root's namespace URI.

localName string

The root's local name.

documentPrefix string

The start of the document, or its whole text.

Returns

bool

true when the root is CAP.

LooksLikeCap(ReadOnlySpan<byte>)

Whether leadingBytes, the start of a file, look like CAP: an XML document whose root is a CAP alert, or an Atom feed that declares the CAP namespace; or JSON from api.weather.gov that names an alert (wx:Alert or an /alerts/ URL). Used to detect CAP files whatever their extension.

public static bool LooksLikeCap(ReadOnlySpan<byte> leadingBytes)

Parameters

leadingBytes ReadOnlySpan<byte>

The file's first bytes; a kilobyte is enough for the NWS forms.

Returns

bool

true when the bytes look like CAP.

Remarks

An S-100 GML dataset (S-124 and the others) has a DataSet root in an S-100 namespace, so it is never CAP; GeoJSON from anywhere other than api.weather.gov isn't claimed.

ParseCircle(string)

Parses a CAP circle: latitude,longitude radius, the radius in kilometres.

public static CapCircle? ParseCircle(string text)

Parameters

text string

The element's text.

Returns

CapCircle?

The circle, or null when it can't be read.

ParsePolygon(string)

Parses a CAP polygon: space-separated latitude,longitude pairs, the first and last the same. A ring that isn't closed is closed.

public static IReadOnlyList<GeoPosition>? ParsePolygon(string text)

Parameters

text string

The element's text.

Returns

IReadOnlyList<GeoPosition>

The ring, or null when it has fewer than three distinct positions or can't be read.

Read(Stream)

Reads CAP from stream, which is left open.

public static CapDocument Read(Stream stream)

Parameters

stream Stream

The stream, read to its end.

Returns

CapDocument

The alerts.

Exceptions

CapFormatException

The stream isn't CAP XML, a CAP Atom feed or NWS alert GeoJSON.

Read(ReadOnlySpan<byte>)

Reads CAP from bytes.

public static CapDocument Read(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

The file's bytes.

Returns

CapDocument

The alerts.

Exceptions

CapFormatException

The bytes aren't CAP XML, a CAP Atom feed or NWS alert GeoJSON.

Read(string)

Reads a CAP file.

public static CapDocument Read(string path)

Parameters

path string

The file's path.

Returns

CapDocument

The alerts.

Exceptions

CapFormatException

The file isn't CAP XML, a CAP Atom feed or NWS alert GeoJSON.