Struct MessageHeader

Source

pub struct MessageHeader { /* private fields */ }

Expand description

Event, area, time, and originator information

The message header is the decoded digital header which precedes the analog SAME message. See crate documentation for an example.

Implementations§

Source §

impl MessageHeader

Source

pub fn new<S>(message: S) -> Result<MessageHeader, MessageDecodeErr>
where S: Into<String>,

Try to construct a SAME header from String

The message string must match the general format of a SAME header. If it does not, an error is returned.

Source

pub fn new_with_errors<S>( message: S, error_counts: &[u8], ) -> Result<MessageHeader, MessageDecodeErr>
where S: Into<String>,

Try to construct a SAME header from String, with error counts

The message string must match the general format of a SAME header. If it does not, an error is returned.

The error_counts slice counts the number of bit errors corrected in byte of message. The slice must have the same length as message.

Source

pub fn new_with_error_info<S>( message: S, error_counts: &[u8], burst_counts: &[u8], ) -> Result<MessageHeader, MessageDecodeErr>
where S: Into<String>,

Try to construct a SAME header from String, with error details

The message string must match the general format of a SAME header. If it does not, an error is returned.

The error_counts slice counts the number of bit errors corrected in byte of message. The slice must have the same byte count as message.

burst_counts is the total number of SAME bursts which were used to estimate each message byte. This slice must have the same byte count as message.

Source

pub fn message(&self) -> &str

Wireline Text Representation

Returns UTF-8 string representation of a SAME/EAS start-of-message: i.e., ZCZC-...

Use release() to obtain an owned String instead.

Source

pub fn as_str(&self) -> &str

Wireline Text Representation

Returns UTF-8 string representation of a SAME/EAS start-of-message: i.e., ZCZC-...

Use release() to obtain an owned String instead.

Source

pub fn originator(&self) -> Originator

Originator code

The ultimate source of the message, such as Originator::NationalWeatherService for the National Weather Service

Source

pub fn originator_str(&self) -> &str

Originator code (as string)

A three-character string that is usually one of the following:

PEP: Primary Entry Point Station. Generally only used for national activations, which are very rare.
CIV: Civil authorities (usu. state and local government)
WXR: National Weather Service or Environment Canada
EAS: EAS Participant. Usually a broadcast station.

The originator code returned is three characters but is not guaranteed to be one of the above.

Source

pub fn event(&self) -> EventCode

Event code

Decodes the SAME event code (like RWT) into an EventCode, which is a combination of:

phenomenon(), which describes what is occurring; and
significance(), which indicates the overall severity and/or how “noisy” or intrusive the alert should be.

EventCode Display as a human-readable string which describes the SAME code. For example, “TOR” displays as “Tornado Warning.”

use sameplace::{MessageHeader, Phenomenon, SignificanceLevel};

let msg = MessageHeader::new("ZCZC-WXR-RWT-012345+0351-3662322-NOCALL  -").unwrap();
let evt = msg.event();

assert_eq!(evt.phenomenon(), Phenomenon::RequiredWeeklyTest);
assert_eq!(evt.significance(), SignificanceLevel::Test);
assert_eq!(format!("{}", evt), "Required Weekly Test");

The decoder will make every effort to interpret SAME codes it does not explicitly know. The EventCode might contain only a valid significance level—or perhaps not even that.

let msg = MessageHeader::new("ZCZC-WXR-OMG-012345+0351-3662322-NOCALL  -").unwrap();
assert_eq!(msg.event_str(), "OMG");
assert_eq!(msg.event().to_string(), "Unrecognized Warning");
assert_eq!(msg.event().significance(), SignificanceLevel::Unknown);
assert!(msg.event().is_unrecognized());

Unrecognized messages are still valid, and clients are encouraged to treat them at their significance level. Messages where even the significance level cannot be decoded should be treated as Warnings.

eventcodes contains the complete list of SAME codes that are interpreted by sameplace. See also: EventCode.

Source

pub fn event_str(&self) -> &str

Event code

A three-character code like “RWT” which describes the phenomenon and/or the severity level of the message. Use the event() method to parse this code into its components for further processing or for a human-readable display.

See eventcodes for the complete list of SAME codes that are interpreted by sameplace. The string value is not guaranteed to be one of these codes.

Source

pub fn location_str_iter<'m>(&'m self) -> Split<'m, char>

Iterator over location codes

Returns an iterator over the location codes in the message. Location codes are six-digit strings of the form PSSCCC:

P: part of county, or zero for entire county
SS: FIPS State code
CCC: FIPS County code

Locations are returned in the order listed in the message. Iterator values are guaranteed to be six-digit strings.

Per the SAME standard, a message can have up to 31 location codes.

Source

pub fn valid_duration(&self) -> TimeDelta

Message validity duration (Duration)

Returns the message validity duration or “purge time.” The duration specifies how long, relative to the issue time, that the message is valid.

The Duration is typically:

increments of 15 minutes for Durations of 1 hour or less
increments of 30 minutes for Durations longer than 1 hour
no longer than 99.5 hours

but sameplace does not enforce any of these restrictions.

This field represents the validity duration of the message and not the expected duration of the severe condition. An expired message may still refer to an ongoing hazard or event. Expiration merely indicates that the message is no longer valid. Clients are encouraged to retain a history of alerts and voice message contents.

The valid duration is relative to the issue_datetime() and not the current time.

Requires chrono.

Source

pub fn valid_duration_fields(&self) -> (u8, u8)

Message validity duration

Returns the message validity duration or “purge time.” This is a tuple of (hours, minutes). The duration specifies how long, relative to the issue time, that the message is valid.

The duration is typically:

increments of 15 minutes for durations of 1 hour or less
increments of 30 minutes for durations longer than 1 hour
no longer than 99.5 hours

but sameplace does not enforce any of these restrictions.

This field represents the validity duration of the message and not the expected duration of the severe condition. An expired message may still refer to an ongoing hazard or event. Expiration merely indicates that the message is no longer valid. Clients are encouraged to retain a history of alerts and voice message contents.

The valid duration is relative to the issue_datetime() and not the current time.

Source

pub fn issue_datetime( &self, received: &DateTime<Utc>, ) -> Result<DateTime<Utc>, InvalidDateErr>

Estimated message issuance datetime (UTC)

Computes the datetime that the SAME message was issued from the time that the message was received, which must be provided.

SAME headers do not include the year of issuance. This makes it impossible to calculate the full datetime of issuance without a rough idea of the message’s true UTC time. It is unnecessary for the received time to be a precision timestamp. As long as the provided value is within ±90 days of true UTC, the output time will be correct.

An error is returned if we are unable to calculate a valid timestamp. This can happen, for example, if we project a message sent on Julian/Ordinal Day 366 into a year that is not a leap year.

The returned datetime is always in one minute increments with the seconds field set to zero.

Requires chrono.

Source

pub fn purge_datetime( &self, received: &DateTime<Utc>, ) -> Result<DateTime<Utc>, InvalidDateErr>

Message purge/expiration datetime (UTC)

Compute the datetime that the SAME message should be purged or discarded. The caller must provide the time that the message was received.

The returned timestamp is rounded per NWSI 10-1712:

For valid durations ≤01h00m, the timestamp is rounded to the nearest 15 minutes
For valid durations greater than an hour, the timestamp is rounded to the nearest 30 minutes

An error is returned if we are unable to calculate a valid timestamp. This can happen, for example, if we project a message sent on Julian/Ordinal Day 366 into a year that is not a leap year.

SAME headers do not include the year of issuance. This makes it impossible to calculate the full datetime of issuance—or purge, for that matter—without a rough idea of the message’s true UTC time. It is unnecessary for the received time to be a precision timestamp. As long as the provided value is within ±90 days of true UTC, the output time will be correct.

This field represents the expiration time of the message and not the expected duration of the severe condition. An expired message may still refer to an ongoing hazard or event. Expiration merely indicates that the message is no longer valid. Clients are encouraged to retain a history of alerts and voice message contents.

Requires chrono.

Source

pub fn is_expired_at(&self, now: &DateTime<Utc>) -> bool

Is the message expired?

Given the current time, determine if this message has expired. It is assumed that now is within ±90 days of the message’s issuance time. The maximum duration of a SAME message is 99.5 hours.

An expired message may still refer to an ongoing hazard or event. Expiration merely indicates that the message is no longer valid. Clients are encouraged to retain a history of alerts and voice message contents.

Requires chrono.

Source

pub fn issue_daytime_fields(&self) -> (u16, u8, u8)

Message issuance day/time (fields)

Returns the message issue day and time, as the string JJJHHMM,

JJJ: Ordinal day of the year. 001 represents 1 Jan., and 365 represents 31 Dec. in non leap-years. During leap-years, 366 represents 31 Dec. 000 is not used. It is up to the receiving station to have some notion of what the current year is and to detect calendar rollovers.
HHMM: UTC time of day, using a 24-hour time scale. Times are UTC and are NOT local times.

Source

pub fn callsign(&self) -> &str

Sending station callsign

The FCC or other regulatory body-assigned callsign of the sending station. Minus signs (-) in the callsign are replaced with slashes (/).

Source

pub fn parity_error_count(&self) -> usize

Count of parity errors

The number of bit errors which were corrected by the 2-of-3 parity correction algorithm. High parity error counts indicate a high bit error rate in the receiving system.

Source

pub fn voting_byte_count(&self) -> usize

Number of bytes which were bit-voted

voting_byte_count is the total number of bytes which were checked via the “two of three” bitwise voting algorithm—i.e., the total number of bytes for which all three SAME bursts were available.

Source