THE CLIENT API

Client API是一个库，它提供使用服务器服务进行数据获取的所有必要方法。 Client API可应用于任何类型 DAQ（数据采集） 单元的常用方法和用于特殊操作的附加设备特定方法组成。客户端 API 可由任何代表客户端的应用程序使用。 API 使用包装在 TCP/IP 消息中的 XML 字符串与服务器服务进行通信。字符串携带诸如命令、配置或采集数据之类的信息。唯一的连接句柄始终是用于标识客户端的 XML 字符串的一部分

术语与歧义消除

g.NEEDaccess 文档中引入了几个术语来区分服务器的几个组件和逻辑概念。本章列出了在所有 g.NEEDaccess 文档中一致使用的一些重复使用的术语。 下图说明了服务器的工作原理。客户端可以通过有线或无线网络连接到服务器。如果客户端与服务器服务在同一台计算机上运行，​​则使用环回（IP 地址：127.0.0.1）来寻址机器自己的以太网适配器。

• DEVICE(设备)（或 DAQ 设备）是一种物理设备，即生物信号放大器，可测量数据并将其发送到所连接的计算机。它可以是 g.USBamp、g.HIamp 或 g.Nautilus 类型。 - MASTER/SLAVE(主机/从机)当多个设备（通常是同一类型）进行硬件同步时（即这些设备之一通过硬件同步所有其他设备之间的数据采集），产生时钟的设备是主设备。与主时钟同步的其余设备称为从设备。 1.1 节图中 DAQ 单元内的主站标记为红色。
• SERVER/CLIENT（服务器/客户端）服务器服务在连接到应从中获取数据的所有设备的计算机上运行。服务器从其连接的设备获取数据并将其分发/流式传输到客户端。客户端是应用程序，而不是通过网络接口（使用网络 API）与服务器通信以配置和检索连接到服务器的某些设备的数据的计算机。多个客户端可以在同一台机器上运行，甚至可以在运行服务器服务的同一台机器上运行。服务器在单独的缓冲区中为每个客户端提供获取的数据，可以将其想象为单独的邮箱。客户端必须定期从其专用缓冲区请求和检索数据。这些缓冲区中的每一个都设计用于存储大约 10 秒的原始数据。如果客户端没有足够快地请求足够的数据，则其专用缓冲区会填满，并且当缓冲区已满时可能会向客户端报告溢出。下图显示了内部数据采集管理和客户端到 DAQ 单元的“路由”
• DATA ACQUISITION UNIT (DAQ UNIT数据采集单元)数据采集​​单元是一个虚拟单元，是服务器的一部分。它封装了一个（最简单的情况）或多个硬件同步设备并从中获取数据。属于同一 DAQ 单元的设备必须具有相同的设备类型（并且该类型必须便于硬件同步）。因此，DAQ 单元也可以看作是实际设备类型的（巨大的）单个设备。对于每个特定的独立硬件同步设备组，存在单独的数据采集单元。一个物理设备只能是单个 DAQ 单元的一部分。考虑一个示例，其中六个 g.USBamp 设备连接到服务器。前四个是硬件同步的，并集中在 DAQ 单元 1 中。其余两个设备以相同的方式组成 DAQ 单元 2。因此，有两组独立的设备，服务器将运行两个独立的数据采集单元（DAQ 1 + 2），每组一个
• DATA ACQUISITION SESSION (DAQ SESSION数据采集会话)数据采集​​会话基本上是指一个特定的数据采集单元，但是以更概念化的方式。服务器本身不知道其连接的哪些设备是硬件同步的。当客户端与服务器建立连接时，它必须指定要从中获取数据的特定设备组。该组中指定的所有设备都必须是硬件同步的。如果这些设备都不是另一个数据采集会话/单元的一部分，则服务器为该组创建一个数据采集单元。访问该特定数据采集单元的每个客户端都参与相同的数据采集会话。一旦客户端连接到服务器，就会生成一个唯一的连接句柄，服务器使用该句柄来寻址客户端。
• SESSION CREATOR/PARTICIPANT(会话创建者/参与者)每个客户端都可以从一个 DAQ 单元访问和获取数据。对于另一个客户端，它可以参与正在运行的 DAQ 会话并从其分配的设备获取数据（参见第 1.1.3 节中的图），或者它可以使用不属于某个设备的设备创建新的数据获取会话。现有的数据采集单元。打开特定设备组的第一个客户端是该特定 DAQ 会话的创建者。服务器创建相应的 DAQ 单元。会话创建者可以完全控制他们分配的设备，并可以配置和操作它们。想要打开同一组设备的任何其他客户端都将成为该现有 DAQ 会话的参与者。服务器将客户端与现有的 DAQ 单元相关联，而不是创建一个新的单元。参与者不得控制数据采集或配置设备。基本上，他们只能检索有关该单元的数据和其他信息。当创建者关闭连接并且该单元被服务器销毁时，DAQ 单元的生命周期就会到期。通知可能的现有参与者。单元内的硬件设备被释放，可用于后续的数据采集会话。另一方面，如果参与者关闭其与服务器的连接，则数据获取单元保持运行，至少对于该会话的创建者和所有剩余参与者而言。
• CONNECTION HANDLE(连接句柄)连接句柄基本上是一个唯一编号，用于标识客户端及其关联的数据获取会话。它在创建或打开数据采集会话时分配给客户端。需要指出的是，同一会话的创建者和参与者被分配了不同的连接句柄。每当客户端向服务器发送命令时，其连接句柄都包含在消息中，因此服务器知道该命令属于哪个客户端（和 DAQ 会话）
• GDS GDS 是服务器服务本身的名称，代表 g.tec 设备服务。该术语可能出现在整个客户端 API 参考中。

使用C程序API库

g.NEEDaccess 带有用于 C 编程语言和 .NET 框架的 API，以及用于从 Windows 以外的平台访问 g.NEEDaccess 服务器的底层网络 API 的文档。本文档重点介绍 g.NEEDaccess 的 C API 库。其余 API 存在单独的文档。 C API 可以使用两种不同的方式与服务器通信。客户端 C API 使用网络与服务器通信。服务器端 C API 将命令直接应用到同一台机器上的服务器上，而无需使用网络通信。两者共享相同的接口。有关如何选择要使用的 API，请参阅针对入口点信息 (lib) 的链接部分。如果应用程序使用具有严格时序约束的高性能数据采集，则服务器端 C API 可能更适合满足其要求。 包含的头文件: 对于每个设备，存在一个单独的头文件，其中包含特定于设备的功能和该设备的配置结构。它们都包含基本的头文件 GDSClientAPI.h。仅在项目中包含您正在使用的设备的头文件就足够了，但要确保基本头文件与包含的头文件位于同一目录中。如果您使用不同类型的设备，请包含每种类型的头文件。不要将头文件与您的应用程序一起部署。 针对入口点信息 (LIB) 的链接对于每个受支持的平台，C API 安装路径中的子文件夹包含入口点信息 lib 文件，以供链接器使用。目前，C API 仅支持 64 位 Windows 平台 (x64)。您可以通过链接以下 lib 文件之一来选择使用客户端 C API 或服务器端 C API： 使用动态链接库 (DLL) 执行包含入口点信息 lib 文件的平台子文件夹还包含执行所需的动态链接库 (DLL)。所有这些 DLL 必须与使用它们的应用程序位于同一目录中，或者位于全局系统搜索路径中。如果运行该应用程序的同一台机器也运行 g.NEEDaccess Server，则这些库已经驻留在系统的 PATH 环境变量指向的系统搜索路径上，不需要额外部署。

一般数据采集流程

要使用客户端 API 方法成功获取数据，请确保服务器首先启动并运行。然后，按顺序执行以下步骤：

1. 在第一次使用之前使用 GDS_Initialize 初始化库一次。
2. 确定本地和目标 IP地址以及端口号。服务器（称为目标端点）默认使用端口 50223进行传入连接。建议在同一台机器上运行客户端应用程序和服务器。在这种情况下，本地和目标端点都使用环回地址 (127.0.0.1)。
3. 初始化 GDS_ENDPOINT 结构的两个实例：一个用于本地（客户端），另一个用于目标（服务器）端点。
4. 连接到服务器并使用 GDS_Connect 创建连接句柄。将服务器的端点作为目标端点传递。
5. 设置回调（这不是必需的，但强烈推荐）。
6. 为每个设备创建一个适当的配置结构实例，如有必要，设置配置或执行其他设备特定任务。
7. 使用 GDS_GetDataInfo 确定缓冲区大小并相应地分配内存。如果需要，创建并打开文件（输出流）以将数据保存到文件中。
8. 使用 GDS_StartStreaming开始流式传输。
9. 使用 GDS_GetData 在循环内收集数据。
10. 使用 GDS_StopStreaming 停止流式传输。
11. 使用GDS_StopAcquisition 停止采集。 释放先前分配的资源。如果以前打开过，请关闭输出文件。
12. 使用GDS_Disconnect 断开与服务器的连接。
13. 如果不再使用，则使用 GDS_Uninitialize 取消初始化库。

说明GDSClientAPIDemo项目

` GDSClientAPIDemo 是一个控制台应用程序，用于说明 Microsoft Windows 操作系统下 C++ 编程语言中 g.NEEDaccess Client API 的基本用法。相关的源代码和项目文件位于 GDSClientAPIDemo 文件夹中，该文件夹作为 MS Windows 的示例安装。提供了将 g.NEEDaccess 与 g.USBamp、g.HIamp、g.Nautilus PRO 和 g.Nautilus 设备配合使用的单独示例。运行示例需要在运行 Microsoft Windows 操作系统的主机上运行 g.NEEDaccess 服务器实例。假设示例在运行服务器的同一台机器上执行。这些示例使用环回适配器地址与服务器通信`（有关详细信息，请参阅 g.NEEDaccess 服务器文档）。此外，需要 Microsoft Visual C++（Microsoft Visual Studio 的一部分）来打开预配置的项目文件并编译示例的源代码

编译 GDSClientAPIDemo项目

打开 GDSClientAPIDemo 文件夹中为每种设备类型提供的 MS Visual C++ 项目文件之一（例如 gUSBampDemo.vcxproj）。确保您使用配置管理器从 Build 菜单中选择了适当的平台设置（Win32 for 32-bit, x64 for 64-bit），并通过从 Build 菜单中选择 Build Solution 来编译它。目前，仅支持 64 位平台 (x64) 根据所选平台和配置命名的文件夹将在 GDSClientAPIDemo 文件夹中创建，生成的可执行文件将构建到其中。从 Visual Studio、双击它或从命令行运行可执行文件。启动时，应用程序会扫描连接到当前机器的受支持设备，并提示您从显示的列表中选择其中一个。选择设备后立即开始测量过程，并将数据记录到二进制文件 (data.bin) 中。当预配置的采集持续时间结束时，数据采集将自动停止。应用程序和设备的配置被打印到控制台窗口。它们对于读取记录的数据文件很重要。

读取记录的数据文件

记录的数据文件包含作为 32 位浮点值的采集样本。数据被组织为一系列扫描。每次扫描都包含每个采集通道的一个样本，从第一个采集通道开始。扫描的所有样本都在同一时间点进行采样。可以将其视为格式为channel x samples 的二维矩阵。下面这段代码说明了如何在MATLAB中读入记录的数据文件。必须事先将文件名变量设置为记录数据文件的名称。通道变量必须设置为文件预先包含的获取通道数，包括可能记录的触发通道（或其他可用的附加通道）。 data 变量从文件中接收记录的数据作为格式通道 x 样本的矩阵 ```filename = ‘data.bin’; channels = 16; fid = fopen(filename, ‘rb’); data = fread(fid, [channels, inf], ‘float32’); fclose(fid);

```