库调用

C 和 C++ 库

在仪器化期间生成的 CoverageScanner 库，可以供您使用

初始化测量系统并选择 .csexe 文件名
安装一个退出时的处理程序，它将保存执行报告
在一个单元测试场景中，向执行报告中传递有关测试的信息，特别是测试名称、注释和测试结果
处理动态加载的库
针对特殊需求自定义输出系统

库函数可以从任何仪器化文件中访问，而无需包含指令。当一个文件被仪器化时，定义了一个预处理器符号 __COVERAGESCANNER__。它可以用来在仪器化关闭时从编译过程中排除对库函数的调用。

`__coveragescanner_install()`

void __coveragescanner_install(const char *appname)

注意：此函数对于 gcc、clang、Microsoft^® Visual Studio^® 或大多数其他现代 C/C++ 编译器不是必需的。

初始化 CoverageScanner 库。它应该是 main() 函数中的第一个函数调用。参数 appname 包含可执行文件名称。它用于设置测量文件名为 <appname>.csmes。

__coveragescanner_install() 通过 atexit() 注册一个退出处理程序，以便在应用程序终止时保存执行报告。处理程序在程序正常终止时调用函数 __coveragescanner_save() 来存储程序结束时的执行迹线。它也是在程序收到信号 SIGABRT、SIGTERM、SIGFPE、SIGILL、SIGINT、SIGSEGV 和 SIGTERM 时调用的。

建议的使用方法

int main(int argc,char *argv[])
{
#ifdef __COVERAGESCANNER__
  __coveragescanner_install(argv[0]);
#endif
  ...
}

平台依赖性

使用 gcc、clang 或 Visual Studio，CoverageScanner 会自动安装一个最小化的处理器。它会在应用程序正常退出时，将执行情况保存在文件 程序名 > .csmes 中。调用 __coveragescanner_install() 允许设置执行报告的文件名，并在程序异常退出（如崩溃或被信号中断）时保存报告。

__coveragescanner_install() 不适用于其配置参数 CUSTOM_SETUP 设置为 NONE 的编译器（参见CoverageScanner 对工具套件的适应）。

`__coveragescanner_testname()`

void __coveragescanner_testname(const char *name)

设置当前测试/执行的名称。它将被保存在执行报告中，并在将 .csmes 文件加载到 CoverageBrowser 时，在 Executions 窗口（参见 Executions）中显示。

由程序结束或下一次调用 __coveragescanner_save() 之前的所有代码都被视为测试 name 的一部分。如果测试有相同的名称，CoverageBrowser 会通过数字进行区别，例如 MyTest (2)。

测试名称可以是分层的，层级之间用斜杠分隔：如果一个程序定义了两个测试，group/test1 和 group/test2，CoverageBrowser 会将其显示为在 common heading group 下的两个测试，test1 和 test2。

注意：此函数以及直到 __coveragescanner_save() 的以下函数特别适用于与单元测试框架一起使用（参见测试套件和 Coco）。

`__coveragescanner_teststate()`

void __coveragescanner_teststate(const char *state)

设置当前测试的状态。参数 状态 可能具有以下值

PASSED：测试成功。
FAILED：测试未成功。
INCIDENT：测试未成功（与失败类似）。
CHECK_MANUALLY：无法确定测试是否成功。
SKIPPED：跳过了测试。

如果该函数被调用两次，第一次的状态将被覆盖。测试状态将被保存在执行报告中，并在将 .csmes 文件加载到 CoverageBrowser 时，显示在 Executions 窗口（参见 Executions）中。

`__coveragescanner_add_html_comment()`

void __coveragescanner_add_html_comment(const char *comment)

为当前执行设置 HTML 注释。任何时候都只有一个活动的 HTML 注释，但它可以通过多次调用 __coveragescanner_add_html_comment() 来组合。在这种情况下，多个 comment 参数的值会被连接起来。

完整的注释必须遵循 HTML 语法，但只使用 <body> 标签的内容。因此，一个简单的注释可能如下所示：<html><body>My comment</body></html>。

`__coveragescanner_clear_html_comment()`

void __coveragescanner_clear_html_comment()

删除由 __coveragescanner_add_html_comment() 调用所添加的注释。

`__coveragescanner_save()`

void __coveragescanner_save()

保存执行报告并重置所有仪器状态。每行代码的覆盖率计数字和当前测试的执行状态都会重置，但HTML注释保持不变。

`__coveragescanner_clear()`

void __coveragescanner_clear()

重置所有行代码的覆盖率计数字。

这在单元测试框架中非常有用。框架启动后，可以调用__coveragescanner_clear()。这样可以确保框架启动时的活动不包括在代码覆盖率中。

`__coveragescanner_filename()`

void __coveragescanner_filename(const char *name)

设置执行报告的文件名。自动添加扩展名.csexe。如果name是NULL，则禁用执行报告的生成。

name可能包含以下转义序列

%p：如果平台提供，则过程标识符，否则为空字符串。
%w：工作目录。当初始化CoverageBrowser库时计算该值；之后不再改变。
%t：当前时间，如果无法计算则为空字符串。
%d：当前日期，如果无法计算则为空字符串。

平台依赖性

仅当编译器的配置参数FILE_FORMAT_SPECIFIER设置为YES时（请参阅CoverageScanner 对工具集的适应性），才可用于转义序列。

在某些嵌入式平台上可能无法获得日期和时间。

`__coveragescanner_get_filename()`

const char * __coveragescanner_get_filename()

返回.csexe文件名。

`__coveragescanner_register_library()`

int __coveragescanner_register_library(const char *library_name)

注册按需加载的共享库。必须在用dlopen()（UNIX^®）或LoadLibrary()（Microsoft^® Windows）加载库之后调用此函数。注册后，库的代码覆盖率将保存在与主应用程序覆盖率相同的覆盖率报告文件中。

可以多次调用__coveragescanner_register_library()，但每个调用都必须与相应的__coveragescanner_unregister_library()调用相匹配。对于每个库都有一个使用计数器来跟踪注册。

返回值

0：成功。
-1：错误：无法加载库。
-2：错误：无效的库名称。
1：成功，但库已注册。库的使用计数器已增加。
2：成功，但库未进行仪器化。

注意：有关使用此函数和以下函数的信息，请参阅库代码覆盖率。

平台依赖性

__coveragescanner_register_library()和__coveragescanner_unregister_library()不可用于配置参数PLUGIN_REGISTRATION_API设置为NO的编译器（请参阅CoverageScanner 对工具集的适应性）。

`__coveragescanner_unregister_library()`

int __coveragescanner_unregister_library(const char *library_name)

注销在需求时加载的共享库。必须在用 dlclose() (UNIX) 或 CloseHandle() (Windows) 卸载库之前调用此函数。

返回值

0：成功。
-1：错误：库未注册。
-2：错误：无效的库名称。
1：成功，但库未注销，因为其使用计数不为空。
2：成功，但库未进行仪器化。

`__coveragescanner_register_squish()`

void __coveragescanner_register_squish()

尝试使用 Squish 注册可测量应用程序。这使得 Coco 库的大多数函数对 Squish 可访问，使其能够控制覆盖率测量的写入。

通常不需要显式调用此函数，因为它在应用程序启动时自动调用（或者在需要时通过 __coveragescanner_install() 调用）。

多次调用该函数的效果与调用一次相同。如果应用程序没有通过 Squish 启动，则该函数没有任何作用。

`__coveragescanner_memory_pool_stat()`

void __coveragescanner_memory_pool_stat(int *size, int *used, int * max_used )

检索内存池的当前内存消耗。

返回以下参数：

size：内存池的整体大小。
used：当前内存使用量。
max_used：峰值内存使用量。

此函数仅在使用内存池的情况下有意义。

`__coveragescanner_set_custom_io()`

默认情况下，CoverageScanner 帮助使用通用 C 库函数将执行报告（.csexe 文件）写入文件系统。在某些情况下，例如在嵌入式系统中，需要使用其他方法。因此，CoverageScanner 提供了 __coveragescanner_set_custom_io()，这允许您替换 __coveragescanner_save() 使用的输出函数。

void __coveragescanner_set_custom_io(
    char *(*csfgets)(char *s, int size, void *stream),
    int (*csfputs)(const char *s, void *stream),
    void *(*csfopenappend)(const char *path),
    void *(*csfopenread)(const char *path),
    void *(*csfopenwrite)(const char *path),
    int (*csfclose)(void *stream),
    int (*csremove)(const char *path) );

参数 0、3 和 6（《code translate="no">csfgets、`csfopenread` 和 `csfremove`）是仅在使用 `coveragescanner` 参数 `--cs-lock-csexe` 时使用的函数的指针。如果您不使用该选项，可以为每个提供 `NULL` 指针。

`csfopenappend`、`csfopenread` 和 `csfopenwrite` 返回的 `void* stream` 指针稍后作为参数传递给 `csfputs`、`csfgets` 和 `csfclose`。它们可以是，但不必须是 `FILE*` 类型。

参数：

csfgets：从 stream 中读取最多 size - 1 个字符并将其存储在由 s 指向的缓冲区中。读取在读取到 EOF 或换行后停止。如果读取到换行，则将其存储在缓冲区中。在缓冲区的最后一个字符之后存储一个 \0。成功时返回非负数，或错误时返回 EOF。仅用于 `--cs-lock-csexe`。
csfputs：将字符串 `s` 写入 `stream`，不写入其尾部的 `\0`。成功时返回非负数，或错误时返回 EOF。
csfopenappend：以附加文本的方式打开文件 `path`。返回稍后传递给 `csfputs` 或 `csfclose` 的流指针
csfopenread: 以读取方式打开文件 path。返回的流指针稍后将传递给 csfgets 或 csfclose。仅用于 --cs-lock-csexe。
csfopenwrite: 以写入方式打开文件 path。返回的流指针稍后将传递给 csfputs 或 csfclose。
csfclose: 清空并关闭 stream。如果成功则返回 0，如果发生错误则返回 EOF。
csremove: 从文件系统中删除 filename。如果成功则返回 0，如果发生错误则返回 EOF。仅用于 --cs-lock-csexe。

这些 I/O 函数默认实现。

char *csfgets(char *s, int size, void *stream) { return fgets(s, size, (FILE *)stream); }
int csfputs(const char *s, void *stream)       { return fputs(s, (FILE *)stream); }
void *csfopenappend(const char *path)          { return (void*)fopen(path, "a+"); }
void *csfopenread(const char *path)            { return (void*)fopen(path, "r"); }
void *csfopenwrite(const char *path)           { return (void*)fopen(path, "w"); }
int csremove(const char *path)                 { return remove(path); }
int csfclose(void *stream)                     { return fclose((FILE*)stream); }

有关示例，请参阅Customizing I/O of CoverageScanner library。

C# 库

CoverageScanner 库在链接过程中生成，使用户能够

生成执行报告。
给正在执行的测试命名。
安装信号处理器，以便在退出时保存执行报告。

此外，CoverageScanner 设置预处理程序符号 __COVERAGESCANNER__，从而将该函数排除在常规编译之外。

`CoverageScanner.__coveragescanner_init()`

void CoverageScanner.__coveragescanner_init()

CoverageScanner.__coveragescanner_init() 显式初始化 CoverageScanner 库。只有当 C# DLL 未自动调用静态模块初始化器时，才需要调用此函数。

`CoverageScanner.__coveragescanner_testname()`

void CoverageScanner.__coveragescanner_testname(string name)

CoverageScanner.__coveragescanner_testname() 设置当前正在执行的测试名称。它将被保存到执行报告中，并在加载到 CoverageBrowser 时显示在 Executions 窗口中（参见Executions）。

`CoverageScanner.__coveragescanner_teststate()`

void CoverageScanner.__coveragescanner_teststate(string state)

设置当前正在执行的测试状态。字符串参数 state 可以有以下值

PASSED: 测试成功执行。
FAILED: 测试未成功通过。
INCIDENT: 测试未成功执行（类似于失败）。
CHECK_MANUALLY: 无法确定测试是否成功执行。
SKIPPED：跳过了测试。

这些值将被保存到执行报告中，并在加载到 CoverageBrowser 时显示在 Executions 窗口中（参见Executions）。

`CoverageScanner.__coveragescanner_add_html_comment()`

void __coveragescanner_add_html_comment(string comment)

将一条注释附加到当前执行中。注释需要遵循 HTML 语法，但只解析正文。忽略 <HEAD> 标签的内容。此函数可以多次调用以附加内容。

`CoverageScanner.__coveragescanner_clear_html_comment()`

void __coveragescanner_clear_html_comment()

清除使用 void __coveragescanner_add_html_comment(string comment) 添加的注释。

`CoverageScanner.__coveragescanner_save()`

void CoverageScanner.__coveragescanner_save()

保存执行报告并重置所有仪器状态。

`CoverageScanner.__coveragescanner_clear()`

void CoverageScanner.__coveragescanner_clear()

重置所有插装的状态。

`CoverageScanner.__coveragescanner_filename()`

void CoverageScanner.__coveragescanner_filename(string name)

设置执行报告的文件名。文件扩展名 .csexe 会自动添加。

注意：如果没有使用初始化函数 __coveragescanner_install()，则设置执行报告文件名是必要的。

`CoverageScanner.__coveragescanner_set_custom_io()`

void CoverageScanner.__coveragescanner_set_custom_io(
    __cs_fgets_delegate cs_fgets,
    __cs_fputs_delegate cs_fputs,
    __cs_fopenappend_delegate cs_fopenappend,
    __cs_fopenread_delegate cs_fopenread,
    __cs_fopenwrite_delegate cs_fopenwrite,
    __cs_fclose_delegate cs_fclose,
    __cs_remove_delegate cs_remove)

CoverageScanner 使用常见的 C# 文件 IO 函数写入执行报告 (.csexe 文件)。例如，对于嵌入式系统，可能需要使用另一种方式来记录它。因此，CoverageScanner 提供了 CoverageScanner.__coveragescanner_set_custom_io()，它将替换 CoverageScanner.__coveragescanner_save() 使用的 IO 函数。

参数：

csfgets:
public delegate string __cs_fgets_delegate(System.IO.Stream stream)

从 stream 中读取最多 size 个字符减一的字符，并存储到由 s 指向的缓冲区中。在读取到 EOF 或换行符后停止读取。如果读取到换行符，它将存储到缓冲区中。在缓冲区中的最后一个字符后面存储一个 \0。
csfputs:
public delegate void __cs_fputs_delegate(string s, System.IO.Stream stream)

将字符串 s 写入 <stream>，不包括其尾随的 \0。
csfopenappend:
public delegate System.IO.Stream __cs_fopenappend_delegate(string path)

以追加模式打开文件 <path>。
csfopenread:
public delegate System.IO.Stream __cs_fopenread_delegate(string path)

以读取模式打开文件 <path>。
csfopenwrite:
public delegate System.IO.Stream __cs_fopenwrite_delegate(string path)

以写入模式打开文件 <path>。
csfclose:
public delegate void __cs_fclose_delegate(System.IO.Stream stream)

刷新并关闭由 <stream> 指向的流。
csremove:
public delegate void __cs_remove_delegate(string path)

从文件系统中删除 path。

CoverageScanner 命令行参数从源代码中控制插装