CAPL内置的时间函数

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

本文几乎全部摘录自Vector的官方文档，只是做了整理与翻译。

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

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

二、 获取当前的模拟时间

这里主要介绍 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个条目。 数组的条目将填充以下信息：

举例说明

示例代码：

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)

3.2 函数: getLocalTimeString()

函数语法

void getLocalTimeString(char timeBuffer[]);

函数功能描述

将当前日期和时间的打印表示复制到提供的字符缓冲区中。字符串的格式为 ddd mmm dd hh:mm:ss jjj （例如"Fri Aug 21 15:22:24 1998"）。

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

函数参数介绍

举例说明

示例代码：

char timeBuffer[64];
getLocalTimeString(timeBuffer);
// now timeBuffer contains for example. "Fri Aug 21 15:22:24 1998"

3.3 函数: getMeasurementStartTime()

函数语法

long getMeasurementStartTime(long time[]);

函数功能描述

返回有关开始测量的绝对时间的详细信息。

注意事项: 在CANoe的offline模式下，函数返回日志文件中存储的最早开始时间。

函数参数介绍

只有一个参数 time ， 它的类型为 long 类型的数组(array) ，至少有8个条目。数组的条目将填充以下信息：

返回值介绍

1 if successful, 0 if not (e.g. array to small).

举例说明

示例代码：

on errorframe
  long time[8];
  addTimeToMeasurementStartTime(timeNowNS(), time);
  write("ErrorFrame occured on %02d/%02d/%02d %02d:%02d:%02d.%-3d",
  time[5]+1, time[4], time[6]-100, time[3], time[2], time[1], time[0]);
  getMeasurementStartTime(time);
  write("Measurement was started on %02d/%02d/%02d %02d:%02d:%02d.%-3d",
  time[5]+1, time[4], time[6]-100, time[3], time[2], time[1], time[0]);
// Output e.g.:
// ErrorFrame occured on 08/15/17 14:39:46.787
// Measurement was started on 08/15/17 14:39:29.547

3.4 函数: addTimeToMeasurementStartTime()

函数语法

long addTimeMeasurementStartTime(int64 timeSpan, long time[]);

函数功能描述

计算测量开始的绝对日期/时间加上偏移量（例如时间戳）。

函数参数介绍

• 参数 timeSpan : 要添加到测量开始时间的时间，例如测量帧的时间戳。
• 参数 time : 与 getMeasurementStartTime() 函数中的入参完全一致

另外，函数的返回值与示例代码，均可参考 getMeasurementStartTime() 函数中的说明。

四、时间转换

这里主要介绍 convertTimestamp() , convertTimestampNS() 两个函数。

4.1. 函数: convertTimestamp()

函数语法

void convertTimestamp(dword timestamp, 
                      dword& days, byte& hours, byte& minutes, 
                      byte& seconds, word& milliSeconds, 
                      word& microSeconds);

函数功能描述

将时间戳转(time stamp)换为单独的部分（最长时间：. 2^32*10微秒 =11小时55分49秒672毫秒96微秒）。

函数参数介绍

示例代码可以参见函数 convertTimestampNS() 中的介绍。

4.2. 函数: convertTimestampNS()

函数语法

void convertTimestampNS(qword timestamp, 
                        dword& days, byte& hours, byte& minutes, 
                        byte& seconds, word& milliSeconds, 
                        word& microSeconds, word& nanoSeconds);

函数功能描述

将时间戳转(time stamp)换为单独的部分。

函数参数介绍

举例说明

示例代码：

on envVar EnvGearUp