# Miinam API Manual

# 1. Version & Platform

- Version: 5.32226.20260808

- 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: PMIINAM_EVENT_CALLBACK, PMIINAM_PARA_CALLBACK, PMIINAM_DATA_CALLBACK, PMIINAM_CAPTURE_CALLBACK

  Event | Description | Value
  MIINAM_EVENT_ENUM | The number of cameras has changed | 0x01
  MIINAM_EVENT_WIFI | WiFi has changed | 0x02
  MIINAM_EVENT_PARA | Parameters change, seeMIINAM_PARA_xxx detailed parameter description | 0x03
  MIINAM_EVENT_IMAGE | Image data arrival (video) | 0x04
  MIINAM_EVENT_THUMBNAIL | Get thumbnail | 0x08
  MIINAM_EVENT_DIRCHANG | dir change notify | 0x09
  MIINAM_EVENT_RECORDSTART | record start | 0x0a
  MIINAM_EVENT_RECORDSTOP | record stop | 0x0b
  MIINAM_EVENT_ERROR | An error occurred | 0x80
  MIINAM_EVENT_EOF | end of file | 0x81

  Parameter | Description | Value
  MIINAM_PARA_UNKNOWN | unknown | 0x00
  MIINAM_PARA_EXPOTIME | exposure time | 0x01
  MIINAM_PARA_AGAIN | Analog gain, percentage, for example, 200 means 200% gain | 0x02
  MIINAM_PARA_AEXPOTARGET | auto exposure target | 0x03
  MIINAM_PARA_TEMP | color temperature | 0x04
  MIINAM_PARA_TINT | Tint | 0x05
  MIINAM_PARA_CONTRAST | contrast | 0x06
  MIINAM_PARA_HUE | hue | 0x07
  MIINAM_PARA_SATURATION | saturation | 0x08
  MIINAM_PARA_BRIGHTNESS | brightness | 0x09
  MIINAM_PARA_GAMMA | Gamma | 0x0a
  MIINAM_PARA_AEXPO | auto exposure | 0x0b
  MIINAM_PARA_AWB | auto White Balance Gain, XCAM1080P:once XCAM4K:(0:manual;1:global auto;2:roi) | 0x0c
  MIINAM_PARA_BINSKIP | bin/skip mode | 0x0d
  MIINAM_PARA_HZ | power supply: 0 -> 60HZ AC; 1 -> 50Hz AC; 2 -> DC | 0x0e
  MIINAM_PARA_BPS | bits per second, kbps | 0x0f
  MIINAM_PARA_KEYFRAME | key frame interval | 0x10
  MIINAM_PARA_LOWLIGHTCOMPENSATION | low light compensation | 0x11
  MIINAM_PARA_SHARPNESS | sharpness | 0x12
  MIINAM_PARA_WBREDGAIN | white balance red gain | 0x13
  MIINAM_PARA_WBGREENGAIN | white balance green gain | 0x14
  MIINAM_PARA_WBBLUEGAIN | white balance blue gain | 0x15
  MIINAM_PARA_DENOISE | denoise | 0x16
  MIINAM_PARA_APSTA | wireless network operating mode: ap or sta | 0x17
  MIINAM_PARA_CODEC | codec, H264, H265, etc | 0x18
  MIINAM_PARA_AFPOSITION | auto focus sensor board position(applicable to both AFDM and EFL) | 0x19
  MIINAM_PARA_AFMODE | auto focus mode (0:manul focus; 1:auto focus; 2:once focus; 3:conjugate calibration) | 0x1a
  MIINAM_PARA_AFZONE | 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
  MIINAM_PARA_AFFEEDBACK | auto focus information feedback AFDM: 0: unknown 1: focused 2: focusing 3: defocuse (out of focus) 4: up (workbench move up) 5: down (workbench move down) EFL: 0: Not available 1: Focus completed, find the focus position 2: End of focus, defocus 3: Focusing ended, object too close 4: Focusing ended, object too far 5: Focusing ends, roi changes 6: Focusing ends, scene changes 7: The end of focusing and the change in focusing mode is usually determined by the user moderator 8: The focus is not complete. At the beginning of focusing, it will be set as incomplete | 0x1c
  MIINAM_PARA_AFPOSITION_ABSOLUTE | absolute auto focus sensor board positon | 0x1d
  MIINAM_PARA_STATUS | status, seeMIINAM_STATE_XXXX | 0x1e
  MIINAM_PARA_EVENT | event, seeMIINAM_EVENT_XXXX | 0x1f
  MIINAM_PARA_WBROILEFT | white balance roi left | 0x20
  MIINAM_PARA_WBROITOP | white balance roi top | 0x21
  MIINAM_PARA_WBROIWIDTH | white balance roi width | 0x22
  MIINAM_PARA_WBROIHEIGHT | white balance roi height | 0x23
  MIINAM_PARA_VFLIP | vertical flip | 0x24
  MIINAM_PARA_HFLIP | horizontal flip | 0x25
  MIINAM_PARA_CHROME | monochromatic mode | 0x26
  MIINAM_PARA_SIZE | video width & height | 0x27
  MIINAM_PARA_LIGHTADJUSTMENT | light source brightness adjustment | 0x28
  MIINAM_PARA_ZOOM | zoom | 0x29
  MIINAM_PARA_EF_MODE | Auto focus mode, 0: lens calibration mode; 1: manual focus; 2: single focus; 3: auto focus; (EF means lens auto focus, the following parameters are EF related) | 0x2a
  MIINAM_PARA_EF_FL | Focal length | 0x2b
  MIINAM_PARA_EF_APERTURE | F#, 24~16bit:Cur, 15~8bit:Min, 7~0bit:Max | 0x2c
  MIINAM_PARA_EF_FOCUS_MAX | Maximum focal length | 0x2d
  MIINAM_PARA_EF_LENS_ID | Lens ID | 0x2e
  MIINAM_PARA_EF_AFMF | Lens focus mode, 0: AF; 1: MF; | 0x2f
  MIINAM_PARA_EF_WD_ENABLE | Enable working distance function | 0x30
  MIINAM_PARA_EF_WD_NEAR | Near working distance point | 0x31
  MIINAM_PARA_EF_WD_FAR | Far working distance point | 0x32
  MIINAM_PARA_CHROME_LOCAL | local monochromatic mode | 0x80
  MIINAM_PARA_VFLIP_LOCAL | local vertical flip | 0x81
  MIINAM_PARA_HFLIP_LOCAL | local horizontal flip | 0x82
  MIINAM_PARA_NEGATIVE_LOCAL | local negative film | 0x83
  MIINAM_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 miinam.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 MIINAM_PARA_xxx changes, pParaCallback will be called back

  pCallbackCtx is the callback context

- ## Miinam_Init

  Return value:NA

  Parameters:pCallback is callback, pCallbackCtx is the callback context

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

- ## Miinam_Fini

  Return value: NA

  Parameters: NA

  Remarks: call only once when application exit

- ## Miinam_Enum

  Return value: non-negative integer, enumerated camera number

  Parameters:

  > MiinamDevice buffer

  > sz: size of the array

  Remarks: call this function to enumerate Miinam 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
  MIINAM_FLAG_WIFI_AP | wifi ap
  MIINAM_FLAG_WIFI_STA | wifi sta
  MIINAM_FLAG_ETHERNET | eth network
  MIINAM_FLAG_CAPTURE | support the ability of capture image from camera
  MIINAM_FLAG_AWBCHECKMODE | auto white balance: check mode vs 'once' mode
  MIINAM_FLAG_UVC | uvc camera
  MIINAM_FLAG_WBGAIN | white balance gain mode or temp tint mode
  MIINAM_FLAG_MULTICAST | RTSP/RTP multicast
  MIINAM_FLAG_AF | support auto focus
  MIINAM_FLAG_SD | support sd card
  MIINAM_FLAG_WBROI | white balance: 0:manual;1:global auto;2:roi
  MIINAM_FLAG_STA_SUPPORT | wifi camera has sta mode, app should have sta ssid & password function
  MIINAM_FLAG_RTP_OVER_RTSP | rtp over rtsp
  MIINAM_FLAG_HZ_AUTOEXPO | enable auto exposure when 50/60 hz
  MIINAM_FLAG_AFDM | a way of auto focus
  MIINAM_FLAG_EFL | Support camera lens autofocus
  MIINAM_FLAG_CAPTURERAW | get raw data
  state | STATE
  MIINAM_STATE_INITING | initialization
  MIINAM_STATE_NORMAL | normal
  MIINAM_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

- ## Miinam_Open
  Miinam_Open_ByIndex

  Return value: camera handle. Return NULL when open failure

  Parameters: camId: Camera ID, obtained by Miinam_Enum enumeration

  Remarks: Open camera

- ## Miinam_Close

  Return value: NA

  Parameters: HMiinam h: camera handle

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

- ## Miinam_PullImagePtr

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

  > MiinamImagePtr* ptrImage: Frame buffer

  Remarks: Use the ImagePtr mode to fetch frame buffer.

- ## Miinam_PushImagePtr

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

  > unsigned ptrId: Frame buffer ID

  Remarks: After a frame buffer has been used, it must be returned to the SDK for reuse. Please note the following:

  > (a) The frame buffer must only be returned back after it is no longer in use. Any access after returning it is unsafe, as the SDK may have already reused the buffer and overwritten the memory with new data.

  > (b) If a frame buffer is not returned, the pool of available buffers will gradually decrease.

  > (c) Each frame buffer obtained via Pull (identified by its ID) may be returned only once; duplicate returns are not allowed.

  > (d) The return order does not need to match the Pull order; buffers may be returned out of order.

  > (e) Frame buffers that have not been returned remain valid after Miinam_Stop. Frame buffers that have not been returned become invalid immediately after Miinam_Close.

- ## Miinam_PullImage

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

  Parameters:

  > HMiinam 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

- ## Miinam_StartPullModeWithCallback

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

  > void* pCallbackContext: callback

  Remarks: NA

- ## Miinam_Stop

  Return value: HRESULT type means success or failure

  Parameters: HMiinam h: camera handle

  Remarks: Stop camera

- ## Miinam_Pause

  Return value: HRESULT type means success or failure

  Parameters: HMiinam h: camera handle

  Remarks: Pause or resume the stream

- ## Miinam_Capture
  Miinam_Capture_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam 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

- ## Miinam_get_Size_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > camId: camera id

  > res: camera resolution

  > pWidth, pHeight: width/height

  Remarks: NA

- ## Miinam_get_Device

  Return value: MiinamDevice represents information about camera

  Parameters: HMiinam h: camera handle

  Remarks: get information about camera

- ## Miinam_get_Size
  Miinam_get_CapSize

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

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

  Remarks: obtain the current resolution or recording resolution

- ## Miinam_get_FourCC

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

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

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

- ## Miinam_Record

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam 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

- ## Miinam_put_Para
  Miinam_get_Para

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

  > unsigned para: parameter type, seeMIINAM_PARA_xxx

  > value: put/get value

  Remarks: NA

- ## Miinam_put_Para_ById
  Miinam_put_Para_ById

  Return value: HRESULT type means success or failure

  Parameters:

  > HMiinam h: camera handle

  > unsigned para: parameter type, seeMIINAM_PARA_xxx

  > value: put/get value

  Remarks: set parameters through camera id, different fromMiinam_put_Para, Miinam_get_Para

- ## Miinam_put_Wifi

  Return value: HRESULT type means success or failure

  Parameters:

  > const char* camId: camera id

  > MiinamWifi wifi: wifi ssid & password

  Remarks: set WiFi

- ## Miinam_add_Ip
  Miinam_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
      };
      Miinam_add_Ip(arr);