ONVIF协议网络摄像机（IPC）客户端程序开发（10）：设备校时

1 专栏导读

本专栏第一篇文章「专栏开篇」列出了专栏的完整目录，按目录顺序阅读，有助于你的理解，专栏前面文章讲过的知识点（或代码段），后面文章不会赘述。为了节省篇幅，突出重点，在文章中展示的示例代码仅仅是关键代码，你可以在「专栏开篇」中获取完整代码。

如有错误，欢迎你的留言纠正！让我们共同成长！你的「点赞」或「打赏」是对我最大的支持和鼓励！

2 编码流程

ONVIF标准中，有 GetSystemDateAndTime和SetSystemDateAndTime两个接口用于获取、设置IPC的系统时间。接口使用大致流程：

1. 搜索出IPC，得到IPC的「设备服务地址」。
2. 根据「设备服务地址」，调用GetSystemDateAndTime和SetSystemDateAndTime接口。

3 注意事项

使用GetSystemDateAndTime和SetSystemDateAndTime这两个接口本是简单的事情，但是有一个细节需要注意，以SetSystemDateAndTime为例，看以上截图（来源于https://www.onvif.org/onvif/ver10/device/wsdl/devicemgmt.wsdl），其中两个字段：

1. TimeZone - 时区

   时区字符串要符合POSIX 1003.1格式，如GMT+00:00、GMT+08:00、GMT-03:30等。

2. UTCDateTime - UTC时间

   该字段要填充UTC时间，不是本地时间，不要搞错了。

IPC摄像头视频中显示的OSD时间，是本地时间，不是UTC时间，而本地时间跟「时区」息息相关。如果你设置了时间，视频OSD显示的时间又不是你预期的，就要注意这里面的关系了。

简单介绍下有关UTC的基础知识：

UTC + 时区差 = 本地时间

时区差，东正西负，北京时区是东八区，领先UTC八个小时，时区差记为+0800，所以

UTC + (＋0800) = 北京时间

UTC与格林尼治平均时(GMT, Greenwich Mean Time)一样，都与英国伦敦的本地时相同。为了简单起见，可以认为UTC与GMT含义是一样的。

4 示例代码

IPC获取、设置系统时间的示例代码如下：

#include 
#include 
#include 
#include "onvif_comm.h"
#include "onvif_dump.h"

#ifdef WIN32
#include 
#endif

/************************************************************************
**函数：ONVIF_GetSystemDateAndTime
**功能：获取设备的系统时间
**参数：
        [in] DeviceXAddr - 设备服务地址
**返回：
        0表明成功，非0表明失败
**备注：
    1). 对于IPC摄像头，OSD打印的时间是其LocalDateTime
************************************************************************/
int ONVIF_GetSystemDateAndTime(const char *DeviceXAddr)
{
    int result = 0;
    struct soap *soap = NULL;
    struct _tds__GetSystemDateAndTime         GetTm_req;
    struct _tds__GetSystemDateAndTimeResponse GetTm_resp;

    SOAP_ASSERT(NULL != DeviceXAddr);

    SOAP_ASSERT(NULL != (soap = ONVIF_soap_new(SOAP_SOCK_TIMEOUT)));

    ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);

    memset(&GetTm_req, 0x00, sizeof(GetTm_req));
    memset(&GetTm_resp, 0x00, sizeof(GetTm_resp));
    result = soap_call___tds__GetSystemDateAndTime(soap, DeviceXAddr, NULL, &GetTm_req, &GetTm_resp);
    SOAP_CHECK_ERROR(result, soap, "GetSystemDateAndTime");

    dump_tds__GetSystemDateAndTime(&GetTm_resp);

EXIT:

    if (NULL != soap) {
        ONVIF_soap_delete(soap);
    }
    return result;
}

/************************************************************************
**函数：ONVIF_GetHostTimeZone
**功能：获取主机的时区信息
**参数：
        [out] TZ    - 返回的时区信息
        [in] sizeTZ - TZ缓存大小
**返回：无
**备注：
************************************************************************/
static void ONVIF_GetHostTimeZone(char *TZ, int sizeTZ)
{
    char timezone[20] = {0};

#ifdef WIN32

    TIME_ZONE_INFORMATION TZinfo;
    GetTimeZoneInformation(&TZinfo);
    sprintf(timezone, "GMT%c%02d:%02d",  (TZinfo.Bias <= 0) ? '+' : '-', labs(TZinfo.Bias) / 60, labs(TZinfo.Bias) % 60);

#else

    FILE *fp = NULL;
    char time_fmt[32] = {0};

    fp = popen("date +%z", "r");
    fread(time_fmt, sizeof(time_fmt), 1, fp);
    pclose(fp);

    if( ((time_fmt[0] == '+') || (time_fmt[0] == '-')) &&
        isdigit(time_fmt[1]) && isdigit(time_fmt[2]) && isdigit(time_fmt[3]) && isdigit(time_fmt[4]) ) {
            sprintf(timezone, "GMT%c%c%c:%c%c", time_fmt[0], time_fmt[1], time_fmt[2], time_fmt[3], time_fmt[4]);
    } else {
        strcpy(timezone, "GMT+08:00");
    }

#endif

    if (sizeTZ > strlen(timezone)) {
        strcpy(TZ, timezone);
    }
    return;
}

/************************************************************************
**函数：ONVIF_SetSystemDateAndTime
**功能：根据客户端主机当前时间，校时IPC的系统时间
**参数：
        [in] DeviceXAddr - 设备服务地址
**返回：
        0表明成功，非0表明失败
**备注：
    1). 对于IPC摄像头，OSD打印的时间是其本地时间（本地时间跟时区息息相关），设置时间时一定要注意时区的正确性。
************************************************************************/
int ONVIF_SetSystemDateAndTime(const char *DeviceXAddr)
{
    int result = 0;
    struct soap *soap = NULL;
    struct _tds__SetSystemDateAndTime           SetTm_req;
    struct _tds__SetSystemDateAndTimeResponse   SetTm_resp;

    char TZ[20];                                                                // 用于获取客户端主机的时区信息（如"GMT+08:00"）
    time_t t;                                                                   // 用于获取客户端主机的UTC时间
    struct tm tm;

    SOAP_ASSERT(NULL != DeviceXAddr);
    SOAP_ASSERT(NULL != (soap = ONVIF_soap_new(SOAP_SOCK_TIMEOUT)));

    ONVIF_GetHostTimeZone(TZ, DIM(TZ));                                         // 获取客户端主机的时区信息

    t = time(NULL);                                                             // 获取客户端主机的UTC时间
#ifdef WIN32
    gmtime_s(&tm, &t);
#else
    gmtime_r(&t, &tm);
#endif

    memset(&SetTm_req, 0x00, sizeof(SetTm_req));
    memset(&SetTm_resp, 0x00, sizeof(SetTm_resp));
    SetTm_req.DateTimeType      = tt__SetDateTimeType__Manual;
    SetTm_req.DaylightSavings   = xsd__boolean__false_;
    SetTm_req.TimeZone          = (struct tt__TimeZone *)ONVIF_soap_malloc(soap, sizeof(struct tt__TimeZone));
    SetTm_req.UTCDateTime       = (struct tt__DateTime *)ONVIF_soap_malloc(soap, sizeof(struct tt__DateTime));
    SetTm_req.UTCDateTime->Date = (struct tt__Date *)ONVIF_soap_malloc(soap, sizeof(struct tt__Date));
    SetTm_req.UTCDateTime->Time = (struct tt__Time *)ONVIF_soap_malloc(soap, sizeof(struct tt__Time));

    SetTm_req.TimeZone->TZ              = TZ;                                   // 设置本地时区（IPC的OSD显示的时间就是本地时间）
    SetTm_req.UTCDateTime->Date->Year   = tm.tm_year + 1900;                    // 设置UTC时间（注意不是本地时间）
    SetTm_req.UTCDateTime->Date->Month  = tm.tm_mon + 1;
    SetTm_req.UTCDateTime->Date->Day    = tm.tm_mday;
    SetTm_req.UTCDateTime->Time->Hour   = tm.tm_hour;
    SetTm_req.UTCDateTime->Time->Minute = tm.tm_min;
    SetTm_req.UTCDateTime->Time->Second = tm.tm_sec;

    ONVIF_SetAuthInfo(soap, USERNAME, PASSWORD);
    result = soap_call___tds__SetSystemDateAndTime(soap, DeviceXAddr, NULL, &SetTm_req, &SetTm_resp);
    SOAP_CHECK_ERROR(result, soap, "SetSystemDateAndTime");

EXIT:

    if (NULL != soap) {
        ONVIF_soap_delete(soap);
    }
    return result;
}