CGI

概述

版本/作者/日期修改内容
1.0/David/2013-03-30初版

ReeCam IP Camera CGI 接口是提供给用户使用的一套基于 HTTP CGI 的应用开发接口。 用户可使用此接口实现:

1.定制 IP Camera Web UI 界面
2.使用浏览器或播放器直接对 IP Camera 进行访问和操作
3.使用计算机编程语言编写程序来实现对 IP Camera 进行访问和操作

CGI 调用

有三种方式可调用 IP Camera 的 CGI 接口:

直接在浏览器和播放器中调用 CGI 接口,例如:

在浏览器地址栏中直接输入 http://192.168.0.188/get_status.cgi
也可以在播放器中直接打开以下地址 http://192.168.0.188/av.asf
在网页中调用。例如:
<html><head><script src="get_status.cgi"></script></head><body>…</body></html>或者:

location=’set_params.cgi?alias=ipcam-demo’;

在计算机编程语言中实现。
注意,在调用 CGI 接口时,应保证发送的 HTTP URL 不能包含非法字符,对于可能包含非法字符的参数应进行 URI 编码。例如:
应使用 location=’set_params.cgi?alias=’+alias_inp.value;
而应使用 location=’set_params.cgi?alias=’+ encodeURIComponent(alias_inp.value);

用户认证

用户调用 IP Camera 的 CGI 接口时,IP Camera 必须对对用户进行用户名/密码的认证来确定用户的权限是否能满足。
每个 CGI 命令所需要的权限根据定义都有所不同,总体来说,IP Camera 上的权限分为两类:管理者和访问者。
管理者具备所有的权限功能;而访问者根据设置可分别授予以下权限的组合:
    1.视频访问权限:可以访问视频。
    2.拍照权限:可以进行拍照操作。
    3.录像权限:可以远程录像操作,即录像在 IP Camera 的 SD 卡上或 IP Camera 所设置的网络共享目录中。
    4.音频访问权限:可以监听。
    5.对话权限:可以与 IP Camera 对话。
    6.控制权限:可以进行 IP Camera 的 PTZ 和摄像头参数控制。
CGI 接口所支持的用户认证的方式有三种:
    1.基于 HTTP Basic Authentication 方式的认证。
        例如,在浏览器地址栏中直接输入 http://192.168.0.188/get_params.cgi ,浏览器会弹出提示用户名/密码的认证窗口来提醒用户,
        如果是用编程语言编写程序,则可以在向 IP Camera 发送的 HTTP 请求中增加 Authentication 字段来实现用户认证。
    2.基于参数形式的认证。
        例如,在浏览器地址栏中直接输入 http://192.168.0.188/get_params.cgi?user=admin&pwd= ,即在 HTTP 请求中直接附加 user 和 pwd 参数来实现用户认证。
    3.基于 Session 的认证。
        如果之前创建了一个 Session,那么可以直接在 HTTP 请求中直接附加 session 参数来实现用户认证。
        例如,可以在在浏览器地址栏中直接输入 http://192.168.0.188/get_params.cgi?session=20983424 ,如果 IP Camera 上存在编号为 20983424 的 Session ,则会将之前创建该 Session 的用户权限授予当前访问的用户。
以上三种认证方式,如果同时使用的话,以第三种的优先级最高,第一种优先级最低。

CGI 返回

CGI 接口可返回四种类型的数据:
    1.文本信息
    2.js 文本信息
    3.json/jsonp 文本信息
    4.文件
CGI 接口中根据返回类型可分为三类:
    一类 CGI ,用户需要得到的会是一个文件或者一系列流媒体的数据。
    例如 snapshot.cgi、backup.cgi、av.asf … 这类 cgi 如操作失败,则返回失败的文本信息,如成功则返回相应的文件。
    一类是操作和设置类的 CGI,此类 CGI 用户只关心操作和设置的结果。例如 set_params.cgi、ptz_control.cgi … 
a. 这类 cgi 如果在调用时设置返回为 json/jsonp 数据时,则无论成功与否,都是返回的 json/jsonp 类型的数据来表示操作结果,例如:
{"error":-2}					json	数据
callback({"error":0});			jsonp 数据
b. 而如果在调用时没有设置返回为 json/jsonp 数据时,则操作失败肯定会返回文本信息,例如
 Operation failed: invalid ip and mask.		代表操作失败,并给出失败的原因是 ip 和 mask 参数无效
	Operation failed: invalid user settings.		代表操作失败,并给出失败的原因是用户参数无效
而操作成功则会根据用户在调用时是否设置next_url 参数,如果没有设置,则返回成功的文本信息,例如:
  Operation Succeed.						代表操作成功
  否则,camera 会返回 next_url 所指定的页面。例如:
		http://192.168.0.188/set_params.cgi?...&next_url=user.htm 
那么如果操作成功,IP Camera 则会返回 user.htm 的页面,当然如果操作失败,则还是会返回代表操作失败和原因的文本信息。
注意: next_url 所指定的页面必须是 IP Camera 上的页面,而不能是其它网站上的页面。
next_url 所指定的页面也不能附带参数。
    一类 CGI 主要是查询类 CGI,对于此类 CGI,用户不仅需要知道操作是否成功,同时还需要知道具体的值。
    例如:get_status.cgi、get_params.cgi
a. 这类 cgi 如果在调用时设置返回为 json/jsonp 数据时,则无论成功与否,都是返回的 json/jsonp 类型的数据来表示操作结果,例如:
{"error":0,"time":1363592625,"alarm":0,"upnp":0,"ntp":1,"record":0,"disk":0,"ddns":0,"skype":0,"tutk":0}  json 数据
callback({"error":-2});  jsonp 数据
b. 这类 cgi 如果在调用时没有设置返回为 json/jsonp 数据时,如果操作失败则返回的是友好的文本信息,但如果操作成功,则会返回 js 文本信息。
例如用户想查询 IP Camera 的 IP 地址:
		http://192.168.0.188/get_params.cgi?ip= 
  IP Camera 会返回:
  var ip='192.168.0.188';
  	而还有些 CGI 返回的可能还会是 javascript 的数组变量形式。例如:
  http://192.168.0.188:8080/get_session_list.cgi
  IP Camera 会返回:
  var session_user=new Array();
  var session_ip=new Array();
  session_user[0]='admin';
  session_ip[0]='192.168.0.16';
  var number=1;
  其中 session_user 和 session_ip 都是数组变量,而 number 是数组的成员数量。
而对于某些应用中,用户可能不希望使用 IP Camera 缺省返回的变量名称,
例如第一个例子,用户不希望使用 ip 的变量名,而想使用 camera_ip 的变量名,则可以:
  http://192.168.0.188/get_params.cgi?ip=camera_ip
  IP Camera 会返回:
var camera_ip='192.168.0.188';

如何设置让 cgi 返回 json/jsonp 类型数据呢? 用户可在 cgi 的参数中增加 json 参数和 jsonp_callback 参数,其中 json 参数指定 camera 返回的数据类型:

0 或者没有附加 json 参数的,则返回文本信息或 js 文本
1: 返回 json 文本
2:返回 jsonp 文本,此时可通过 jsonp_callback 参数指定返回的回调函数名称,否则缺省使用 “callback” 函数名称,参数则是返回的 json 对象。

Camera 返回的 json 对象中,始终会有一个 error 变量来指定本次 cgi 调用的结果:

  0  

操作成功

 -1 

操作失败:认证错误

 -2 

操作失败:参数错误

 -3 

操作失败:达到最大的 session 数目

 -4 

操作失败:camera 内部错误

 -5 

操作失败:超时

 -6 

操作失败:错误或不支持的操作请求

当 error 不等于0 时,就没有后续的返回了。

版权所有:深圳市瑞彩电子科技有限公司

信产部备案号:粤ICP备09050685号 技术支持:800069965