Messaging API

group ee_nvmessaging_group

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

Typedefs

typedef void *NvDsMsgApiHandle

Defines the handle used by messaging API functions.

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.

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

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.

Enums

enum NvDsMsgApiEventType

Defines events associated with connections to remote entities.

Values:

enumerator NVDS_MSGAPI_EVT_SUCCESS

Specifies that a connection attempt was Successful.

enumerator NVDS_MSGAPI_EVT_DISCONNECT

Specifies disconnection of a connection handle.

enumerator NVDS_MSGAPI_EVT_SERVICE_DOWN

Specifies that the remote service is down.

enum NvDsMsgApiErrorType

Defines completion codes for operations in the messaging API.

Values:

enumerator NVDS_MSGAPI_OK
enumerator NVDS_MSGAPI_ERR
enumerator NVDS_MSGAPI_UNKNOWN_TOPIC

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.

Return

A connection handle.

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.

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

Sends a message synchronously over a connection.

Return

A completion code for the send operation.

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.

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.

Return

A completion code for the send operation.

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.

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)

Return

Status of the subscribe operation.

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

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.

NvDsMsgApiErrorType nvds_msgapi_disconnect(NvDsMsgApiHandle h_ptr)

Terminates a connection.

Return

A completion code for the “terminate” operation.

Parameters
  • [in] h_ptr: The connection handle.

char *nvds_msgapi_getversion(void)

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

Return

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

char *nvds_msgapi_get_protocol_name(void)

Gets the name of the protocol used in the adapter.

Return

A pointer to a string

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

Return

Valid connection signature if success Empty string(“”) in case of errors or if share-connection cfg option is not set to 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