ZoneMi...Memory(3pm)

📦
version 1.36.37 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 ZoneMinder::MappedMem 💖

okay bestie, welcome to ZoneMinder::MappedMem — the ZoneMinder Mapped Memory access module, straight out of the User Contributed Perl Documentation (that's the 3pm manual, iykyk). She's long, she's powerful, and she's about to make your life so much easier. let's GO 🦋

✨ NAME ✨

ZoneMinder::MappedMem — the ZoneMinder Mapped Memory access module. literally what it says on the tin, no cap.

🌸 SYNOPSIS 🌸

here's the vibe, in code, exactly as it goes down:

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" } );

see? iconic behaviour. 💅

🎀 DESCRIPTION 🎀

so, ZoneMinder::MappedMem is packed with methods for reading from and writing to mapped memory, plus a whole lil squad of helper methods for the common stuff you're gonna do over and over.

the core elements of ZoneMinder use mapped memory so that multiple things can access resources at the same time — like, shared access, main character energy for the whole system. and yes, ZoneMinder scripts have used this info before, but ngl, up until now it was difficult to access and prone to errors. 😭 a mess. this module comes in and introduces a common API for mapped memory access — both reading and writing — which makes customising scripts, or even building your own, soooo much easier. obsessed.

the one thing you must remember: all the methods listed below need a 'monitor' parameter. this has to be a reference to a hash with at least the 'Id' field set to the monitor id of the mapped memory you wanna poke at. using database methods to select the monitor details will also return this kind of data, so you're covered there. and heads up — some of the mapped memory methods will add and amend new fields to this hash. so don't be shocked when it grows. 🙈

👑 METHODS 👑

every single one, in order, no skips:

  • zmMemVerify ( $monitor ); — verify that the mapped memory of the monitor given exists and is valid. it returns an undefined value if it's not valid. you should generally call this one first before using any of the others, but most of the remaining methods will also do it for you if the memory hasn't already been verified. considerate queens. 💖
  • zmMemInvalidate ( $monitor ); — after an error, this resets the mapped memory ids and attempts to reverify on the next operation. mostly used when a mapped memory segment has gone away and been recreated with a different id. the glow-up after the crisis. ✨
  • zmMemRead ( $monitor, $readspec ); — used to read data from the mapped memory attached to the given monitor. the mapped memory will be verified if it hasn't been already. the 'readspec' must either be a string of the form "<section>:<field>" or a reference to an array of strings of that same format. first case → a single value comes back. latter case → a list of values comes back. errors cause undefined to be returned. the allowable sections and field names are described below, keep scrolling. 🌈
  • zmMemWrite ( $monitor, $writespec ); — used to write data to the mapped memory attached to the given monitor. the mapped memory will be verified if it hasn't been already. the 'writespec' must be a reference to a hash with keys of the form "<section>:<field>" and values as the data to be written. errors cause undefined to be returned, otherwise a non-undefined value comes back. allowable sections and field names are described below. 💅
  • $state = zmGetMonitorState ( $monitor ); — returns the current state of the given monitor. it's an integer value, and you can compare it with the STATE constants given below. ⭐
  • $event_id = zmGetLastEvent ( $monitor ); — returns 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 ); — returns 1 if the monitor given is currently in an alarm state, 0 otherwise.
  • zmInAlarm ( $monitor ); — returns 1 if the monitor given is currently in an alarm or alerted state, 0 otherwise.
  • zmHasAlarmed ( $monitor ); — returns 1 if the given monitor is in an alarm state, or has been in an alarm state since the last call to this method. it remembers. 👀
  • ( $x, $y ) = zmGetAlarmLocation ( $monitor ); — returns an x,y pair showing the image co-ordinates 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 wasn't motion related, it 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. you'd use this to stop camera actions like panning or zooming from triggering events. and if it's configured to do so, the monitor may automatically resume after a defined period. self-care era. 🧚
  • zmMonitorResume ( $monitor ); — allow the given monitor to resume generating events caused by motion. welcome back babe. 🫶
  • zmTriggerEventOn ( $monitor, $score, $cause [, $text, $showtext ] ); — trigger the given monitor to generate an event. you must supply an event score and a cause string explaining the reason for the event. you may also supply a text string with 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 it's configured to do so. 🔥
  • zmTriggerEventOff ( $monitor ); — trigger the given monitor to not generate any events. this method does not cancel zmTriggerEventOn, it's exclusive to it. the point is to let external triggers prevent normal events being generated by monitors, same way as zmMonitorSuspend does — but this one applies to all events, not just motion, and it's intended for longer timescales than are appropriate for suspension. big-picture blocking, periodt.
  • zmTriggerEventCancel ( $monitor ); — cancel any previous trigger on or off requests. this stops a triggered alarm, if one exists from a previous 'on', and lets events be generated once more following a previous 'off'. the reset button, the clean slate. 💅
  • 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 go a lil something like this. there are two main sections: shared_data, which is general data, and trigger_data, which is used for event triggering. reading from these fields is harmless, but extreme care must be taken when writing to mapped memory — especially in the shared_data section, because that's normally written to only by monitor capture and analysis processes. do not be reckless bestie, that's not the vibe. 💀

🍓 shared_data — the general mapped memory section

  • size — the size, in bytes, of this section
  • valid — flag indicating whether this section has been initialised
  • active — flag indicating whether this monitor is active (enabled/disabled)
  • 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 co-ordinate (from left) of the centre of the last motion event, -1 if none
  • alarm_y — image y co-ordinate (from top) of the centre of the last motion event, -1 if none
  • alarm_cause — the current alarm event cause string along with zone names(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 🌈

these constants are used by the methods above, but they're also up for grabs by user scripts if you need them. sharing is caring. 💜

  • 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're 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 indicates 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, and 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, bestie. as in, nothing.

  • the :constants tag will export the mapped memory constants, which mostly define enumerations for the variables held in memory
  • the :functions tag will export the mapped memory access functions
  • the :all tag will export all above symbols

pick your fighter. ✨

🔥 SEE ALSO 🔥

http://www.zoneminder.com — go, explore, slay.

🫶 AUTHOR 🫶

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

and that's only part 1, so don't you dare close the tab — more is coming. 🌸

Okay bestie, legal moment but make it cute. ✨

Copyright (C) 2001-2008 Philip Coombes

This library is free software — like, actually free, not "free trial" free. 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. 💅

So fr fr: pick whichever Perl 5 version works for you, 5.8.3 or newer, and you're golden. 🫶

And that's the whole page, bestie!! 🎀 You made it to the end of ZoneMi...Memory(3pm) — this version comes to you courtesy of perl v5.40.1, dated 2026-02-01. Go forth and memory-zone slay. 👑💜

📦 where this page comes from