video_streamer_c_api.h File Reference

#include <streamer.h>

Go to the source code of this file.

Classes
struct	VsParams
struct	VsTelemetry
struct	VsTelemetry::DoubleValue

Typedefs
typedef void *	VideoStreamerHandle
typedef void(*	VsLogCallback) (Log::Level level, const char *msg)
typedef void(*	VsStatusCallback) (Streamer::Status status, void *opaque)
typedef void(*	VsQueueOverflowCallback) (bool status, void *opaque)

Enumerations
enum	VsError {   VsError::NONE, VsError::INVALID_PARAM, VsError::INVALID_OP, VsError::INTERNAL_ERROR,   VsError::OTHER }

Functions
VsError	VsGetLastError (char *msgBuf, uint32_t *bufSize)
int	VsInitialize (VsLogCallback logCbk)
int	VsTerminate ()
VideoStreamerHandle	VsCreate (const VsParams *params, VsStatusCallback statusCbk, VsQueueOverflowCallback queueOverflowCbk)
void	VsDestroy (VideoStreamerHandle vs)
int	VsStart (VideoStreamerHandle vs)
int	VsStop (VideoStreamerHandle vs)
int	VsSetTailNumber (VideoStreamerHandle vs, const char *tailNumber)
int	VsFeedData (VideoStreamerHandle vs, const uint8_t *dataBuf, uint32_t bufSize)
int	VsFeedTelemetry (VideoStreamerHandle vs, const VsTelemetry *telemetry)
int	VsGetStatistics (VideoStreamerHandle vs, char *dataBuf, uint32_t *bufSize)

Detailed Description

API in this file is intended for external clients which will use this library in a plug-in manner like dlopen(). This is not intended to be compiled by C compiler and thus references C++ code (like enums). All strings in the API are UTF-8 encoded where not otherwise specified.

Overall workflow

The library responsibility is to produce MISP-compliant video stream with telemetry metadata integrated. It is up to the library user to obtain the video stream suitable for the library input (raw H.264 video stream) and telemetry values. Typically the input video stream can be obtained using ffmpeg or gstreamer library from some local video input devices or network video stream (see ffmpeg V4L example and stdin reading example). DJI drones provide such stream in their DJI SDK. In some cases the source may not provide H.264-encoded stream and uses either another encoder or provides raw unencoded video. It is up to the library user to perform transcoding or encoding into H.264 in such case.

First, the library must be initialized by calling VsInitialize(). The passed callback allows integration with a logging framework used in your application. No other calls are permitted before the library is initialized. Then the streamer instance can be created by calling VsCreate(). To use, for example, with UgCS video server, the URL like urtp+connect://<ip_address>://3341 should be passed in VsParams, where <ip_address> is UgCS video server address. The status callback argument allows to specify function which will receive all updates about the streamer instance status. The returned instance handle should be used for all the rest instance-bound calls. Then the instance can be started by calling VsStart() method. After started the video data can be fed by VsFeedData() function. It expects raw H.264 video stream. At the same time telemetry data can be provided by VsFeedTelemetry() function. Call VsStop() when done with the streamer instance and VsTerminate() when done with the entire library.

Typedef Documentation

VideoStreamerHandle

typedef void* VideoStreamerHandle

Represents handle for video streamer instance. One instance is bound to one streaming target.

VsLogCallback

typedef void(* VsLogCallback) (Log::Level level, const char *msg)

Called on each log message.

Parameters

opaque

Caller-defined parameter specified in VsParams.

VsQueueOverflowCallback

typedef void(* VsQueueOverflowCallback) (bool status, void *opaque)

Called when queue is overflowed or when it is consumed again.

Parameters

status

True when overflowed, false when back in normal state.

VsStatusCallback

typedef void(* VsStatusCallback) (Streamer::Status status, void *opaque)

Called on streamer status change.

Parameters

opaque

Caller-defined parameter specified in VsParams.

See also

Streamer::Status

Enumeration Type Documentation

VsError

enum VsError

strong

Error code. Will be extended with more specific error codes when necessarily.

Enumerator
NONE	No error.
INVALID_PARAM	Parameter is invalid.
INVALID_OP	Requested operation is not permitted in current state.
INTERNAL_ERROR	Internal error which indicates a software bug. Should not be caught in any way.
OTHER	Other error.

Function Documentation

VsCreate()

VideoStreamerHandle VsCreate	(	const VsParams *	params,
		VsStatusCallback	statusCbk,
		VsQueueOverflowCallback	queueOverflowCbk
	)

Create streamer instance. All events callbacks are called in a dedicated thread.

Parameters

Streamer	parameters. Owned by the caller.
statusCbk	Callback for status change events. See VsStatusCallback.
queueOverflowCbk	Callback for queue overflow events. See VsQueueOverflowCallback.

Returns

Returned instance should be later released by VsDestroy(). Null can be returned in case of failure.

VsDestroy()

void VsDestroy

(

VideoStreamerHandle

vs

)

Destroy the streamer instance and release all resources.

VsFeedData()

int VsFeedData	(	VideoStreamerHandle	vs,
		const uint8_t *	dataBuf,
		uint32_t	bufSize
	)

Feed next chunk of raw H.264 video stream. There are no requirements for chunks alignment and sizes respectively to H.264 protocol data units.

Parameters

dataBuf	Buffer with the data chunk.
bufSize	Size of the provided buffer in bytes.

Returns

Zero on success, non-zero on failure.

VsFeedTelemetry()

int VsFeedTelemetry	(	VideoStreamerHandle	vs,
		const VsTelemetry *	telemetry
	)

Set most recent telemetry values to send in next metadata packet. Fields may be updated selectively, only non-empty values are accounted in each invocation. Values are validated and INVALID_PARAM error is set if any value is out of range. Whole the specified telemetry block is discarded in such case.

Returns

Zero on success, non-zero on failure.

VsGetLastError()

VsError VsGetLastError	(	char *	msgBuf,
		uint32_t *	bufSize
	)

Get error from last API call in current thread. Each API call overwrites previously stored error value. Calling VcGetLastError() does not change last error value.

Parameters

msgBuf	Buffer for accepting error message (mostly for troubleshooting, not for forwarding to user). UTF-8 encoded null-terminated message is stored here. The string is truncated if buffer is too small, null terminator is always written.
bufSize	Should contain buffer size in bytes on input. Contains necessary size to accept whole the string on return (including null terminating character).

Returns

Last error code.

VsGetStatistics()

int VsGetStatistics	(	VideoStreamerHandle	vs,
		char *	dataBuf,
		uint32_t *	bufSize
	)

Get statistics report for the streamer instance.

Parameters

dataBuf	Buffer which receives string with JSON statistics data. The data do not have any fixed structure (actual content is a subject for change at any time) and are intended for display/logging only. No any logic should be bound to. The returned string is always null terminated.
bufSize	Should contain buffer size in bytes on input. Contains necessary size to accept whole the string on return (including null terminating character). Keep in mind that next call will most probably return another string so some spare space is recommended.

Returns

Zero on success, non-zero on failure.

VsInitialize()

int VsInitialize

(

VsLogCallback

logCbk

)

Initialize the library. Should be called before any other API call.

Parameters

logCbk

Callback for connecting logging to the framework used by an application.

Returns

Zero on success, non-zero on failure.

VsSetTailNumber()

int VsSetTailNumber	(	VideoStreamerHandle	vs,
		const char *	tailNumber
	)

Set new tail number. This is user-readable part of composite tail number which can be changed at any time (in contrast with vehicle ID part). Some non-permitted characters may be replaced.

Returns

Zero on success, non-zero on failure.

VsStart()

int VsStart

(

VideoStreamerHandle

vs

)

Start the streamer instance. Should be called before trying to pass any video or telemetry to the streamer instance. VsStop() should be called after successful streamer start.

Returns

Zero on success, non-zero on failure.

VsStop()

int VsStop

(

VideoStreamerHandle

vs

)

Stop the streamer instance, releasing all the processing resources. Should not be called in events thread.

Returns

Zero on success, non-zero on failure.

VsTerminate()

int VsTerminate

(

)

Shutdown the library. Should be called when done working with the library.