iothub_service_client/inc/iothub_deviceconfiguration.h

// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

// This file is under development and it is subject to change

#ifndef IOTHUB_DEVICECONFIGURATION_H
#define IOTHUB_DEVICECONFIGURATION_H

#include "azure_c_shared_utility/crt_abstractions.h"
#include "azure_c_shared_utility/singlylinkedlist.h"
#include <time.h>
#include "iothub_service_client_auth.h"

#include "umock_c/umock_c_prod.h"

#ifdef __cplusplus
extern "C"
{
#endif

#define IOTHUB_DEVICE_CONFIGURATION_RESULT_VALUES \
    IOTHUB_DEVICE_CONFIGURATION_OK,                      \
    IOTHUB_DEVICE_CONFIGURATION_INVALID_ARG,             \
    IOTHUB_DEVICE_CONFIGURATION_ERROR,                   \
    IOTHUB_DEVICE_CONFIGURATION_HTTPAPI_ERROR,           \
    IOTHUB_DEVICE_CONFIGURATION_JSON_ERROR,              \
    IOTHUB_DEVICE_CONFIGURATION_OUT_OF_MEMORY_ERROR,     \
    IOTHUB_DEVICE_CONFIGURATION_CONFIGURATION_NOT_EXIST, \
    IOTHUB_DEVICE_CONFIGURATION_CONFIGURATION_EXIST      \

MU_DEFINE_ENUM_WITHOUT_INVALID(IOTHUB_DEVICE_CONFIGURATION_RESULT, IOTHUB_DEVICE_CONFIGURATION_RESULT_VALUES);

#define IOTHUB_DEVICECONFIGURATION_REQUEST_MODE_VALUES              \
    IOTHUB_DEVICECONFIGURATION_REQUEST_GET_LIST,                    \
    IOTHUB_DEVICECONFIGURATION_REQUEST_GET,                         \
    IOTHUB_DEVICECONFIGURATION_REQUEST_ADD,                         \
    IOTHUB_DEVICECONFIGURATION_REQUEST_UPDATE,                      \
    IOTHUB_DEVICECONFIGURATION_REQUEST_DELETE,                      \
    IOTHUB_DEVICECONFIGURATION_REQUEST_APPLY_CONFIGURATION_CONTENT

MU_DEFINE_ENUM_WITHOUT_INVALID(IOTHUB_DEVICECONFIGURATION_REQUEST_MODE, IOTHUB_DEVICECONFIGURATION_REQUEST_MODE_VALUES);

typedef struct IOTHUB_DEVICE_CONFIGURATION_CONTENT_TAG
{
    const char* deviceContent;
    const char* modulesContent;
} IOTHUB_DEVICE_CONFIGURATION_CONTENT;

typedef struct IOTHUB_DEVICE_CONFIGURATION_METRICS_RESULTS_TAG
{
    size_t numQueries;
    const char** queryNames;
    double* results;
} IOTHUB_DEVICE_CONFIGURATION_METRICS_RESULT;

typedef struct IOTHUB_DEVICE_CONFIGURATION_METRICS_DEFINITION_TAG
{
    size_t numQueries;
    const char** queryNames;
    const char** queryStrings;
} IOTHUB_DEVICE_CONFIGURATION_METRICS_DEFINITION;

typedef struct IOTHUB_DEVICE_CONFIGURATION_LABEL_TAG
{
    size_t numLabels;
    const char** labelNames;
    const char** labelValues;
} IOTHUB_DEVICE_CONFIGURATION_LABELS;

#define IOTHUB_DEVICE_CONFIGURATION_SCHEMA_VERSION_1 "1.0"
#define IOTHUB_DEVICE_CONFIGURATION_VERSION_1 1
typedef struct IOTHUB_DEVICE_CONFIGURATION_TAG
{
    int version;
    const char* schemaVersion;                                                    //version 1+
    const char* configurationId;                                                  //version 1+
    const char* targetCondition;                                                  //version 1+
    const char* eTag;                                                             //version 1+
    const char* createdTimeUtc;                                                   //version 1+
    const char* lastUpdatedTimeUtc;                                               //version 1+
    int priority;                                                                 //version 1+

    IOTHUB_DEVICE_CONFIGURATION_CONTENT content;                                  //version 1+
    IOTHUB_DEVICE_CONFIGURATION_LABELS labels;                                    //version 1+

    IOTHUB_DEVICE_CONFIGURATION_METRICS_RESULT systemMetricsResult;               //version 1+
    IOTHUB_DEVICE_CONFIGURATION_METRICS_DEFINITION systemMetricsDefinition;       //version 1+

    IOTHUB_DEVICE_CONFIGURATION_METRICS_RESULT metricResult;                      //version 1+
    IOTHUB_DEVICE_CONFIGURATION_METRICS_DEFINITION metricsDefinition;             //version 1+
} IOTHUB_DEVICE_CONFIGURATION;

#define IOTHUB_DEVICE_CONFIGURATION_ADD_VERSION_1 1
typedef struct IOTHUB_DEVICE_CONFIGURATION_ADD_TAG
{
    int version;
    const char* configurationId;                                    //version 1+
    const char* targetCondition;                                    //version 1+
    int priority;                                                   //version 1+

    IOTHUB_DEVICE_CONFIGURATION_CONTENT content;                    //version 1+
    IOTHUB_DEVICE_CONFIGURATION_LABELS labels;                      //version 1+
    IOTHUB_DEVICE_CONFIGURATION_METRICS_DEFINITION metrics;         //version 1+
} IOTHUB_DEVICE_CONFIGURATION_ADD;

/** @brief Handle to hide struct and use it in consequent APIs
*/
typedef struct IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_TAG* IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE;


/** @brief  Creates a IoT Hub Service Client DeviceConfiguration handle for use it in consequent APIs.
*
* @param    serviceClientHandle    Service client handle.
*
* @return   A non-NULL @c IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE value that is used when
*           invoking other functions for IoT Hub DeviceConfiguration and @c NULL on failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, IoTHubDeviceConfiguration_Create, IOTHUB_SERVICE_CLIENT_AUTH_HANDLE, serviceClientHandle);

/** @brief  Disposes of resources allocated by the IoT Hub IoTHubDeviceConfiguration_Create.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
*/
MOCKABLE_FUNCTION(, void, IoTHubDeviceConfiguration_Destroy, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle);

/** @brief  Retrieves the Configuration info for multiple configurations from IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    maxConfigurationsCount                    Maximum number of configurations requested
* @param    configurations                            Output parameter, if it is not NULL will contain the requested configurations
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_GetConfigurations, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, size_t, maxConfigurationsCount, SINGLYLINKEDLIST_HANDLE, configurationsList);

/** @brief  Retrieves the Configuration info for specified configurationId from IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    configurationId                         The configuration name (id) to retrieve Configuration info for.
* @param    configuration                           Output parameter, if it is not NULL will contain the requested configuration info structure
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_GetConfiguration, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, const char*, configurationId, IOTHUB_DEVICE_CONFIGURATION*, configuration);

/** @brief  Adds the Configuration info to IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    configurationAdd     IOTHUB_DEVICE_CONFIGURATION_ADD structure containing
*                                   the new configuration Id and other optional parameters
* @param    configuration           Output parameter, if it is not NULL will contain the created configuration info structure
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_AddConfiguration, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, const IOTHUB_DEVICE_CONFIGURATION_ADD*, configurationAdd, IOTHUB_DEVICE_CONFIGURATION*, configuration);

/** @brief  Updates the given Configuration in IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    configuration           IOTHUB_DEVICE_CONFIGURATION structure containing the new configuration info.
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_UpdateConfiguration, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, const IOTHUB_DEVICE_CONFIGURATION*, configuration);

/** @brief  Deletes the given Configuration from IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    configurationId         The configuration name (id) to delete Configuration info for.
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_DeleteConfiguration, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, const char*, configurationId);

/** @brief  Deletes the given Configuration from IoT Hub.
*
* @param    serviceClientDeviceConfigurationHandle    The handle created by a call to the create function.
* @param    deviceOrModuleId                     The target device or module id for the Configuration content.
* @param    configurationContent                 The configuration content to be applied.
*
* @return   IOTHUB_DEVICE_CONFIGURATION_RESULT upon success or an error code upon failure.
*/
MOCKABLE_FUNCTION(, IOTHUB_DEVICE_CONFIGURATION_RESULT, IoTHubDeviceConfiguration_ApplyConfigurationContentToDeviceOrModule, IOTHUB_SERVICE_CLIENT_DEVICE_CONFIGURATION_HANDLE, serviceClientDeviceConfigurationHandle, const char*, deviceOrModuleId, const IOTHUB_DEVICE_CONFIGURATION_CONTENT*, configurationContent);


/**
* @brief    Free members of the IOTHUB_DEVICE_CONFIGURATION structure (NOT the structure itself)
*
* @param    configuration      The structure to have its members freed.
*/
extern void IoTHubDeviceConfiguration_FreeConfigurationMembers(IOTHUB_DEVICE_CONFIGURATION* configuration);

#ifdef __cplusplus
}
#endif

#endif // IOTHUB_DEVICECONFIGURATION_H