fleet_provisioning.c File Reference

Implementation of the AWS IoT Fleet Provisioning Library. More...

#include <assert.h>
#include <stddef.h>
#include <string.h>
#include "fleet_provisioning.h"

Enumerations
enum	TopicSuffix_t { TopicPublish , TopicAccepted , TopicRejected , TopicInvalidSuffix }
	Identifier for which of the topic suffixes for a given format and Fleet Provisioning MQTT API.
enum	TopicFormatSuffix_t {   TopicJsonPublish , TopicJsonAccepted , TopicJsonRejected , TopicCborPublish ,   TopicCborAccepted , TopicCborRejected , TopicInvalidFormatSuffix }
	Identifier for which of the topics in each Fleet Provisioning MQTT API.

Functions
static uint16_t	getRegisterThingTopicLength (uint16_t templateNameLength, FleetProvisioningFormat_t format, FleetProvisioningApiTopics_t topic)
	Get the topic length for a given RegisterThing topic.
static void	writeTopicFragmentAndAdvance (char **pBufferCursor, const char *fragment, uint16_t length)
	Write the given piece of the topic to the remaining buffer and advance the remaining buffer pointer.
static FleetProvisioningStatus_t	GetRegisterThingTopicCheckParams (const char *pTopicBuffer, FleetProvisioningFormat_t format, FleetProvisioningApiTopics_t topic, const char *pTemplateName, uint16_t templateNameLength, const uint16_t *pOutLength)
	Check the parameters for FleetProvisioning_GetRegisterThingTopic().
static TopicSuffix_t	parseTopicSuffix (const char *pRemainingTopic, uint16_t remainingLength)
	Match the suffix from the remaining topic string and return the corresponding suffix.
static TopicFormatSuffix_t	parseTopicFormatSuffix (const char *pRemainingTopic, uint16_t remainingLength)
	Match the format and suffix from the remaining topic string and return the corresponding format and suffix.
static FleetProvisioningTopic_t	parseCreateCertificateFromCsrTopic (const char *pTopic, uint16_t topicLength)
	Match a topic string with the CreateCertificateFromCsr topics.
static FleetProvisioningTopic_t	parseCreateKeysAndCertificateTopic (const char *pTopic, uint16_t topicLength)
	Match a topic string with the CreateKeysAndCertificate topics.
static FleetProvisioningTopic_t	parseRegisterThingTopic (const char *pTopic, uint16_t topicLength)
	Match a topic string with the RegisterThing topics.
static FleetProvisioningStatus_t	consumeIfMatch (const char **pBufferCursor, uint16_t *pRemainingLength, const char *matchString, uint16_t matchLength)
	Check if the remaining buffer starts with a specified string. If so, moves the remaining buffer pointer past the matched section and updates the remaining length.
static FleetProvisioningStatus_t	consumeTemplateName (const char **pTopicCursor, uint16_t *pRemainingLength)
	Move the remaining topic pointer past the template name in the unparsed topic so far, and update the remaining topic length.
FleetProvisioningStatus_t	FleetProvisioning_GetRegisterThingTopic (char *pTopicBuffer, uint16_t bufferLength, FleetProvisioningFormat_t format, FleetProvisioningApiTopics_t topic, const char *pTemplateName, uint16_t templateNameLength, uint16_t *pOutLength)
	Populate the topic string for a Fleet Provisioning RegisterThing topic.
FleetProvisioningStatus_t	FleetProvisioning_MatchTopic (const char *pTopic, uint16_t topicLength, FleetProvisioningTopic_t *pOutApi)
	Check if the given topic is one of the Fleet Provisioning topics.

Detailed Description

Implementation of the AWS IoT Fleet Provisioning Library.

Function Documentation

getRegisterThingTopicLength()

static uint16_t getRegisterThingTopicLength ( uint16_t  templateNameLength, FleetProvisioningFormat_t  format, FleetProvisioningApiTopics_t  topic  )

static

Get the topic length for a given RegisterThing topic.

Parameters

[in]	templateNameLength	the length of the template name registered with AWS IoT.
[in]	format	The RegisterThing API format to use.
[in]	topic	The RegisterThing API format to use.

Returns

the template length for the given RegisterThing topic.

writeTopicFragmentAndAdvance()

static void writeTopicFragmentAndAdvance ( char **  pBufferCursor, const char *  fragment, uint16_t  length  )

static

Write the given piece of the topic to the remaining buffer and advance the remaining buffer pointer.

The caller is responsible for assuring that there is enough space remaining in the buffer to write the given string.

Parameters

[in,out]	pBufferCursor	Pointer to the remaining buffer.
[in]	fragment	The piece of the topic string to write.
[in]	length	The length of fragment.

GetRegisterThingTopicCheckParams()

static FleetProvisioningStatus_t GetRegisterThingTopicCheckParams ( const char *  pTopicBuffer, FleetProvisioningFormat_t  format, FleetProvisioningApiTopics_t  topic, const char *  pTemplateName, uint16_t  templateNameLength, const uint16_t *  pOutLength  )

static

Check the parameters for FleetProvisioning_GetRegisterThingTopic().

Parameters

[in]	pTopicBuffer	The buffer to write the topic string into.
[in]	format	The desired RegisterThing format.
[in]	topic	The desired RegisterThing topic.
[in]	pTemplateName	The name of the provisioning template configured with AWS IoT.
[in]	templateNameLength	The length of pTemplateName.
[in]	pOutLength	The length of the topic string written to the buffer.

Returns

FleetProvisioningSuccess if no errors are found with the parameters; FleetProvisioningBadParameter otherwise.

parseTopicSuffix()

static TopicSuffix_t parseTopicSuffix ( const char *  pRemainingTopic, uint16_t  remainingLength  )

static

Match the suffix from the remaining topic string and return the corresponding suffix.

Suffix: empty, /accepted, or /rejected.

Parameters

[in]	pRemainingTopic	The remaining portion of the topic.
[in]	remainingLength	The remaining length of the topic.

Returns

The matching TopicSuffix_t.

parseTopicFormatSuffix()

static TopicFormatSuffix_t parseTopicFormatSuffix ( const char *  pRemainingTopic, uint16_t  remainingLength  )

static

Match the format and suffix from the remaining topic string and return the corresponding format and suffix.

Format: json or cbor. Suffix: empty, /accepted, or /rejected.

Parameters

[in]	pRemainingTopic	The remaining portion of the topic.
[in]	remainingLength	The remaining length of the topic.

Returns

The matching TopicFormatSuffix_t.

parseCreateCertificateFromCsrTopic()

static FleetProvisioningTopic_t parseCreateCertificateFromCsrTopic ( const char *  pTopic, uint16_t  topicLength  )

static

Match a topic string with the CreateCertificateFromCsr topics.

Parameters

[in]	pTopic	The topic string to match.
[in]	topicLength	The length of the topic string.

Returns

The matching FleetProvisioningTopic_t if the topic string is a Fleet Provisioning CreateCertificateFromCsr topic, else FleetProvisioningInvalidTopic.

parseCreateKeysAndCertificateTopic()

static FleetProvisioningTopic_t parseCreateKeysAndCertificateTopic ( const char *  pTopic, uint16_t  topicLength  )

static

Match a topic string with the CreateKeysAndCertificate topics.

Parameters

[in]	pTopic	The topic string to match.
[in]	topicLength	The length of the topic string.

Returns

The matching FleetProvisioningTopic_t if the topic string is a Fleet Provisioning CreateKeysAndCertificate topic, else FleetProvisioningInvalidTopic.

parseRegisterThingTopic()

static FleetProvisioningTopic_t parseRegisterThingTopic ( const char *  pTopic, uint16_t  topicLength  )

static

Match a topic string with the RegisterThing topics.

Parameters

[in]	pTopic	The topic string to match.
[in]	topicLength	The length of the topic string.

Returns

The matching FleetProvisioningTopic_t if the topic string is a Fleet Provisioning RegisterThing topic, else FleetProvisioningInvalidTopic.

consumeIfMatch()

static FleetProvisioningStatus_t consumeIfMatch ( const char **  pBufferCursor, uint16_t *  pRemainingLength, const char *  matchString, uint16_t  matchLength  )

static

Check if the remaining buffer starts with a specified string. If so, moves the remaining buffer pointer past the matched section and updates the remaining length.

Parameters

[in,out]	pBufferCursor	Pointer to the remaining portion of the buffer.
[in,out]	pRemainingLength	The remaining length of the buffer.
[in]	matchString	The string to match against.
[in]	matchLength	The length of matchString.

Returns

FleetProvisioningSuccess if the string matches and is skipped over; FleetProvisioningNoMatch otherwise.

consumeTemplateName()

static FleetProvisioningStatus_t consumeTemplateName ( const char **  pTopicCursor, uint16_t *  pRemainingLength  )

static

Move the remaining topic pointer past the template name in the unparsed topic so far, and update the remaining topic length.

The end of thing name is marked by a forward slash. A zero length thing name is not valid.

This function extracts the same template name from the following topic strings:

• $aws/provisioning-templates/TEMPLATE_NAME/provision/json/accepted
• $aws/provisioning-templates/TEMPLATE_NAME The second topic is not a valid Fleet Provisioning topic and the matching will fail when we try to match the bridge part.

Parameters

[in,out]	pTopicCursor	Pointer to the remaining topic string.
[in,out]	pRemainingLength	Pointer to the length of the remaining topic string.

Returns

FleetProvisioningSuccess if a valid template name is skipped over; FleetProvisioningNoMatch otherwise.

FleetProvisioning_GetRegisterThingTopic()

FleetProvisioningStatus_t FleetProvisioning_GetRegisterThingTopic	(	char *	pTopicBuffer,
		uint16_t	bufferLength,
		FleetProvisioningFormat_t	format,
		FleetProvisioningApiTopics_t	topic,
		const char *	pTemplateName,
		uint16_t	templateNameLength,
		uint16_t *	pOutLength
	)

Populate the topic string for a Fleet Provisioning RegisterThing topic.

Parameters

[out]	pTopicBuffer	The buffer to write the topic string into.
[in]	bufferLength	The length of pTopicBuffer.
[in]	format	The desired RegisterThing format.
[in]	topic	The desired RegisterThing topic.
[in]	pTemplateName	The name of the provisioning template configured with AWS IoT.
[in]	templateNameLength	The length of the provisioning template name.
[out]	pOutLength	The length of the topic string written to the buffer.

Returns

FleetProvisioningSuccess if the topic string is written to the buffer; FleetProvisioningBadParameter if invalid parameters, such as non-RegisterThing topics, are passed; FleetProvisioningBufferTooSmall if the buffer cannot hold the full topic string.

example

// The following example shows how to use the FleetProvisioning_GetRegisterThingTopic
// function to generate a topic string for getting an accepted response for
// a JSON RegisterThing request.
 
#define TOPIC_BUFFER_LENGTH      ( 256u )
 
// In order to use the AWS IoT Fleet Provisioning service, there must be a
// provisioning template registered with AWS IoT Core.
// This example assumes that the template is named "template_name".
#define TEMPLATE_NAME "template_name"
#define TEMPLATE_NAME_LENGTH ( ( uint16_t ) ( sizeof( TEMPLATE_NAME ) - 1U )
char pTopicbuffer[ TOPIC_BUFFER_LENGTH ] = { 0 };
uint16_t topicLength = 0;
FleetProvisioningStatus_t status = FleetProvisioningError;
 
status = FleetProvisioning_GetRegisterThingTopic( pTopicBuffer,
                                                  TOPIC_BUFFER_LENGTH,
                                                  FleetProvisioningJson,
                                                  FleetProvisioningAccepted,
                                                  TEMPLATE_NAME,
                                                  TEMPLATE_NAME_LENGTH,
                                                  &( topiclength ) );
 
if( status == FleetProvisioningSuccess )
{
     // The buffer pTopicBuffer contains the topic string of length
     // topicLength for getting a response for an accepted JSON RegisterThing
     // request. Subscribe to this topic using an MQTT library of your choice.
}

FleetProvisioning_MatchTopic()

FleetProvisioningStatus_t FleetProvisioning_MatchTopic	(	const char *	pTopic,
		uint16_t	topicLength,
		FleetProvisioningTopic_t *	pOutApi
	)

Check if the given topic is one of the Fleet Provisioning topics.

The function outputs which API the topic is for.

Parameters

[in]	pTopic	The topic string to check.
[in]	topicLength	The length of the topic string.
[out]	pOutApi	The Fleet Provisioning topic API value.

Returns

FleetProvisioningSuccess if the topic is one of the Fleet Provisioning topics; FleetProvisioningBadParameter if invalid parameters are passed; FleetProvisioningNoMatch if the topic is NOT one of the Fleet Provisioning topics (parameter pOutApi gets FleetProvisioningInvalidTopic).

Example

// The following example shows how to use the FleetProvisioning_MatchTopic
// function to check if an incoming MQTT publish message is a Fleet
// Provisioning message.
 
FleetProvisioningTopic_t api;
FleetProvisioningStatus_t status = FleetProvisioningError;
 
// pTopic and topicLength are the topic string and length of the topic on
// which the publish message is received. These are usually provided by the
// MQTT library used.
status = FleetProvisioning_MatchTopic( pTopic
                                       topicLength,
                                       &( api ) );
 
if( status == FleetProvisioningSuccess )
{
     if( api == FleetProvJsonCreateCertFromCsrAccepted )
     {
         // The published JSON request was accepted and completed by the AWS
         // IoT Fleet Provisioning service. You can parse the response using
         // your choice of JSON parser get the certificate, ID, and ownership
         // token.
     }
     else if( api == FleetProvJsonCreateCertFromCsrRejected )
     {
         // The published JSON request was rejected by the AWS IoT Fleet
         // Provisioning service.
     }
     else
     {
         // Unexpected response.
     }
}