tencent cloud

All product documents
C Field Device SDK API
Last updated: 2025-02-11 16:48:53
C Field Device SDK API
Last updated: 2025-02-11 16:48:53

API Description

Applicable to Linux 64-bit systems. Include the header file trro_field.h, and refer to the comments in the header file for API details. Below are descriptions of commonly used APIs.
Note:
APIs marked as atomic capability APIs are functional interfaces not associated with TRRO real-time interaction services. These APIs can be freely used after SDK initialization, allowing customers to reuse SDK capabilities to develop other features.

API Overview

Initialization API

Interfaces
Description
Initializing with a JSON String
Initializing with a Configuration File Path
Initializing with a Configuration Path and License Path (Private)
Initializing with a JSON String and License Path (Private)

Status Retrieval APIs

Interfaces
Description
Registration Signaling Status Callback
Registration of video connection status callback
Registration of latency status callback
Registration of video media and network status callback
Registration of audio media and network status callback
Registration of external encoding suggestion callback (for external encoding)

Start/Stop APIs

Interfaces
Description
Starting the SDK
Stopping the SDK

Audio and Video Input/Output APIs

Interfaces
Description
Inputting External Source Video Stream (Image Data)
Register Video Capture Data Callback Function
Inputting External Source Video Stream (Encoded Data)
Inputting External Audio Stream (PCM Data)

Camera Capture API (Atomic Capability API)

Interfaces
Description
Start Camera Capture
Stop camera capture

Message APIs

Interfaces
Description
Send data to remote devices
Register callback for remote device control messages

Permission Control APIs

Interfaces
Description
Register callback for remote device permission request notification
Set remote device operation permissions

Reconfiguration APIs

Interfaces
Description
Reconfigure field device video stream, only supports reconfiguration of extended capture protocols such as normal/combine/rtsp_enc

Audio Control APIs

Interfaces
Description
Mute Settings
Retrieve the Number of Audio Capture/Playback Devices
Retrieve the Name of Audio Capture/Playback Devices
Change the Current Audio Capture/Playback Device

Log/Error Message APIs

Interfaces
Description
Register Log Callback Function
Register Error Event Callback
API for Retrieving Error Information Based on Error Code

Video Recording API (Atomic Capability API)

Interfaces
Description
Start Recording
Sending Recording Data
Switching Recording File
End recording

Network Evaluation API

Interfaces
Description
Testing if the network quality meets the requirements for video transmission, can be used to check the network at startup

Getting Software Information

Interfaces
Description
Get the software version number

Initialization API

Use Instructions: You can choose the corresponding initialization API based on whether to use a local license (no local license is needed for public cloud) and the input configuration type (file/string). Only one is needed.

Initializing with a JSON String

Use Instructions: Users must ensure the JSON string format is correct. This API is used for SDK configuration loading and initialization.
/*
* @name : TRRO_initGwJson
* @brief : Initializing with a String
* @input : json_str Configuration file JSON string
* @input : mode 0 synchronous mode, always waiting
* -1 asynchronous mode, notify TRRO_onSignalState after successful initialization
* @return : 1 for success, other failed
*/
int TRRO_initGwJson(const char * json_str, int mode = 0);
Parameters
Meaning
json_str
Configuration information JSON string
mode
Return mode
0: Synchronous blocking mode
1: Asynchronous mode

Initializing with a Configuration File Path

Use Instructions: Users must ensure the JSON configuration file format is correct. This API is used for SDK configuration loading and initialization.
/*
* @name : TRRO_initGwPath
* @brief : Initializing with a configuration file
* @input : cfg_path JSON configuration file path, e.g. "./config.json"
* @input : mode 0 synchronous mode, always waiting
* -1 asynchronous mode, TRRO_onSignalState information after successful initialization
* @return : 1 for success, other failed
*/
int TRRO_initGwPath(const char * cfg_path, int mode = 0);
Parameters
Meaning
cfg_path
Configuration file path
mode
Return mode
0: Synchronous blocking mode
1: Asynchronous mode

Initializing with a Configuration File Path and License File Path

Use Instructions: Users must ensure the JSON configuration file format is correct and the license file path is valid. This API is used for SDK configuration loading and initialization.
/*
* @name : TRRO_initGwPathWithLicense
* @brief : Initializing with a Configuration File and Local License
* @input : cfg_path JSON configuration file path, e.g. "./config.json"
* @input : license_path license file path, e.g. "./license.txt"
* @input : mode 0 synchronous mode, always waiting
* -1 asynchronous mode, notify TRRO_onSignalState after successful initialization
* @return : 1 for success, other failed
*/
int TRRO_initGwPathWithLicense(const char * cfg_path, const char * license_path, int mode = 0);

Parameters
Meaning
cfg_path
Configuration file name
license_path
Local license file path
mode
Return mode
0: Synchronous blocking mode
1: Asynchronous mode

Initializing with a Configuration String and License File Path

Use Instructions: Users must ensure the JSON string and license content formats are correct. This API is used for SDK configuration loading and initialization.
/*
* @name : TRRO_initGwJsonWithLicense
* @brief : Initializing with a String and Local License
* @input : json_str Configuration file JSON string
* @input : license_path license file path, e.g. "./license.txt"
* @input : mode initialization mode
* 0 synchronous mode, always waiting
* -1 asynchronous mode, notify TRRO_onSignalState after successful initialization
* @return : 1 for success, other failed
*/
int TRRO_initGwJsonWithLicense(const char * json_str, const char * license_path, int mode = 0);
Parameters
Meaning
json_str
Configuration file JSON string
license_path
license path
mode
Return mode
0: Synchronous blocking mode
1: Asynchronous mode

Status Retrieval APIs

Usage Instructions: Register the required callback APIs as needed.

Registering Signaling Status Callback (Asynchronous Initialization Callback)

Usage Instructions: This API is used to register the signaling status callback API, which is required for asynchronous initialization. The initialization success is determined by the Ready status.
/*
* @name : TRRO_registerSignalStateCallback
* @brief : Register signaling service connection status callback
* @input : context Context pointer
           callback Callback function
* @return : 1 for success, other failed
*/
int TRRO_registerSignalStateCallback(void *context, TRRO_onSignalState *callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
Callback Definition
enum SignalState {
kTrroReady = 0, /**< Connection established successfully */
kTrroLost = 1, /**< Connection lost, automatic reconnection will be attempted internally */
kTrroReup = 2, /**< Automatic reconnection successful */
kTrroKickout = 3,
kTrroAuthFailed = 4, /**< Incorrect username or password */
};

/*
* @name : TRRO_onSignalState
* @brief : Signaling connection status callback
* @input : context Context pointer
* state kTrroReady Connection established successfully
* kTrroLost Connection lost, automatic reconnection will be attempted internally
* kTrroReup Automatic reconnection successful
* @return : void
*/
typedef void TRRO_onSignalState(void *context, SignalState state);
Parameters
Meaning
context
Callback context pointer, returns the context passed during registration
state
Signaling connection status

Registration of video connection status callback

Usage Instructions: This API is used to register video stream connection status callback. You can choose to call this API as needed.
/**
* @name TRRO_registerOnState
* @brief Register video connection status callback function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerOnState(void* context, TRRO_OnState * callback);
Parameters
Meaning
context
Context pointer, returned during callback for positioning
callback
the permission to be set
Callback Function Definition
enum TrroState {
kDisconnect = 0, /**< Disconnected */
kConnecting = 1, /**< Connecting */
kConnected = 2, /**< Connected */
kDisconnecting = 3, /**< Disconnecting */
};

/**
* @name TRRO_onState
* @brief Video connection status callback
* @param[in] context Context pointer
* @param[in] stream_id video stream id
* @param[in] state TrroState connection status
* @return void
*/
typedef void TRRO_OnState(void* context, int stream_id, int state);

Registering Latency Callback

Use instructions: This API is used to obtain the video data processing delay from push to pull on the field device side, and can be used as needed.
/**
* @name TRRO_registerLatencyCallback
* @brief Register latency callback function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerLatencyCallback(void *context, TRRO_onLatencyReport *callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
/**
* @name TRRO_onLatencyReport
* @brief Delayed message callback
* @param[in] context Context pointer
* @param[in] stream_id Stream ID
* @param[in] vcct Video control closed-loop delay, equal to video uplink delay (excluding capture) + control downlink delay
* @return void
*/
typedef void TRRO_onLatencyReport(void *context, int stream_id, int vcct);
Parameters
Meaning
context
target remote device id
stream_id
Stream ID
vcct
Video control closed-loop delay, equal to video uplink delay (excluding capture) + control downlink delay

Registering the Video Media Status Callback

Use instructions: This API is used to obtain the media status of the connected video stream on the field device, and can be used as needed.
/**
* @name TRRO_registerMediaState
* @brief Register network status
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerMediaState(void* context, TRRO_onMediaState * callback);
Parameters
Meaning
context
target remote device id
callback
Media status callback function
/**
* @name TRRO_onMediaState
* @brief Media transmission status callback
* @param[in] context Callback context pointer
* @param[in] stream_id Stream ID
* @param[in] fps Frames per second
* @param[in] bps Bits per second
* @param[in] rtt Round-trip time
* @param[in] lost Total packet loss
* @param[in] packets_send Total number of packets sent
* @param[in] stun NAT traversal mode 0: host, 1: srflx, 2: prflx, 3: relay
* @return void
*/
typedef void TRRO_onMediaState(void* context, int stream_id, int fps, int bps, int rtt, long long lost, long long packets_send, int stun);
Parameters
Meaning
context
target remote device id
stream_id
Stream ID
fps
Frames per second
bps
Data per second
rtt
Packet round-trip time
lost
Total packet loss
packets_send
Total sent count
stun
NAT Traversal Mode
0:host
1:srflx
2:prflx
3:relay

Registering Audio Status Callback

Use instructions: This API is used to obtain the media status of the connected audio stream on the field device, and can be used as needed.

/**
* @name TRRO_registerAudioMediaState
* @brief Registering Audio Status Callback
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerAudioMediaState(void* context, TRRO_onMediaState * callback);

Parameters
Meaning
context
target remote device id
callback
Media status callback function

Registering Encoding Suggestion Callback

Usage Instructions: This API is used together with the external encoding stream input data API. Users can process the input encoding stream based on the callback information from this API.
/**
* @name TRRO_registerEncodeFrameInfoCallback
* @brief Registering Encoding Suggestion Callback Function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerEncodeFrameInfoCallback(void *context, TRRO_onEncodeFrameInfo *callback);
Parameters
Meaning
context
Context pointer, returned during callback for positioning
callback
the permission to be set
Callback Function Definition
/**
* @name TRRO_onEncodeFrameInfo
* @brief Encoding suggestion callback, applicable to external input encoding frame scenarios
* @param[in] context Context pointer
* @param[in] stream_id Stream ID
* @param[in] type Callback type, 0: Force keyframe request, 1: Bitrate update request
* @param[in] bitrate Effective when type is 1, indicates the suggested input encoding data bitrate, in kbps
* @return void
*/
typedef void TRRO_onEncodeFrameInfo(void *context, int stream_id, int type, int bitrate);
Parameters
Meaning
context
Callback context pointer, returns the context passed during registration
strem_id
Stream ID
type
Callback Type
0: Force keyframe request
1: Bitrate update request
bitrate
Effective when type is 1, indicates the suggested input encoding data bitrate, in kbps

Start/Stop APIs

Start API

Use instructions: This API is used to start the field device SDK. It can be called after successful initialization, either when synchronous mode initialization returns success or when asynchronous mode initialization TRRO_onSignalState notifies the connection is Ready.
/**
* @name TRRO_start
* @brief Start the audio and video transmission service, to be called after successful initialization (synchronous mode init returns success or asynchronous mode initialization TRRO_onSignalState notifies the connection is Ready)
* @param[in] void
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_start();

Stop API

Use instructions: This API is used to stop the field device SDK.
/**
* @name TRRO_stop
* @brief Destroy the SDK and release SDK resources
* @param[in] void
* @return void
*/
extern "C" TRRO_EXPORT void TRRO_stop();

Audio and Video Input/Output APIs

Inputting External Source Video Stream (Image Data)

Use instructions: This API is used to provide the raw image data stream of the video input by the user. Note that the input data source must match the number of streams and stream configuration nodes in the configuration file.
The width and height of the input data source must be consistent with the width and height in the Field Device Configuration Instructions, and the value of the "protocol" node in the configuration file should be changed to "outside".

/**
* @name TRRO_externalVideoData
* @brief External Image Input API
* @param[in] stream_id Stream ID
* @param[in] data Message body
* @param[in] width Data source width
* @param[in] height Data source height
* @param[in] type Data source type, currently supports Trro_ColorYUVI420, Trro_ColorJPEG, Trro_ColorYUYV
* @param[in] dataSize Data size, automatically calculated based on format if 0, must specify for data like JPEG with no specific size
* @param[in] text String to overlay on image (experimental)
* @param[in] point_x Starting x-coordinate for overlay text, 0 at the leftmost (experimental)
* @param[in] point_y Starting y-coordinate for overlay text, 0 at the top (experimental)
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_externalVideoData(int stream_id, const char * data, int width, int height, int type, int dataSize = 0, const char* text = "", int point_x = 0, int point_y = 0);
Parameters
Meaning
stream_id
Video stream ID, starting from 0, the second stream is 1, and so on
data
Image data
width
Image width
height
Image height
type
Image type
0:YUVI420
4:YUYV
5: JPEG, YUVI420 format recommended
dataSize
Image data size, 0 for auto calculation, must specify for image formats like JPEG with no fixed size
text
Reserved
point_x
Reserved
point_y
Reserved

Register Video Capture Data Callback Function

Use instructions: This API is used to obtain the camera data source collected by the SDK for upper-level business use.
/**
* @name TRRO_registerVideoCaptureCallback
* @brief Register video capture data callback function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerVideoCaptureCallback(void* context, TRRO_onVideoCaptureData * callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
/**
* @name TRRO_onVideoCaptureData
* @brief Video frame capture callback
* @param[in] context Context pointer, returns the context passed in during registration
* @param[in] data Video data
* @param[in] width Width
* @param[in] height Height
* @param[in] type Video format, 0 YUV420, 4 YUYV
* @param[in] stream_id Stream number
* @return void
*/
typedef void TRRO_onVideoCaptureData(void *context, const char* data, int width, int height, int type, int stream_id);
Parameters
Meaning
remote_devid
Set the target device ID for permissions
data
Video Data
width
Video data width
height
Video data height
type
Video format:
0 YUV420
4 YUYV
stream_id
Stream number

Inputting External Source Video Stream (Encoded Data)

Notes:
It is recommended to use single slice encoding, and I-frames need to carry SPS/PPS.
Note: This API is used to provide the user-input encoded video stream for transmission. Note that the input data source must match the number of streams and stream configuration nodes in the configuration file. The input video stream encoding type (e.g., H264) must be consistent with the codec of the corresponding stream in the configuration file, and the keyframe must contain SPS/PPS information. Meanwhile, the "protocol" node value in the configuration file should be modified to "outenc".
/**
* @name TRRO_externalEncodeVideoData
* @brief External encoded stream input, the encoded stream codec needs to be consistent with the configuration codec
* @param[in]    stream_id            Stream ID
* @param[in]    data                 Message body
* @param[in]    width                Data source width
* @param[in]    height               Data source height
* @param[in]    size                 Data size
* @param[in]    type                 Data source type, refer to FrameType
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_externalEncodeVideoData(int stream_id, const char * data, int width, int height, int size, FrameType type);
Parameters
Meaning
stream_id
Video stream ID, starting from 0, the second stream is 1, and so on
data
Video stream data
width
Video width
height
Video height
size
Video frame size
type
Encoding type
0: P frame
1: I frame (must include SPS/PPS information)

Inputting External Audio Stream (PCM Data)

Notes:
In the configuration, the "audio_external" node value needs to be modified to 1.
Use instructions: This API is used to provide user input audio stream for transmission, with input as PCM data, 16-bit sampling.

/**
* @name TRRO_externAudioData(Experimental)
* @brief External audio data input (PCM data), 16-bit audio sampling
* @param[in] data Source data
* @param[in] data_size Data size
* @param[in] channel Number of audio channels
* @param[in] sample_rate Audio sample rate
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_externAudioData(const char* data, int data_size, int channel, int sample_rate);

Parameters
Meaning
data
Audio stream data
data_size
Data size
channel
Number of channels
1: Mono
2: Stereo
sample_rate
Sampling frequency, supports 8k/16k/24k/32k/44.1k/48kHz, for example, 48k sampling rate input is 48000

Message APIs

Send data to remote devices

Use Instructions: This API is used to send binary data to remote devices, in conjunction with the remote device SDK data callback API. This API can be called as needed. Currently, the data size limit for a single transmission is 700 bytes, with a frequency limit of 100 times per second.
/**
* @name TRRO_sendControlData
* @brief Send data to remote devices
* @param[in] msg Message body
* @param[in] len Message body length
* @param[in] qos 0:unreliable 1:reliable
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_sendControlData(const char* msg, int len, int qos = 0);
Parameters
Meaning
msg
Binary message content
len
Message length
qos
Send qos type
0: unreliable transmission
1: Reliable Transmission

Register callback for remote device control messages

This interface is used to register the report data callback function to receive the data sent by the field device.
/**
* @name TRRO_registerControlDataCallback
* @brief Register Remote Device Message Callback Function
* @param[in]   context              Context pointer, returns this context pointer during callback
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerControlDataCallback(void* context, TRRO_onControlData * callback);
Parameters
Meaning
context
Context pointer, the context indicator will be returned upon callback for localization
callback
the permission to be set
Callback Function Definition
/**
* @name TRRO_onControlData
* @brief Receive Remote Device Message Callback
* @param[in]     context        Context pointer, returns the context passed in during registration
* @param[in]     controller_id  Remote device ID
* @param[in]     msg            Message body
* @param[in]     len            Message body length
* @param[in] qos Message qos type 0:unreliable, 1:reliable
* @return void
*/
typedef void TRRO_onControlData(void *context, const char *controller_id, const char* msg, int len, int qos);
Parameters
Meaning
context
Callback context, returns the context passed in during registration
controller_id
Field Device ID
msg
pointer to the data buffer
len
String Length
qos
Message qos type
0: ultra-low latency transmission, data lost is allowed
1: Reliable Transmission

Permission Control APIs

Register callback for remote device permission request notification

This interface is used for the field device to receive permission requests from the remote device.
/**
* @name TRRO_registerOperationPermissionRequest
* @brief Register callback for remote device control permission request notification
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerOperationPermissionRequest(void *context, TRRO_onOperationPermissionRequest *callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
/**
* @name TRRO_onOperationPermissionRequest
* @brief Notification of remote device control permission request
* @param[in] remote_devid Remote device ID requesting permission
* @param[in] permission Requested permission, refer to TrroPermission, 0: guest (view only), 1: master (full control)
* @return void
*/
typedef void TRRO_onOperationPermissionRequest(void* context, const char* remote_devid, int permission);
Parameters
Meaning
context
target remote device id
remote_devid
Remote device ID requesting permission
permission
Requested permissions, see TrroPermission 
0:guest (view-only permission)
1:master (full control permission)

Set remote device operation permissions

This interface is used to set the remote device operation permissions on the field device.
/**
 * @name TRRO_setOperationPermission
 * @brief Set remote device control permissions. Currently, only one remote device can have master permission at a time. If a remote device already has master permission, calling this API to set master permission will automatically revoke the previous device's master permission and set the new device.
 * @param[in] remote_devid Remote device ID to set permissions
 * @param[in] permission Refer to TrroPermission, 0 guest, view only, 1 master, full control
 * @return 1 for success, other failed
 */
extern "C" TRRO_EXPORT int TRRO_setOperationPermission(const char* remote_devid, int permission);
Parameters
Meaning
context
target remote device id
callback
the permission to be set

Reconfiguration APIs

Reconfiguring RTC Settings

Use instructions: Reconfiguring video stream settings
/**
* @name TRRO_reinitRtc(Experimental)
* @brief Reconfiguration, currently only supports resetting extended capture protocols such as normal/combine/rtsp_enc
* @param[in] config Reconfigure JSON Data
*/
extern "C" TRRO_EXPORT int TRRO_reinitRtc(const char * config);
Parameters
Meaning
config
Reconfigure JSON Data

Audio Control Interface

Setting Mute

Use Instructions: Disable Audio Transmission
/**
* @name TRRO_audioMute(Experimental)
* @brief Mute the audio of the remote deviceID
* @param[in] userid Pullstream End ID
* @param[in] mute Whether to mute
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_audioMute(const char* userid, bool mute);
Parameters
Meaning
userid
remote deviceID
mute
Whether to mute

Retrieve the Number of Audio Capture/Playback Devices

Use instructions: Retrieve the number of audio capture/playback devices, which can be used to iterate over audio device names.
/**
* MediaDeviceType device type enumeration
*/
enum MediaDeviceType {
///Microphone type device
MediaDeviceTypeMic = 0,
///Speaker type device
MediaDeviceTypeSpeaker = 1,
};

/**
* @name TRRO_getDeviceCount(Experimental)
* @brief Query the number of audio devices based on MediaDeviceType.
* @param[in] type Audio device type
* @return Number of devices
*/
extern "C" TRRO_EXPORT int TRRO_getDeviceCount(MediaDeviceType type);
Parameters
Meaning
MediaDeviceType
Audio device types: Microphone (MediaDeviceTypeMic), Speaker (MediaDeviceTypeSpeaker)

Querying Audio Device Names

Use instructions: Querying the names of audio capture/playback devices, which can be used to filter target audio devices

/**
* @name TRRO_getDeviceName(Experimental)
* @brief Query the device name based on MediaDeviceType and index.
* @param[in] type Device type
* @param[in] index Device index, value is [0, TRRO_getDeviceCount)
* @return Device name, returns null on failure
*/
extern "C" TRRO_EXPORT const char* TRRO_getDeviceName(MediaDeviceType type, int index);

Parameters
Meaning
MediaDeviceType
Audio device types: Microphone (MediaDeviceTypeMic), Speaker (MediaDeviceTypeSpeaker)
index
Audio device index, value is [0, TRRO_getDeviceCount)

Changing the Current Audio Device

Usage Instructions: Change the current audio capture/playback device. The SDK will select the default audio device based on the configuration at startup. You can call this API to change it.

/**
* @name TRRO_setCurrentDevice(Experimental)
* @brief Set the current capture or playback device based on MediaDeviceType and index.
* @param[in] type Device type
* @param[in] index Device index, value is [0, TRRO_getDeviceCount)
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_setCurrentDevice(MediaDeviceType type, int index);

Parameters
Meaning
MediaDeviceType
Audio device types: Microphone (MediaDeviceTypeMic), Speaker (MediaDeviceTypeSpeaker)
index
Audio device index, value is [0, TRRO_getDeviceCount)



Log/Error Message APIs

Register Log Callback Function

Usage Instructions: This API is used to register a log callback function for upper-layer applications to obtain logs.
/**
* @name  TRRO_registerLogCallback
* @brief Register log callback function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerLogCallback(void *context, TRRO_OnLogData *callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
/**
* @name TRRO_OnLogData
* @brief Log callback
* @param[in]     context        Context pointer
* @param[in]     msg            Log content
* @param[in]     level          Log level, refer to the enumeration TrroLogLevel
* @return void
*/
typedef void TRRO_OnLogData(void *context, const char *msg, int level);
Parameters
Meaning
context
target remote device id
msg
Log content
level
Log level, refer to the enumeration TrroLogLevel

Register Error Event Callback

Usage Instructions: This API is used to register error event callback, which is triggered when an exception occurs on the streaming end. You can choose to use it as needed.
/**
* @name TRRO_registerOnErrorEvent
* @brief Register error event callback function
* @param[in] context Context pointer
* @param[in] callback Callback function
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_registerOnErrorEvent(void* context, TRRO_OnErrorEvent * callback);
Parameters
Meaning
context
target remote device id
callback
the permission to be set
/**
* @name TRRO_OnErrorEvent
* @brief Error message callback
* @param[in] context Context pointer
* @param[in] error_code Error code, negative value
* @param[in] error_msg Error message
* @return void
*/
typedef void TRRO_OnErrorEvent(void* context, int error_code, const char* error_msg);
Parameters
Meaning
context
target remote device id
error_code
Error Code
error_msg
Error Message

Error Message Query

Use Instructions: Query the error message corresponding to the error code.
/**
* @name getErrorMsg
* @brief Returns the error message based on the error code.
* @param[in] errorCode Error code
* @return errorMsg Troubleshooting help information
*/
extern "C" TRRO_EXPORT const char* getErrorMsg(int errorCode);
Parameters
Meaning
errorCode
To query the error code, you can input either positive or negative error codes.
errorMsg
Corresponding Error Message

Recording APIs

Start Recording

Use Instructions: Create a video recorder for local recording of video streams from field devices.
/**
* @name TRRO_startRecorder(Experimental)
* @brief Start Recording
* @param[in] recorderID Recording ID (To record SDK collected streams, the ID should be set to the corresponding stream, and "record_on":1 should be added to stream_config in the config file)
* @param[in] format Recording format: 0 : 264
* @param[in] width Encoding width
* @param[in] height Encoding height
* @param[in] jump Recording frame skip count (record one frame every few frames)
* @param[in] fps Encoding frame rate
* @param[in] bps Bit rate
* @param[in] filename File name
* @param[in] config Recording options (reserved)
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_startRecorder(int recorderID, int format, int width, int heigh, int jump, int fps, int bps,
                                  const char* filename, const char* config);
Parameters
Meaning
recorderID
Recording ID
(To record SDK collected video streams, the ID should be set to the corresponding stream ID, and "record_on":1 should be added to the stream_config of the corresponding stream. The corresponding stream data will be automatically imported into the recorder with the matching ID.)
format              
Recording format: 0 : 264
width                
Encoding width
heigh  
Encoding height
jump                
Recording frame skip count (record one frame every few frames)
fps                  
 Encoding frame rate
bps                  
Bitrate
filename            
File Name
config              
Recording options (reserved)

Sending Recording Data

Use instructions: Input the video data to be recorded. When recording external input video streams, use with TRRO_startRecorder API and TRRO_stopRecorder API.
/**
* @name TRRO_sendRecordVideoData(Experimental)
* @brief Send recording data
* @param[in] recorderID Recording ID
* @param[in] data Recording data
* @param[in] width Data source width
* @param[in] height Data source height
* @param[in] size Recording data size
* @param[in]   format               Video source format 1 yuv420, 4 YUYV
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_sendRecordVideoData(int recorderID, const char* data, int width, int height, int format);
Parameters
Meaning
recorderID
Recorder ID
data                
Recording data
width                
Encoding width
heigh  
Encoding height
size                
Recording data size
format              
Encoding frame rate
bps                  
Video source format 1 yuv420, 4 YUYV

Switching Recording File

Use instructions: Switch recording file, used with recording feature.
/**
 * @name TRRO_switchRecorderFile(Experimental)
 * @brief Switch Recording File
 * @param[in] recorderID Recording ID
 * @param[in] filename File name
 * @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_switchRecorderFile(int recorderID, const char* filename);
Parameters
Meaning
recorderID
Recorder ID
filename            
Name of the recording file after switching

Stop recording

Use instructions: Stop recording, used with recording feature.
/**
* @name Trro_TRRO_OnStatestopRecorder(Experimental)
* @brief Stop Recording
* @param[in] recorderID Recording ID
* @return 1 for success, other failed
*/
extern "C" TRRO_EXPORT int TRRO_stopRecorder(int recorderID);
Parameters
Meaning
recorderID
Recorder ID

Video Capture APIs

Starting Capture

Use instructions: Used to capture camera data and callback the camera data to the user through a callback function.
/**
* @name TRRO_onVideoCaptureFrame
* @brief Data callback when TRRO_startVideoCapture is called externally
* @param[in] context Context pointer
* @param[in] capture_id Current source ID of the captured video
* @param[in] data Captured video data
* @param[in] length Length of the captured video data
* @param[in] width Captured video width
* @param[in] height Captured video height
* @param[in] color_format Captured video format
* @return void
*/
typedef void TRRO_onVideoCaptureFrame(void *context, unsigned long long capture_id, const char* data, int length, int width, int height, TrroColor color_format);

/**
* @name TRRO_startVideoCapture
* @brief Start camera capture
* @param[in] context Context
* @param[in] url Capture path, /dev/video* for camera, rtsp address for rtsp
* @param[in] protocol When equal to kV4L2_DMA or kV4L2_MMAP, for camera capture. When equal to kRTSP, for rtsp address
* @param[in] TrroColor Captured video format
* @param[in] width Captured video width
* @param[in] height Captured video height
* @param[in] fps Video capture frame rate
* @param[in] callback Video capture callback
* @param[in, out] capture_id Unique identifier for the capture stream (returns an error if duplicated), supports input and output (use input value only when (*capture_id) > 0, otherwise internally generate and modify this value)
* @return Returns error code if capture start fails, returns 1 for success
*/
extern "C" TRRO_EXPORT int TRRO_startVideoCapture(void *context, const char* url, VideoCaptureProtocol protocol, TrroColor color_format, int width, int height, int fps, TRRO_onVideoCaptureFrame callback, unsigned long long* capture_id);
Parameters
Meaning
context
Context pointer, used for callback positioning
url
Capture path, /dev/video* for camera, rtsp address for rtsp
protocol
kRTSP for network camera RTSP protocol capture, kV4L2_MMAP for USB/GMSL camera V4L2 protocol capture, kV4L2_DMA for NVIDIA Jetson platform V4L2 capture
TrroColor
Captured video format, V4L2 protocol for camera image format, RTSP protocol capture for target callback format
width
Captured video width
height
Captured video height
fps
Captured video frame rate
callback
Video capture callback
capture_id
Capture identifier, used to distinguish different captures, passed as a pointer, supports value specification or auto-generation (use specified input value when (*capture_id) > 0, use SDK auto-generated value when 0)

Stopping the Capture

Use instructions: Used to capture camera data and callback the camera data to the user through a callback function.
/**
* @name TRRO_stopVideoCapture
* @brief Stop camera capture
* @param[in] capture_id Capturing source ID (cannot be 0)
* @return Returns error code if capture stop fails, returns 1 for success
*/
extern "C" TRRO_EXPORT int TRRO_stopVideoCapture(unsigned long long capture_id);
Parameters
Meaning
capture_id
Capturing source ID (cannot be 0)



Network Evaluation API

Starting Network Evaluation

Use instructions: Used to evaluate whether the network quality meets the requirements for video transmission, and can be used to test the network before business starts. This API is a blocking function. When using this API, the SDK will actively push the video stream for network testing and collect network metrics for evaluation. If the SDK is already pushing the video stream, it is recommended to directly observe the network metrics through the media status callback API.

/**
* @name TRRO_testNetworkQuality
* @brief Evaluate network status Note: This function is a blocking function
* If the network connection is not successful, the timeout period is 10s plus the network detection time
* @param[in] stream_ids Array of Stream IDs to be detected
* @param[in] stream_size Size of the array of Stream IDs to be detected
* @param[in] test_time Duration of the detection after a successful connection, minimum 2s, maximum 10s;
*
* @return int Network assessment 0: Unable to assess network, 1: Good network, 2: Poor network, 3: Unavailable network
*/
extern "C" TRRO_EXPORT int TRRO_testNetworkQuality(int* stream_ids, int stream_size, int test_time);

Parameters
Meaning
stream_ids
Array of video stream IDs for network assessment
stream_size
Size of the video stream ID array
test_time
Detection duration, minimum 2 seconds, maximum 10 seconds

Getting SDK Information

SDK version API

Use Instructions: Get the sdk version number.
/**
* @name getSdkVersion
* @brief Get the SDK version information
* @param[in] void
* @return version number
*/
extern "C" TRRO_EXPORT const char* TRRO_getSdkVersion();




Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support