defender.c File Reference

Implementation of the AWS IoT Device Defender Client Library. More...

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

Functions
static uint16_t	getTopicLength (uint16_t thingNameLength, DefenderTopic_t api)
	Get the topic length for a given defender API.
static void	writeFormatAndSuffix (char *pBuffer, DefenderTopic_t api)
	Write the format and suffix part for the given defender API to the buffer.
static DefenderStatus_t	matchPrefix (const char *pRemainingTopic, uint16_t remainingTopicLength)
	Check if the unparsed topic so far starts with the defender prefix.
static DefenderStatus_t	extractThingNameLength (const char *pRemainingTopic, uint16_t remainingTopicLength, uint16_t *pOutThingNameLength)
	Extract the length of thing name in the unparsed topic so far.
static DefenderStatus_t	matchBridge (const char *pRemainingTopic, uint16_t remainingTopicLength)
	Check if the unparsed topic so far starts with the defender bridge.
static DefenderStatus_t	matchApi (const char *pRemainingTopic, uint16_t remainingTopicLength, DefenderTopic_t *pOutApi)
	Check if the unparsed topic so far exactly matches one of the defender api topics.
DefenderStatus_t	Defender_GetTopic (char *pBuffer, uint16_t bufferLength, const char *pThingName, uint16_t thingNameLength, DefenderTopic_t api, uint16_t *pOutLength)
	Populate the topic string for a Device Defender operation.
DefenderStatus_t	Defender_MatchTopic (const char *pTopic, uint16_t topicLength, DefenderTopic_t *pOutApi, const char **ppOutThingName, uint16_t *pOutThingNameLength)
	Check if the given topic is one of the Device Defender topics.

Detailed Description

Implementation of the AWS IoT Device Defender Client Library.

Function Documentation

getTopicLength()

static uint16_t getTopicLength ( uint16_t  thingNameLength, DefenderTopic_t  api  )

static

Get the topic length for a given defender API.

Parameters

[in]	thingNameLength	The length of the thing name as registered with AWS IoT.
[in]	api	The defender API value.

Returns

The topic length for the given defender API.

writeFormatAndSuffix()

static void writeFormatAndSuffix ( char *  pBuffer, DefenderTopic_t  api  )

static

Write the format and suffix part for the given defender API to the buffer.

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

Parameters

[in]	pBuffer	The buffer to write the format and suffix part into.
[in]	api	The defender API value.

Note

This function assumes that the buffer is large enough to hold the value.

matchPrefix()

static DefenderStatus_t matchPrefix ( const char *  pRemainingTopic, uint16_t  remainingTopicLength  )

static

Check if the unparsed topic so far starts with the defender prefix.

The defender prefix is "$aws/things/".

Parameters

[in]	pRemainingTopic	Starting location of the unparsed topic.
[in]	remainingTopicLength	The length of the unparsed topic.

Returns

DefenderSuccess if the unparsed topic starts with the defender prefix; DefenderNoMatch otherwise.

extractThingNameLength()

static DefenderStatus_t extractThingNameLength ( const char *  pRemainingTopic, uint16_t  remainingTopicLength, uint16_t *  pOutThingNameLength  )

static

Extract the length of thing name in the unparsed topic so far.

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

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

• $aws/things/THING_NAME/defender/metrics/json
• $aws/things/THING_NAME The second topic is not a valid defender topic and the matching will fail when we try to match the bridge part.

Parameters

[in]	pRemainingTopic	Starting location of the unparsed topic.
[in]	remainingTopicLength	The length of the unparsed topic.
[out]	pOutThingNameLength	The length of the thing name in the topic string.

Returns

DefenderSuccess if a valid thing name is found; DefenderNoMatch otherwise.

matchBridge()

static DefenderStatus_t matchBridge ( const char *  pRemainingTopic, uint16_t  remainingTopicLength  )

static

Check if the unparsed topic so far starts with the defender bridge.

The defender bridge is "/defender/metrics/".

Parameters

[in]	pRemainingTopic	Starting location of the unparsed topic.
[in]	remainingTopicLength	The length of the unparsed topic.

Returns

DefenderSuccess if the unparsed topic starts with the defender bridge; DefenderNoMatch otherwise.

matchApi()

static DefenderStatus_t matchApi ( const char *  pRemainingTopic, uint16_t  remainingTopicLength, DefenderTopic_t *  pOutApi  )

static

Check if the unparsed topic so far exactly matches one of the defender api topics.

The defender api topics are the following:

• json
• json/accepted
• json/rejected
• cbor
• cbor/accepted
• cbor/rejected

The function also outputs the defender API value if a match is found.

Parameters

[in]	pRemainingTopic	Starting location of the unparsed topic.
[in]	remainingTopicLength	The length of the unparsed topic.
[out]	pOutApi	The defender topic API value.

Returns

DefenderSuccess if the unparsed topic exactly matches one of the defender api topics; DefenderNoMatch otherwise.

Defender_GetTopic()

DefenderStatus_t Defender_GetTopic	(	char *	pBuffer,
		uint16_t	bufferLength,
		const char *	pThingName,
		uint16_t	thingNameLength,
		DefenderTopic_t	api,
		uint16_t *	pOutLength
	)

Populate the topic string for a Device Defender operation.

Parameters

[in]	pBuffer	The buffer to write the topic string into.
[in]	bufferLength	The length of the buffer.
[in]	pThingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thing name.
[in]	api	The desired Device Defender API.
[out]	pOutLength	The length of the topic string written to the buffer.

Returns

DefenderSuccess if the topic string is written to the buffer; DefenderBadParameter if invalid parameters are passed; DefenderBufferTooSmall if the buffer cannot hold the full topic string.

Example

// The following example shows how to use the Defender_GetTopic API to
// generate a topic string for getting a JSON report accepted response.
 
#define TOPIC_BUFFER_LENGTH      ( 256U )
 
// Every device should have a unique thing name registered with AWS IoT Core.
// This example assumes that the device has a unique serial number which is
// registered as the thing name with AWS IoT Core.
const char * pThingName = GetDeviceSerialNumber();
uint16_t thingNameLength = ( uint16_t )strlen( pThingname );
char topicBuffer[ TOPIC_BUFFER_LENGTH ] = { 0 };
uint16_t topicLength = 0;
DefenderStatus_t status = DefenderSuccess;
 
status = Defender_GetTopic( &( topicBuffer[ 0 ] ),
                            TOPIC_BUFFER_LENGTH,
                            pThingName,
                            thingNameLength,
                            DefenderJsonReportAccepted,
                            &( topicLength ) );
 
if( status == DefenderSuccess )
{
     // The buffer topicBuffer contains the topic string of length
     // topicLength for getting a JSON report accepted response. Subscribe
     // to this topic using an MQTT client of your choice.
}

Defender_MatchTopic()

DefenderStatus_t Defender_MatchTopic	(	const char *	pTopic,
		uint16_t	topicLength,
		DefenderTopic_t *	pOutApi,
		const char **	ppOutThingName,
		uint16_t *	pOutThingNameLength
	)

Check if the given topic is one of the Device Defender topics.

The function outputs which API the topic is for. It also optionally outputs the starting location and length of the thing name in the given topic.

Parameters

[in]	pTopic	The topic string to check.
[in]	topicLength	The length of the topic string.
[out]	pOutApi	The defender topic API value.
[out]	ppOutThingName	Optional parameter to output the beginning of the thing name in the topic string. Pass NULL if not needed.
[out]	pOutThingNameLength	Optional parameter to output the length of the thing name in the topic string. Pass NULL if not needed.

Returns

DefenderSuccess if the topic is one of the defender topics; DefenderBadParameter if invalid parameters are passed; DefenderNoMatch if the topic is NOT one of the defender topics (parameter pOutApi gets DefenderInvalidTopic).

Example

// The following example shows how to use the Defender_MatchTopic API to
// check if an incoming MQTT publish message is a Device Defender message.
 
DefenderTopic_t api;
DefenderStatus_t status = DefenderSuccess;
 
// 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 client used. We pass the last two argument as NULL as we are not
// interested in the thing name in the topic string.
status = Defender_MatchTopic( pTopic,
                              topicLength,
                              &( api ),
                              NULL,
                              NULL );
 
if( status == DefenderSuccess )
{
     if( api == DefenderJsonReportAccepted )
     {
         // The published JSON report was accepted by the AWS IoT Device
         // Defender service. You can parse the response using your choice
         // of JSON parser and ensure that the report Id is same as was sent
         // in the defender report.
     }
     else if( api == DefenderJsonReportRejected )
     {
         // The published JSON report was rejected by the AWS IoT Device
         // Defender service.
     }
     else
     {
         // Unexpected response.
     }
}