Toupnam API Manual

1. Version & Platform

• Version: 5.28760.20250623

• 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);