ZoneMinder::Memory(3pm)
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 ZoneMinder:MappedMem module contains methods for accessing and
writing to mapped memory as well as helper methods for common
operations.
The core elements of ZoneMinder used mapped memory to allow multiple
access to resources. Although ZoneMinder scripts have used this
information before, 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.
All the methods listed below require a 'monitor' parameter. This must
be a reference to a hash with at least the 'Id' 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.
METHODS
- zmMemVerify ( $monitor );
- Verify that the mapped memory of the monitor given exists and is
valid. It will return 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 );
- This method is used to read data from mapped memory attached to the
given monitor. The mapped memory will be verified if it has not
already been. The 'readspec' must either be a string of the form
"<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 return. Errors will cause undefined to be returned. The allowable sections and field names are
described below. - zmMemWrite ( $monitor, $writespec );
- This method is used to write data to mapped memory attached to the
given monitor. The mapped memory will be verified if it has not
already been. 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 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 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 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 as this is
normally written to only by monitor capture and analysis processes. - 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 reciving 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 - 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 defines 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 signal 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 exaiming images
for motion, though other alarms may still occur. ACTION_RESUME
sigansl that a monitor should resume motion detectiom. - TRIGGER_CANCEL TRIGGER_ON TRIGGER_OFF
- These constants are used in the definition of external triggers.
TRIGGER_CANCEL is used to indicated 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. 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.
SEE ALSO
http://www.zoneminder.com
AUTHOR
Philip Coombes, <philip.coombes@zoneminder.com>
COPYRIGHT AND LICENSE
Copyright (C) 2001-2008 Philip Coombes
This library is free software; 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.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
- Around line 670:
- You forgot a '=back' before '=head1'
- Around line 672:
- '=item' outside of any '=over'
- Around line 744:
- You forgot a '=back' before '=head1'
- Around line 779:
- '=item' outside of any '=over'
- Around line 791:
- You forgot a '=back' before '=head1'