Show Contents

# Start Cloud Connector

Using the Cloud Connector API, you can connect or disconnect from Remote Manager at any time. Manage the connection to Remote Manager using the following functions:

Function | Description
--- | ---
cc_init_error_t init_cloud_connection(const char *config_file) | Initializes Cloud Connector with the parameters in the provided configuration file. If it is NULL, default configuration file location is used, /etc/cc.conf.
cc_start_error_t start_cloud_connection(void) | Opens the Cloud Connector connection.
cc_status_t get_cloud_connection_status(void) | Returns the Cloud Connector connection status.
cc_stop_error_t stop_cloud_connection(void) | Closes the Cloud Connector connection.

Make sure your device is registered within your Remote Manager account before attempting to connect. For more information on registering your device in Remote Manager see Add your device to Remote Manager.

    Managing Device Cloud connection

    int main (void)
    {
        cc_init_error_t init_error;
        cc_start_error_t start_error;
        cc_stop_error_t stop_error;

        [...]

        init_error = init_cloud_connection(config_file);
        if (init_error != CC_INIT_ERROR_NONE) {
            log_error("Cannot initialize cloud connection, error %d", init_error);
            return EXIT_FAILURE;
        }

        [...]

        start_error = start_cloud_connection();
        if (start_error != CC_START_ERROR_NONE) {
            log_error("Cannot start cloud connection, error %d", start_error);
            return EXIT_FAILURE;
        }

        [...]

        stop_error = stop_cloud_connection();

        [...]

        return EXIT_SUCCESS;
    }

## Initialize connection

The initialization process configures Cloud Connector with the values in the provided configuration file.

    cc_init_error_t init_cloud_connection(const char *config_file)

By default, if config_file is NULL, /etc/cc.conf is used.

In this configuration file:

- General settings give descriptive information about your device in Remote Manager. You can access this information through the Remote Manager web interface and use it to easily identify your devices.
- Connection settings establish the parameters for the connection with Remote Manager, such as enable reconnection or the time to wait before attempting to reconnect.
- Service settings allow you to enable file system service, map virtual directories, or identify the path to download the firmware file.
- System monitor settings manage the status of this feature and the parameters to monitor.
- Logging settings allow you to establish the logging level.

Note For more information about the configuration settings, review the configuration file cc.conf.

The function init_cloud_connection() returns a cc_init_error_t error code indicating if any failure occurs during the initialization process. The following subset of cc_init_error_t errors can be returned by init_cloud_connection():

Error | Description
--- | ---
CC_INIT_ERROR_NONE | Operation completed successfully. No error found.
CC_INIT_CCAPI_START_ERROR_INSUFFICIENT_MEMORY | Cloud Connector encountered problems allocating memory to initialize the connection. Your system may have run out of resources.
CC_INIT_CCAPI_START_ERROR_THREAD_FAILED | Error while trying to create thread. Your system has insufficient resources to create another thread, or it reached the limit on the number of threads.
CC_INIT_CCAPI_START_ERROR_LOCK_FAILED | Cloud Connector encountered problems using synchronization mechanisms. Your system may have run out of resources.
CC_INIT_CCAPI_START_ERROR_ALREADY_STARTED | Cloud Connector is already initialized.
CC_INIT_ERROR_PARSE_CONFIGURATION | The provided configuration file is invalid.
CC_INIT_ERROR_ADD_VIRTUAL_DIRECTORY | Cloud Connector cannot add a virtual directory because the target directory does not exist, you do not have permissions, or it is already mapped.

## Start connection

Once Cloud Connector is properly initialized, you can connect to Remote Manager using function start_cloud_connection().

    cc_start_error_t start_cloud_connection(void)

This function establishes the connection with the cloud based on the settings configured during the initialization.

The following subset of cc_start_error_t errors can be returned by start_cloud_connection():

Error | Description
--- | ---
CC_START_ERROR_NONE | Operation completed successfully. No error found.
CC_START_CCAPI_TCP_START_ERROR_ALREADY_STARTED | Cloud Connector is already started.
CC_START_CCAPI_TCP_START_ERROR_INSUFFICIENT_MEMORY | Cloud Connector encountered problems allocating memory to start the connection. Your system may have run out of resources.
CC_START_CCAPI_TCP_START_ERROR_INIT | Cloud Connector cannot initialize the connection with Remote Manager.
CC_START_ERROR_NOT_INITIALIZE | Cloud Connector is not initialized before starting.
CC_START_ERROR_SYSTEM_MONITOR | Cloud Connector cannot start System Monitor feature.

## Get connection status

You can get the current status of the connection with Remote Manager using get_cloud_connection_status() function.

    cc_status_t get_cloud_connection_status(void)

The following values of cc_status_t may be returned by this function:

Status | Description
--- | ---
CC_STATUS_DISCONNECTED | Device is not connected to Remote Manager.
CC_STATUS_CONNECTING | Device is trying to connect to Remote Manager.
CC_STATUS_CONNECTED | Device is connected to Remote Manager.

Note If the connection is lost and reconnection is enabled in the configuration file (enable_reconnect setting), the device automatically tries to connect to Remote Manager once the configured reconnect timeout elapses (reconnect_time setting).

## Stop connection

You can manually stop Cloud Connector, free allocated memory, and stop all active Cloud Connector threads with function stop_cloud_connection().

    cc_stop_error_t stop_cloud_connection(void)

Function stop_cloud_connection() returns a cc_stop_error_t error code indicating if any failure occurs during the stop process. The following subset of cc_stop_error_t errors can be returned by this function:

Error | Description
--- | ---
CC_STOP_ERROR_NONE | Operation completed successfully. No error found.
CC_STOP_CCAPI_STOP_ERROR_NOT_STARTED | Cloud Connector not started

© 2018 Digi International Inc. All rights reserved.
Start Cloud Connector updated on 22 January 2018 02:43:38 PM