exportVideo

Configuration Article | CA-20240119-MF-20

VDG Sense | API | Functions | Media

 

Note:

  • This function requires an API license

  • Introduced in VDG Sense version 2.7.3

The exportVideo command can be used to create video exports in native format on the VDG Sense server. These exports can be stored on the server itself or on a user specified drive location such as a mapped network drive. They can not be downloaded directly via the API.

The exportVideo requires the POST method, with additional parameters in XML format as described below.
Using this command, it is possible to create an export of multiple cameras in one API request, each camera with independed start and end times as described in the <devices> node of the XML body.

Special care must be taken when including xml specific characters. These are ‘&’, ‘<' en '>‘. The ampersand (‘&’) character can not be sent by this command because it will be part of the URL. See next paragraph.

As the value of this event is in the query part of an URL, the ampersand character (‘&’) cannot be part of it. It must be URL Encoded. See i.e. http://www.w3schools.com/TAGS/ref_urlencode.asp. The best practive is to URL Encode the complete value.

Request

 

The exportVideo API function can be used in two ways:

  1. to create a video export

  2. to remove a pending videoexport

 

Creating a video export

POST exportVideo <!--?xml version="1.0" ?--> <export> <devices> <device> <serverid>[UID]</serverid> <deviceid>[UID]</deviceid> <starttime>[timestamp]</starttime> <endtime>[timestamp]</endtime> </device> <device> ... </device> </devices> <path>[path]</path> <bandwidth>[bandwidth]</bandwidth> </export>

The parameters in the XML body should be of the following format:

parameters

type

remarks

parameters

type

remarks

serverid

[UID]

Unique server id

deviceid

[UID]

Unique device id

starttime

[timestamp]

UTC Timestamp (format: yyyy-mm-dd hh:nn:ss.zzz)

endtime

[timestamp]

UTC timestamp (format: yyyy-mm-dd hh:nn:ss.zzz)

path

[string]

Path (on the server) to where the video is exported to, if the folder doesn’t exist it will be created

bandwidth

[value]

[optional] If the storage path is connected via a metered connection, then it’s possible to add a maximum bandwidth value here in bytes per second. If a value of 0 is used, it will try to copy with maximal available bandwith

Deleting a pending videoexport:

Post a request using the DELETE method, where exportid is the id of the export to be deleted.

127.0.0.1/command?command=exportVideo&exportid=[exportid]

Response

The server will return an exportId if the export is in progress. If it fails it will return an error message.

The exportid’s will only be valid during the currently open API session. After that, it will be reset to 1. Also after a SensePluginManager reset it will be reset.

 

Result:

<!--?xml version="1.0" ?--> <result errorcode="0"> <export> <exportid>[exportid]</exportid> </export> </result>

In case of error:

error code

description

remarks

error code

description

remarks

0

Ok

Ok, no error

-2

No device

 No device found for the supplied cameraid/deviceid.

-4

Invalid Timestamp.

Invalid datetime format. See Timestamp.

-17

No server

There is no server with the supplied id.

-33

No serverID

No serverID parameter given.

-34

No deviceID

No deviceID parameter given.

-37

Enddate before startdate

Enddate parameter is before the startdate parameter.

-48

No videodata for timestamp

No videodata for the given timestamp

-57

No exportid

in case of a DELETE, exportid needs to be added to the request

-58

Incorrect path

path does not exist

-60

Not enough disk space

there is not enough space to store the video in supplied path

-61

Unable to create directory

The directory could not be created on the server

Related

https://tkhsecurity.atlassian.net/wiki/spaces/KB/pages/9750675486

Changelog

  • 2.7.3 - Introduced