Initializing Your C Application

You must initialize your application to get the agent library handle to use for future agent API calls.

You must have a valid agent library handle to use when you register telemetry (numeric and location data), alarms, and actions (methods), publish events and attributes (string data), and perform file transfers.

Optionally, you can register a callback function to receive the agent log messages generated using the IOT_LOG macro. You can also use the IOT_LOG macro to generate your own application log messages. Your log handler receives all the logs in your log handler, which can help you debug your application.

The application and the thing definition that corresponds to your client application must exist in Device Cloud.

To enable auto-registration, the thing definition must be associated with the application. Otherwise, you must create the thing manually on the Management Portal before you run your application.

For more information about creating applications and thing definitions, see the following:

Device Cloud Management Portal User's Guide: Thing Definitions
Device Cloud Management Portal User's Guide: Applications

Retrieve the agent library handle.
For the id parameter, specify a name for the application. S

For the flags parameter, specify 0u.

For the cfg_path parameter, specify the path to the configuration directory or NULL to use the default, which is /etc/iot.
```
iot_t *agentLib;
agentLib = iot_initialize("myApp", NULL, 0);
```
The agent uses the value you specify for the id parameter to find the associated connection configuration file, which is id.cfg. When you create the file, ensure that the file name matches this format.
Optionally, register a callback to receive log messages.
1. Write the log handler function.
  Use the following function signature:
```
void log_handler( iot_log_level_t log_level, const iot_log_source_t *log_source, const char *message, void *user_data )
```
2. Register the callback function.
```
iot_log_callback_set(agentLib, &log_handler, NULL );
```
Connect the application to Device Cloud.
For the handle parameter ,specify the value returned from the iot_initialize function.

Specify zero for the max_time_out parameter.
```
result = iot_connect(agentLib, 0);
```
When the application runs, it blocks until the agent successfully connects to Device Cloud at least once or until the request times out, based on the value of the max_time_out.

You are now ready to implement other elements of the thing definition.

Example: Basic Application Initialization

static iot_t *initialize( void )
{
    iot_status_t result = IOT_STATUS_FAILURE;

    iot_t  *agentLib = iot_initialize("appName", NULL, 0u);
    
    if (agentLib) 
        {
        result = iot_connect(agentLib, NULL);

        if (result == IOT_STATUS_SUCCESS) {
            /* Continue with application initialization
               Register actions and metrics as required.
            */
        }
        else  {
            fprintf( stderr, "Error connecting to IoT service: %s\n", iot_error( result ) );
        }
    }
    else
    {
        fprintf( stderr, "Failed to retrieve agent handle\n" );
    }

    return agentLib;
}

When your application terminates, call the iot_disconnect and iot_terminate functions to disconnect your application from the agent and free the associated memory.