Messaging API

Detailed Description

Defines an API for exchanging messages with remote entities and services.

Typedefs
typedef void *	NvDsMsgApiHandle
	Defines the handle used by messaging API functions. More...
typedef void(*	nvds_msgapi_send_cb_t )(void *user_ptr, NvDsMsgApiErrorType completion_flag)
	Type definition for a "send" callback. More...
typedef void(*	nvds_msgapi_subscribe_request_cb_t )(NvDsMsgApiErrorType flag, void *msg, int msg_len, char *topic, void *user_ptr)
	Type definition for callback registered during subscribe. More...
typedef void(*	nvds_msgapi_connect_cb_t )(NvDsMsgApiHandle h_ptr, NvDsMsgApiEventType ds_evt)
	Type definition for a "handle" callback. More...

Enumerations
enum	NvDsMsgApiEventType {   NVDS_MSGAPI_EVT_SUCCESS,   NVDS_MSGAPI_EVT_DISCONNECT,   NVDS_MSGAPI_EVT_SERVICE_DOWN }
	Defines events associated with connections to remote entities. More...
enum	NvDsMsgApiErrorType {   NVDS_MSGAPI_OK,   NVDS_MSGAPI_ERR,   NVDS_MSGAPI_UNKNOWN_TOPIC }
	Defines completion codes for operations in the messaging API. More...

Functions
NvDsMsgApiHandle	nvds_msgapi_connect (char *connection_str, nvds_msgapi_connect_cb_t connect_cb, char *config_path)
	Connects to a remote agent by calling into a protocol adapter. More...
NvDsMsgApiErrorType	nvds_msgapi_send (NvDsMsgApiHandle h_ptr, char *topic, const uint8_t *payload, size_t nbuf)
	Sends a message synchronously over a connection. More...
NvDsMsgApiErrorType	nvds_msgapi_send_async (NvDsMsgApiHandle h_ptr, char *topic, const uint8_t *payload, size_t nbuf, nvds_msgapi_send_cb_t send_callback, void *user_ptr)
	Sends message asynchronously over a connection. More...
NvDsMsgApiErrorType	nvds_msgapi_subscribe (NvDsMsgApiHandle h_ptr, char **topics, int num_topics, nvds_msgapi_subscribe_request_cb_t cb, void *user_ctx)
	Subscribe to a remote entity for receiving messages on a particular topic(s) More...
void	nvds_msgapi_do_work (NvDsMsgApiHandle h_ptr)
	Calls into the adapter to allow for execution of undnerlying protocol logic. More...
NvDsMsgApiErrorType	nvds_msgapi_disconnect (NvDsMsgApiHandle h_ptr)
	Terminates a connection. More...
char *	nvds_msgapi_getversion (void)
	Gets the version number of the messaging API interface supported by the protocol adapter. More...
char *	nvds_msgapi_get_protocol_name (void)
	Gets the name of the protocol used in the adapter. More...
NvDsMsgApiErrorType	nvds_msgapi_connection_signature (char *broker_str, char *cfg, char *output_str, int max_len)
	Fetch the connection signature by parsing broker_connection string and cfg file. More...

Typedef Documentation

typedef void(* nvds_msgapi_connect_cb_t)(NvDsMsgApiHandle h_ptr, NvDsMsgApiEventType ds_evt)

Type definition for a "handle" callback.

This callback reports any event (success or error) during a call to nvds_msgapi_connect().

Parameters

[in]	h_ptr	A handle for the event.
[in]	ds_evt	Type of the event.

Definition at line 98 of file nvds_msgapi.h.

typedef void(* nvds_msgapi_send_cb_t)(void *user_ptr, NvDsMsgApiErrorType completion_flag)

Type definition for a "send" callback.

Parameters

[in]	user_ptr	A context pointer passed by async_send. The pointer may refer to any type of information that is useful to the callback.
[in]	completion_flag	The completion code from a send operation.

Definition at line 70 of file nvds_msgapi.h.

typedef void(* nvds_msgapi_subscribe_request_cb_t)(NvDsMsgApiErrorType flag, void *msg, int msg_len, char *topic, void *user_ptr)

Type definition for callback registered during subscribe.

This callback reports any event (success or error) during message consume If success, this callback reports the consumed message, on a subscribed topic

Parameters

[in]	flag	Message Consume Status
[in]	msg	Received message/payload
[in]	msg_len	Length of message/payload
[in]	topic	Topic name where the message was received
[in]	user_ptr	pointer passed during subscribe() for context

Definition at line 87 of file nvds_msgapi.h.

typedef void* NvDsMsgApiHandle

Defines the handle used by messaging API functions.

Definition at line 39 of file nvds_msgapi.h.

Enumeration Type Documentation

enum NvDsMsgApiErrorType

Defines completion codes for operations in the messaging API.

Enumerator
NVDS_MSGAPI_OK
NVDS_MSGAPI_ERR
NVDS_MSGAPI_UNKNOWN_TOPIC

Definition at line 56 of file nvds_msgapi.h.

enum NvDsMsgApiEventType

Defines events associated with connections to remote entities.

Enumerator
NVDS_MSGAPI_EVT_SUCCESS	Specifies that a connection attempt was Successful.
NVDS_MSGAPI_EVT_DISCONNECT	Specifies disconnection of a connection handle.
NVDS_MSGAPI_EVT_SERVICE_DOWN	Specifies that the remote service is down.

Definition at line 44 of file nvds_msgapi.h.

Function Documentation

NvDsMsgApiHandle nvds_msgapi_connect	(	char *	connection_str,
		nvds_msgapi_connect_cb_t	connect_cb,
		char *	config_path
	)

Connects to a remote agent by calling into a protocol adapter.

Parameters

[in]	connection_str	A connection string with format "url;port;topic".
[in]	connect_cb	A callback function for events associated with the connection.
[in]	config_path	A pointer to the pathname of a configuration file passed to the protocol adapter.

Returns

A connection handle.

NvDsMsgApiErrorType nvds_msgapi_connection_signature	(	char *	broker_str,
		char *	cfg,
		char *	output_str,
		int	max_len
	)

Fetch the connection signature by parsing broker_connection string and cfg file.

A connection signature is a unique string used to identify a connection. It is generated by parsing all the connection params provided in broker_str and cfg file

Connection signature can be retreived only if the cfg option share-connection = 1

Parameters

[in]	broker_str	Broker connection string used to create connection
[in]	cfg	Path to config file
[out]	output_str	connection signature
[in]	max_len	max len of output_str

Returns

Valid connection signature if success Empty string("") in case of errors or if share-connection cfg option is not set to 1

NvDsMsgApiErrorType nvds_msgapi_disconnect

(

NvDsMsgApiHandle

h_ptr

)

Terminates a connection.

Parameters

[in]

h_ptr

The connection handle.

Returns

A completion code for the "terminate" operation.

void nvds_msgapi_do_work

(

NvDsMsgApiHandle

h_ptr

)

Calls into the adapter to allow for execution of undnerlying protocol logic.

In this call the adapter is expected to service pending incoming and outgoing messages. It can also perform periodic housekeeping tasks such as sending heartbeats.

This design gives the client control over when protocol logic gets executed. The client must call it periodically, according to the individual adapter's requirements.

Parameters

[in]

h_ptr

A connection handle.

char* nvds_msgapi_get_protocol_name

(

void

)

Gets the name of the protocol used in the adapter.

Returns

A pointer to a string

char* nvds_msgapi_getversion

(

void

)

Gets the version number of the messaging API interface supported by the protocol adapter.

Returns

A pointer to a string that contains version number in "major.minor" format.

NvDsMsgApiErrorType nvds_msgapi_send	(	NvDsMsgApiHandle	h_ptr,
		char *	topic,
		const uint8_t *	payload,
		size_t	nbuf
	)

Sends a message synchronously over a connection.

Parameters

[in]	h_ptr	A connection handle.
[in]	topic	A pointer to a string which specifies the topic to which to send the message.
[in]	payload	A pointer to a byte array containing the message. The message may but need not be a NULL-terminated string.
[in]	nbuf	The number of bytes of data to send, including the terminating NULL if the message is a string.

Returns

A completion code for the send operation.

NvDsMsgApiErrorType nvds_msgapi_send_async	(	NvDsMsgApiHandle	h_ptr,
		char *	topic,
		const uint8_t *	payload,
		size_t	nbuf,
		nvds_msgapi_send_cb_t	send_callback,
		void *	user_ptr
	)

Sends message asynchronously over a connection.

Parameters

[in]	h_ptr	A connection handle.
[in]	topic	A pointer to a string which specifies the topic to which to send the message.
[in]	payload	A pointer to a byte array containing the message. The message may but need not be a NULL-terminated string.
[in]	nbuf	The number of bytes of data to send, including the terminating NULL if the message is a string.
[in]	send_callback	A callback to be invoked when operation completes.
[in]	user_ptr	A context pointer to pass to callback.

Returns

A completion code for the send operation.

NvDsMsgApiErrorType nvds_msgapi_subscribe	(	NvDsMsgApiHandle	h_ptr,
		char **	topics,
		int	num_topics,
		nvds_msgapi_subscribe_request_cb_t	cb,
		void *	user_ctx
	)

Subscribe to a remote entity for receiving messages on a particular topic(s)

Parameters

[in]	h_ptr	Connection handle
[in]	topics	Array of topics to subscribe for messages
[in]	num_topics	num of topics
[in]	cb	A pointer to a callback function for notifying the DS event handler
[in]	user_ctx	user ptr to be passed to callback for context

Returns

Status of the subscribe operation.