ZoneMinder::Memory(3)

📦
version 1.38.6 · 2 versions
, in nixpkgs unstable

okay bestie, welcome to ZoneMinder::Memory(3) — the User Contributed Perl Documentation page for ZoneMinder::MappedMem, aka the mapped-memory access module. This is the part where we make mapped memory make sense, no cap. 💅

💖 NAME 💖

ZoneMinder::MappedMem - ZoneMinder Mapped Memory access module

✨ SYNOPSIS ✨

use ZoneMinder::MappedMem; use ZoneMinder::MappedMem qw(:all);

if ( zmMemVerify( $monitor ) ) {
  $state = zmGetMonitorState( $monitor );
  if ( $state == STATE_ALARM ) {
    ...
  } }

( $lri, $lwi ) = zmMemRead( $monitor, [ 'shared_data:last_read_index',
    'shared_data:last_write_index' ] ); zmMemWrite( $monitor, {
  'trigger_data:trigger_showtext' => "Some Text" } );

🌸 DESCRIPTION 🌸

The <pink>ZoneMinder:MappedMem</pink> module contains methods for accessing and writing to mapped memory, plus helper methods for common operations. 💖

The core elements of ZoneMinder used mapped memory to allow multiple access to resources. ZoneMinder scripts have used this information before, but up until now it was difficult to access and prone to errors. This module introduces a common API for mapped memory access (both reading and writing), making it a lot easier to customise scripts or even create your own. Slay. ✨

All the methods listed below require a <purple>'monitor'</purple> parameter. This must be a reference to a hash with at least the <purple>'Id'</purple> field set to the monitor id of the mapped memory you wish to access. Using database methods to select the monitor details will also return this kind of data. Some of the mapped memory methods will add and amend new fields to this hash. Noted. 🫶

💅 METHODS 💅

  • zmMemVerify ( $monitor ); — Verify that the mapped memory of the monitor given exists and is valid. It returns an undefined value if it is not valid. You should generally call this method first before using any of the other methods, but most of the remaining methods will also do so if the memory has not already been verified. 💖
  • zmMemInvalidate ( $monitor ); — Following an error, reset the mapped memory ids and attempt to reverify on the next operation. This is mostly used when a mapped memory segment has gone away and been recreated with a different id. 🌀
  • zmMemRead ( $monitor, $readspec ); — Read data from mapped memory attached to the given monitor. The mapped memory will be verified if it has not already been. The <purple>'readspec'</purple> must either be a string of the form <cyan>"<section>:<field>"` or a reference to an array of strings of the same format. In the first case a single value is returned; in the latter case a list of values is returned. Errors will cause undefined to be returned. The allowable sections and field names are described below. 📖
  • zmMemWrite ( $monitor, $writespec ); — Write data to mapped memory attached to the given monitor. The mapped memory will be verified if it has not already been. The <purple>'writespec'</purple> must be a reference to a hash with keys of the form <cyan>"<section>:<field>"` and values as the data to be written. Errors will cause undefined to be returned; otherwise a non-undefined value will be returned. The allowable sections and field names are described below. ✍️
  • $state = zmGetMonitorState ( $monitor ); — Return the current state of the given monitor. This is an integer value and can be compared with the STATE constants given below. 🔥
  • $event_id = zmGetLastEvent ( $monitor ); — Return the event id of the last event that the monitor generated, or 0 if no event has been generated by the current monitor process. 🎀
  • zmIsAlarmed ( $monitor ); — Return 1 if the monitor given is currently in an alarm state, 0 otherwise. 🚨
  • zmInAlarm ( $monitor ); — Return 1 if the monitor given is currently in an alarm or alerted state, 0 otherwise. ⚡
  • zmHasAlarmed ( $monitor ); — Return 1 if the given monitor is in an alarm state, or has been in an alarm state since the last call to this method. 👀
  • ( $x, $y ) = zmGetAlarmLocation ( $monitor ); — Return an x,y pair indicating the image coordinates of the centre of the last motion event generated by the given monitor. If no event has been generated by the current monitor process, or the alarm was not motion related, returns -1,-1. 📍
  • zmGetLastWriteTime ( $monitor ); — Returns the time (in utc seconds) since the last image was captured by the given monitor and written to shared memory, or 0 otherwise. ⏱️
  • zmGetLastReadTime ( $monitor ); — Returns the time (in utc seconds) since the last image was read from shared memory by the analysis daemon of the given monitor, or 0 otherwise or if the monitor is in monitor only mode. 🕰️
  • zmMonitorSuspend ( $monitor ); — Suspend the given monitor from generating events caused by motion. This method can be used to prevent camera actions such as panning or zooming from causing events. If configured to do so, the monitor may automatically resume after a defined period. 🛑
  • zmMonitorResume ( $monitor ); — Allow the given monitor to resume generating events caused by motion. ▶️
  • zmTriggerEventOn ( $monitor, $score, $cause [, $text, $showtext ] ); — Trigger the given monitor to generate an event. You must supply an event score and a cause string indicating the reason for the event. You may also supply a text string containing further details about the event, and a showtext string which may be included in the timestamp annotation on any images captured during the event, if configured to do so. 🎬
  • zmTriggerEventOff ( $monitor ); — Trigger the given monitor to not generate any events. This method does not cancel zmTriggerEventOn, but is exclusive to it. This method is intended to allow external triggers to prevent normal events being generated by monitors in the same way as zmMonitorSuspend, but applies to all events and not just motion, and is intended for longer timescales than are appropriate for suspension. 🚫
  • zmTriggerEventCancel ( $monitor ); — Cancel any previous trigger on or off requests. This stops a triggered alarm if it exists from a previous 'on' and allows events to be generated once more following a previous 'off'. ♻️
  • zmTriggerShowtext ( $monitor, $showtest ); — Indicate that the given text should be displayed in the timestamp annotation on any images captured, if the format of the annotation string defined for the monitor permits. 💬

🦋 DATA 🦋

The data fields in mapped memory that may be accessed are as follows. There are two main sections: shared_data, which is general data, and trigger_data, which is used for event triggering. Whilst reading from these fields is harmless, extreme care must be taken when writing to mapped memory — especially in the shared_data section, because this is normally written to only by monitor capture and analysis processes. 💀

bestie, seriously: reading is fine, writing is main-character risk. Be careful in there. 🙈

💖 shared_data — the general mapped memory section 💖

  • size — the size, in bytes, of this section.
  • valid — flag indicating whether this section has been initialised.
  • capturing — flag indicating whether this monitor is presently capturing.
  • analysing — flag indicating whether this monitor is presently analysing.
  • recording — flag indicating whether this monitor is presently recording.
  • signal — flag indicating whether this monitor is receiving a valid signal.
  • state — the current monitor state; see the STATE constants below.
  • last_write_index — the last index, in the image buffer, that an image has been saved to.
  • last_read_index — the last index, in the image buffer, that an image has been analysed from.
  • last_write_time — the time (in utc seconds) when the last image was captured.
  • last_read_time — the time (in utc seconds) when the last image was analysed.
  • last_event — the id of the last event generated by the monitor analysis process, 0 if none.
  • action — the monitor actions bitmask; see the ACTION constants below.
  • brightness — read/write location for the current monitor brightness.
  • hue — read/write location for the current monitor hue.
  • colour — read/write location for the current monitor colour.
  • contrast — read/write location for the current monitor contrast.
  • alarm_x — image x coordinate (from left) of the centre of the last motion event, -1 if none.
  • alarm_y — image y coordinate (from top) of the centre of the last motion event, -1 if none.
  • alarm_cause — the current alarm event cause string along with zone name(s) alarmed.

🦋 trigger_data — the triggered event mapped memory section 🦋

  • size — the size, in bytes, of this section.
  • trigger_state — the current trigger state; see the TRIGGER constants below.
  • trigger_score — the current triggered event score.
  • trigger_cause — the current triggered event cause string.
  • trigger_text — the current triggered event descriptive text string.
  • trigger_showtext — the triggered text that will be displayed on captured image timestamps.

⭐ CONSTANTS ⭐

The following constants are used by the methods above, but can also be used by user scripts if required. 💫

  • STATE_IDLE, STATE_PREALARM, STATE_ALARM, STATE_ALERT, STATE_TAPE — these constants define the state of the monitor with respect to alarms and events. They are used in the shared_data:state field. 👑
  • ACTION_GET, ACTION_SET, ACTION_RELOAD, ACTION_SUSPEND, ACTION_RESUME — these constants define the various values that can exist in the shared_data:action field. This is a bitmask which, when non-zero, defines an action that an executing monitor process should take.
    • ACTION_GET — requires that the current values of brightness, contrast, colour and hue are taken from the camera and written to the equivalent mapped memory fields.
    • ACTION_SET — implies the reverse: that the values in mapped memory should be written to the camera.
    • ACTION_RELOAD — signals that the monitor process should reload itself from the database in case any settings have changed there.
    • ACTION_SUSPEND — signals that a monitor should stop examining images for motion, though other alarms may still occur.
    • ACTION_RESUME — signals that a monitor should resume motion detection.
  • TRIGGER_CANCEL, TRIGGER_ON, TRIGGER_OFF — these constants are used in the definition of external triggers.
    • TRIGGER_CANCEL — used to indicate that any previous trigger settings should be cancelled.
    • TRIGGER_ON — signals that an alarm should be created (or continued) as a result of the current trigger.
    • TRIGGER_OFF — signals that the trigger should prevent any alarms from being generated.
    • See the trigger methods above for further details. 🔔

🎀 EXPORT 🎀

  • None by default.
  • :constants — will export the mapped memory constants, which mostly define enumerations for the variables held in memory.
  • :functions — will export the mapped memory access functions.
  • :all — will export all above symbols. 🫶

🔥 SEE ALSO 🔥

💜 AUTHOR 💜

Philip Coombes, <philip.coombes@zoneminder.com>

okay bestie, legal era — but make it cute ✨

Copyright (C) 2001-2008 Philip Coombes</p>

so here's the tea 🫖: this library is free software — iconic behavior, honestly 👑

you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available. slay, so many choices 💅

no cap, that's literally the whole license. short, sweet, ate 💀🌸

and that's a wrap on ZoneMinder::Memory(3), bestie 🎀 ty for reading my whole roman empire fr fr 💜

source & version vibes: perl v5.42.3 🌈 dated: 1980-01-01 🦋 page: ZoneMinder::Memory(3) 👑

go forth and memory responsibly, queen 🧚✨💖

📦 where this page comes from