AWS IoT Device Defender  v1.0.0
AWS IoT Device Defender Client Library
defender.h File Reference

Interface for the AWS IoT Device Defender Client Library. More...

#include <stdint.h>
#include "defender_config.h"
#include "defender_config_defaults.h"

Go to the source code of this file.

Macros

#define STRING_LITERAL_LENGTH(literal)   ( ( uint16_t ) ( sizeof( literal ) - 1U ) )
 Helper macro to calculate the length of a string literal.
 
#define DEFENDER_THINGNAME_MAX_LENGTH   128U
 Maximum length of a thing's name as permitted by AWS IoT Core.
 
#define DEFENDER_REPORT_MIN_PERIOD_SECONDS   300
 Minimum period between 2 consecutive defender reports sent by the device. More...
 
#define DEFENDER_API_LENGTH_JSON_PUBLISH(thingNameLength)
 Length of the topic string for publishing a JSON report. More...
 
#define DEFENDER_API_LENGTH_JSON_ACCEPTED(thingNameLength)
 Length of the topic string for getting a JSON report accepted response. More...
 
#define DEFENDER_API_LENGTH_JSON_REJECTED(thingNameLength)
 Length of the topic string for getting a JSON report rejected response. More...
 
#define DEFENDER_API_LENGTH_CBOR_PUBLISH(thingNameLength)
 Length of the topic string for publishing a CBOR report. More...
 
#define DEFENDER_API_LENGTH_CBOR_ACCEPTED(thingNameLength)
 Length of the topic string for getting a CBOR report accepted response. More...
 
#define DEFENDER_API_LENGTH_CBOR_REJECTED(thingNameLength)
 Length of the topic string for getting a CBOR report rejected response. More...
 
#define DEFENDER_API_MAX_LENGTH(thingNameLength)    DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )
 Maximum length of the topic string for any defender operation. More...
 
#define DEFENDER_API_JSON_PUBLISH(thingName)
 Topic string for publishing a JSON report. More...
 
#define DEFENDER_API_JSON_ACCEPTED(thingName)
 Topic string for getting a JSON report accepted response. More...
 
#define DEFENDER_API_JSON_REJECTED(thingName)
 Topic string for getting a JSON report rejected response. More...
 
#define DEFENDER_API_CBOR_PUBLISH(thingName)
 Topic string for publishing a CBOR report. More...
 
#define DEFENDER_API_CBOR_ACCEPTED(thingName)
 Topic string for getting a CBOR report accepted response. More...
 
#define DEFENDER_API_CBOR_REJECTED(thingName)
 Topic string for getting a CBOR report rejected response. More...
 
#define DEFENDER_REPORT_HEADER_KEY   DEFENDER_REPORT_SELECT_KEY( "header", "hed" )
 "header" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_HEADER_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_HEADER_KEY )
 Length of the "header" key in the defender report.
 
#define DEFENDER_REPORT_METRICS_KEY   DEFENDER_REPORT_SELECT_KEY( "metrics", "met" )
 "metrics" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_METRICS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_METRICS_KEY )
 Length of the "metrics" key in the defender report.
 
#define DEFENDER_REPORT_ID_KEY   DEFENDER_REPORT_SELECT_KEY( "report_id", "rid" )
 "report_id" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_ID_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_ID_KEY )
 Length of the "report_id" key in the defender report.
 
#define DEFENDER_REPORT_VERSION_KEY   DEFENDER_REPORT_SELECT_KEY( "version", "v" )
 "version" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_VERSION_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_VERSION_KEY )
 Length of the "version" key in the defender report.
 
#define DEFENDER_REPORT_TCP_CONNECTIONS_KEY   DEFENDER_REPORT_SELECT_KEY( "tcp_connections", "tc" )
 "tcp_connections" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_TCP_CONNECTIONS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_CONNECTIONS_KEY )
 Length of the "tcp_connections" key in the defender report.
 
#define DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY   DEFENDER_REPORT_SELECT_KEY( "established_connections", "ec" )
 "established_connections" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_ESTABLISHED_CONNECTIONS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY )
 Length of the "established_connections" key in the defender report.
 
#define DEFENDER_REPORT_CONNECTIONS_KEY   DEFENDER_REPORT_SELECT_KEY( "connections", "cs" )
 "connections" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_CONNECTIONS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_CONNECTIONS_KEY )
 Length of the "connections" key in the defender report.
 
#define DEFENDER_REPORT_REMOTE_ADDR_KEY   DEFENDER_REPORT_SELECT_KEY( "remote_addr", "rad" )
 "remote_addr" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_REMOTE_ADDR_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_REMOTE_ADDR_KEY )
 Length of the "remote_addr" key in the defender report.
 
#define DEFENDER_REPORT_LOCAL_PORT_KEY   DEFENDER_REPORT_SELECT_KEY( "local_port", "lp" )
 "local_port" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_LOCAL_PORT_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_PORT_KEY )
 Length of the "local_port" key in the defender report.
 
#define DEFENDER_REPORT_LOCAL_INTERFACE_KEY   DEFENDER_REPORT_SELECT_KEY( "local_interface", "li" )
 "local_interface" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_LOCAL_INTERFACE_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_INTERFACE_KEY )
 Length of the "local_interface" key in the defender report.
 
#define DEFENDER_REPORT_TOTAL_KEY   DEFENDER_REPORT_SELECT_KEY( "total", "t" )
 "total" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_TOTAL_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_TOTAL_KEY )
 Length of the "total" key in the defender report.
 
#define DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY   DEFENDER_REPORT_SELECT_KEY( "listening_tcp_ports", "tp" )
 "listening_tcp_ports" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_TCP_LISTENING_PORTS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY )
 Length of the "listening_tcp_ports" key in the defender report.
 
#define DEFENDER_REPORT_PORTS_KEY   DEFENDER_REPORT_SELECT_KEY( "ports", "pts" )
 "ports" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_PORTS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORTS_KEY )
 Length of the "ports" key in the defender report.
 
#define DEFENDER_REPORT_PORT_KEY   DEFENDER_REPORT_SELECT_KEY( "port", "pt" )
 "port" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_PORT_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORT_KEY )
 Length of the "port" key in the defender report.
 
#define DEFENDER_REPORT_INTERFACE_KEY   DEFENDER_REPORT_SELECT_KEY( "interface", "if" )
 "interface" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_INTERFACE_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_INTERFACE_KEY )
 Length of the "interface" key in the defender report.
 
#define DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY   DEFENDER_REPORT_SELECT_KEY( "listening_udp_ports", "up" )
 "listening_udp_ports" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_UDP_LISTENING_PORTS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY )
 Length of the "listening_udp_ports" key in the defender report.
 
#define DEFENDER_REPORT_NETWORK_STATS_KEY   DEFENDER_REPORT_SELECT_KEY( "network_stats", "ns" )
 "network_stats" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_NETWORK_STATS_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_NETWORK_STATS_KEY )
 Length of the "network_stats" key in the defender report.
 
#define DEFENDER_REPORT_BYTES_IN_KEY   DEFENDER_REPORT_SELECT_KEY( "bytes_in", "bi" )
 "bytes_in" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_BYTES_IN_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_IN_KEY )
 Length of the "bytes_in" key in the defender report.
 
#define DEFENDER_REPORT_BYTES_OUT_KEY   DEFENDER_REPORT_SELECT_KEY( "bytes_out", "bo" )
 "bytes_out" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_BYTES_OUT_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_OUT_KEY )
 Length of the "bytes_out" key in the defender report.
 
#define DEFENDER_REPORT_PKTS_IN_KEY   DEFENDER_REPORT_SELECT_KEY( "packets_in", "pi" )
 "packets_in" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_PKTS_IN_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_PKTS_IN_KEY )
 Length of the "packets_in" key in the defender report.
 
#define DEFENDER_REPORT_PKTS_OUT_KEY   DEFENDER_REPORT_SELECT_KEY( "packets_out", "po" )
 "packets_out" key in the defender report.
 
#define DEFENDER_REPORT_LENGTH_PKS_OUT_KEY   STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_PKS_OUT_KEY )
 Length of the "packets_out" key in the defender report.
 

Enumerations

enum  DefenderStatus_t {
  DefenderError = 0, DefenderSuccess, DefenderNoMatch, DefenderBadParameter,
  DefenderBufferTooSmall
}
 Return codes from defender APIs. More...
 
enum  DefenderTopic_t {
  DefenderInvalidTopic = -1, DefenderJsonReportPublish, DefenderJsonReportAccepted, DefenderJsonReportRejected,
  DefenderCborReportPublish, DefenderCborReportAccepted, DefenderCborReportRejected, DefenderMaxTopic
}
 Topic values for subscription requests. More...
 

Functions

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. More...
 
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. More...
 

Detailed Description

Interface for the AWS IoT Device Defender Client Library.

Macro Definition Documentation

◆ DEFENDER_API_LENGTH_JSON_PUBLISH

#define DEFENDER_API_LENGTH_JSON_PUBLISH (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_JSON_FORMAT, \
DEFENDER_API_LENGTH_NULL_SUFFIX )

Length of the topic string for publishing a JSON report.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_JSON_ACCEPTED

#define DEFENDER_API_LENGTH_JSON_ACCEPTED (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_JSON_FORMAT, \
DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )

Length of the topic string for getting a JSON report accepted response.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_JSON_REJECTED

#define DEFENDER_API_LENGTH_JSON_REJECTED (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_JSON_FORMAT, \
DEFENDER_API_LENGTH_REJECTED_SUFFIX )

Length of the topic string for getting a JSON report rejected response.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_PUBLISH

#define DEFENDER_API_LENGTH_CBOR_PUBLISH (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_CBOR_FORMAT, \
DEFENDER_API_LENGTH_NULL_SUFFIX )

Length of the topic string for publishing a CBOR report.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_ACCEPTED

#define DEFENDER_API_LENGTH_CBOR_ACCEPTED (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_CBOR_FORMAT, \
DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )

Length of the topic string for getting a CBOR report accepted response.

Parameters
[in]thingNameLengthLength of the thing name. as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_REJECTED

#define DEFENDER_API_LENGTH_CBOR_REJECTED (   thingNameLength)
Value:
DEFENDER_API_COMMON_LENGTH( thingNameLength, \
DEFENDER_API_LENGTH_CBOR_FORMAT, \
DEFENDER_API_LENGTH_REJECTED_SUFFIX )

Length of the topic string for getting a CBOR report rejected response.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_MAX_LENGTH

#define DEFENDER_API_MAX_LENGTH (   thingNameLength)     DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )

Maximum length of the topic string for any defender operation.

Parameters
[in]thingNameLengthLength of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_PUBLISH

#define DEFENDER_API_JSON_PUBLISH (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_JSON_FORMAT, \
DEFENDER_API_NULL_SUFFIX )

Topic string for publishing a JSON report.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_ACCEPTED

#define DEFENDER_API_JSON_ACCEPTED (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_JSON_FORMAT, \
DEFENDER_API_ACCEPTED_SUFFIX )

Topic string for getting a JSON report accepted response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_REJECTED

#define DEFENDER_API_JSON_REJECTED (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_JSON_FORMAT, \
DEFENDER_API_REJECTED_SUFFIX )

Topic string for getting a JSON report rejected response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_PUBLISH

#define DEFENDER_API_CBOR_PUBLISH (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_CBOR_FORMAT, \
DEFENDER_API_NULL_SUFFIX )

Topic string for publishing a CBOR report.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_ACCEPTED

#define DEFENDER_API_CBOR_ACCEPTED (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_CBOR_FORMAT, \
DEFENDER_API_ACCEPTED_SUFFIX )

Topic string for getting a CBOR report accepted response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_REJECTED

#define DEFENDER_API_CBOR_REJECTED (   thingName)
Value:
DEFENDER_API_COMMON( thingName, \
DEFENDER_API_CBOR_FORMAT, \
DEFENDER_API_REJECTED_SUFFIX )

Topic string for getting a CBOR report rejected response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters
thingNameThe thing name as registered with AWS IoT Core.

Function Documentation

◆ 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]pBufferThe buffer to write the topic string into.
[in]bufferLengthThe length of the buffer.
[in]pThingNameThe device's thingName as registered with AWS IoT.
[in]thingNameLengthThe length of the thing name.
[in]apiThe desired Device Defender API.
[out]pOutLengthThe 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;
status = Defender_GetTopic( &( topicBuffer[ 0 ] ),
TOPIC_BUFFER_LENGTH,
pThingName,
thingNameLength,
&( 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]pTopicThe topic string to check.
[in]topicLengthThe length of the topic string.
[out]pOutApiThe defender topic API value.
[out]ppOutThingNameOptional parameter to output the beginning of the thing name in the topic string. Pass NULL if not needed.
[out]pOutThingNameLengthOptional 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.
// 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 )
{
{
// 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.
}
}
DefenderSuccess
@ DefenderSuccess
Definition: defender.h:52
DefenderJsonReportRejected
@ DefenderJsonReportRejected
Definition: defender.h:67
DefenderJsonReportAccepted
@ DefenderJsonReportAccepted
Definition: defender.h:66
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.
Definition: defender.c:381
DefenderStatus_t
DefenderStatus_t
Return codes from defender APIs.
Definition: defender.h:50
DefenderTopic_t
DefenderTopic_t
Topic values for subscription requests.
Definition: defender.h:63
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.
Definition: defender.c:462