# Toupnam API Manual

# 1. Version & Platform

- Version: 5.29030.20250722

- Platform
  - Win32:
    - x64: Win7 or above
    - x86: XP SP3 or above; CPU supports SSE2 instruction set or above
  - macOS:
    - x64: macOS 10.10 or above
  - Linux: kernel 2.6.27 or above; GLIBC 2.17 or above
    - x64
    - x86: CPU supports SSE3 instruction set or above
    - arm64: built by toolchain arm-linux-gnueabi (version 5.4.0)
    - armhf: built by toolchain arm-linux-gnueabihf (version 5.4.0)
    - armel: built by toolchain aarch64-linux-gnu (version 5.4.0)

# 2. Functions

- ## Callback: PTOUPNAM_EVENT_CALLBACK, PTOUPNAM_PARA_CALLBACK, PTOUPNAM_DATA_CALLBACK, PTOUPNAM_CAPTURE_CALLBACK

  Event | Description | Value
  TOUPNAM_EVENT_ENUM | The number of cameras has changed | 0x01
  TOUPNAM_EVENT_WIFI | WiFi has changed | 0x02
  TOUPNAM_EVENT_PARA | Parameters change, seeTOUPNAM_PARA_xxx detailed parameter description | 0x03
  TOUPNAM_EVENT_IMAGE | Image data arrival (video) | 0x04
  TOUPNAM_EVENT_THUMBNAIL | Get thumbnail | 0x08
  TOUPNAM_EVENT_DIRCHANG | dir change notify | 0x09
  TOUPNAM_EVENT_RECORDSTART | record start | 0x0a
  TOUPNAM_EVENT_RECORDSTOP | record stop | 0x0b
  TOUPNAM_EVENT_ERROR | An error occurred | 0x80
  TOUPNAM_EVENT_EOF | end of file | 0x81

  Parameter | Description | Value
  TOUPNAM_PARA_UNKNOWN | unknown | 0x00
  TOUPNAM_PARA_EXPOTIME | exposure time | 0x01
  TOUPNAM_PARA_AGAIN | Analog gain, percentage, for example, 200 means 200% gain | 0x02
  TOUPNAM_PARA_AEXPOTARGET | auto exposure target | 0x03
  TOUPNAM_PARA_TEMP | color temperature | 0x04
  TOUPNAM_PARA_TINT | Tint | 0x05
  TOUPNAM_PARA_CONTRAST | contrast | 0x06
  TOUPNAM_PARA_HUE | hue | 0x07
  TOUPNAM_PARA_SATURATION | saturation | 0x08
  TOUPNAM_PARA_BRIGHTNESS | brightness | 0x09
  TOUPNAM_PARA_GAMMA | Gamma | 0x0a
  TOUPNAM_PARA_AEXPO | auto exposure | 0x0b
  TOUPNAM_PARA_AWB | auto White Balance Gain, XCAM1080P:once XCAM4K:(0:manual;1:global auto;2:roi) | 0x0c
  TOUPNAM_PARA_BINSKIP | bin/skip mode | 0x0d
  TOUPNAM_PARA_HZ | power supply: 0 -> 60HZ AC; 1 -> 50Hz AC; 2 -> DC | 0x0e
  TOUPNAM_PARA_BPS | bits per second, kbps | 0x0f
  TOUPNAM_PARA_KEYFRAME | key frame interval | 0x10
  TOUPNAM_PARA_LOWLIGHTCOMPENSATION | low light compensation | 0x11
  TOUPNAM_PARA_SHARPNESS | sharpness | 0x12
  TOUPNAM_PARA_WBREDGAIN | white balance red gain | 0x13
  TOUPNAM_PARA_WBGREENGAIN | white balance green gain | 0x14
  TOUPNAM_PARA_WBBLUEGAIN | white balance blue gain | 0x15
  TOUPNAM_PARA_DENOISE | denoise | 0x16
  TOUPNAM_PARA_APSTA | wireless network operating mode: ap or sta | 0x17
  TOUPNAM_PARA_CODEC | codec, H264, H265, etc | 0x18
  TOUPNAM_PARA_AFPOSITION | auto focus sensor board positon | 0x19
  TOUPNAM_PARA_AFMODE | auto focus mode (0:manul focus; 1:auto focus; 2:once focus; 3:conjugate calibration) | 0x1a
  TOUPNAM_PARA_AFPOSITION | auto focus zone: the whole resolution is divided in w * h zones: w = imax >> 16 h = imax & 0xffff then: zone row: value / w zone column: value % w | 0x1b
  TOUPNAM_PARA_AFFEEDBACK | auto focus information feedback 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 | absolute auto focus sensor board positon | 0x1d
  TOUPNAM_PARA_STATUS | status, seeTOUPNAM_STATE_XXXX | 0x1e
  TOUPNAM_PARA_EVENT | event, seeTOUPNAM_EVENT_XXXX | 0x1f
  TOUPNAM_PARA_WBROILEFT | white balance roi left | 0x20
  TOUPNAM_PARA_WBROITOP | white balance roi top | 0x21
  TOUPNAM_PARA_WBROIWIDTH | white balance roi width | 0x22
  TOUPNAM_PARA_WBROIHEIGHT | white balance roi height | 0x23
  TOUPNAM_PARA_VFLIP | vertical flip | 0x24
  TOUPNAM_PARA_HFLIP | horizontal flip | 0x25
  TOUPNAM_PARA_CHROME | monochromatic mode | 0x26
  TOUPNAM_PARA_SIZE | video width & height | 0x27
  TOUPNAM_PARA_LIGHTADJUSTMENT | light source brightness adjustment | 0x28
  TOUPNAM_PARA_ZOOM | zoom | 0x29
  TOUPNAM_PARA_EF_MODE | EF refers to auto focus, and the following refers to EF related parameters | 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 | local monochromatic mode | 0x80
  TOUPNAM_PARA_VFLIP_LOCAL | local vertical flip | 0x81
  TOUPNAM_PARA_HFLIP_LOCAL | local horizontal flip | 0x82
  TOUPNAM_PARA_NEGATIVE_LOCAL | local negative film | 0x83
  TOUPNAM_PARA_FORMAT_LOCAL | output format: 0 => BGR888, 1 => BGRA8888, 2 => RGB888, 3 => RGBA8888, 4 => RAW; default: 0 must be set before StartXXXX | 0x84

  These callback functions are called back from the internal thread in toupnam.dll, so great attention should be paid to multithread issue.
  Please ensure that the callback funcion is simple and return quickly.

  When the frame arrives, pDataCallback is called back (NULL==pData) indicates an error

  When the value of TOUPNAM_PARA_xxx changes, pParaCallback will be called back

  pCallbackCtx is the callback context

- ## Toupnam_Init

  Return value:NA

  Parameters:pCallback is callback, pCallbackCtx is the callback context

  Remarks: when toupnam.dll/libtoupnam.so discovery new camera, pCallback will be called.
  pCallback can be NULL if the application does not interest this. Toupnam_Init call only once when application startup

- ## Toupnam_Fini

  Return value: NA

  Parameters: NA

  Remarks: call only once when application exit

- ## Toupnam_Enum

  Return value: non-negative integer, enumerated camera number

  Parameters:

  > ToupnamDevice buffer

  > sz: size of the array

  Remarks: call this function to enumerate Toupnam cameras that are currently connected to computer, when sz is too small, return value will be greater than sz, means that the caller must use bigger array
  If we don't care about that multiple cameras connect to the computer simultaneously, it's optional to call this function to enumerate the camera instances.

  name | The name of this model
  flag | Bitwise flag
  TOUPNAM_FLAG_WIFI_AP | wifi ap
  TOUPNAM_FLAG_WIFI_STA | wifi sta
  TOUPNAM_FLAG_ETHERNET | eth network
  TOUPNAM_FLAG_CAPTURE | support the ability of capture image from camera
  TOUPNAM_FLAG_AWBCHECKMODE | auto white balance: check mode vs 'once' mode
  TOUPNAM_FLAG_UVC | uvc camera
  TOUPNAM_FLAG_WBGAIN | white balance gain mode or temp tint mode
  TOUPNAM_FLAG_MULTICAST | RTSP/RTP multicast
  TOUPNAM_FLAG_AF | support auto focus
  TOUPNAM_FLAG_SD | support sd card
  TOUPNAM_FLAG_WBROI | white balance: 0:manual;1:global auto;2:roi
  TOUPNAM_FLAG_STA_SUPPORT | wifi camera has sta mode, app should have sta ssid & password function
  TOUPNAM_FLAG_RTP_OVER_RTSP | rtp over rtsp
  TOUPNAM_FLAG_HZ_AUTOEXPO | enable auto exposure when 50/60 hz
  TOUPNAM_FLAG_AFDM | a way of auto focus
  TOUPNAM_FLAG_EFL | Support camera lens autofocus
  TOUPNAM_FLAG_CAPTURERAW | get raw data
  state | STATE
  TOUPNAM_STATE_INITING | initialization
  TOUPNAM_STATE_NORMAL | normal
  TOUPNAM_STATE_UNREACHABLE | unable to connect to the network
  url | network address, for example rtsp://xxxx/yyyy
  addr | ip address
  version | camera version
  sn | camera sn
  id | camera ID

- ## Toupnam_Open
  Toupnam_Open_ByIndex

  Return value: camera handle. Return NULL when open failure

  Parameters: camId: Camera ID, obtained by Toupnam_Enum enumeration

  Remarks: Open camera

- ## Toupnam_Close

  Return value: NA

  Parameters: HToupnam h: camera handle

  Remarks: Close camera, please do not use it again after the handle is closed.

- ## Toupnam_PullImage

  Return value: HRESULT type means success or failure, when there is no image available for retrieval, return the value of E_PENDING

  Parameters:

  > HToupnam h: camera handle

  > pImageData: data buffer. The application must ensure that the buffer is large enough to accommodate image data

  > bits: The number of color bits in the image supports 24, 32, 48, 8, 16, and 64, representing RGB24 respectively, RGB32, RGB48, MONO8, MONO16, RGB64 image

  > pnWidth, pnHeight: Output parameters, width and height of the image

  Remarks: NA

- ## Toupnam_StartPullModeWithCallback

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > void* pCallbackContext: callback

  Remarks: NA

- ## Toupnam_Stop

  Return value: HRESULT type means success or failure

  Parameters: HToupnam h: camera handle

  Remarks: Stop camera

- ## Toupnam_Pause

  Return value: HRESULT type means success or failure

  Parameters: HToupnam h: camera handle

  Remarks: Pause or resume the stream

- ## Toupnam_Capture
  Toupnam_Capture_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > camId: camera id

  > pstrFileName: file name

  > pCaptureCallback: callback

  > pCallbackCtx: context

  Remarks: capture image, compare this to image extracted from video

  > pstrFileName: NULL->capture image and then return by callback

  > “raw”->capture raw image and then return by callback

  > “abc.jpg”->capture image and then save it in the camera sd card with filename 'abc.jpg'

  > “abc.raw”->capture raw image and then save it in the camera sd card with filename 'abc.raw'

  > “thumbnail”->capture the thumbnail image and then return by callback

  > “*”->capture image and then save it in the camera sd card with auto generated file name

  > “*.raw”->capture raw image and then save it in the camera sd card with auto generated file name

- ## Toupnam_get_Size_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > camId: camera id

  > res: camera resolution

  > pWidth, pHeight: width/height

  Remarks: NA

- ## Toupnam_get_Device

  Return value: ToupnamDevice represents information about camera

  Parameters: HToupnam h: camera handle

  Remarks: get information about camera

- ## Toupnam_get_Size
  Toupnam_get_CapSize

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > pWidth, pHeight: the width and height of the current resolution

  Remarks: obtain the current resolution or recording resolution

- ## Toupnam_get_FourCC

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > unsigned* pFourCC: Four-Character Codes, four character code

  Remarks: see http://en.wikipedia.org/wiki/FourCC, http://www.fourcc.org

- ## Toupnam_Record

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > const char* fullpathname: absolute address for recording and saving files

  Remarks: Stop recording when fullpathname == NULL, supported file formats: *.asf, *.mp4, *.mkv

- ## Toupnam_put_Para
  Toupnam_get_Para

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > unsigned para: parameter type, seeTOUPNAM_PARA_xxx

  > value: put/get value

  Remarks: NA

- ## Toupnam_put_Para_ById
  Toupnam_put_Para_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > HToupnam h: camera handle

  > unsigned para: parameter type, seeTOUPNAM_PARA_xxx

  > value: put/get value

  Remarks: set parameters through camera id, different fromToupnam_put_Para, Toupnam_get_Para

- ## Toupnam_put_Wifi

  Return value: HRESULT type means success or failure

  Parameters:

  > const char* camId: camera id

  > ToupnamWifi wifi: wifi ssid & password

  Remarks: set WiFi

- ## Toupnam_add_Ip
  Toupnam_del_Ip

  Return value: NA

  Parameters: const char** arr: ip buffer

  Remarks: used for multicast communication mode, it can communicate with cameras with specified IP addresses, but not for broadcast communication mode

  The code snippet shows as below:

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