Struct TrendLogObject 

pub struct TrendLogObject { /* private fields */ }

BACnet TrendLog object (type 20, Clause 12.25).

Ring buffer of timestamped values of the one property Log_DeviceObjectProperty names. The database’s trend poller samples it every Log_Interval while Logging_Type is POLLED, at clock-aligned times when Align_Intervals asks for them, and once for each Trigger while it is TRIGGERED, and while it is COV it logs each change of a property of this device as a COV notification would report it (#1480); the application may also call add_record(). Records are kept only while Enable is TRUE and the local time lies between Start_Time and Stop_Time.

Implementations

impl TrendLogObject

pub fn with_persistence( instance: u32, name: impl Into<String>, buffer_size: u32, persistence: Arc<dyn LogPersistence<BACnetLogRecord>>, ) -> Result<Self, Error>

Open a Trend Log kept in persistence, or start one there when it holds none yet.

A log storage holds comes back as it was saved: Enable, Stop_When_Full, its records and Total_Record_Count, its BUFFER_READY counting and Notification_Threshold, and the settings a peer can write (the window, Logging_Type, Log_Interval, Align_Intervals, Interval_Offset and Log_DeviceObjectProperty). buffer_size wins over the saved Buffer_Size; a smaller one keeps the newest records. It then owes a LOG_INTERRUPTED record, appended once it can read a valid clock, unless it reopens full and stopped. See crate::log_persistence for when it commits.

Fails with Error::OutOfRange for a buffer_size a slot can’t hold, with storage’s error when the snapshot can’t be loaded, and when it doesn’t hold together as a Trend Log’s: another object’s identity, a zero generation, more records than Buffer_Size, records with a Total_Record_Count of zero, a full buffer while Stop_When_Full and Enable are both TRUE, a window end that isn’t an actual moment, a Logging_Type a Trend Log can’t take, or more than one reference.

pub fn reopened(&self) -> bool

Whether the log came back from a snapshot its storage held, rather than starting empty. Always false without storage.

pub fn commit_cadence(&self) -> Option<LogCommitCadence>

When the log commits to its storage; None without storage.

pub fn set_commit_cadence(&mut self, cadence: LogCommitCadence)

Set when the log commits to its storage. Does nothing without storage.

pub fn storage_generation(&self) -> Option<u64>

The generation of the last snapshot storage took: the loaded one’s until a commit lands, zero for storage that held none, and None without storage.

impl TrendLogObject

pub fn new( instance: u32, name: impl Into<String>, buffer_size: u32, ) -> Result<Self, Error>

Create a new Trend Log object with logging enabled; buffer_size is the record capacity.

pub fn add_record(&mut self, record: BACnetLogRecord) -> Result<(), Error>

Add a BACnetLogRecord to the trend log buffer.

Success does not guarantee a resident ordinary record: disabled logging and a record outside the Start_Time / Stop_Time window are ignored, zero-capacity logging may only count, and a stop-before-full transition records status instead. Missing/invalid status clocks fail atomically with DEVICE / OPERATIONAL_PROBLEM. A successful call serves a pending Trigger, which reads FALSE again, even when the record is ignored (Enable FALSE, or outside the window): the acquisition was made.

pub fn records(&self) -> &VecDeque<BACnetLogRecord>

Get the current buffer contents.

pub fn total_record_count(&self) -> u32

Total_Record_Count: the records collected since the log was created or restored, going from 2^32 - 1 on to 1. The newest record in records carries this number. Save the two to restore the log later.

pub fn restore_log_buffer( &mut self, total_record_count: u32, records: impl IntoIterator<Item = BACnetLogRecord>, ) -> Result<(), Error>

Restore the log buffer, as a device restarting with saved records does, or seed Total_Record_Count with no records, as a test that needs the count near its wrap does (#1537).

records become the resident records, oldest first. The newest is numbered total_record_count and each one before it one less, going from 1 back to 2^32 - 1, so a count below the number of records is a count that has wrapped. The records are kept as given, whatever Enable and the Start_Time / Stop_Time window say, and nothing is recorded for the restore. BUFFER_READY counts from the restored count, as when detection starts.

Fails with Error::OutOfRange, or a record’s encoding error, leaving the log unchanged, when there are more records than Buffer_Size, when records come with a count of zero, when Stop_When_Full and Enable are both TRUE and the records fill the buffer (such a log stops before its last slot is taken), or when a record would not encode.

Restore a log before adding it to an ObjectDatabase. A running server reaches its objects only through BACnetObject, which offers no restore on purpose: renumbering a log that peers are reading would change what their sequence numbers mean, with no BUFFER_PURGED record to tell them, and the BUFFER_READY reports already sent would name counts that no longer hold.

A device restoring its saved records after a restart then calls record_interruption with the time it came back: Clause 12.25.14 gives a log that status when a power failure or reset broke its collection, so readers know samples may be missing. That record counts toward Total_Record_Count like any other, numbered one past the restored count.

pub fn record_interruption( &mut self, date: Date, time: Time, ) -> Result<(), Error>

Append a LOG_INTERRUPTED status record stamped date and time, as a log restored after a restart does (#1537); see restore_log_buffer.

The record goes in whatever Enable and the window say, counts toward Total_Record_Count, and pushes out the oldest record of a full buffer. It also carries LOG_DISABLED while collection is off; when it fills a Stop_When_Full buffer it does so and turns Enable FALSE, as the log’s own status records do. Without a clock bound, as before the log is added to a database, the time has to come from the caller: a date and time that aren’t an actual moment (every field given, the weekday matching the date) fail with Error::OutOfRange and change nothing.

A log reopened from storage (with_persistence) appends this record itself; calling this first takes its place.

pub fn clear(&mut self)

Clear the buffer.

pub fn set_description(&mut self, desc: impl Into<String>)

Set the description string.

pub fn set_log_device_object_property( &mut self, reference: Option<BACnetDeviceObjectPropertyReference>, ) -> Result<(), Error>

Set Log_DeviceObjectProperty, the property the log samples, as local configuration: the log buffer is left as it is.

A reference may name another device; the poller then logs a failure for each sample instead of reading it. None, or a reference whose object or Device is at the reserved instance 4194303, leaves the log without one (#1417). A Device member that isn’t a Device identifier fails with PROPERTY / VALUE_OUT_OF_RANGE and changes nothing.

pub fn set_logging_type( &mut self, logging_type: LoggingType, ) -> Result<(), Error>

Set Logging_Type, as a client’s write does: POLLED, TRIGGERED or COV. Any other value is PROPERTY / OPTIONAL_FUNCTIONALITY_NOT_SUPPORTED (Clause 12.25.26) and changes nothing. POLLED with a zero Log_Interval sets DEFAULT_LOG_INTERVAL; TRIGGERED and COV set Log_Interval to zero.

While COV, the database’s trend poller looks at the referenced property on each pass and logs it, with the monitored object’s Status_Flags, whenever its change passes the Clause 13.1 COV test (held to Client_COV_Increment when set) or those flags have changed. The first pass after the log starts collecting logs the current value; Enable turned off and on within one pass (about 100 ms) isn’t seen and restarts nothing. Only references to this device are followed: one naming another device logs PROPERTY / OPTIONAL_FUNCTIONALITY_NOT_SUPPORTED once, since no COV subscription is made to a peer.

pub fn set_log_interval(&mut self, hundredths: u32) -> Result<(), Error>

Set Log_Interval in hundredths of a second, as a client’s write does. While Logging_Type is TRIGGERED it is read-only and this is PROPERTY / WRITE_ACCESS_DENIED. Clause 12.25.9’s switches apply: a POLLED log’s nonzero interval set to zero turns it to COV, and a nonzero interval set on a COV log turns it to POLLED.

pub fn set_client_cov_increment( &mut self, increment: Option<f32>, ) -> Result<(), Error>

Set Client_COV_Increment, the increment a COV log holds a numeric value’s changes to (Clause 12.25.11). None, NULL, uses the referenced property’s own criteria: the object’s COV_Increment for a numeric Present_Value, any change otherwise. An increment that is negative or not finite is PROPERTY / VALUE_OUT_OF_RANGE.

pub fn set_cov_resubscription_interval( &mut self, seconds: u32, ) -> Result<(), Error>

Set COV_Resubscription_Interval in seconds (Clause 12.25.10); zero is PROPERTY / VALUE_OUT_OF_RANGE. It is stored and served, but unused until the log subscribes to another device’s property, which it doesn’t yet: COV logging follows this device’s properties only.

pub fn set_start_time(&mut self, date: Date, time: Time) -> Result<(), Error>

Set Start_Time, the local date and time from which records are kept, as local configuration: nothing is recorded for the change itself, but the log notes at once where the window stands, so a client’s write that then opens or shuts it is recorded. Every field unspecified leaves the start open. Any other value has to name an actual date and time, or it is PROPERTY / VALUE_OUT_OF_RANGE: the weekday may stay unspecified, and unspecified seconds or hundredths count as zero.

pub fn set_stop_time(&mut self, date: Date, time: Time) -> Result<(), Error>

Set Stop_Time, the local date and time from which records are no longer kept, under the same rules as set_start_time.

pub fn set_align_intervals(&mut self, align: bool)

Set Align_Intervals: whether a POLLED log acquires at clock-aligned times.

pub fn set_interval_offset(&mut self, hundredths: u32)

Set Interval_Offset, the delay after each aligned boundary, in hundredths; it applies modulo Log_Interval.

pub fn trigger(&mut self) -> Result<(), Error>

Ask for one acquisition, as a local process writing Trigger TRUE does. Only a TRIGGERED log takes it; any other is PROPERTY / NOT_CONFIGURED_FOR_TRIGGERED_LOGGING.

pub fn set_notification_threshold(&mut self, threshold: u32)

Set Notification_Threshold, the number of records that makes a BUFFER_READY report; zero, the default, makes none.

pub fn set_notification_class(&mut self, class: u32)

Set Notification_Class: the number of the Notification Class whose recipients get the log’s reports (0 by default).

pub fn set_event_enable(&mut self, enable: EventTransitionBits)

Set Event_Enable; a report goes out only while its TO_NORMAL flag is set, as it is by default.

pub fn set_notify_type(&mut self, notify_type: NotifyType)

Set Notify_Type, sent with each report (EVENT by default).

Trait Implementations

impl BACnetObject for TrendLogObject

fn object_identifier(&self) -> ObjectIdentifier

The object’s identifier (type + instance).

fn object_name(&self) -> &str

The object’s name.

fn read_property( &self, property: PropertyIdentifier, array_index: Option<u32>, ) -> Result<PropertyValue, Error>

Read a property value.

fn write_property( &mut self, property: PropertyIdentifier, array_index: Option<u32>, value: PropertyValue, _priority: Option<u8>, ) -> Result<(), Error>

Write a property value.

fn property_metadata(&self) -> Cow<'_, [PropertyMetadata]>

Return canonical metadata for this object’s effective property rows.

fn property_list(&self) -> Cow<'static, [PropertyIdentifier]>

List all properties this object supports in the legacy projection.

fn log_record_identities_internal(&self) -> Option<Vec<LogRecordIdentity>>

Return stable identities aligned with this object’s resident log records.

fn log_buffer_internal(&self) -> Option<&dyn LogBufferRecords>

Borrow this object’s Log_Buffer records as ReadRange pages them.

fn add_trend_record(&mut self, record: BACnetLogRecord) -> Result<(), Error>

Submit a trend record to an object’s log lifecycle.

fn evaluate_intrinsic_reporting(&mut self) -> Option<TransitionOutcome>

Evaluate intrinsic reporting after a present_value change.

fn tick_intrinsic_reporting(&mut self) -> Option<TransitionOutcome>

Advance the Time_Delay countdown for a pending transition.

fn write_property_from( &mut self, property: PropertyIdentifier, array_index: Option<u32>, value: PropertyValue, priority: Option<u8>, _origin: &CommandOrigin, ) -> Result<(), Error>

Write with explicit actual command provenance. Standalone callers assert the origin; server boundaries additionally validate ingress or membership. Decorators must forward this hook without discarding the origin. The default preserves custom/unaffected object behavior. First-party source-tracked commands require this hook and deny context-free writing.

fn is_writable_property(&self, property: PropertyIdentifier) -> bool

Whether a property write route can accept property for this object.

fn is_array_property(&self, property: PropertyIdentifier) -> bool

Whether property accepts an array index on this object.

fn is_list_property(&self, property: PropertyIdentifier) -> bool

Whether property is a BACnetLIST on this object.

fn is_createable(&self) -> bool

Whether this object type can be created at runtime via CreateObject.

fn creation_only_properties(&self) -> &'static [PropertyIdentifier]

The properties whose whole value a CreateObject initial value may set on this object although WriteProperty can’t change it afterwards.

fn initialize_property( &mut self, _property: PropertyIdentifier, _value: PropertyValue, ) -> Result<(), Error>

Apply a CreateObject initial value to one of Self::creation_only_properties, written whole.

fn is_deleteable(&self) -> bool

Whether this object type can be deleted at runtime via DeleteObject.

fn required_properties(&self) -> Cow<'static, [PropertyIdentifier]>

List the REQUIRED properties for this object type.

fn supports_cov(&self) -> bool

Whether this object type supports COV notifications.

fn supports_subscribe_cov_property(&self) -> bool

Whether SubscribeCOVProperty and SubscribeCOVPropertyMultiple may monitor this object’s properties.

fn supports_cov_property(&self, property: PropertyIdentifier) -> bool

Whether a readable property supports property-specific COV.

fn cov_increment(&self) -> Option<f64>

COV increment for this object (objects with a COV_Increment property).

fn cov_reported_properties(&self) -> &'static [CovReportedProperty]

Properties a whole-object (SubscribeCOV) notification reports after its leading value and Status_Flags, in report order.

fn set_overridden(&mut self, _overridden: bool)

Set the OVERRIDDEN bit in StatusFlags.

fn tick_schedule( &mut self, _today: SpecificDate, _time: Time, _calendar_active: &dyn Fn(ObjectIdentifier) -> bool, ) -> Option<ScheduleWrite>

Evaluate this object’s schedule at time on today (Clause 12.24.4).

fn take_owed_schedule_writes(&mut self) -> Vec<ScheduleWrite>

Take the writes this schedule owes its targets apart from its calculation, each once, in order: a NULL to every priority slot a change of List_Of_Object_Property_References or Priority_For_Writing left behind (#1088), then the Present_Value owed out of service, for a client’s write (Clause 12.24.14) or a change of those two properties.

fn complete_schedule_write( &mut self, _write: &ScheduleWrite, _outcomes: &[ScheduleTargetOutcome], ) -> bool

Report how each target took write, one of this schedule’s writes: outcomes holds one entry per member of write.references, in order.

fn retry_refusals_naming( &self, _target: ObjectIdentifier, ) -> Option<ScheduleWrite>

The retry of the current value to the references whose last write was refused and that name target, an object just added to the database (#1440), so the refusal can clear without waiting for the next pass. None when no such refusal stands, or when the pass itself would retry nothing: out of service, outside Effective_Period, or with a NULL Present_Value. Only meaningful for Schedule objects; default returns None.

fn acknowledge_alarm( &mut self, _transition_bit: EventTransitionBits, ) -> Result<(), Error>

Acknowledge an alarm transition. Sets the transition_bit flags in acked_transitions. Returns Ok(()) if the object supports event detection, Err otherwise.

fn apply_life_safety_operation( &mut self, _operation: LifeSafetyOperation, ) -> Result<LifeSafetyOperationOutcome, Error>

Apply a LifeSafetyOperation atomically to this object.

fn set_life_safety_operation_expected_internal( &mut self, _operation: LifeSafetyOperation, ) -> Result<(), Error>

Set the next LifeSafetyOperation expected by trusted local logic.

fn set_event_state_internal(&mut self, _state: EventState) -> Result<(), Error>

Apply an internally-detected Event_State transition.

fn enrollment_eval_state_internal(&self) -> Option<EventEnrollmentEvalState>

Snapshot this object’s Event Enrollment evaluation state, if it models one.

fn set_enrollment_eval_state_internal( &mut self, _state: EventEnrollmentEvalState, ) -> Result<(), Error>

Store this object’s Event Enrollment evaluation state.

fn enrollment_eval_source_internal( &self, ) -> Option<Option<EventEnrollmentMonitoredSource>>

Snapshot the monitored source that owns Event Enrollment private state.

fn set_enrollment_eval_source_internal( &mut self, _source: Option<EventEnrollmentMonitoredSource>, ) -> Result<(), Error>

Store or clear the monitored source that owns Event Enrollment state.

fn set_acked_transitions_internal( &mut self, _transition_bit: EventTransitionBits, _acknowledged: bool, ) -> Result<(), Error>

Set or clear one Acked_Transitions bit on a received event-state transition.

fn evaluate_reliability_internal( &mut self, ) -> Result<ReliabilityEvaluation, Error>

Evaluate and, when necessary, mutate this object’s Reliability.

fn set_reliability_internal( &mut self, _reliability: Reliability, ) -> Result<(), Error>

Apply an internally-derived Reliability value.

fn set_present_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the logical Present_Value supplied by the local application.

fn set_present_value_from_internal( &mut self, value: PropertyValue, _origin: &CommandOrigin, ) -> Result<(), Error>

set_present_value_internal on behalf of origin, the local Device the application runs in.

fn set_tracking_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the Tracking_Value the local application derived.

fn report_access_input_internal( &mut self, _input: AccessControlInput, ) -> Result<(), Error>

Apply an input the application reports for an access-control object the server holds (#1132): an Access Point’s access event, a Credential Data Input’s read or an Access Door’s hardware state, each a record whose values change together. See AccessControlInput.

fn set_controlled_variable_value_internal( &mut self, _value: PropertyValue, ) -> Result<(), Error>

Apply the Controlled_Variable_Value measured by the local application.

fn add_averaging_sample_internal( &mut self, _sample: Option<PropertyValue>, ) -> Result<(), Error>

Record one sample for an Averaging object.

fn audit_log_storage_internal(&self) -> Option<&dyn AuditLogStorage>

Borrow this object’s Audit Log query storage, if it has any.

fn audit_log_notification_sink_internal( &mut self, ) -> Option<&mut dyn AuditLogNotificationSink>

Mutably borrow this object’s Audit notification receiver capability.

fn file_storage_internal(&self) -> Option<&dyn FileStorage>

Borrow this object’s File storage, if it has any.

fn file_storage_internal_mut(&mut self) -> Option<&mut dyn FileStorage>

Mutably borrow this object’s File storage, if it has any.

fn add_trend_multiple_record( &mut self, _record: BACnetLogMultipleRecord, ) -> Result<(), Error>

Submit a Trend Log Multiple record, one value per monitored member, to an object’s log lifecycle.

fn add_event_log_record( &mut self, _record: BACnetEventLogRecord, ) -> Result<(), Error>

Submit an Event Log record to an object’s log lifecycle.

impl Drop for TrendLogObject

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.