tvcmi_client.h

Go to the documentation of this file.

/*
 * MIT License
 * Copyright (c) 2017 TeamViewer GmbH
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
*/
 
 
 
#ifndef __TVCMI_CLIENT_H__
#define __TVCMI_CLIENT_H__
 
#include <stdint.h>
#include <time.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define IOTTVCMI_API
#if defined(_MSC_VER)
#   if defined(IOTTVCMI_CREATE_SHARED_LIBRARY)
#       undef IOTTVCMI_API
#       define IOTTVCMI_API __declspec(dllexport)
#   elif defined(IOTTVCMI_LINKED_AS_SHARED_LIBRARY)
#       undef IOTTVCMI_API
#       define IOTTVCMI_API __declspec(dllimport)
#   endif
#endif
 
#define ApiVersion "v1.0"
 
 
typedef enum TVCMI_ApiErrorTag
{
    TVCMI_ApiError_NoError = -1,
    TVCMI_ApiError_UnknownError = 0,
    TVCMI_ApiError_NoBackendConnection = 1,
    TVCMI_ApiError_NoLicence = 2,
    TVCMI_ApiError_InternalError = 3,
    TVCMI_ApiError_InvalidJson = 4,
    TVCMI_ApiError_JsonIsNotAnObject = 5,
    TVCMI_ApiError_MissingParameter = 6,
    TVCMI_ApiError_ParameterIsNotAString = 7,
    TVCMI_ApiError_ParameterIsNotANumber = 8,
    TVCMI_ApiError_ParameterIsNotABool = 9,
    TVCMI_ApiError_ParameterIsNotAnArray = 10,
    TVCMI_ApiError_ParameterIsNotAnInteger = 11,
    TVCMI_ApiError_UnknownValueUnit = 12,
    TVCMI_ApiError_UnknownMetricType = 13,
    TVCMI_ApiError_ValueUnitOrValueTypeHasToBeProvided = 14,
    TVCMI_ApiError_UnknownSensorId = 15,
    TVCMI_ApiError_UnknownMetricId = 16,
    TVCMI_ApiError_NoMetricsUpdated = 17,
    TVCMI_ApiError_ForbiddendAccess = 18,
    TVCMI_ApiError_OutOfRange = 19,
    TVCMI_ApiError_CertificateFormatError = 20,
    TVCMI_ApiError_CertificateIsEmptyError = 21,
    TVCMI_ApiError_CertificateWithoutCommonName = 22,
    TVCMI_ApiError_DeleteMetricsFailed = 23,
    TVCMI_ApiError_ChangeMetricsFailed = 24,
    TVCMI_ApiError_InvalidClientName = 25,
    TVCMI_ApiError_CreateMetricsFailed = 26,
    TVCMI_ApiError_PushValuesFailed = 27
 
} TVCMI_ApiError;
 
typedef enum TVCMI_ErrorTag
{
    TVCMI_Error_Unknown = -1,
    TVCMI_Error_Success = 0,
    TVCMI_Error_WrongApiVersion = 1,
    TVCMI_Error_WrongConfigName = 2,
    TVCMI_Error_ConfigReadFailed = 3,
    TVCMI_Error_WrongConfigParams = 4,
    TVCMI_Error_NoMemory = 5,
    TVCMI_Error_InvalidArguments = 6,
    TVCMI_Error_NoResource = 7,
    TVCMI_Error_ConnectionFailed = 8,
    TVCMI_Error_WrongProtocol = 9,
    TVCMI_Error_WrongIdentifier = 10,
    TVCMI_Error_ServerUnavailable = 11,
    TVCMI_Error_UnexpectedDisconnect = 12,
    TVCMI_Error_NoConnectionToServer = 13,
    TVCMI_Error_PayloadSize = 14,
    TVCMI_Error_WrongReply = 15,
    TVCMI_Error_Busy = 16,
    TVCMI_Error_CreateCertificate = 17,
    TVCMI_Error_CreateProvisionCertificate = 18,
    TVCMI_Error_CreatePrivateKey = 19,
    TVCMI_Error_GetClientId = 20,
    TVCMI_Error_TlsSetFailed = 21,
    TVCMI_Error_ClientProvision = 22,
    TVCMI_Error_ModifySensor = 23,
    TVCMI_Error_DeleteSensor = 24,
    TVCMI_Error_DeleteMetrics = 25,
    TVCMI_Error_RemoveCertificates = 26,
    TVCMI_Error_TlsConnection = 27,
    TVCMI_Error_Errno = 28,
    TVCMI_Error_ComposeJson = 29,
    TVCMI_Error_NoThreadSupport = 30,
    TVCMI_Error_ReadCertificateCN = 31,
    TVCMI_Error_CertificateRequestPath = 32,
    TVCMI_Error_CertifcateFolderPath = 33,
    TVCMI_Error_AlreadyProvisioned = 34,
    TVCMI_Error_WritingToCertificateFile = 35,
    TVCMI_Error_WrongCertificateFile = 36,
    TVCMI_Error_ThreadCreate = 37,
    TVCMI_Error_NoBackendConnection = 38,
    TVCMI_Error_CertificateRequest = 39
 
} TVCMI_Error;
 
typedef enum TVCMI_ValueUnitTag
{
    TVCMI_ValueUnit_NoUnit,
    TVCMI_ValueUnit_SIAmpere,
    TVCMI_ValueUnit_SIBit,
    TVCMI_ValueUnit_SICandela,
    TVCMI_ValueUnit_SICelsius,
    TVCMI_ValueUnit_SIFarad,
    TVCMI_ValueUnit_SIKilogram,
    TVCMI_ValueUnit_SIHertz,
    TVCMI_ValueUnit_SIJoule,
    TVCMI_ValueUnit_SIMeter,
    TVCMI_ValueUnit_SIMetersPerSecond,
    TVCMI_ValueUnit_SIMetersPerSquareSecond,
    TVCMI_ValueUnit_SIMole,
    TVCMI_ValueUnit_SINewtone,
    TVCMI_ValueUnit_SIOhm,
    TVCMI_ValueUnit_SIPascal,
    TVCMI_ValueUnit_SIRadian,
    TVCMI_ValueUnit_SISecond,
    TVCMI_ValueUnit_SISquareMeter,
    TVCMI_ValueUnit_SIVolt,
    TVCMI_ValueUnit_SIWatt,
    TVCMI_ValueUnit_NoSIDecibel,  // Non-SI Decibel unit
    TVCMI_ValueUnit_NoSIPercent   // Non-SI Percent unit
 
} TVCMI_ValueUnit;
 
typedef enum TVCMI_ValueTypeTag
{
    TVCMI_ValueType_NoType,
    TVCMI_ValueType_Integer,
    TVCMI_ValueType_Double,
    TVCMI_ValueType_Bool,
    TVCMI_ValueType_String
 
} TVCMI_ValueType;
 
typedef struct TVCMI_CreatedMetricTag
{
    char* matchingId;
    char* metricId;
 
} TVCMI_CreatedMetric;
 
typedef struct TVCMI_CreatedMetricsTag
{
    char*                    sensorId;
    TVCMI_CreatedMetric*     metrics;
    int                      metricsCount;
 
} TVCMI_CreatedMetrics;
 
typedef struct TVCMI_MetricInfoTag
{
    char* metricId;
 
} TVCMI_MetricInfo;
 
typedef enum TVCMI_SensorTypeTag
{
    TVCMI_SensorType_None,
    TVCMI_SensorType_Standard,
    TVCMI_SensorType_Plugin
 
} TVCMI_SensorType;
 
typedef struct TVCMI_PluginParameterTag
{
    char*               parameterName;
    char*               parameterValue;
 
} TVCMI_PluginParameter;
 
typedef struct TVCMI_SensorMetadataTag
{
    char*                   name;
    char*                   sensorId;
    int                     frequency;
    TVCMI_SensorType        sensorType;
    char*                   pluginName;
    char*                   pluginDownloadUrl;
    TVCMI_PluginParameter*  pluginParameters;
    int                     pluginParametersCount;
    char*                   monitoringService;
    TVCMI_MetricInfo*       metrics;
    int                     metricsCount;
 
} TVCMI_SensorMetadata;
 
typedef struct TVCMI_SensorsInfoTag
{
    TVCMI_SensorMetadata*   sensors;
    int                     sensorsCount;
 
} TVCMI_SensorsInfo;
 
typedef struct TVCMI_MetricMetadataTag
{
    char*           id;
    TVCMI_ValueUnit valueUnit;
    TVCMI_ValueType valueType;
    char*           valueAnnotation;
    uint64_t        lastUpdated;
    char*           value;
    char*           name;
 
} TVCMI_MetricMetadata;
 
typedef struct TVCMI_MetricSchemaContainerTag TVCMI_MetricSchemaContainer;
 
typedef struct TVCMI_MetricValueContainerTag TVCMI_MetricValueContainer;
 
typedef struct TVCMI_ClientTag TVCMI_Client;
 
 
IOTTVCMI_API TVCMI_Error  TVCMI_LibInit();
 
 
IOTTVCMI_API TVCMI_Error TVCMI_LibCleanup();
 
 
IOTTVCMI_API TVCMI_Client* TVCMI_NewClient(const char* confFile, void* callbackParameter, TVCMI_Error* err);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteClient(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ProvisionClient(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_Connect(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_Disconnect(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CreateSensor(TVCMI_Client* client, const char* name);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_UpdateSensor(TVCMI_Client* client, const char* sensorId, const char* sensorName);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteSensor(TVCMI_Client* client, const char* sensorId);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CreateMetrics(TVCMI_Client* client, const char* sensorId, TVCMI_MetricSchemaContainer* container);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_UpdateMetrics(TVCMI_Client* client, const char* sensorId, TVCMI_MetricSchemaContainer* container);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_PushMetricValues(TVCMI_Client* client, const char* sensorId, TVCMI_MetricValueContainer* container);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteMetrics(TVCMI_Client* client, const char* sensorId, char** metricIds, int metricsCount);
 
 
IOTTVCMI_API TVCMI_MetricSchemaContainer* TVCMI_CreateMetricSchemaContainer();
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DestroyMetricSchemaContainer(TVCMI_MetricSchemaContainer* container);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddStandardMetricSchema(
    TVCMI_MetricSchemaContainer* container,
    const char* matchingId,
    const char* name,
    TVCMI_ValueUnit valueUnit);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddCustomMetricSchema(
    TVCMI_MetricSchemaContainer* container,
    const char* matchingId,
    const char* name,
    TVCMI_ValueType valueType,
    const char* valueAnnotation);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddMetricUpdateSchema(
    TVCMI_MetricSchemaContainer* container,
    const char* metricId,
    const char* name,
    const char* valueAnnotation);
 
 
IOTTVCMI_API TVCMI_MetricValueContainer* TVCMI_CreateMetricValueContainer();
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DestroyMetricValueContainer(TVCMI_MetricValueContainer* container);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddIntegerMetricValue(TVCMI_MetricValueContainer* container, int64_t value, const char* metricId);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddBoolMetricValue(TVCMI_MetricValueContainer* container, int value, const char* metricId);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddDoubleMetricValue(TVCMI_MetricValueContainer* container, double value, const char* metricId);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_AddStringMetricValue(TVCMI_MetricValueContainer* container, const char* value, const char* metricId);
 
IOTTVCMI_API TVCMI_Error TVCMI_AddEpochTimeStamp(TVCMI_MetricValueContainer* container, uint64_t epochTimestamp);
 
IOTTVCMI_API TVCMI_Error TVCMI_ListSensors(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DescribeMetric(TVCMI_Client* client, const char* sensorId, const char* metricId);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ReportClientError(TVCMI_Client* client, int error, const char* errMessage);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ReportSensorError(
    TVCMI_Client* client,
    const char* sensorId,
    int error,
    const char* errMessage);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ReportMetricError(
    TVCMI_Client* client,
    const char* sensorId,
    const char* metricId,
    int error,
    const char* errMessage);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ProvisionClientCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnProvisionClient)(
        TVCMI_Client* client,
        void* callbackParameter,
        TVCMI_Error err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ConnectCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnConnect)(
        TVCMI_Client* client,
        void* callbackParameter,
        TVCMI_Error err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DisconnectCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDisconnect)(
        TVCMI_Client* client,
        void* callbackParameter,
        TVCMI_Error err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CreateSensorCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnCreateSensor)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorName,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_UpdateSensorCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnUpdateSensor)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteSensorCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDeleteSensor)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CreateMetricsCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnCreateMetrics)(
        TVCMI_Client* client,
        void* callbackParameter,
        TVCMI_CreatedMetrics* createdMetrics,
        TVCMI_ApiError err));
 
IOTTVCMI_API TVCMI_Error TVCMI_UpdateMetricsCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnUpdateMetrics)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API void TVCMI_DestroyCreatedMetrics(TVCMI_CreatedMetrics* createdMetrics);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteMetricsCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDeleteMetrics)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_PushMetricValuesCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnPushMetricValues)(
        TVCMI_Client* client,
        void* callbackParameter,
        const char* sensorId,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_ListSensorsCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnListSensors)(
        TVCMI_Client* client,
        TVCMI_SensorsInfo* sensorsInfo,
        void* callbackParameter,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API void TVCMI_DestroySensorsInfo(TVCMI_SensorsInfo* sensorsInfo);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DescribeMetricCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDescribeMetric)(
        TVCMI_Client* client,
        const char* sensorId,
        TVCMI_MetricMetadata* metricMetadata,
        void* callbackParameter,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API void TVCMI_DestroyMetricMetadata(TVCMI_MetricMetadata* metricMetadata);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_LogCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnLog)(
        TVCMI_Client* client,
        const char* logMessage,
        void* callbackParameter));
 
 
IOTTVCMI_API const char* TVCMI_GetClientId(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CheckConnection(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CheckConnectionCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnCheckConnection)(
        TVCMI_Client* client,
        void* callbackParameter,
        TVCMI_ApiError err));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_CreateSensorJobCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnCreateSensorJob)(
        TVCMI_Client* client,
        TVCMI_SensorMetadata* sensorMetadata,
        void* callbackParameter));
 
 
void TVCMI_DestroySensorMetadata(TVCMI_SensorMetadata* sensorMetadata);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeleteSensorJobCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDeleteSensorJob)(
        TVCMI_Client* client,
        const char* sensorId,
        void* callbackParameter));
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeprovisionClient(TVCMI_Client* client);
 
 
IOTTVCMI_API TVCMI_Error TVCMI_DeprovisionClientCallbackSet(
    TVCMI_Client* client,
    void (*TVCMI_OnDeprovisionClient)(
        TVCMI_Client* client,
        void* callbackParameter));
 
 
#ifdef __cplusplus
}
#endif //__cplusplus
 
#endif //__TVCMI_CLIENT_H__