Provisioning callback wrapper. More...

#include <Provision_Callback.h>

Inheritance diagram for Provision_Callback:

Collaboration diagram for Provision_Callback:

Public Member Functions
	Provision_Callback ()=default
	Constructs empty callback, will result in never being called. Internals are simply default constructed as nullptr. More...

	Provision_Callback (Access_Token, function callback, char const provision_device_key, char const provision_device_secret, char const *device_name=nullptr, uint64_t const &timeout_microseconds=0U, Callback_Watchdog::function timeout_callback=nullptr)
	Constructs callback that will be called upon a provision request arrival, where the requested credentials were sent by the cloud and received by the client. More...

	Provision_Callback (Device_Access_Token, function callback, char const provision_device_key, char const provision_device_secret, char const access_token, char const device_name=nullptr, uint64_t const &timeout_microseconds=0U, Callback_Watchdog::function timeout_callback=nullptr)
	@copydetail Provision_Callback(Access_Token, function, char const , char const , char const *, uint64_t const &, Callback_Watchdog::function) More...

	Provision_Callback (Basic_MQTT_Credentials, function callback, char const provision_device_key, char const provision_device_secret, char const username, char const password, char const client_id, char const device_name=nullptr, uint64_t const &timeout_microseconds=0U, Callback_Watchdog::function timeout_callback=nullptr)
	@copydetail Provision_Callback(Access_Token, function, char const , char const , char const *, uint64_t const &, Callback_Watchdog::function) More...

	Provision_Callback (X509_Certificate, function callback, char const provision_device_key, char const provision_device_secret, char const hash, char const device_name=nullptr, uint64_t const &timeout_microseconds=0U, Callback_Watchdog::function timeout_callback=nullptr)
	@copydetail Provision_Callback(Access_Token, function, char const , char const , char const *, uint64_t const &, Callback_Watchdog::function) More...

	~Provision_Callback () override=default

char const *	Get_Device_Key () const
	Gets the provisioning key of the Device Profile, that should be used to create the device under. More...

void	Set_Device_Key (char const *provision_device_key)
	Sets the provisioning key of the Device Profile, that should be used to create the device under. More...

char const *	Get_Device_Secret () const
	Gets the provisioning secret of the Device Profile that should be used to create the device under. More...

void	Set_Device_Secret (char const *provision_device_secret)
	Sets the provisioning secret of the Device Profile that should be used to create the device under. More...

char const *	Get_Device_Name () const
	Gets the name the created device should have on the cloud. More...

void	Set_Device_Name (char const *device_name)
	Sets the name the created device should have on the cloud, pass nullptr or an empty string if a random string generated by the server should be used as the name. More...

char const *	Get_Device_Access_Token () const
	Gets the access token generated by the device, that will be used by the provisioned device. More...

void	Set_Device_Access_Token (char const *access_token)
	Sets the access token generated by the device, that will be used by the provisioned device. More...

char const *	Get_Credentials_Username () const
	Gets the basic MQTT credentials username, that will be used by the provisioned device. More...

void	Set_Credentials_Username (char const *username)
	Sets the basic MQTT credentials username, that will be used by the provisioned device. More...

char const *	Get_Credentials_Password () const
	Gets the basic MQTT credentials password, that will be used by the provisioned device. More...

void	Set_Credentials_Password (char const *password)
	Sets the basic MQTT credentials password, that will be used by the provisioned device. More...

char const *	Get_Credentials_Client_ID () const
	Gets the basic MQTT credentials client ID, that will be used by the provisioned device. More...

void	Set_Credentials_Client_ID (char const *client_id)
	Sets the basic MQTT credentials client ID, that will be used by the provisioned device. More...

char const *	Get_Certificate_Hash () const
	Gets the public X.509 certificate hash, that will be used by the provisioned device. More...

void	Set_Certificate_Hash (char const *hash)
	Sets the public X.509 certificate hash, that will be used by the provisioned device. More...

char const *	Get_Credentials_Type () const
	Gets the string containing the used credentials type that decides which provisioning method is actually used, by the Provision_Callback and therefore decides what response we will receive from the server. More...

Timeoutable_Request &	Get_Request_Timeout ()
	Gets the request timeout callback. More...

Public Member Functions inherited from Callback< void, JsonDocument const & >
	Callback ()=default
	Constructs empty callback, will result in never being called. Internals are simply default constructed as nullptr. More...

	Callback (function callback)
	Constructor. More...

virtual	~Callback ()=default
	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...

void	Call_Callback (argument_types const &... arguments) const
	Calls the callback that was subscribed, when this class instance was initally created. More...

void	Set_Callback (function callback)
	Sets the callback method that will be called upon data arrival with the given data that was received. If nullptr is passed the callback will never be called and instead return with a defaulted instance of the requested return variable. More...

Additional Inherited Members
Public Types inherited from Callback< void, JsonDocument const & >
using	function = std::function< void(argument_types... arguments)>
	Callback signature. More...

Detailed Description

Provisioning callback wrapper.

Note: Contains the needed configuration settings to create the request that should be sent to the server. Documentation about the specific use of Provisioning devices in ThingsBoard can be found here https://thingsboard.io/docs/user-guide/device-provisioning/

Constructor & Destructor Documentation

◆ Provision_Callback() [1/5]

Provision_Callback::Provision_Callback ( )

default

Constructs empty callback, will result in never being called. Internals are simply default constructed as nullptr.

◆ Provision_Callback() [2/5]

Provision_Callback::Provision_Callback	(	Access_Token	,
		function	callback,
		char const *	provision_device_key,
		char const *	provision_device_secret,
		char const *	device_name = `nullptr`,
		uint64_t const &	timeout_microseconds = `0U`,
		Callback_Watchdog::function	timeout_callback = `nullptr`
	)

Constructs callback that will be called upon a provision request arrival, where the requested credentials were sent by the cloud and received by the client.

Note: The requested credentials are one of the possible MQTT provisioning strategies either Access Token, Device Access Token, Basic MQTT Credentials or X509 Certificate. Access Token and Device Access Token are nearly identically, meaning they both consists of a Key and Secret that is used to identify the Device Profile to use, as well as the unqiue name that should be assigned to the device. The only difference is that for Access Token strategy, the Access Token that is used to reconnect as a created device to the cloud is generated by the server and the Device Access Token strategy excepcts this Access Token to be generated by the device instead. The Basic MQTT Credentials strategy, additionally expects a MQTT Client Username, Password and ID and only allows registered users to provision devices for certain Device Profiles. Lastly the most advanced and secure, but also most difficult strategy, X509 Certificate, which expects a hash of a X509 certificate that has to be registered with the server. This allows to uniquely ensure that only registered and authenticated devices can self-register, this is not possible for the other provisioning strategies. See https://thingsboard.io/docs/user-guide/device-provisioning/?mqttprovisioning=without#mqtt-device-apis for more information

Parameters

callback	Callback method that will be called upon provisioning response arrival
provision_device_key	Non owning pointer to the provisioning key of the Device Profile that should be used to create the device under. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
provision_device_secret	Non owning pointer to the provisioning secret of the Device Profile that should be used to create the device under. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
username	Non owning pointer to the basic MQTT credentials username, that will be used by the provisioned device. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
password	Non owning pointer to the basic MQTT credentials password, that will be used by the provisioned device. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
client_id	Non owning pointer to the basic MQTT credentials client ID, that will be used by the provisioned device. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
access_token	Non owning pointer to the access token generated by the device, that will be used by the provisioned device. Alternative to letting the access token be generated by the cloud instead. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
hash	Non owning pointer to the public X.509 certificate hash, that will be used by the provisioned device. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
device_name	Non owning pointer to the name the created device should have on the cloud, pass nullptr or an empty string if a random string generated by the server should be used as the name. Needs to be unique, therefore using the Mac Address of the device is recommended if an actual name is passed. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request
timeout_microseconds	Optional amount of microseconds until a response should have been received from the server, counted from the moment the request is sent. If a response is not received in the timeout time, the timeout callback method will be called to inform the user that the request has failed. If the value is 0 the timer will not be started and therefore never call the timeout callback method, default = 0
timeout_callback	Optional callback method that will be called upon request timeout (did not receive a response in the given timeout time). Can happen if the requested method does not exist on the cloud, or if the connection could not be established. A nullptr means even if a timeout occured the callback is simply ignored and the user not informed, default = nullptr

◆ Provision_Callback() [3/5]

Provision_Callback::Provision_Callback	(	Device_Access_Token	,
		function	callback,
		char const *	provision_device_key,
		char const *	provision_device_secret,
		char const *	access_token,
		char const *	device_name = `nullptr`,
		uint64_t const &	timeout_microseconds = `0U`,
		Callback_Watchdog::function	timeout_callback = `nullptr`
	)

@copydetail Provision_Callback(Access_Token, function, char const *, char const *, char const *, uint64_t const &, Callback_Watchdog::function)

◆ Provision_Callback() [4/5]

Provision_Callback::Provision_Callback	(	Basic_MQTT_Credentials	,
		function	callback,
		char const *	provision_device_key,
		char const *	provision_device_secret,
		char const *	username,
		char const *	password,
		char const *	client_id,
		char const *	device_name = `nullptr`,
		uint64_t const &	timeout_microseconds = `0U`,
		Callback_Watchdog::function	timeout_callback = `nullptr`
	)

@copydetail Provision_Callback(Access_Token, function, char const *, char const *, char const *, uint64_t const &, Callback_Watchdog::function)

◆ Provision_Callback() [5/5]

Provision_Callback::Provision_Callback	(	X509_Certificate	,
		function	callback,
		char const *	provision_device_key,
		char const *	provision_device_secret,
		char const *	hash,
		char const *	device_name = `nullptr`,
		uint64_t const &	timeout_microseconds = `0U`,
		Callback_Watchdog::function	timeout_callback = `nullptr`
	)

@copydetail Provision_Callback(Access_Token, function, char const *, char const *, char const *, uint64_t const &, Callback_Watchdog::function)

◆ ~Provision_Callback()

Provision_Callback::~Provision_Callback ( )

overridedefault

Member Function Documentation

◆ Get_Certificate_Hash()

const char * Provision_Callback::Get_Certificate_Hash ( ) const

Gets the public X.509 certificate hash, that will be used by the provisioned device.

Returns: Non owning pointer to the public X.509 certificate hash. Owned by the user that passed it originally in the constructor or with the Set_Certificate_Hash method

◆ Get_Credentials_Client_ID()

const char * Provision_Callback::Get_Credentials_Client_ID ( ) const

Gets the basic MQTT credentials client ID, that will be used by the provisioned device.

Returns: Non owning pointer to the basic MQTT credentials client ID. Owned by the user that passed it originally in the constructor or with the Set_Credentials_Client_ID method

◆ Get_Credentials_Password()

const char * Provision_Callback::Get_Credentials_Password ( ) const

Gets the basic MQTT credentials password, that will be used by the provisioned device.

Returns: Non owning pointer to the basic MQTT credentials password Owned by the user that passed it originally in the constructor or with the Set_Credentials_Password method

◆ Get_Credentials_Type()

const char * Provision_Callback::Get_Credentials_Type ( ) const

Gets the string containing the used credentials type that decides which provisioning method is actually used, by the Provision_Callback and therefore decides what response we will receive from the server.

Returns: Owning pointer to th string containing the used credentials type. Simply points to a compile time string constant saved into static memory

◆ Get_Credentials_Username()

const char * Provision_Callback::Get_Credentials_Username ( ) const

Gets the basic MQTT credentials username, that will be used by the provisioned device.

Returns: Non owning pointer to the basic MQTT credentials username. Owned by the user that passed it originally in the constructor or with the Set_Credentials_Username method

◆ Get_Device_Access_Token()

const char * Provision_Callback::Get_Device_Access_Token ( ) const

Gets the access token generated by the device, that will be used by the provisioned device.

Note: Alternative to letting the access token be generated by the cloud instead

Returns: Non owning pointer to the access token generated by the device. Owned by the user that passed it originally in the constructor or with the Set_Device_Access_Token method

◆ Get_Device_Key()

const char * Provision_Callback::Get_Device_Key ( ) const

Gets the provisioning key of the Device Profile, that should be used to create the device under.

Returns: Non owning pointer to the provisioning key of the Device Profile. Owned by the user that passed it originally in the constructor or with the Set_Device_Key method

◆ Get_Device_Name()

const char * Provision_Callback::Get_Device_Name ( ) const

Gets the name the created device should have on the cloud.

Note: If the value is a nullptr or an empty string, a random string will be generated by the server that will be used as the name instead

Returns: Non owning pointer to the name the created device should have on the cloud. Owned by the user that passed it originally in the constructor or with the Set_Device_Name method

◆ Get_Device_Secret()

const char * Provision_Callback::Get_Device_Secret ( ) const

Gets the provisioning secret of the Device Profile that should be used to create the device under.

Returns: Non owning pointer to the provisioning secret of the Device Profile. Owned by the user that passed it originally in the constructor or with the Set_Device_Secret method

◆ Get_Request_Timeout()

Timeoutable_Request & Provision_Callback::Get_Request_Timeout ( )

Gets the request timeout callback.

Note: Will be called when no response to the request was received in the expected amount of time, causing the internal watchdog to time out. To achieve this behaviour the internal timer can be started and stopped, and simply calls the subscribed callback if the timer is not stopped before it times out

Returns: Request timeout callback

◆ Set_Certificate_Hash()

void Provision_Callback::Set_Certificate_Hash ( char const * hash )

Sets the public X.509 certificate hash, that will be used by the provisioned device.

Parameters

hash	Non owning pointer to the public X.509 certificate hash. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Credentials_Client_ID()

void Provision_Callback::Set_Credentials_Client_ID ( char const * client_id )

Sets the basic MQTT credentials client ID, that will be used by the provisioned device.

Parameters

client_id Non owning pointer to the basic MQTT credentials client ID. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Credentials_Password()

void Provision_Callback::Set_Credentials_Password ( char const * password )

Sets the basic MQTT credentials password, that will be used by the provisioned device.

Parameters

password Non owning pointer to the basic MQTT credentials password. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Credentials_Username()

void Provision_Callback::Set_Credentials_Username ( char const * username )

Sets the basic MQTT credentials username, that will be used by the provisioned device.

Parameters

username Non owning pointer to the basic MQTT credentials username. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Device_Access_Token()

void Provision_Callback::Set_Device_Access_Token ( char const * access_token )

Sets the access token generated by the device, that will be used by the provisioned device.

Note: Alternative to letting the access token be generated by the cloud instead

Parameters

access_token Non owning pointer to the access token generated by the device. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Device_Key()

void Provision_Callback::Set_Device_Key ( char const * provision_device_key )

Sets the provisioning key of the Device Profile, that should be used to create the device under.

Parameters

provision_device_key Non owning pointer to the provisioning key of the Device Profile. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Device_Name()

void Provision_Callback::Set_Device_Name ( char const * device_name )

Sets the name the created device should have on the cloud, pass nullptr or an empty string if a random string generated by the server should be used as the name.

Note: Needs to be unique, therefore using the Mac Address of the device is recommended if an actual name is passed.

Parameters

device_name Non owning pointer to the name the created device should have on the cloud. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

◆ Set_Device_Secret()

void Provision_Callback::Set_Device_Secret ( char const * provision_device_secret )

Sets the provisioning secret of the Device Profile that should be used to create the device under.

Parameters

provision_device_secret Non owning pointer to the provisioning secret of the Device Profile. Additionally it has to be kept alive by the user until the Provision_Request method has been called with this instance as the argument, because that method copies the data into the outgoing MQTT buffer to create the provision request

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

src/Provision_Callback.h
src/Provision_Callback.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Provision_Callback() [1/5]

◆ Provision_Callback() [2/5]

◆ Provision_Callback() [3/5]

◆ Provision_Callback() [4/5]

◆ Provision_Callback() [5/5]

◆ ~Provision_Callback()

Member Function Documentation

◆ Get_Certificate_Hash()

◆ Get_Credentials_Client_ID()

◆ Get_Credentials_Password()

◆ Get_Credentials_Type()

◆ Get_Credentials_Username()

◆ Get_Device_Access_Token()

◆ Get_Device_Key()

◆ Get_Device_Name()

◆ Get_Device_Secret()

◆ Get_Request_Timeout()

◆ Set_Certificate_Hash()

◆ Set_Credentials_Client_ID()

◆ Set_Credentials_Password()

◆ Set_Credentials_Username()

◆ Set_Device_Access_Token()

◆ Set_Device_Key()

◆ Set_Device_Name()

◆ Set_Device_Secret()