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 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

       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.