/*
 * Copyright (c) 2018-2020 NVIDIA Corporation.  All rights reserved.
 *
 * NVIDIA Corporation and its licensors retain all intellectual property
 * and proprietary rights in and to this software, related documentation
 * and any modifications thereto.  Any use, reproduction, disclosure or
 * distribution of this software and related documentation without an express
 * license agreement from NVIDIA Corporation is strictly prohibited.
 *
 */

/**
 * @file
 * <b>DeepStream Messaging API </b>
 *
 * @b Description: This file defines the DeepStream API for exchanging
 * messages with remote entities and services.
 */

/**
 * @defgroup  ee_nvmessaging_group  Messaging API
 *
 * Defines an API for exchanging messages with remote entities and services.
 *
 * @ingroup NvDsMsgApi
 * @{
 */

#ifndef __NVDS_MSGAPI_H__
#define __NVDS_MSGAPI_H__

#ifdef __cplusplus
extern "C"
{
#endif
#include <stdint.h>

/** Defines the handle used by messaging API functions. */
typedef void *NvDsMsgApiHandle;

/**
 * Defines events associated with connections to remote entities.
 */
typedef enum {
  /** Specifies that a connection attempt was Successful*/
  NVDS_MSGAPI_EVT_SUCCESS,
  /** Specifies disconnection of a connection handle. */
  NVDS_MSGAPI_EVT_DISCONNECT,
  /** Specifies that the remote service is down. */
  NVDS_MSGAPI_EVT_SERVICE_DOWN
} NvDsMsgApiEventType;

/**
 * Defines completion codes for operations in the messaging API.
 */
typedef enum {
NVDS_MSGAPI_OK,
NVDS_MSGAPI_ERR,
NVDS_MSGAPI_UNKNOWN_TOPIC
} NvDsMsgApiErrorType;

/**
  * Type definition for a "send" callback.
  *
  * @param[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.
  * @param[in] completion_flag  The completion code from a send operation.
  */
typedef void (*nvds_msgapi_send_cb_t)(void *user_ptr,  NvDsMsgApiErrorType completion_flag);

/**
 * @brief 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
 *
 * @param[in]  flag                  Message Consume Status
 * @param[in]  msg                   Received message/payload
 * @param[in]  msg_len               Length of message/payload
 * @param[in]  topic                 Topic name where the message was received
 * @param[in]  user_ptr              pointer passed during subscribe() for context
 */

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

/**
 * @brief  Type definition for a "handle" callback.
 *
 * This callback reports any event (success or error)
 * during a call to nvds_msgapi_connect().
 *
 * @param[in] h_ptr     A handle for the event.
 * @param[in] ds_evt    Type of the event.
 */
typedef void (*nvds_msgapi_connect_cb_t)(NvDsMsgApiHandle h_ptr, NvDsMsgApiEventType ds_evt);

/**
 * Connects to a remote agent by calling into a protocol adapter.
 *
 * @param[in] connection_str    A connection string with format
 *                              `"url;port;topic"`.
 * @param[in] connect_cb        A callback function for events associated with
 *                              the connection.
 * @param[in] config_path       A pointer to the pathname of a configuration
 *                              file passed to the protocol adapter.
 * @return A connection handle.
 */
NvDsMsgApiHandle nvds_msgapi_connect(char *connection_str, nvds_msgapi_connect_cb_t connect_cb, char *config_path);

/**
 * Sends a message synchronously over a connection.
 *
 * @param[in] h_ptr    A connection handle.
 * @param[in] topic    A pointer to a string which specifies the topic
 *                     to which to send the message.
 * @param[in] payload  A pointer to a byte array containing the message. The
 *                     message may but need not be a NULL-terminated string.
 * @param[in] nbuf     The number of bytes of data to send, including the
 *                     terminating NULL if the message is a string.
 *
 * @return  A completion code for the send operation.
 */
NvDsMsgApiErrorType nvds_msgapi_send(NvDsMsgApiHandle h_ptr, char *topic, const uint8_t *payload, size_t nbuf);

/**
 * Sends message asynchronously over a connection.
 *
 * @param[in] h_ptr         A connection handle.
 * @param[in] topic         A pointer to a string which specifies the topic
 *                          to which to send the message.
 * @param[in] payload       A pointer to a byte array containing the message.
 *                          The message may but need not be a NULL-terminated
 *                          string.
 * @param[in] nbuf          The number of bytes of data to send, including the
 *                          terminating NULL if the message is a string.
 * @param[in] send_callback A callback to be invoked when operation completes.
 * @param[in] user_ptr      A context pointer to pass to callback.
 *
 * @return  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);

/**
  * Subscribe to a remote entity for receiving messages on a particular topic(s)
 *
  * @param[in] h_ptr                     Connection handle
  * @param[in] topics                    Array of topics to subscribe for messages
  * @param[in] num_topics                num of topics
  * @param[in] cb                        A pointer to a callback function for notifying the DS event handler
  * @param[in] user_ctx                  user ptr to be passed to callback for context
  *
  * @return Status of the subscribe operation.
 */
NvDsMsgApiErrorType nvds_msgapi_subscribe (NvDsMsgApiHandle h_ptr, char ** topics, int num_topics, nvds_msgapi_subscribe_request_cb_t  cb, void *user_ctx);

/**
 * 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.
 *
 * @param[in] h_ptr     A connection handle.
 */
void nvds_msgapi_do_work(NvDsMsgApiHandle h_ptr);

/**
 * Terminates a connection.
 *
 * @param[in] h_ptr    The connection handle.
 *
 * @return  A completion code for the "terminate" operation.
 */
NvDsMsgApiErrorType nvds_msgapi_disconnect(NvDsMsgApiHandle h_ptr);

/**
 * 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_getversion(void);

/**
 * Gets the name of the protocol used in the adapter.
 *
 * @return  A pointer to a string
 */
char *nvds_msgapi_get_protocol_name(void);

/**
 * 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
 *
 * @param[in] broker_str  Broker connection string used to create connection
 * @param[in] cfg         Path to config file
 * @param[out] output_str connection signature
 * @param[in] max_len     max len of output_str
 *
 * @return                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_connection_signature(char *broker_str, char *cfg, char *output_str, int max_len);

#ifdef __cplusplus
}
#endif

#endif

/** @} */