Base functionality required by all API implementation. More...

#include <IAPI_Implementation.h>

Inheritance diagram for IAPI_Implementation:

Public Member Functions
virtual	~IAPI_Implementation ()
	Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor. More...

virtual API_Process_Type	Get_Process_Type () const =0
	Returns the way the server response should be processed. More...

virtual void	Process_Response (char const topic, uint8_t payload, uint32_t length)=0
	Process callback that will be called upon response arrival. More...

virtual void	Process_Json_Response (char const *topic, JsonDocument const &data)=0
	Process callback that will be called upon response arrival. More...

virtual bool	Is_Response_Topic_Matching (char const *topic) const =0
	Compares received response topic and the topic this api implementation handles responses on, messages from all other topics are ignored and only messages from topics that match are handled. More...

virtual bool	Unsubscribe ()=0
	Unsubcribes all callbacks, to clear up any ongoing subscriptions and stop receiving information over the previously subscribed topic. More...

virtual bool	Resubscribe_Permanent_Subscriptions ()=0
	Forwards the call to let the API clear up any ongoing single-event subscriptions (Provision, Attribute Request, RPC Request) and simply resubscribes the topic for all permanent subscriptions (RPC, Shared Attribute Update) More...

virtual void	loop ()=0
	Internal loop method to update inernal timers for API calls that can timeout. More...

virtual void	Initialize ()=0
	Method that allows to construct internal objects, after the required callback member methods have been set already. More...

virtual void	Set_Client_Callbacks (Callback< void, IAPI_Implementation & >::function subscribe_api_callback, Callback< bool, char const const, JsonDocument const & >::function send_json_callback, Callback< bool, char const const, char const const >::function send_json_string_callback, Callback< bool, char const const >::function subscribe_topic_callback, Callback< bool, char const const >::function unsubscribe_topic_callback, Callback< uint16_t >::function get_receive_size_callback, Callback< uint16_t >::function get_send_size_callback, Callback< bool, uint16_t, uint16_t >::function set_buffer_size_callback, Callback< size_t >::function get_request_id_callback)=0
	Sets the underlying callbacks that are required for the different API Implementation to communicate with the cloud. More...

Detailed Description

Base functionality required by all API implementation.

Constructor & Destructor Documentation

◆ ~IAPI_Implementation()

virtual IAPI_Implementation::~IAPI_Implementation ( )

inlinevirtual

Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor.

Note: Deleting a base class destructor that does not have a virtual destructor is undefined behaviour, because the derived class destructor originally instantiated with new is never called. This can cause potential memory leaks, because derived classes can not clean up their internal members as expected and instead simply leak them

Member Function Documentation

◆ Get_Process_Type()

virtual API_Process_Type IAPI_Implementation::Get_Process_Type ( ) const

pure virtual

Returns the way the server response should be processed.

Note: Response can only ever be process using one option, because the response is either unserialized data, which we need to process as such (OTA Firmware Update) or actually JSON which needs to be serialized (everything else)

Returns: How the API implementation processes the server response

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Initialize()

virtual void IAPI_Implementation::Initialize ( )

pure virtual

Method that allows to construct internal objects, after the required callback member methods have been set already.

Note: Required for API Implementations that subscribe further API calls, because immediately calling in the constructor can lead, to attempted subscriptions before the client callbacks are actually subscribed. Therefore we have to call methods like that, in this method instead, because it ensures all member methods are instantiated already

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Is_Response_Topic_Matching()

virtual bool IAPI_Implementation::Is_Response_Topic_Matching ( char const * topic ) const

pure virtual

Compares received response topic and the topic this api implementation handles responses on, messages from all other topics are ignored and only messages from topics that match are handled.

Note: For the comparsion we either compare the full expected string with null termination, if the response topic does not include additional parameters, example being shared attribute update (v1/devices/me/attributes). Or we compare only before the null termination for topics that include additional parameters in the response. Like for example the original request id in the response of the attribute request (v1/devices/me/attributes/response/1)

Parameters

topic Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself

Returns: Whether the received response topic matches the topic this api implementation handles responses on

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ loop()

virtual void IAPI_Implementation::loop ( )

pure virtual

Internal loop method to update inernal timers for API calls that can timeout.

Note: Only exists on boards that can not use the ESP Timer, because that one uses the FreeRTOS timer in the background instead and therefore does not require calling a loop method

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Process_Json_Response()

virtual void IAPI_Implementation::Process_Json_Response	(	char const *	topic,
		JsonDocument const &	data
	)

pure virtual

Process callback that will be called upon response arrival.

Note: Responsible for handling the alredy serialized payload. If the response only wants to be handled before serialization Process_Response should contain the implementation instead and Get_Process_Type should return API_Process_Type::RAW

Parameters

topic	Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself
data	Payload sent by the server over our given topic, that contains our key value pairs

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Process_Response()

virtual void IAPI_Implementation::Process_Response	(	char const *	topic,
		uint8_t *	payload,
		uint32_t	length
	)

pure virtual

Process callback that will be called upon response arrival.

Note: Responsible for handling the payload before serialization. If the response only wants to be handled after serialization Process_Json_Response should contain the implementation instead and Get_Process_Type should return API_Process_Type::JSON

Parameters

topic	Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself
payload	Non owning pointer to the payload that was sent over the cloud and received over the given topic. Does not need to be kept alive, because the byte payload is only used for the scope of the method itself
length	Total length of the received payload

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Resubscribe_Permanent_Subscriptions()

virtual bool IAPI_Implementation::Resubscribe_Permanent_Subscriptions ( )

pure virtual

Forwards the call to let the API clear up any ongoing single-event subscriptions (Provision, Attribute Request, RPC Request) and simply resubscribes the topic for all permanent subscriptions (RPC, Shared Attribute Update)

Returns: Whether resubscribing was successfull or not

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Set_Client_Callbacks()

virtual void IAPI_Implementation::Set_Client_Callbacks	(	Callback< void, IAPI_Implementation & >::function	subscribe_api_callback,
		Callback< bool, char const *const, JsonDocument const & >::function	send_json_callback,
		Callback< bool, char const const, char const const >::function	send_json_string_callback,
		Callback< bool, char const *const >::function	subscribe_topic_callback,
		Callback< bool, char const *const >::function	unsubscribe_topic_callback,
		Callback< uint16_t >::function	get_receive_size_callback,
		Callback< uint16_t >::function	get_send_size_callback,
		Callback< bool, uint16_t, uint16_t >::function	set_buffer_size_callback,
		Callback< size_t * >::function	get_request_id_callback
	)

pure virtual

Sets the underlying callbacks that are required for the different API Implementation to communicate with the cloud.

Note: Directly set by the used ThingsBoard client to its internal methods, therefore calling again and overriding as a user ist not recommended, unless you know what you are doing

Parameters

subscribe_api_callback	Method which allows to subscribe additional API endpoints, points to Subscribe_API_Implementation per default
send_json_callback	Method which allows to send arbitrary JSON payload, points to Send_Json per default
send_json_string_callback	Method which allows to send arbitrary JSON string payload, points to Send_Json_String per default
subscribe_topic_callback	Method which allows to subscribe to arbitrary topics, points to m_client.subscribe per default
unsubscribe_topic_callback	Method which allows to unsubscribe from arbitrary topics, points to m_client.unsubscribe per default
get_receive_size_callback	Method which allows to get the current underlying receive size of the buffer, points to m_client.get_receive_buffer_size per default
get_send_size_callback	Method which allows to get the current underlying send size of the buffer, points to m_client.get_send_buffer_size per default
set_buffer_size_callback	Method which allows to set the current underlying size of the buffer, points to m_client.set_buffer_size per default
get_request_id_callback	Method which allows to get the current request id as a mutable reference, points to getRequestID per default

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

◆ Unsubscribe()

virtual bool IAPI_Implementation::Unsubscribe ( )

pure virtual

Unsubcribes all callbacks, to clear up any ongoing subscriptions and stop receiving information over the previously subscribed topic.

Returns: Whether unsubscribing all the previously subscribed callbacks and from the previously subscribed topic, was successful or not

Implemented in Attribute_Request< MaxSubscriptions, MaxAttributes, Logger >, Attribute_Request< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >, Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >, OTA_Firmware_Update< Logger >, Provision< Logger >, Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >, Shared_Attribute_Update< MaxSubscriptions, MaxAttributes, Logger >, and Shared_Attribute_Update< 1U, OTA_ATTRIBUTE_KEYS_AMOUNT, DefaultLogger >.

The documentation for this class was generated from the following file:

src/IAPI_Implementation.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IAPI_Implementation()

Member Function Documentation

◆ Get_Process_Type()

◆ Initialize()

◆ Is_Response_Topic_Matching()

◆ loop()

◆ Process_Json_Response()

◆ Process_Response()

◆ Resubscribe_Permanent_Subscriptions()

◆ Set_Client_Callbacks()

◆ Unsubscribe()