ONVIF协议网络摄像机（IPC）客户端程序开发（14）：修改分辨率
1 专栏导读
本专栏第一篇文章「专栏开篇」列出了专栏的完整目录，按目录顺序阅读，有助于你的理解，专栏前面文章讲过的知识点（或代码段），后面文章不会赘述。为了节省篇幅，突出重点，在文章中展示的示例代码仅仅是关键代码，你可以在「专栏开篇」中获取完整代码。
如有错误，欢迎你的留言纠正！让我们共同成长！你的**「点赞」或「打赏」**是对我最大的支持和鼓励！
2 原理简介
IPC有关多媒体的参数，都是由媒体配置文件（media profile）来管理。想通过ONVIF协议修改IPC诸如分辨率这样的媒体参数，就得先弄懂媒体配置文件。
媒体配置文件（media profile）是用于管理音视频流相关的一系列配置的集合，一个配置文件由一系列相关联的配置类实体构成。配置类包括：
- Video source configuration（视频源配置）
- Audio source configuration（音频源配置）
- Video encoder configuration（视频编码器配置）
- Audio encoder configuration（音频编码器配置）
- PTZ configuration（PTZ配置）
- Video analytics configuration（视频分析配置）
- Metadata configuration（元数据配置）
- Audio output configuration（音频输出配置）
- Audio decoder configuration（音频解码器配置）
对应的结构体为：
struct tt__Profile {
char *Name;
struct tt__VideoSourceConfiguration *VideoSourceConfiguration;
struct tt__AudioSourceConfiguration *AudioSourceConfiguration;
struct tt__VideoEncoderConfiguration *VideoEncoderConfiguration;
struct tt__AudioEncoderConfiguration *AudioEncoderConfiguration;
struct tt__VideoAnalyticsConfiguration *VideoAnalyticsConfiguration;
struct tt__PTZConfiguration *PTZConfiguration;
struct tt__MetadataConfiguration *MetadataConfiguration;
struct tt__ProfileExtension *Extension;
char *token;
enum xsd__boolean *fixed;
};
一个tt__Profile结构体就是一个媒体配置文件，一个配置文件由全部的或部分的配置类实体组成，“部分”的意思是，对于不支持的功能（如PTZ），允许其配置信息为空（PTZConfiguration为NULL）。
这里有一个概念一定要理清楚，配置类和实体的区别：
- 就某个配置类而言，一个设备可以有多个实体。如「视频编码器配置」类，一个IPC设备至少包含两个「视频编码器配置」实体，分别关联主码流和辅码流，这两个「视频编码器配置」实体参数有所区别，如分辨率不同，码率不同等等。
- 一个媒体配置文件由一不同配置类的实体组成，同一配置类的不同实体，只能有一个实体跟媒体配置文件关联。
- 一个设备可以有多个媒体配置文件，如主码流、辅码流就是两个不同的媒体配置文件。
为了唯一标识某个配置实体，每个配置实体都有对应的唯一标识符token，很多的ONVIF媒体接口也是通过这些token来访问（修改）这些配置的。比如，视频源配置token、音频源配置token、视频编码器配置token，甚至连媒体配置文件本身都有token。如下图红色矩形框所示（GetProfiles接口）：
3 函数接口
对于某个具体的配置类，ONVIF都提供了一套完整的函数接口，类似如下：
- AddXXXConfiguration：新增XXX配置
- RemoveXXXConfiguration：删除指定的XXX配置
- GetXXXConfigurations：获取所有的XXX配置
- GetXXXConfiguration：获取指定的XXX配置
- GetXXXConfigurationOptions：获取XXX配置选项集
- GetCompatibleXXXConfigurations：获取所有兼容的XXX配置
- SetXXXConfiguration：修改指定的XXX配置
将XXX替换成VideoEncoder，就得到了「视频编码器配置」类相关的ONVIF接口，其他配置类也如此：
- AddVideoEncoderConfiguration：新增视频编码器配置
- RemoveVideoEncoderConfiguration：删除指定的视频编码器配置
- GetVideoEncoderConfigurations：获取所有的视频编码器配置
- GetVideoEncoderConfiguration：获取指定的视频编码器配置
- GetVideoEncoderConfigurationOptions：获取视频编码器配置选项集
- GetCompatibleVideoEncoderConfigurations：获取所有兼容的视频编码器配置
- SetVideoEncoderConfiguration：修改指定的视频编码器配置
「媒体配置文件」与「视频编码器配置」的关系：
| ONVIF对应的函数接口 | 备注 | |
|---|---|---|
| 一个设备可以有多个「媒体配置文件」 | GetProfile GetProfiles |
比如主码流、辅码流，是两个相互独立的媒体配置文件。每个媒体配置文件的token不同。 |
| 一个设备可以有多个「视频编码器配置」实体 | GetVideoEncoderConfiguration GetVideoEncoderConfigurations |
|
| 一个「媒体配置文件」只能关联一个「视频编码器配置」实体 | AddVideoEncoderConfiguration | |
| 每个「视频编码器配置」实体独享属于自己的一套参数选项集 | GetVideoEncoderConfigurationOptions | 比如IPC的主码流，视频分辨率只能设置为预先设定好的几个分辨率（选项集）中的一种，不能随意配置。可选择的分辨率是IPC出厂时就与设定好的，没法通过ONVIF接口增/删/改。 “独享”的意思，就是视频编码器配置1的分辨率，只能在视频编码器配置1中使用，不能在视频编码器配置2中使用。比如主码流的1080P分辨率，不能配置到辅码流中。 |
4 编码流程
IPC客户端通过ONVIF修改分辨率的步骤如下：
- 先通过GetProfiles获取所有媒体配置文件，可得知主/辅码流的视频编码器配置token；
- 由视频编码器配置token通过SetVideoEncoderConfiguration修改视频编码器配置（如修改分辨率、帧率、码率等）；
- 修改的参数必须在GetVideoEncoderConfigurationOptions中的选项集范围内（即IPC出厂时预设定好的那几个选项集），如分辨率只能设置为那几种中的一种，不能随意设置。否则SetVideoEncoderConfiguration会返回失败。
- 每个视频编码器配置的分辨率可选集，只能自个使用，不能用于其他视频编码器配置中。比如主码流的1080P分辨率，不能配置到辅码流中，SetVideoEncoderConfiguration会调用失败。
5 示例代码
#include
#include
#include
#include "onvif_comm.h"
#include "onvif_dump.h"
/************************************************************************
**函数：ONVIF_GetVideoEncoderConfigurationOptions
**功能：获取指定视频编码器配置的参数选项集
**参数：
[in] MediaXAddr - 媒体服务地址
[in] ConfigurationToken - 视频编码器配置的令牌字符串，如果为NULL，则获取所有视频编码器配置的选项集（会杂在一起，无法区分选项集是归属哪个视频编码配置器的）
**返回：
0表明成功，非0表明失败
**备注：
1). 有两种方式可以获取指定视频编码器配置的参数选项集：一种是根据ConfigurationToken，另一种是根据ProfileToken
************************************************************************/
int ONVIF_GetVideoEncoderConfigurationOptions(const char *MediaXAddr, char *ConfigurationToken)
{
int result = 0;
struct soap *soap = NULL;
struct _trt__GetVideoEncoderConfigurationOptions req;
struct _trt__GetVideoEncoderConfigurationOptionsResponse rep;
SOAP_ASSERT(NULL != MediaXAddr);
SOAP_ASSERT(NULL != (soap = ONVIF_soap_new(SOAP_SOCK_TIMEOUT)));
memset(&req, 0x00, sizeof(req));
memset(&rep, 0x00, sizeof(rep));
req.ConfigurationToken = ConfigurationToken;
ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);
result = soap_call___trt__GetVideoEncoderConfigurationOptions(soap, MediaXAddr, NULL, &req, &rep);
SOAP_CHECK_ERROR(result, soap, "GetVideoEncoderConfigurationOptions");
dump_trt__GetVideoEncoderConfigurationOptionsResponse(&rep);
EXIT:
if (NULL != soap) {
ONVIF_soap_delete(soap);
}
return result;
}
/************************************************************************
**函数：ONVIF_GetVideoEncoderConfiguration
**功能：获取设备上指定的视频编码器配置信息
**参数：
[in] MediaXAddr - 媒体服务地址
[in] ConfigurationToken - 视频编码器配置的令牌字符串
**返回：
0表明成功，非0表明失败
**备注：
************************************************************************/
int ONVIF_GetVideoEncoderConfiguration(const char *MediaXAddr, char *ConfigurationToken)
{
int result = 0;
struct soap *soap = NULL;
struct _trt__GetVideoEncoderConfiguration req;
struct _trt__GetVideoEncoderConfigurationResponse rep;
SOAP_ASSERT(NULL != MediaXAddr);
SOAP_ASSERT(NULL != (soap = ONVIF_soap_new(SOAP_SOCK_TIMEOUT)));
ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);
memset(&req, 0x00, sizeof(req));
memset(&rep, 0x00, sizeof(rep));
req.ConfigurationToken = ConfigurationToken;
result = soap_call___trt__GetVideoEncoderConfiguration(soap, MediaXAddr, NULL, &req, &rep);
SOAP_CHECK_ERROR(result, soap, "GetVideoEncoderConfiguration");
dump_trt__GetVideoEncoderConfigurationResponse(&rep);
EXIT:
if (NULL != soap) {
ONVIF_soap_delete(soap);
}
return result;
}
/************************************************************************
**函数：ONVIF_SetVideoEncoderConfiguration
**功能：修改指定的视频编码器配置信息
**参数：
[in] MediaXAddr - 媒体服务地址
[in] venc - 视频编码器配置信息
**返回：
0表明成功，非0表明失败
**备注：
1). 所设置的分辨率必须是GetVideoEncoderConfigurationOptions返回的“分辨率选项集”中的一种，否则调用SetVideoEncoderConfiguration会失败。
************************************************************************/
int ONVIF_SetVideoEncoderConfiguration(const char *MediaXAddr, struct tagVideoEncoderConfiguration *venc)
{
int result = 0;
struct soap *soap = NULL;
struct _trt__GetVideoEncoderConfiguration gVECfg_req;
struct _trt__GetVideoEncoderConfigurationResponse gVECfg_rep;
struct _trt__SetVideoEncoderConfiguration sVECfg_req;
struct _trt__SetVideoEncoderConfigurationResponse sVECfg_rep;
SOAP_ASSERT(NULL != MediaXAddr);
SOAP_ASSERT(NULL != venc);
SOAP_ASSERT(NULL != (soap = ONVIF_soap_new(SOAP_SOCK_TIMEOUT)));
memset(&gVECfg_req, 0x00, sizeof(gVECfg_req));
memset(&gVECfg_rep, 0x00, sizeof(gVECfg_rep));
gVECfg_req.ConfigurationToken = venc->token;
ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);
result = soap_call___trt__GetVideoEncoderConfiguration(soap, MediaXAddr, NULL, &gVECfg_req, &gVECfg_rep);
SOAP_CHECK_ERROR(result, soap, "GetVideoEncoderConfiguration");
if (NULL == gVECfg_rep.Configuration) {
SOAP_DBGERR("video encoder configuration is NULL.\n");
goto EXIT;
}
memset(&sVECfg_req, 0x00, sizeof(sVECfg_req));
memset(&sVECfg_rep, 0x00, sizeof(sVECfg_rep));
sVECfg_req.ForcePersistence = xsd__boolean__true_;
sVECfg_req.Configuration = gVECfg_rep.Configuration;
if (NULL != sVECfg_req.Configuration->Resolution) {
sVECfg_req.Configuration->Resolution->Width = venc->Width;
sVECfg_req.Configuration->Resolution->Height = venc->Height;
}
ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);
result = soap_call___trt__SetVideoEncoderConfiguration(soap, MediaXAddr, NULL, &sVECfg_req, &sVECfg_rep);
SOAP_CHECK_ERROR(result, soap, "SetVideoEncoderConfiguration");
EXIT:
if (SOAP_OK == result) {
SOAP_DBGLOG("\nSetVideoEncoderConfiguration success!!!\n");
}
if (NULL != soap) {
ONVIF_soap_delete(soap);
}
return result;
}
void cb_discovery(char *DeviceXAddr)
{
int stmno = 0; // 码流序号，0为主码流，1为辅码流
int profile_cnt = 0; // 设备配置文件个数
struct tagProfile *profiles = NULL; // 设备配置文件列表
struct tagCapabilities capa; // 设备能力信息
ONVIF_GetCapabilities(DeviceXAddr, &capa); // 获取设备能力信息（获取媒体服务地址）
profile_cnt = ONVIF_GetProfiles(capa.MediaXAddr, &profiles); // 获取媒体配置信息（主/辅码流配置信息）
if (profile_cnt > stmno) {
struct tagVideoEncoderConfiguration venc;
char *vencToken = profiles[stmno].venc.token;
ONVIF_GetVideoEncoderConfigurationOptions(capa.MediaXAddr, vencToken); // 获取该码流支持的视频编码器参数选项集
ONVIF_GetVideoEncoderConfiguration(capa.MediaXAddr, vencToken); // 获取该码流当前的视频编码器参数
venc = profiles[stmno].venc;
venc.Height = 960;
venc.Width = 1280;
ONVIF_SetVideoEncoderConfiguration(capa.MediaXAddr, &venc); // 设置该码流当前的视频编码器参数
ONVIF_GetVideoEncoderConfiguration(capa.MediaXAddr, vencToken); // 观察是否修改成功
}
if (NULL != profiles) {
free(profiles);
profiles = NULL;
}
}
int main(int argc, char **argv)
{
ONVIF_DetectDevice(cb_discovery);
return 0;
}