CAPL内置的时间函数

CAPL内置的时间函数

在CAPL中我们要经常和时间打交道，为了方便的写CAPL脚本，所以我整理了Vector官方提供的与时间有关的函数，并对常用的进行简单说明。

本文主体部分摘录了Vector的官方文档，做了整理与翻译；另外增加了一些我自己的理解与编写的实际函数 。

一、CAPL中与时间管理有关的函数

Windows和Linux支持这些CAPL功能。Linux下的功能尚未经过全面测试。

Functions	Short Description
addTimeToMeasurementStartTime	计算测量开始的绝对日期/时间加上偏移量
cancelTimer	停止一个已经激活的定时器
convertGPSTimestamp	将GPS时间戳转换为基于UTC的日期和时间信息
convertTimestamp	将时间戳转换为单独的部分
convertTimestampNS	将时间戳转换为单独的部分
convertTimestampToNS	将以天、小时、分钟和秒为单位的时间戳转换为纳秒时间戳
convertUTCDateToUnixTimestamp	将给定的UTC时间和日期转换为UNIX时间戳（自1970-01-01以来的秒数）
EnvVarTimeNS	返回环境变量 envVariable 的时间戳（以纳秒为单位）
getDrift	Determines the constant deviation when Drift is set.
getGPSTimeString	Copies a printed representation of the GPS time stamp represented as UTC date and time into the supplied character buffer.
getJitterMax	确定设置抖动(Jitter)时允许偏差的上限
getJitterMin	确定设置抖动(Jitter)时允许偏差的下限
getLocalTime	返回当前日期和时间的详细信息
getLocalTimeString	复制当前日期和时间的打印表示
getMeasurementStartTime	返回有关开始测量的绝对时间的详细信息
isTimerActive	返回值指示特定计时器是否处于活动状态
MessageTimeNS	返回以纳秒为单位的时间戳
setDrift	为网络节点的计时器设置恒定偏差
setJitter	设置网络节点的计时器的抖动间隔(Jitter interval)
setTimer	设置一个定时器
setTimerCyclic	设置一个周期性的定时器
timeDiff	消息之间或消息与当前时间之间的时间差（毫秒）
timeNow	提供当前模拟时间[10微秒]
timeNowFloat	提供当前模拟时间[10微秒]
timeNowInt64	提供当前模拟时间[纳秒]
timeNowNS	提供当前模拟时间[纳秒]
timeToElapse	返回一个值，该值指示在调用计时器上的事件过程之前还要经过多少时间

二、 获取当前的模拟时间

这里主要介绍 timeNow()、 timeNowFloat()、 TimeNowNS() 三个函数，它们的作用几乎相同，主要是返回值类型不同。

2.1 函数: timeNow()

返回当前模拟时间（最长时间：.2^32*10微秒 = 11小时55分49秒672毫秒96微秒）

函数语法

dword timeNow();

函数功能描述

模拟时间(The simulation time)可以与网络接口的硬件结果相关联。这个时间的分辨率取决于所使用的硬件（通常是一毫秒或更好）。

根据硬件配置的不同，模拟时间(The simulation time)可能有两种情况:

• 将与网络接口计算的消息时间相同。
• 消息时间将具有更高的准确性(accuracy)

返回值介绍

模拟时间（单位：10微秒）

举例说明

示例代码：

float x;
x = timeNow()/100000.0; //current time in seconds

2.2 函数: timeNowFloat()

这个函数与timeNow()函数功能几乎完全相同，只有返回值类型有点不同，语法如下：

float timeNowFloat();

示例代码：

float x;
x = timeNowFloat()/100000.0; //current time in seconds

2.3 函数: TimeNowNS()

这个函数与timeNowFloat()函数功能相同，提供当前模拟时间，但是以纳秒为单位，语法如下：

float TimeNowNS();

三、获取机器的绝对时间以及测量的绝对时间

这里主要介绍：

1. getLocalTime()、 getLocalTimeString() 它们的作用几乎相同，主要是返回值类型不同。
2. getMeasurementStartTime()、 addTimeToMeasurementStartTime() 它们通常配合使用，记录测量的绝对时间。

3.1. 函数: getLocalTime()

函数语法

void getLocalTime(long time[]);

函数功能描述

以long类型的数组(array)返回当前日期和时间的详细信息。

分布式模式(distributed mode)使用的注意事项:
此函数始终返回用户计算机的本地时间。

函数参数介绍

类型为long的数组(array)，至少有9个条目。
数组的条目将填充以下信息：

Index	Information
0	Seconds (0 - 59)
1	Minutes (0 - 59)
2	Hours (0 - 23)
3	Day of month (1 - 31)
4	Month (0 - 11)
5	Year (0 - xxx, offset of 1900, e.g. 117 = 2017)
6	Day of week (0 - 6, sunday is 0)
7	Day of Year (0 - 365)
8	Flag for daylight saving time (0 - 1, 1 = daylight saving time)

注意： 这个精确度只能到秒，如果需要更高的精确度，则不能使用这个函数。

举例说明

示例代码：

long tm[9];
getLocalTime(tm);
// now tm contains the following entries:
// tm[0] = 3; (seconds)
// tm[1] = 51; (minutes)
// tm[2] = 16; (hours)
// tm[3] = 21; (day of month)
// tm[4] = 7; (month stating with 0)
// tm[5] = 98; (year)
// tm[6] = 5; (weekday)
// tm[7] = 232;(day of year)
// tm[8] = 1; (Summer time)

我写的一个可以格式化当前时间的函数（本文的后面章节中，我会用到这个函数）：

// 获取当前时间(精确到秒)， 入参保证至少要容纳20个字符
void get_current_Local_Time(char time_str[]){
   
  long tm[9];
  getLocalTime(tm)