# Toupnam API 手册

# 1. 版本和平台

- 版本:5.29030.20250722

- 平台
  - Win32:
    - x64: Win7及以上版本
    - x86: XP SP3及以上版本; CPU至少需要支持SSE2指令集
  - macOS:
    - x64; macOS 10.10及以上版本
  - Linux: 内核2.6.27及以上, GLIBC 2.17及以上
    - x64
    - x86: CPU至少需要支持SSE3指令集
    - arm64: 由aarch64-linux-gnu(版本5.4.0)编译
    - armhf: 由arm-linux-gnueabihf(版本5.4.0)编译
    - armel: 由arm-linux-gnueabi(版本5.4.0)编译

# 2. 函数

- ## 回调函数: PTOUPNAM_EVENT_CALLBACK, PTOUPNAM_PARA_CALLBACK, PTOUPNAM_DATA_CALLBACK, PTOUPNAM_CAPTURE_CALLBACK

  事件 | 描述 | 值
  TOUPNAM_EVENT_ENUM | 相机数量发生变化 | 0x01
  TOUPNAM_EVENT_WIFI | WiFi发生变化 | 0x02
  TOUPNAM_EVENT_PARA | 参数发生变化, 详见TOUPNAM_PARA_xxx详细参数说明 | 0x03
  TOUPNAM_EVENT_IMAGE | 视频图像数据到达(视频) | 0x04
  TOUPNAM_EVENT_THUMBNAIL | 获取缩略图 | 0x08
  TOUPNAM_EVENT_DIRCHANG | 目录更改事件 | 0x09
  TOUPNAM_EVENT_RECORDSTART | 记录开始 | 0x0a
  TOUPNAM_EVENT_RECORDSTOP | 记录停止 | 0x0b
  TOUPNAM_EVENT_ERROR | 发生错误 | 0x80
  TOUPNAM_EVENT_EOF | 录入文件结束 | 0x81

  参数 | 描述 | 值
  TOUPNAM_PARA_UNKNOWN | 未知 | 0x00
  TOUPNAM_PARA_EXPOTIME | 曝光时间 | 0x01
  TOUPNAM_PARA_AGAIN | 模拟增益, 百分比, 如200表示增益200% | 0x02
  TOUPNAM_PARA_AEXPOTARGET | 自动曝光的目标 | 0x03
  TOUPNAM_PARA_TEMP | 色温 | 0x04
  TOUPNAM_PARA_TINT | Tint | 0x05
  TOUPNAM_PARA_CONTRAST | 对比度 | 0x06
  TOUPNAM_PARA_HUE | 色度 | 0x07
  TOUPNAM_PARA_SATURATION | 饱和度 | 0x08
  TOUPNAM_PARA_BRIGHTNESS | 亮度 | 0x09
  TOUPNAM_PARA_GAMMA | Gamma | 0x0a
  TOUPNAM_PARA_AEXPO | 自动曝光 | 0x0b
  TOUPNAM_PARA_AWB | 自动白平衡 XCAM1080P:once XCAM4K:(0:manual;1:global auto;2:roi) | 0x0c
  TOUPNAM_PARA_BINSKIP | bin/skip模式 | 0x0d
  TOUPNAM_PARA_HZ | 光源的电力供应频率0表示60Hz交流, 1表示50Hz交流, 2表示直流 | 0x0e
  TOUPNAM_PARA_BPS | 带宽kbps (bits per second) | 0x0f
  TOUPNAM_PARA_KEYFRAME | 关键帧间隔 | 0x10
  TOUPNAM_PARA_LOWLIGHTCOMPENSATION | 低光补偿 | 0x11
  TOUPNAM_PARA_SHARPNESS | 锐化 | 0x12
  TOUPNAM_PARA_WBREDGAIN | 白平衡红增益 | 0x13
  TOUPNAM_PARA_WBGREENGAIN | 白平衡绿增益 | 0x14
  TOUPNAM_PARA_WBBLUEGAIN | 白平衡蓝增益 | 0x15
  TOUPNAM_PARA_DENOISE | 降噪 | 0x16
  TOUPNAM_PARA_APSTA | ap或sta (无线网络工作模式) | 0x17
  TOUPNAM_PARA_CODEC | 编解码器, H264, H265等 | 0x18
  TOUPNAM_PARA_AFPOSITION | 自动对焦传感器板位置 | 0x19
  TOUPNAM_PARA_AFMODE | 自动对焦传感器板位置 | 0x1a
  TOUPNAM_PARA_AFPOSITION | 自动对焦区域整个分辨率被划分为w*h区域:w=imax>>16, h=imax&0xffff, 所以自动对焦的行 row=value / w, 自动对焦的列column=value % w (value位区域的序号) | 0x1b
  TOUPNAM_PARA_AFFEEDBACK | 自动对焦信息反馈 0: unknown 1: focused 2: focusing 3: defocuse (out of focus) 4: up (workbench move up) 5: down (workbench move down) | 0x1c
  TOUPNAM_PARA_AFPOSITION_ABSOLUTE | 自动对焦传感器板的绝对位置 | 0x1d
  TOUPNAM_PARA_STATUS | 状态, 详见TOUPNAM_STATE_XXXX | 0x1e
  TOUPNAM_PARA_EVENT | 事件, 详见TOUPNAM_EVENT_XXXX | 0x1f
  TOUPNAM_PARA_WBROILEFT | 白平衡下roi区域的左边界 | 0x20
  TOUPNAM_PARA_WBROITOP | 白平衡下roi区域的上边界 | 0x21
  TOUPNAM_PARA_WBROIWIDTH | 白平衡下roi区域的宽度 | 0x22
  TOUPNAM_PARA_WBROIHEIGHT | 白平衡下roi区域的高度 | 0x23
  TOUPNAM_PARA_VFLIP | 垂直翻转 | 0x24
  TOUPNAM_PARA_HFLIP | 水平翻转 | 0x25
  TOUPNAM_PARA_CHROME | 单色模式 | 0x26
  TOUPNAM_PARA_SIZE | 视频的宽和高 | 0x27
  TOUPNAM_PARA_LIGHTADJUSTMENT | 光源亮度调节 | 0x28
  TOUPNAM_PARA_ZOOM | 变焦 | 0x29
  TOUPNAM_PARA_EF_MODE | EF表示镜头自动对焦, 下列即表示EF相关的参数 | 0x2a
  TOUPNAM_PARA_EF_FL |  | 0x2b
  TOUPNAM_PARA_EF_APERTURE |  | 0x2c
  TOUPNAM_PARA_EF_FOCUS_MAX |  | 0x2d
  TOUPNAM_PARA_EF_LENS_ID |  | 0x2e
  TOUPNAM_PARA_EF_AFMF |  | 0x2f
  TOUPNAM_PARA_EF_WD_ENABLE |  | 0x30
  TOUPNAM_PARA_EF_WD_NEAR |  | 0x31
  TOUPNAM_PARA_EF_WD_FAR |  | 0x32
  TOUPNAM_PARA_CHROME_LOCAL | 本地的单色模式 | 0x80
  TOUPNAM_PARA_VFLIP_LOCAL | 本地的垂直翻转 | 0x81
  TOUPNAM_PARA_HFLIP_LOCAL | 本地的水平翻转 | 0x82
  TOUPNAM_PARA_NEGATIVE_LOCAL | 本地的负片 | 0x83
  TOUPNAM_PARA_FORMAT_LOCAL | 图像输出格式, 必须在start之前设置 | 0x84

  pDataCallback和pParaCallback是由toupnam.dll的内部线程回调的, 因此请注意多线程问题. 请尽量保持回调函数代码的简洁, 并且快速返回.
  当帧到达时, pDataCallback被回调. (NULL==pData)表示有错误.
  当TOUPNAM_PARA_xxx值更改时, pParaCallback将被回调.
  pCallbackCtx是Start传递的回调上下文.

- ## Toupnam_Init

  返回值：无

  参数：pCallback回调函数, pCallbackCtx传到回调函数的指针

  说明：当toupnam.dll/libtoupnam.so发现新相机时, 将调用pCallback, 如果应用程序对此不感兴趣, pCallback可以为NULL. Toupnam_Init应用程序启动时只调用一次

- ## Toupnam_Fini

  返回值：无

  参数：无

  说明：应用程序退出时只调用一次

- ## Toupnam_Enum

  返回值：非负整数, 枚举到的相机数目

  参数：ToupnamDevice数组缓冲区

  说明：函数返回时, ToupnamDevice缓冲区包含有枚举到的每个相机实例的信息. 如果不关心多个相机同时联入电脑的情况的话, 调用本函数枚举相机实例是可选的.

  name | 型号名称
  flag | 位标记 (Bitwise flag)
  TOUPNAM_FLAG_WIFI_AP | 终端
  TOUPNAM_FLAG_WIFI_STA | 客户端
  TOUPNAM_FLAG_ETHERNET | 以太网
  TOUPNAM_FLAG_CAPTURE | 支持从相机捕获图像
  TOUPNAM_FLAG_AWBCHECKMODE | 支持自动白平衡
  TOUPNAM_FLAG_UVC | UVC相机
  TOUPNAM_FLAG_WBGAIN | 支持白平衡下的增益模式或者色温模式
  TOUPNAM_FLAG_MULTICAST | RTSP/RTP
  TOUPNAM_FLAG_AF | 支持自动对焦
  TOUPNAM_FLAG_SD | 支持sd卡
  TOUPNAM_FLAG_WBROI | 支持白平衡的roi
  TOUPNAM_FLAG_STA_SUPPORT | 相机具有sta模式, 应用程序应具有sta账号和密码功能
  TOUPNAM_FLAG_RTP_OVER_RTSP | rtp over rtsp
  TOUPNAM_FLAG_HZ_AUTOEXPO | 在50/60HZ光源的电力供应频率约束下支持自动曝光
  TOUPNAM_FLAG_AFDM | 自动对焦的一种方式
  TOUPNAM_FLAG_EFL | 支持镜头自动对焦
  TOUPNAM_FLAG_CAPTURERAW | 获取raw图
  state | 状态
  TOUPNAM_STATE_INITING | 初始化
  TOUPNAM_STATE_NORMAL | 常态
  TOUPNAM_STATE_UNREACHABLE | 网络无法连接
  url | 网络地址, 例如rtsp://xxxx/yyyy
  addr | ip地址
  version | 版本号
  sn | 序列号
  id | 相机ID

- ## Toupnam_Open
  Toupnam_Open_ByIndex

  返回值：相机句柄. 失败时返回NULL

  参数：camId: 相机ID, 由Toupnam_Enum枚举得到

  说明：打开相机实例.

- ## Toupnam_Close

  返回值：无

  参数：HToupnam h: 相机句柄

  说明：关闭相机实例. 句柄关闭之后, 请不要再使用

- ## Toupnam_PullImage

  返回值：HRESULT类型表示成功或失败, 不存在图像可供获取时返回E_PENDING

  参数：

  > HToupnam h: 相机句柄

  > pImageData: 数据缓冲区. 用户应用程序必须确保改缓冲区足够大以容纳图像数据

  > bits: 图像颜色位数, 支持24, 32, 48, 8, 16和64, 分别代表RGB24, RGB32, RGB48, 8位灰度, 16位灰度, RGB64图像

  > pnWidth, pnHeight: 输出参数, 图像的宽度高度

  说明：无

- ## Toupnam_StartPullModeWithCallback

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > void* pCallbackContext: 用户程序指定的回调函数

  说明：无

- ## Toupnam_Stop

  返回值：HRESULT类型表示成功或失败

  参数：HToupnam h: 相机句柄

  说明：停止相机实例

- ## Toupnam_Pause

  返回值：HRESULT类型表示成功或失败

  参数：HToupnam h: 相机句柄

  说明：暂停或者继续视频流

- ## Toupnam_Capture
  Toupnam_Capture_ById

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > camId: 相机id

  > pstrFileName: 文件名

  > pCaptureCallback: 回调函数

  > pCallbackCtx: 传递的回调上下文

  说明：捕获图像，将其与从视频中提取的图像进行比较

  > pstrFileName: NULL->捕获图像，然后通过回调返回

  > “raw”->捕获原始图像，然后通过回调返回

  > “abc.jpg”->捕获图像, 然后将其保存在相机sd卡中, 文件名为“abc.jpg”

  > “abc.raw”->捕获原始图像, 然后将其保存在相机sd卡中, 文件名为“abc.raw”

  > “thumbnail”->捕获缩略图图像，然后通过回调返回

  > “*”->捕获图像, 然后用自动生成的文件名将其保存在相机sd卡中

  > “*.raw”->捕获原始图像, 然后用自动生成的文件名将其保存在相机sd卡中

- ## Toupnam_get_Size_ById

  返回值：HRESULT类型表示成功或失败

  参数：

  > camId: 相机id

  > res: 相机分辨率

  > pWidth, pHeight: 传递宽和高的指针

  说明：无

- ## Toupnam_get_Device

  返回值：ToupnamDevice类型表示相机实例的信息

  参数：HToupnam h: 相机句柄

  说明：获取相机实例的信息

- ## Toupnam_get_Size
  Toupnam_get_CapSize

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > pWidth, pHeight: 当前分辨率的宽度高度

  说明：得到当前分辨率或录制分辨率

- ## Toupnam_get_FourCC

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > unsigned* pFourCC: Four-Character Codes, 四字符代码

  说明：详见 http://en.wikipedia.org/wiki/FourCC, http://www.fourcc.org

- ## Toupnam_Record

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > const char* fullpathname: 录制保存文件的绝对地址

  说明：当fullpathname == NULL 表示停止录制，支持的文件格式：*.asf, *.mp4, *.mkv

- ## Toupnam_put_Para
  Toupnam_get_Para

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > unsigned para: 参数类型, 详见TOUPNAM_PARA_xxx

  > value: 设置或获取的值

  说明：得到当前分辨率或录制分辨率

- ## Toupnam_put_Para_ById
  Toupnam_put_Para_ById

  返回值：HRESULT类型表示成功或失败

  参数：

  > HToupnam h: 相机句柄

  > unsigned para: 参数类型, 详见TOUPNAM_PARA_xxx

  > value: 设置或获取的值

  说明：通过相机id来设置参数, 与Toupnam_put_Para, Toupnam_get_Para有所区分

- ## Toupnam_put_Wifi

  返回值：HRESULT类型表示成功或失败

  参数：

  > const char* camId: 相机id

  > ToupnamWifi wifi: wifi账号密码

  说明：设置WiFi

- ## Toupnam_add_Ip
  Toupnam_del_Ip

  返回值：无

  参数：const char** arr: 记录相机ip地址的列表

  说明：用于组播通讯模式, 可以对指定ip地址的相机进行通信, 对广播通讯模式无效

  如下面的代码片段：

                  char* arr[] = {
                      "1.2.3.4",
                      "1.2.3.5",
                      ...,
                      NULL
                  };
                  Toupnam_add_Ip(arr);