AwsIotDefender_Start

Start the defender agent.

AwsIotDefenderError_t AwsIotDefender_Start( AwsIotDefenderStartInfo_t * pStartInfo );

Parameters

[in]

pStartInfo

Pointer of parameters of start function

Periodically, defender agent collects metrics and publish to specific AWS reserved MQTT topic.

Returns

• On success, AWS_IOT_DEFENDER_SUCCESS is returned.
• If pStartInfo is invalid, AWS_IOT_DEFENDER_INVALID_INPUT is returned.
• If memory allocation fails, AWS_IOT_DEFENDER_ERROR_NO_MEMORY is returned.
• If defender is already started, AWS_IOT_DEFENDER_ALREADY_STARTED is returned.

Warning

This function is not thread safe.

Note

No need to manage the memory allocated for AwsIotDefenderCallbackInfo_t. This function save the information internally.

Example:

// assume valid IotMqttConnection_t is created and available.
const IotMqttConnection_t _mqttConnection;
// use AWS thing name as client identifier
const char * pClientIdentifier = "AwsThingName";

void logDefenderCallback( void * param1, AwsIotDefenderCallbackInfo_t * const pCallbackInfo )
{
    if ( pCallbackInfo->eventType == AWS_IOT_DEFENDER_METRICS_ACCEPTED )
    {
        // log info: metrics report accepted by defender service is a happy case
    }
    else
    {
        // log error: pCallbackInfo->eventType
    }

    if ( pCallbackInfo->pPayload != NULL )
    {
        // log info: pCallbackInfo->pPayload with length pCallbackInfo->payloadLength
    }

    if ( pCallbackInfo->pMetricsReport != NULL )
    {
        // log info: pCallbackInfo->pMetricsReport with length pCallbackInfo->metricsReportLength
    }
}

void startDefender()
{
    // define a simple callback function which simply logs
    const AwsIotDefenderCallback_t callback = { .function = logDefenderCallback, .pCallbackContext = NULL };

    // define parameters of AwsIotDefender_Start function
    // Note: This example assumes MQTT connection is already established and metrics library is initialized.
    const AwsIotDefenderStartInfo_t startInfo =
    {
        .pClientIdentifier = pClientIdentifier,
        .clientIdentifierLength = strlen( pClientIdentifier ),
        .mqttConnection = _mqttConnection,
        .callback = callback
    };

    // specify two TCP connections metrics: total count and local port
    AwsIotDefenderError_t error = AwsIotDefender_SetMetrics(AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS,
                                                            AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL |
                                                            AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR );

    if ( error == AWS_IOT_DEFENDER_SUCCESS )
    {
        // set metrics report period to 10 minutes (600 seconds)
        error = AwsIotDefender_SetPeriod( 600 );
    }

    if (error == AWS_IOT_DEFENDER_SUCCESS)
    {
        // start the defender
        error = AwsIotDefender_Start( &startInfo );
    }

    if ( error != AWS_IOT_DEFENDER_SUCCESS )
    {
        const char * pError = AwsIotDefender_strerror( error );
        // log error: pError
    }
}

void stopDefender()
{
    //stop the defender
    AwsIotDefender_Stop();
}