Merge branch 'master' of github.com:ZoneMinder/ZoneMinder

CMakeLists.txt

@@ -5,6 +5,8 @@
 cmake_minimum_required (VERSION 2.6)
 project (zoneminder)
 set(zoneminder_VERSION "1.28.1")
+# make API version a minor of ZM version
+set(zoneminder_API_VERSION "${zoneminder_VERSION}.1")
 
 # CMake does not allow out-of-source build if CMakeCache.exists 
 # in the source folder. Abort and notify the user
@@ -452,7 +454,9 @@ if(NOT ZM_NO_FFMPEG)
 	endif(SWSCALE_LIBRARIES)
 
 	# Find the path to the ffmpeg executable
-	find_program(FFMPEG_EXECUTABLE ffmpeg PATH_SUFFIXES ffmpeg)
+	find_program(FFMPEG_EXECUTABLE 
+		NAMES ffmpeg avconv
+		PATH_SUFFIXES ffmpeg)
 	if(FFMPEG_EXECUTABLE)
 		set(PATH_FFMPEG "${FFMPEG_EXECUTABLE}")
 		set(OPT_FFMPEG "yes")
@@ -627,6 +631,7 @@ endif(NOT POLKIT_FOUND)
 set(ZM_PID "${ZM_RUNDIR}/zm.pid")
 set(ZM_CONFIG "${ZM_CONFIG_DIR}/zm.conf")
 set(VERSION "${zoneminder_VERSION}")
+set(API_VERSION "${zoneminder_API_VERSION}")
 set(PKGDATADIR "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/zoneminder")
 set(BINDIR "${CMAKE_INSTALL_FULL_BINDIR}")
 set(LIBDIR "${CMAKE_INSTALL_FULL_LIBDIR}")

docs/api.rst

@@ -1,10 +1,10 @@
 API
-===
+^^^
 
-This document will provide an overview of ZoneMinder's API.
+This document will provide an overview of ZoneMinder's API. This is work in progress. 
 
 Overview
---------
+^^^^^^^^
 
 In an effort to further 'open up' ZoneMinder, an API was needed.  This will
 allow quick integration with and development of ZoneMinder.
@@ -14,7 +14,7 @@ provides a RESTful service and supports CRUD (create, retrieve, update, delete)
 functions for Monitors, Events, Frames, Zones and Config.
 
 Examples
---------
+^^^^^^^^
 
 Here be a list of examples.  Some results may be truncated.
 
@@ -22,97 +22,244 @@ You will see each URL ending in either ``.xml`` or ``.json``.  This is the
 format of the request, and it determines the format that any data returned to
 you will be in.  I like json, however you can use xml if you'd like.
 
+(In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running)
+
+API Version
+^^^^^^^^^^^
+To retrieve the API version:
+::
+  http://server/zm/api/host/getVersion.json
+
+
 Return a list of all monitors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``curl -XGET http://zmdevapi/monitors.json``
+::
+  
+  curl -XGET http://server/zm/api/monitors.json
 
 Retrieve monitor 1
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^
-``curl -XGET http://zmdevapi/monitors/1.json``
+
+ ::
+  
+  curl -XGET http://server/zm/api/monitors/1.json
+
+
+Change State of Monitor 1
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This API changes monitor 1 to Modect and Enabled
+::
+
+  curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true"
 
 Add a monitor
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
 
 This command will add a new http monitor.
 
-``curl -XPOST http://zmdevapi/monitors.js -d "Monitor[Name]=Cliff-Burton \
+::
-&Monitor[Function]=Modect \
+
-&Monitor[Protocol]=http \
+  curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \
-&Monitor[Method]=simple \
+  &Monitor[Function]=Modect \
-&Monitor[Host]=ussr:pass@192.168.11.20 \
+  &Monitor[Protocol]=http \
-&Monitor[Port]=80 \
+  &Monitor[Method]=simple \
-&Monitor[Path]=/mjpg/video.mjpg \
+  &Monitor[Host]=usr:pass@192.168.11.20 \
-&Monitor[Width]=704 \
+  &Monitor[Port]=80 \
-&Monitor[Height]=480 \
+  &Monitor[Path]=/mjpg/video.mjpg \
-&Monitor[Colours]=4"``
+  &Monitor[Width]=704 \
+  &Monitor[Height]=480 \
+  &Monitor[Colours]=4"
 
 Edit monitor 1
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
 
 This command will change the 'Name' field of Monitor 1 to 'test1'
 
-``curl -XPUT http://zmdevapi/monitors/1.json -d "Monitor[Name]=test1"``
+::
+
+  curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1"
+
 
 Delete monitor 1
-^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^
 
 This command will delete Monitor 1, but will _not_ delete any Events which
 depend on it.
 
+::
+
+  curl -XDELETE http://server/zm/api/monitors/1.json
 
-``curl -XDELETE http://zmdevapi/monitors/1.json``
 
 Return a list of all events
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``curl -XGET http://zmdevapi/events.json``
+::
+
+  curl -XGET http://server/zm/api/events.json
+
+
+Note that events list can be quite large and this API (as with all other APIs in ZM)
+uses pagination. Each page returns a specific set of entries. By default this is 25
+and ties into WEB_EVENTS_PER_PAGE in the ZM options menu. 
+
+So the logic to iterate through all events should be something like this (pseudocode):
+(unfortunately there is no way to get pageCount without getting the first page)
+
+::
+
+  data = http://server/zm/api/events.json?page=1 # this returns the first page
+  # The json object returned now has a property called data.pagination.pageCount
+  count = data.pagination.pageCount;
+  for (i=1, i<count, i++)
+  {
+    data = http://server/zm/api/events.json?page=i;
+     doStuff(data);
+  }
+
+
+Retrieve event Id 1000
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+  curl -XGET http://server/zm/api/events/1000.json
 
-Retrieve event 1
-^^^^^^^^^^^^^^^^
-``curl -XGET http://zmdevapi/events/1.json``
 
 Edit event 1
-^^^^^^^^^^^^
+^^^^^^^^^^^^^
 
 This command will change the 'Name' field of Event 1 to 'Seek and Destroy'
 
-``curl -XPUT http://zmdevapi/events/1.json -d "Event[Name]=Seek and Destroy"``
+::
+
+  curl -XPUT http://server/zm/api/events/1.json -d "Event[Name]=Seek and Destroy"
 
 Delete event 1
 ^^^^^^^^^^^^^^
 This command will delete Event 1, and any Frames which depend on it.
 
-``curl -XDELETE http://zmdevapi/events/1.json``
+::
 
-Edit config 121
+  curl -XDELETE http://server/zm/api/events/1.json
+
+
+Return a list of events for a specific monitor Id =5
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+  curl -XGET http://server/zm/api/events/events/index/MonitorId:5.json``
+
+
+Note that the same pagination logic applies if the list is too long
+
+
+Return a list of events for a specific monitor within a specific date/time range
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+  http://server/zm/api/events/events/index/MonitorId:5/StartTime >=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json
+
+
+To try this in CuRL, you need to URL escape the spaces like so:
+
+::
+
+  curl -XGET  "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json"
+
+
+Return a list of events for all monitors within a specified date/time range
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+  curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json"
+
+
+
+Configuration Apis
+^^^^^^^^^^^^^^^^^^^
+
+The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console.
+This returns the full list of configuration parameters:
+
+::
+
+  curl -XGET http://server/zm/api/configs.json
+
+
+Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3.
+
+(Example of changing config TBD)
+
+Run State Apis
 ^^^^^^^^^^^^^^^
 
-This command will change the 'Value' field of Config 121 to 901.
+ZM API can be used to start/stop/restart/list states of  ZM as well
+Examples:
+
+::
+
+  curl -XGET  http://server/zm/api/states.json # returns list of run states
+  curl -XPOST  http://server/zm/api/states/change/restart.json #restarts ZM
+  curl -XPOST  http://server/zm/api/states/change/stop.json #Stops ZM
+  curl -XPOST  http://server/zm/api/states/change/start.json #Starts ZM
+
 
-``curl -XPUT http://zmdevapi/configs/121.json -d "Config[Value]=901"``
 
 Create a Zone
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
+
+::
+
+  curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \
+  &Zone[MonitorId]=3 \
+  &Zone[Type]=Active \
+  &Zone[Units]=Percent \
+  &Zone[NumCoords]=4 \
+  &Zone[Coords]=0,0 639,0 639,479 0,479 \
+  &Zone[AlarmRGB]=16711680 \
+  &Zone[CheckMethod]=Blobs \
+  &Zone[MinPixelThreshold]=25 \
+  &Zone[MaxPixelThreshold]= \
+  &Zone[MinAlarmPixels]=9216 \
+  &Zone[MaxAlarmPixels]= \
+  &Zone[FilterX]=3 \
+  &Zone[FilterY]=3 \
+  &Zone[MinFilterPixels]=9216 \
+  &Zone[MaxFilterPixels]=230400 \
+  &Zone[MinBlobPixels]=6144 \
+  &Zone[MaxBlobPixels]= \
+  &Zone[MinBlobs]=1 \
+  &Zone[MaxBlobs]= \
+  &Zone[OverloadFrames]=0"
+
+PTZ Control APIs
+^^^^^^^^^^^^^^^^
+PTZ controls associated with a monitor are stored in the Controls table and not the Monitors table inside ZM. What that means is when you get the details of a Monitor, you will only know if it is controllable (isControllable:true) and the control ID.
+To be able to retrieve PTZ information related to that Control ID, you need to use the controls API
+
+This returns all the control definitions:
+::
+
+  curl http://server/zm/api/controls.json
+
+This returns control definitions for a specific control ID=5
+::
+  
+  curl http://server/zm/api/controls/5.json
+
+Host APIs
+^^^^^^^^^^
+
+ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples:
+
+::
+
+  curl -XGET  http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running
+  curl -XGET  http://server/zm/api/host/getLoad.json # returns current load of ZM
+  curl -XGET  http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is,   space taken to store various event related information,images etc. per monitor) ``
 
-``curl -XPOST http://zmdevapi/zones.json -d "Zone[Name]=Jason-Newsted \
-&Zone[MonitorId]=3 \
-&Zone[Type]=Active \
-&Zone[Units]=Percent \
-&Zone[NumCoords]=4 \
-&Zone[Coords]=0,0 639,0 639,479 0,479 \
-&Zone[AlarmRGB]=16711680 \
-&Zone[CheckMethod]=Blobs \
-&Zone[MinPixelThreshold]=25 \
-&Zone[MaxPixelThreshold]= \
-&Zone[MinAlarmPixels]=9216 \
-&Zone[MaxAlarmPixels]= \
-&Zone[FilterX]=3 \
-&Zone[FilterY]=3 \
-&Zone[MinFilterPixels]=9216 \
-&Zone[MaxFilterPixels]=230400 \
-&Zone[MinBlobPixels]=6144 \
-&Zone[MaxBlobPixels]= \
-&Zone[MinBlobs]=1 \
-&Zone[MaxBlobs]= \
-&Zone[OverloadFrames]=0"``

web/api/app/Config/bootstrap.php.in

@@ -107,3 +107,37 @@ CakeLog::config('error', array(
 	'types' => array('warning', 'error', 'critical', 'alert', 'emergency'),
 	'file' => 'error',
 ));
+
+Configure::write('ZM_CONFIG',  '@ZM_CONFIG@');
+Configure::write('ZM_VERSION', '@VERSION@');
+Configure::write('ZM_API_VERSION', '@API_VERSION@');
+
+loadConfigFile();
+
+function loadConfigFile() {
+		        $configFile = Configure::read('ZM_CONFIG');
+		        $localConfigFile = basename($configFile);
+		        if ( file_exists( $localConfigFile ) && filesize( $localConfigFile ) > 0 )
+		        {
+		            if ( php_sapi_name() == 'cli' && empty($_SERVER['REMOTE_ADDR']) )
+		                print( "Warning, overriding installed $localConfigFile file with local copy\n" );
+		            else
+		                error_log( "Warning, overriding installed $localConfigFile file with local copy" );
+			            $configFile = $localConfigFile;
+		        }
+
+		        $cfg = fopen( $configFile, "r") or die("Could not open config file.");
+		        while ( !feof($cfg) )
+		        {
+		            $str = fgets( $cfg, 256 );
+		            if ( preg_match( '/^\s*$/', $str ))
+		                continue;
+		            elseif ( preg_match( '/^\s*#/', $str ))
+		                continue;
+		            elseif ( preg_match( '/^\s*([^=\s]+)\s*=\s*(.*?)\s*$/', $str, $matches ))
+	                    Configure::write("$matches[1]", "$matches[2]");
+		        }
+		        fclose( $cfg );
+}
+
+

web/api/app/Controller/HostController.php

@@ -101,10 +101,12 @@ class HostController extends AppController {
 
 	function getVersion() {
 		$version = Configure::read('ZM_VERSION');
+		$apiversion = Configure::read('ZM_API_VERSION');
 
 		$this->set(array(
 			'version' => $version,
-			'_serialize' => array('version')
+			'apiversion' => $apiversion,
+			'_serialize' => array('version', 'apiversion')
 		));
 	}
 }