115.工业相机海康SDK开发指南（阅读）_海康工业相机sdk

一、SDK初始化

包含初始化SDK和反初始化SDK接口。（由于看不到函数内部的具体实现，因此以下的解释仅代表个人的理解）

函数说明

MV_CAMCTRL_API int __stdcall MV_CC_Initialize()//初始化SDK

初始化SDK

成功，返回MV_OK；失败，返回错误码。

MV_CC_Initialize() 函数是用于初始化相机SDK的函数，其内部实现通常包括以下步骤：

1. 检查环境：函数内部会检查当前系统环境，包括操作系统版本、CPU架构、SDK依赖的动态链接库等，确保相机SDK可以在当前系统上正常运行。

2. 资源分配：在初始化过程中，函数会分配所需的资源，包括内存空间、缓冲区等。这些资源通常用于存储相机连接信息、图像数据以及其他相关数据。

3. 加载配置：相机SDK通常会加载预设的配置文件或默认参数，以确保相机的基本设置处于可用状态。这些配置可能涉及图像格式、分辨率、曝光时间、增益等。

4. 初始化设备：函数会初始化与相机通信的硬件接口，包括USB、GigE、CameraLink等接口，以确保能够与相机进行正常通信。

5. 初始化通信协议：针对相机的通信协议（例如GigE Vision、USB3 Vision等），函数会进行相应的协议初始化，确保能够正确地与相机进行数据交换。

6. 设置默认参数：在初始化过程中，函数可能会设置一些默认参数，以便用户在不进行额外设置的情况下即可开始使用相机。

7. 返回状态码：初始化过程中可能会出现各种异常情况，如硬件连接问题、驱动程序错误等。函数会根据实际情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

MV_CAMCTRL_API int __stdcall MV_CC_Finalize()

反初始化SDK，释放资源

成功，返回MV_OK；失败，返回错误码

MV_CC_Finalize() 函数是用于反初始化相机SDK的函数，其内部实现通常包括以下步骤：

1. 释放资源：函数会释放在初始化过程中分配的资源，包括内存空间、缓冲区、连接句柄等。这些资源在反初始化过程中被释放，以避免内存泄漏和资源浪费。

2. 关闭连接：如果相机SDK与相机建立了连接，函数会关闭与相机的连接。这涉及释放相机句柄、关闭相机通信接口等操作。

3. 清理配置：在反初始化过程中，函数可能会清理相机SDK加载的配置信息，包括临时文件、日志文件、缓存数据等，以确保相机SDK在下次初始化时能够重新加载正确的配置。

4. 释放协议资源：针对相机通信所使用的协议（例如GigE Vision、USB3 Vision等），函数会释放相应的协议资源，包括关闭网络连接、释放协议句柄等。

5. 关闭通信接口：函数会关闭与相机通信的硬件接口，包括USB、GigE、CameraLink等接口，以确保相机SDK不再与相机进行数据交换。

6. 返回状态码：反初始化过程中可能会出现各种异常情况，如资源释放失败、连接关闭失败等。函数会根据实际情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

总之，MV_CC_Finalize() 函数的内部实现旨在确保相机SDK在反初始化过程中能够安全、完整地释放资源，并在关闭与相机的连接后恢复到初始状态，以保证系统的稳定性和可靠性。

二、相机初始化 

包含枚举相机、创建句柄、打开相机等接口

函数说明

MV_CC_EnumerateTls()

MV_CAMCTRL_API int __stdcall MV_CC_EnumerateTls()

获取支持的传输层

当前支持的传输层协议类型和数值总和

MV_CC_EnumerateTls() 函数用于获取支持的传输层信息，其内部实现通常包括以下步骤：

1. 搜索传输层设备：函数会搜索系统中支持的传输层设备，例如GigE Vision、USB3 Vision等。它可能会遍历系统的设备管理器或者扫描特定目录，以发现已安装的传输层设备。

2. 获取设备信息：一旦发现传输层设备，函数会获取这些设备的详细信息，包括设备类型、设备标识、连接状态等。这些信息有助于用户了解系统中存在的传输层设备情况。

3. 返回传输层列表：函数会将搜索到的传输层设备信息组织成一个列表或数组，并将其返回给调用者。每个元素通常包含设备的名称、标识符、连接状态等信息。

4. 错误处理：在搜索传输层设备的过程中，可能会出现各种异常情况，如设备丢失、连接失败等。函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

5. 返回状态码：函数会根据执行情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

总之，MV_CC_EnumerateTls() 函数的内部实现旨在获取系统中支持的传输层设备信息，并将其返回给调用者，以便用户选择合适的传输层设备进行相机操作。

MV_CC_EnumDevices()

MV_CAMCTRL_API int __stdcall MV_CC_EnumDevices  ( IN unsigned int  nTLayerType,  
  IN OUT MV_CC_DEVICE_INFO_LIST *  pstDevList  )   

枚举设备，支持枚举对应采集卡上的相机

MV_CC_EnumDevices() 函数用于枚举设备，支持枚举对应采集卡上的相机。其内部实现通常包括以下步骤：

1. 指定传输层类型：函数的第一个参数 nTLayerType 是传输层类型，用于指定要枚举的设备类型，比如 GigE Vision、USB3 Vision 等。

2. 获取设备列表：函数会根据指定的传输层类型，在系统中查找相应类型的设备。它可能会调用操作系统的设备管理接口，或者调用厂商提供的 SDK 函数来获取设备列表。

3. 填充设备信息：找到的设备信息会被填充到 MV_CC_DEVICE_INFO_LIST 结构体中。这个结构体通常包含设备的数量、设备的唯一标识符、设备的 IP 地址（对于网络设备）、设备的型号和厂商等信息。

4. 返回设备列表：填充好设备信息后，函数会将设备列表返回给调用者。调用者可以通过遍历设备列表来获取每个设备的详细信息，进而实现对设备的操作。

5. 错误处理：在获取设备列表的过程中，可能会出现各种异常情况，如设备连接失败、权限不足等。函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

6. 返回状态码：函数会根据执行情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

总之，MV_CC_EnumDevices() 函数的内部实现旨在获取系统中指定传输层类型的设备列表，并将其返回给调用者，以便用户对设备进行操作和控制。

MV_CC_EnumDevicesEx()

MV_CAMCTRL_API int __stdcall MV_CC_EnumDevicesEx(IN unsigned int  nTLayerType,  
  IN OUT MV_CC_DEVICE_INFO_LIST *  pstDevList,  
  IN const char *  strManufacturerName) 

根据厂商名字枚举设备，支持枚举对应采集卡上的相机

MV_CC_EnumDevicesEx() 函数用于根据厂商名称枚举设备，支持枚举对应采集卡上的相机。其内部实现大致如下：

1. 指定传输层类型和厂商名称：函数的第一个参数 nTLayerType 是传输层类型，用于指定要枚举的设备类型，比如 GigE Vision、USB3 Vision 等。第三个参数 strManufacturerName 是要枚举的设备的厂商名称。

2. 获取设备列表：函数会根据指定的传输层类型和厂商名称，在系统中查找相应类型和厂商的设备。它可能会调用操作系统的设备管理接口，或者调用厂商提供的 SDK 函数来获取设备列表。

3. 填充设备信息：找到的设备信息会被填充到 MV_CC_DEVICE_INFO_LIST 结构体中，其中包含设备的数量、设备的唯一标识符、设备的 IP 地址（对于网络设备）、设备的型号和厂商等信息。

4. 返回设备列表：填充好设备信息后，函数会将设备列表返回给调用者。调用者可以通过遍历设备列表来获取每个设备的详细信息，进而实现对设备的操作。

5. 错误处理：在获取设备列表的过程中，可能会出现各种异常情况，如设备连接失败、权限不足等。函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

6. 返回状态码：函数会根据执行情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

总之，MV_CC_EnumDevicesEx() 函数的内部实现旨在根据指定的传输层类型和厂商名称获取系统中对应的设备列表，并将其返回给调用者，以便用户对设备进行操作和控制。

MV_CC_EnumDevicesEx2()

 
MV_CAMCTRL_API int __stdcall MV_CC_EnumDevicesEx2（IN unsigned int  nTLayerType,  
  IN OUT MV_CC_DEVICE_INFO_LIST *  pstDevList,  
  IN const char *  strManufacturerName,  IN MV_SORT_METHOD  enSortMethod)   
 

枚举设备扩展（可指定排序方式枚举、根据厂商名字过滤），支持枚举对应采集卡上的相机

MV_CC_EnumDevicesEx2() 函数是枚举设备的扩展版本，支持指定排序方式枚举，并可以根据厂商名称进行过滤。其内部实现大致如下：

1. 传输层类型和厂商名称：函数的第一个参数 nTLayerType 是传输层类型，用于指定要枚举的设备类型，比如 GigE Vision、USB3 Vision 等。第三个参数 strManufacturerName 是要枚举的设备的厂商名称。

2. 设备列表排序：函数通过第四个参数 enSortMethod 可以指定枚举设备时的排序方式，例如按照设备 ID、设备型号等进行排序。根据指定的排序方法，函数会对获取到的设备列表进行排序处理。

3. 获取设备列表：函数会根据传入的传输层类型和厂商名称，在系统中查找相应类型和厂商的设备。它可能会调用操作系统的设备管理接口，或者调用厂商提供的 SDK 函数来获取设备列表。

4. 填充设备信息：找到的设备信息会被填充到 MV_CC_DEVICE_INFO_LIST 结构体中，其中包含设备的数量、设备的唯一标识符、设备的 IP 地址（对于网络设备）、设备的型号和厂商等信息。

5. 返回设备列表：填充好设备信息后，函数会将设备列表返回给调用者。调用者可以通过遍历设备列表来获取每个设备的详细信息，进而实现对设备的操作。

6. 错误处理：在获取设备列表的过程中，可能会出现各种异常情况，如设备连接失败、权限不足等。函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

7. 返回状态码：函数会根据执行情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

综上所述，MV_CC_EnumDevicesEx2() 函数是枚举设备的扩展版本，可以根据传输层类型、厂商名称和排序方法获取系统中对应的设备列表，并将其返回给调用者，以便用户对设备进行操作和控制。

MV_CC_IsDeviceAccessible()

 
MV_CAMCTRL_API bool __stdcall MV_CC_IsDeviceAccessible(IN MV_CC_DEVICE_INFO *  pstDevInfo,  IN unsigned int  nAccessMode)   

设备是否可达

MV_CC_IsDeviceAccessible() 函数用于判断指定的设备是否可达，即是否可以正常访问和控制。其内部实现大致如下：

1. 参数说明：

   • pstDevInfo：表示要判断的设备信息，包括设备的唯一标识符、设备的 IP 地址（对于网络设备）、设备的型号和厂商等信息。
   • nAccessMode：表示设备的访问模式，通常有读取、写入、读写等模式，用于指定要对设备进行的操作。

2. 设备可达性检查：

   • 函数会根据传入的设备信息，尝试连接设备并进行通讯，以验证设备是否可达。
   • 对于网络设备，函数会尝试通过网络协议（如UDP、TCP等）与设备建立连接，并发送测试指令或请求数据来确认设备的可达性。
   • 对于本地设备，函数会尝试通过本地接口或系统调用与设备进行通讯，以验证设备是否可达和操作是否受限。

3. 返回值说明：

   • 如果设备可达且访问模式合法，则函数返回 true，表示设备可正常访问。
   • 如果设备不可达或者访问模式不合法，则函数返回 false，表示无法访问设备。

4. 错误处理：

   • 在连接和通讯的过程中，可能会出现各种异常情况，如设备未连接、网络超时、权限不足等。
   • 函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

5. 返回状态码：

   • 函数会根据执行情况返回相应的状态码，以便用户根据状态码进行错误处理或进一步调试。

综上所述，MV_CC_IsDeviceAccessible() 函数用于判断指定设备是否可达，并返回相应的状态以供调用者进一步处理。

MV_CC_CreateHandle()

MV_CAMCTRL_API int __stdcall MV_CC_CreateHandle  ( IN OUT void **  handle,  
  IN const MV_CC_DEVICE_INFO *  pstDevInfo) 

创建设备句柄

MV_CC_CreateHandle() 函数用于创建一个设备句柄，该句柄用于后续对相机设备进行控制、设置参数以及获取图像等操作。函数的内部实现大致如下：

1. 参数说明：

   • handle：是一个指向指针的指针，用于存储创建的设备句柄。
   • pstDevInfo：是一个指向 MV_CC_DEVICE_INFO 结构体的指针，包含有关设备的信息，如设备的唯一标识符、型号、厂商等。

2. 设备句柄的创建：

   • 函数根据传入的设备信息，以及设备所使用的通信协议和驱动程序等信息，创建一个与设备通信的句柄。
   • 在创建过程中，可能会进行初始化操作，如分配内存空间、建立通信连接等。

3. 句柄的返回：

   • 函数通过参数 handle 返回创建的设备句柄，以便用户后续使用该句柄对设备进行操作。

4. 返回值说明：

   • 如果句柄创建成功，则返回相应的成功状态码。
   • 如果创建失败，则返回相应的错误码，表示无法创建设备句柄。

5. 错误处理：

   • 在创建句柄的过程中，可能会出现各种异常情况，如设备不存在、通信失败、权限不足等。
   • 函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

综上所述，MV_CC_CreateHandle() 函数用于创建一个与设备通信的句柄，并将句柄通过参数返回，以便用户后续对设备进行控制和操作。

MV_CC_CreateHandleWithoutLog()

MV_CAMCTRL_API int __stdcall MV_CC_CreateHandleWithoutLog  ( IN OUT void **  handle,  
  IN const MV_CC_DEVICE_INFO *  pstDevInfo) 

创建设备句柄，不生成日志

MV_CC_CreateHandleWithoutLog() 函数与 MV_CC_CreateHandle() 函数类似，用于创建一个设备句柄，但不会生成日志信息。函数的内部实现大致如下：

1. 参数说明：

   • handle：是一个指向指针的指针，用于存储创建的设备句柄。
   • pstDevInfo：是一个指向 MV_CC_DEVICE_INFO 结构体的指针，包含有关设备的信息，如设备的唯一标识符、型号、厂商等。

2. 设备句柄的创建：

   • 函数根据传入的设备信息，以及设备所使用的通信协议和驱动程序等信息，创建一个与设备通信的句柄。
   • 与 MV_CC_CreateHandle() 函数类似，但不会在创建过程中生成日志信息。

3. 句柄的返回：

   • 函数通过参数 handle 返回创建的设备句柄，以便用户后续使用该句柄对设备进行操作。

4. 返回值说明：

   • 如果句柄创建成功，则返回相应的成功状态码。
   • 如果创建失败，则返回相应的错误码，表示无法创建设备句柄。

5. 错误处理：

   • 在创建句柄的过程中，可能会出现各种异常情况，如设备不存在、通信失败、权限不足等。
   • 函数会对这些异常情况进行处理，并通过返回值或错误码通知调用者。

MV_CC_IsDeviceConnected()

MV_CAMCTRL_API bool __stdcall MV_CC_IsDeviceConnected  ( IN void *  handle ) 

判断设备是否处于连接状态

MV_CC_IsDeviceConnected() 函数用于判断设备是否处于连接状态。其内部实现大致如下：

1. 参数说明：

   • handle：是一个设备句柄，用于指定要检查连接状态的设备。

2. 连接状态检查：

   • 函数通过设备句柄 handle，与相应的设备通信，查询设备的连接状态。
   • 可能的实现方式包括向设备发送特定的控制命令，或者通过设备驱动程序中的API查询设备的连接状态。

3. 返回值说明：

   • 如果设备处于连接状态，则返回 true。
   • 如果设备未连接或连接状态异常，则返回 false。

4. 错误处理：

   • 如果设备句柄无效或设备通信异常，函数可能返回连接状态未知或错误信息。

5. 注意事项：

   • 在调用该函数之前，通常需要确保设备句柄有效，并且已经通过其他方式正确初始化和连接了设备。

总之，MV_CC_IsDeviceConnected() 函数内部会通过设备句柄进行通信，以查询设备的连接状态，并返回相应的结果。

MV_CC_OpenDevice()

MV_CAMCTRL_API int __stdcall MV_CC_OpenDevice  ( IN void *  handle,  
  IN unsigned int  nAccessMode,IN unsigned short  nSwitchoverKey) 

打开设备

MV_CC_OpenDevice() 函数用于打开设备以进行数据采集或控制操作。其内部实现大致如下：

1. 参数说明：

   • handle：设备句柄，用于指定要打开的设备。
   • nAccessMode：访问模式，指定对设备的访问权限，如只读、读写等。
   • nSwitchoverKey：切换键，用于在设备支持多种模式时进行模式切换。

2. 设备打开操作：

   • 函数通过设备句柄 handle，向相应的设备发送命令，请求打开设备。
   • 在设备打开成功后，可以进行数据采集、参数设置等操作。

3. 访问模式：

   • 根据参数 nAccessMode 指定的访问模式，可能会对设备的访问权限进行限制，如只读模式可能只允许读取设备参数而不允许修改。

4. 切换键：

   • 如果设备支持多种模式（如不同采集模式、配置文件等），则可以使用切换键 nSwitchoverKey 进行模式切换。

5. 返回值说明：

   • 如果设备成功打开，则返回相应的成功代码。
   • 如果设备打开失败，则返回相应的错误代码，表示打开操作未能成功。

6. 错误处理：

   • 函数内部会处理打开设备过程中可能出现的各种错误情况，如设备已被占用、设备连接异常等，并返回相应的错误码。

总之，MV_CC_OpenDevice() 函数内部会通过设备句柄向设备发送命令，请求打开设备，并根据操作结果返回相应的成功或错误代码。

MV_CC_GetAllMatchInfo()

MV_CAMCTRL_API int __stdcall MV_CC_GetAllMatchInfo  ( IN void *  handle,  
  IN OUT MV_ALL_MATCH_INFO *  pstInfo) 

获取各种类型的信息

MV_CC_GetAllMatchInfo() 函数用于获取设备的各种类型信息，其内部实现大致如下：

1. 参数说明：

   • handle：设备句柄，用于指定要获取信息的设备。
   • pstInfo：输出参数，用于接收获取到的各种类型信息。

2. 信息获取操作：

   • 函数通过设备句柄 handle，向相应的设备发送命令，请求获取各种类型的信息。
   • 可能获取的信息包括设备的基本信息、配置信息、状态信息等。

3. 信息存储：

   • 获取到的各种类型信息会被存储在 pstInfo 参数所指向的内存区域中。

4. 返回值说明：

   • 如果获取信息成功，则返回相应的成功代码，并将获取到的信息存储在 pstInfo 中。
   • 如果获取信息失败，则返回相应的错误代码，表示获取操作未能成功。

5. 错误处理：

   • 函数内部会处理获取信息过程中可能出现的各种错误情况，如设备连接异常、获取信息超时等，并返回相应的错误码。

总之，MV_CC_GetAllMatchInfo() 函数内部会通过设备句柄向设备发送命令，请求获取各种类型的信息，并将获取到的信息存储在指定的内存区域中。

MV_CC_GetDeviceInfo()

MV_CAMCTRL_API int __stdcall MV_CC_GetDeviceInfo  ( IN void *  handle,  
  IN OUT MV_CC_DEVICE_INFO *  pstDevInfo) 

获取设备信息，取流之前调用

MV_CC_GetDeviceInfo() 函数用于获取设备信息，其内部实现大致如下：

1. 参数说明：

   • handle：设备句柄，用于指定要获取信息的设备。
   • pstDevInfo：输出参数，用于接收获取到的设备信息。

2. 信息获取操作：

   • 函数通过设备句柄 handle，向相应的设备发送命令，请求获取设备的信息。
   • 可能获取的信息包括设备的型号、序列号、厂商信息、固件版本等。

3. 信息存储：

   • 获取到的设备信息会被存储在 pstDevInfo 参数所指向的内存区域中。

4. 返回值说明：

   • 如果获取设备信息成功，则返回相应的成功代码，并将获取到的设备信息存储在 pstDevInfo 中。
   • 如果获取设备信息失败，则返回相应的错误代码，表示获取操作未能成功。

5. 错误处理：

   • 函数内部会处理获取信息过程中可能出现的各种错误情况，如设备连接异常、获取信息超时等，并返回相应的错误码。

总之，MV_CC_GetDeviceInfo() 函数内部会通过设备句柄向设备发送命令，请求获取设备的信息，并将获取到的信息存储在指定的内存区域中

MV_CC_CloseDevice()

MV_CAMCTRL_API int __stdcall MV_CC_CloseDevice  ( IN void *  handle ) 

关闭设备

MV_CC_CloseDevice() 函数用于关闭设备连接。其内部实现大致如下：

1. 参数说明：

   • handle：设备句柄，用于指定要关闭连接的设备。

2. 关闭设备连接操作：

   • 函数内部根据提供的设备句柄 handle，执行关闭设备连接的操作。
   • 这可能涉及释放相关资源、关闭网络连接或其他与设备连接相关的操作。

3. 返回值说明：

   • 如果成功关闭设备连接，则返回相应的成功代码。
   • 如果关闭设备连接失败，则返回相应的错误代码，表示关闭操作未能成功。

4. 错误处理：

   • 函数内部会处理关闭设备连接过程中可能出现的各种错误情况，如设备连接已经关闭、连接异常等，并返回相应的错误码。

总之，MV_CC_CloseDevice() 函数内部会根据提供的设备句柄执行关闭设备连接的操作，并根据操作结果返回相应的成功或错误代码

MV_CC_DestroyHandle()

MV_CAMCTRL_API int __stdcall MV_CC_DestroyHandle  ( IN void *  handle ) 

销毁设备句柄

MV_CC_DestroyHandle() 函数用于销毁设备句柄。其内部实现大致如下：

1. 参数说明：

   • handle：要销毁的设备句柄。

2. 释放资源操作：

   • 函数内部根据提供的设备句柄 handle，执行释放相关资源的操作。
   • 这可能包括释放设备句柄所占用的内存空间、关闭相关连接、清理临时数据等。

3. 返回值说明：

   • 如果成功销毁设备句柄及相关资源，则返回相应的成功代码。
   • 如果销毁设备句柄失败，则返回相应的错误代码，表示销毁操作未能成功。

4. 错误处理：

   • 函数内部会处理销毁设备句柄过程中可能出现的各种错误情况，如无效的设备句柄、资源释放失败等，并返回相应的错误码。

总之，MV_CC_DestroyHandle() 函数内部会根据提供的设备句柄执行释放相关资源的操作，并根据操作结果返回相应的成功或错误代码。