/**
@mainpage Overview
@brief C SDK providing secured connections to the AWS IoT platform. <br><br>

The AWS IoT Device SDK for C is a collection of [C99](https://en.wikipedia.org/wiki/C99) source files that allow applications to securely connect to the AWS IoT platform. It includes an [MQTT 3.1.1 client](../mqtt/index.html), as well as libraries specific to AWS IoT, such as [Thing Shadows](../shadow/index.html). It is distributed in source form and may be build into firmware along with application code.

Design goals of this SDK include:
- <b>Configurability</b> <br>
  Each library in this SDK has <i>Configuration Settings</i> that allow it to be tailored to systems ranging from microcontrollers to desktop computers.
- <b>Portability</b> <br>
  All system calls go through a lightweight portability layer to allow this SDK to be easily ported to many systems. See [platform layer](../platform/index.html) for a list of functions that must be ported.
*/

/**
@page global_config Global Configuration

Configuration settings should be set using compiler arguments (like `-D` in gcc) or through a config file. The config file for this SDK must be called `iot_config.h` and be present in the include path.

The following pages describe configuration settings that affect multiple components of this SDK.
- @subpage global_library_config <br>
  Settings that affect all libraries.
- @subpage global_demos_config <br>
  Settings that affect all demos.
- @subpage global_tests_config <br>
  Settings that affect all tests.
*/

/**
@globalconfigpage{library,Library,libraries}

@section IOT_LOG_LEVEL_GLOBAL
@brief Set a default log level.

Any libraries that do not define a log level will use this setting. If a both a global log level and a library log level are defined, the library log level overrides the global one.

@configpossible One of the @ref logging_constants_levels.<br>
@configdefault @ref IOT_LOG_NONE

@section IOT_STATIC_MEMORY_ONLY
@brief Set this to `1` to disable the usage of dynamic memory allocation ([malloc](http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html) and [free](http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html)) throughout the libraries in this SDK.

When dynamic memory allocation is disabled, all of the memory allocation functions used in the libraries must be re-implemented. See each library's <i>Configuration/Memory allocation</i> section for a list of functions that must be re-implemented for that library.

@configpossible `0` (dynamic memory allocation enabled) or `1` (dynamic memory allocation disabled)<br>
@configrecommended `0`<br>
@configdefault `0`

@attention This settings has no effect on system calls or third-party libraries; it may also have no effect on [platform layer] (@ref platform) implementations.

@section Iot_DefaultMalloc IotDefault_Malloc and Iot_DefaultFree
@brief Set these to the names of the default memory allocation functions to use across all libraries.

<b>No default value is provided for this setting.</b> If these functions are not set, libraries will fail to build.

All libraries allow each memory allocation function to be overridden with a custom implementation. If a function does not have a custom implementation set, then these functions will be used.

@configpossible Functions that match the signatures of [malloc](http://pubs.opengroup.org/onlinepubs/9699919799/functions/malloc.html) and [free](http://pubs.opengroup.org/onlinepubs/9699919799/functions/free.html).

@section Iot_DefaultAssert
@brief Set this to the name of the default assert function to use across all libraries.

<b>No default value is provided for this setting.</b> If this function is not set, libraries will fail to build when asserts are enabled.

All libraries allow the assert function to be overridden with a custom implementation. If a custom implementation assert function is not set, then this functions will be used.

@configpossible A function that matches the signature of [assert](http://pubs.opengroup.org/onlinepubs/9699919799/functions/assert.html).
*/

/**
@globalconfigpage{demos,Demo,demos}

@section IOT_DEMO_SECURED_CONNECTION
@brief Determines if the demos default to a TLS-secured connection with the remote host.

When this setting is `true`, all demo applications will use a TLS-secured connection by default. The default credentials for connections are @ref IOT_DEMO_ROOT_CA, @ref IOT_DEMO_CLIENT_CERT, and @ref IOT_DEMO_PRIVATE_KEY. Any connection with AWS IoT must be secured.

In demo applications, the default secured connection setting can be overridden using the command line options `-s` or `-u`. Neither of these command line options have an argument, and only one of the two should be used at a time. Passing `-s` will cause the demo application to use a secured connection, and passing `-u` will cause the demo application to use an unsecured connection.

@configpossible `true` (secured connection) or `false` (unsecured connection) <br>
@configrecommended When using the demo applications with AWS IoT, connections must be secured. Therefore, the recommended value for this setting is `true`. <br>
@configdefault If this setting is undefined <i>and</i> neither `-s` nor `-u` are passed as command line options, then any connections will be unsecured.

@section IOT_DEMO_SERVER
@brief The default remote host to use in the demos.

All demo applications will open TCP connections to this host. When using the demos with AWS IoT, this should be set to the AWS account's custom IoT endpoint. This custom endpoint can be found under the <i>Settings</i> tab of the AWS IoT console. It has a format of `ABCDEFG1234567.iot.us-east-2.amazonaws.com`, where `ABCDEFG1234567` is a placeholder subdomain and `us-east-2` is the region.

In demo applications, the default server can be overridden using the command line option `-h`. The command line option will override this setting.

<b>No default value is provided for this setting.</b> If this setting is undefined and no command line option `-h` is given to the demo application, the demo will fail.

@configpossible Any string representing a hostname, such as
- `ABCDEFG1234567.iot.us-east-2.amazonaws.com`
- `192.168.1.1`
- `localhost`

@section IOT_DEMO_PORT
@brief The default remote port to use in the demos.

All demo applications will open TCP connections to @ref IOT_DEMO_SERVER on this port. When using the demos with AWS IoT, this should be set to either `443` or `8883`.  Port `8883` provides a standard encrypted MQTT connection, while port `443` provides a secured MQTT connection using [ALPN](https://aws.amazon.com/about-aws/whats-new/2018/02/aws-iot-core-now-supports-mqtt-connections-with-certificate-based-client-authentication-on-port-443/).

In demo applications, the default server port may be overridden using the command line option `-p`. The command line option will override this setting.

<b>No default value is provided for this setting.</b> If this setting is undefined and no command line option `-p` is given to the demo application, the demo will fail.

@configpossible Any positive integer below `65536`.<br>
@configrecommended When using the demo applications with AWS IoT, port `443` is recommended.

@section IOT_DEMO_ROOT_CA
@brief The path to the default trusted server root certificate to use in the demos.

A trusted server root certificate only needs to be set for [secured connections](@ref IOT_DEMO_SECURED_CONNECTION). See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html) for more information about AWS IoT server certificates.

In demo applications, the default trusted server root certificate can be overridden using the command line option `-r`. The command line option will override this setting.

<b>No default value is provided for this setting.</b> If this setting is undefined and no command line option `-r` is given to a demo application using a secured connection, the demo will fail.

@configpossible Any string representing a filesystem path to a PEM-encoded trusted server root certificate. <br>
@configrecommended When using the demo applications with AWS IoT, one of [these root certificates](https://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html#server-authentication) should be used.

@section IOT_DEMO_CLIENT_CERT
@brief The path to the default client certificate to use in the demos.

A client certificate only needs to be set for [secured connections](@ref IOT_DEMO_SECURED_CONNECTION). See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html) for a tutorial on how to set up client certificates with AWS IoT.

In demo applications, the default client certificate can be overridden with the command line option `-c`. The command line option will override this setting.

<b>No default value is provided for this setting.</b> If this setting is undefined and no command line option `-c` is given to a demo application using a secured connection, the demo will fail.

@configpossible Any string representing a filesystem path to a PEM-encoded client certificate.

@section IOT_DEMO_PRIVATE_KEY
@brief The path to the default client certificate private key to use in the demos.

A client certificate private key only needs to be set for [secured connections](@ref IOT_DEMO_SECURED_CONNECTION). This private key must match the [client certificate](@ref IOT_DEMO_CLIENT_CERT).

In demo applications, the default client certificate private key can be overridden with the command line option `-k`. The command line option will override this setting.

<b>No default value is provided for this setting.</b> If this setting is undefined and no command line option `-k` is given to a demo application using a secured connection, the demo will fail.

@configpossible Any string representing a filesystem path to a PEM-encoded private key matching the [client certificate](@ref IOT_DEMO_CLIENT_CERT).

@section IOT_DEMO_IDENTIFIER
@brief A string that identifies this client to the cloud.

Depending on the demo, this identifier is used for the client identifier (general MQTT demos) or the AWS IoT Thing Name (demos specific to AWS IoT).

In demo applications, the default identifier can be overridden with the command line option `-i`. The command line option will override this setting.

In the [general MQTT demos](@ref mqtt_demo), this identifier becomes the MQTT client identifier. No two clients may use the same identifier simultaneously. MQTT client identifiers may be subject to certain constraints; for example, servers are not obligated to accept client identifiers longer than 23 characters or client identifiers containing non-alphanumeric characters. If this setting is undefined and no command line option is provided at runtime, the MQTT demos may generate a unique client identifier for use.

In the demos specific to AWS IoT, this identifier becomes the Thing Name, which is used to manage devices in AWS IoT. See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/iot-thing-management.html) for more information. <b>No default value is provided for Thing Names.</b> For demos requiring a Thing Name (such as Shadow) this setting must be defined (or a command line option `-i` given to the demo application); otherwise, the demo will fail.

@configpossible Strings representing MQTT client identifiers or Thing Names.
*/

/**
@globalconfigpage{tests,Test,tests}

@section IOT_BUILD_TESTS
@brief Specifies that the tests are being built.

This setting modifies the behavior of the libraries under test. For example, it may expose internal variables or functions for testing.

<span style="color:red;font-weight:bold">`IOT_BUILD_TESTS` will be automatically configured during build and generally does not need to be defined.</span>

@configpossible `1` (tests are being built) or `0` (tests are not being built) <br>
@configrecommended This must always be set to `1` if building any test files. Otherwise, it should be set to `0`. <br>
@configdefault `0`

@section IOT_TEST_SECURED_CONNECTION
@brief Determines if the tests use a TLS-secured connection with the remote host.

When this setting is `true`, all test applications will use a TLS-secured connection. The credentials for connections are @ref IOT_TEST_ROOT_CA, @ref IOT_TEST_CLIENT_CERT, and @ref IOT_TEST_PRIVATE_KEY. Any connection with AWS IoT must be secured.

@configpossible `true` (secured connection) or `false` (unsecured connection) <br>
@configrecommended When testing against AWS IoT, connections must be secured. Therefore, the recommended value for this setting is `true`. <br>
@configdefault `true`

@section IOT_TEST_SERVER
@brief The remote host to use in the tests.

Tests using the network will open TCP connections to this host. When testing against AWS IoT, this should be set to the AWS account's custom IoT endpoint. This custom endpoint can be found under the <i>Settings</i> tab of the AWS IoT console. It has a format of `ABCDEFG1234567.iot.us-east-2.amazonaws.com`, where `ABCDEFG1234567` is a placeholder subdomain and `us-east-2` is the region.

<b>No default value is provided for this setting.</b> If this setting is undefined, the tests will fail to compile.

@configpossible Any string representing a hostname, such as
- `ABCDEFG1234567.iot.us-east-2.amazonaws.com`
- `192.168.1.1`
- `localhost`

@section IOT_TEST_PORT
@brief The remote port to use in the tests.

Tests using the network will open TCP connections to @ref IOT_TEST_SERVER on this port. When testing against AWS IoT, this should be set to either `443` or `8883`.  Port `8883` provides a standard encrypted MQTT connection, while port `443` provides a secured MQTT connection using [ALPN](https://aws.amazon.com/about-aws/whats-new/2018/02/aws-iot-core-now-supports-mqtt-connections-with-certificate-based-client-authentication-on-port-443/).

<b>No default value is provided for this setting.</b> If this setting is undefined, the tests will fail to compile.

@configpossible Any positive integer below `65536`.<br>
@configrecommended When testing against AWS IoT, port `443` is recommended.

@section IOT_TEST_ROOT_CA
@brief The path to the trusted server root certificate to use in the tests.

A trusted server root certificate only needs to be set for [secured connections](@ref IOT_TEST_SECURED_CONNECTION). See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html) for more information about AWS IoT server certificates.

<b>No default value is provided for this setting.</b> If this setting is undefined, tests requiring secured connections will fail to compile.

@configpossible Any string representing a filesystem path to a PEM-encoded trusted server root certificate. <br>
@configrecommended When testing against AWS IoT, one of [these root certificates](https://docs.aws.amazon.com/iot/latest/developerguide/managing-device-certs.html#server-authentication) should be used.

@section IOT_TEST_CLIENT_CERT
@brief The path to the client certificate to use in the tests.

A client certificate only needs to be set for [secured connections](@ref IOT_TEST_SECURED_CONNECTION). See [this page](https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html) for a tutorial on how to set up client certificates with AWS IoT.

<b>No default value is provided for this setting.</b> If this setting is undefined, tests requiring secured connections will fail to compile.

@configpossible Any string representing a filesystem path to a PEM-encoded client certificate.

@section IOT_TEST_PRIVATE_KEY
@brief The path to the client certificate private key to use in the tests.

A client certificate private key only needs to be set for [secured connections](@ref IOT_TEST_SECURED_CONNECTION). This private key must match the [client certificate](@ref IOT_TEST_CLIENT_CERT).

<b>No default value is provided for this setting.</b> If this setting is undefined, tests requiring secured connections will fail to compile.

@configpossible Any string representing a filesystem path to a PEM-encoded private key matching the [client certificate](@ref IOT_TEST_CLIENT_CERT).
*/
