AWS IoT Fleet Provisioning  v1.0.0
AWS IoT Fleet Provisioning Library
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. More...
 
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. More...
 
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(). More...
 
static TopicSuffix_t parseTopicSuffix (const char *pRemainingTopic, uint16_t remainingLength)
 Match the suffix from the remaining topic string and return the corresponding suffix. More...
 
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. More...
 
static FleetProvisioningTopic_t parseCreateCertificateFromCsrTopic (const char *pTopic, uint16_t topicLength)
 Match a topic string with the CreateCertificateFromCsr topics. More...
 
static FleetProvisioningTopic_t parseCreateKeysAndCertificateTopic (const char *pTopic, uint16_t topicLength)
 Match a topic string with the CreateKeysAndCertificate topics. More...
 
static FleetProvisioningTopic_t parseRegisterThingTopic (const char *pTopic, uint16_t topicLength)
 Match a topic string with the RegisterThing topics. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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]templateNameLengththe length of the template name registered with AWS IoT.
[in]formatThe RegisterThing API format to use.
[in]topicThe 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]pBufferCursorPointer to the remaining buffer.
[in]fragmentThe piece of the topic string to write.
[in]lengthThe 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]pTopicBufferThe buffer to write the topic string into.
[in]formatThe desired RegisterThing format.
[in]topicThe desired RegisterThing topic.
[in]pTemplateNameThe name of the provisioning template configured with AWS IoT.
[in]templateNameLengthThe length of pTemplateName.
[in]pOutLengthThe 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]pRemainingTopicThe remaining portion of the topic.
[in]remainingLengthThe 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]pRemainingTopicThe remaining portion of the topic.
[in]remainingLengthThe 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]pTopicThe topic string to match.
[in]topicLengthThe 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]pTopicThe topic string to match.
[in]topicLengthThe 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]pTopicThe topic string to match.
[in]topicLengthThe 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]pBufferCursorPointer to the remaining portion of the buffer.
[in,out]pRemainingLengthThe remaining length of the buffer.
[in]matchStringThe string to match against.
[in]matchLengthThe 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]pTopicCursorPointer to the remaining topic string.
[in,out]pRemainingLengthPointer 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]pTopicBufferThe buffer to write the topic string into.
[in]bufferLengthThe length of pTopicBuffer.
[in]formatThe desired RegisterThing format.
[in]topicThe desired RegisterThing topic.
[in]pTemplateNameThe name of the provisioning template configured with AWS IoT.
[in]templateNameLengthThe length of the provisioning template name.
[out]pOutLengthThe 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;
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]pTopicThe topic string to check.
[in]topicLengthThe length of the topic string.
[out]pOutApiThe 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.
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.
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.
}
}
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.
Definition: fleet_provisioning.c:729
FleetProvisioningStatus_t
FleetProvisioningStatus_t
Return codes for Fleet Provisioning APIs.
Definition: fleet_provisioning.h:56
FleetProvisioningTopic_t
FleetProvisioningTopic_t
Fleet Provisioning topic values.
Definition: fleet_provisioning.h:69
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.
Definition: fleet_provisioning.c:638