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都提供了一套完整的函数接口，类似如下：

扫描二维码关注公众号，回复： 1157239 查看本文章

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 <stdio.h>
#include <stdlib.h>
#include <assert.h>
#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;
}

ONVIF协议网络摄像机（IPC）客户端程序开发（14）：修改分辨率

1 专栏导读

2 原理简介

3 函数接口

4 编码流程

5 示例代码

猜你喜欢