client.h

Go to the documentation of this file.

/************************************************************************************************************************
 Copyright (c) 2016, Imagination Technologies Limited and/or its affiliated group companies.
 All rights reserved.

 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 following conditions are met:
     1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
        following disclaimer.
     2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
        following disclaimer in the documentation and/or other materials provided with the distribution.
     3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
        products derived from this software without specific prior written permission.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
************************************************************************************************************************/


#ifndef AWA_CLIENT_H
#define AWA_CLIENT_H

// @cond
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
// @endcond

#include "common.h"

#ifdef __cplusplus
extern "C" {
#endif

/**************************************************************************************************
 * Example Usage
 *************************************************************************************************/

/**************************************************************************************************
 * Public Types and Enumerations
 *************************************************************************************************/

typedef struct _AwaClientSession            AwaClientSession;
typedef struct _AwaClientGetOperation       AwaClientGetOperation;
typedef struct _AwaClientGetResponse        AwaClientGetResponse;
typedef struct _AwaClientDefineOperation    AwaClientDefineOperation;
typedef struct _AwaClientSetOperation       AwaClientSetOperation;
typedef struct _AwaClientSetResponse        AwaClientSetResponse;
typedef struct _AwaClientDeleteOperation    AwaClientDeleteOperation;
typedef struct _AwaClientDeleteResponse     AwaClientDeleteResponse;
typedef struct _AwaClientSubscribeOperation AwaClientSubscribeOperation;
typedef struct _AwaClientSubscribeResponse  AwaClientSubscribeResponse;
typedef struct _AwaClientSubscription       AwaClientChangeSubscription;
typedef struct _AwaClientSubscription       AwaClientExecuteSubscription;

/**************************************************************************************************
 * Callbacks
 *************************************************************************************************/

typedef void (*AwaClientSubscribeToChangeCallback)(const AwaChangeSet * changeSet, void * context);

typedef void (*AwaClientSubscribeToExecuteCallback)(const AwaExecuteArguments * arguments, void * context);


/**************************************************************************************************
 * Session Management
 *************************************************************************************************/

AwaClientSession * AwaClientSession_New(void);

AwaError AwaClientSession_SetIPCAsUDP(AwaClientSession * session, const char * address, uint16_t port);

// Not yet implemented:
//AwaError AwaClientSession_SetIPCAsLocal(AwaClientSession * session);
//AwaError AwaClientSession_SetIPCAsMQTT(AwaClientSession * session /* ... */);
//AwaError AwaClientSession_SetIPCAsUbus(AwaClientSession * session /* ... */);
//AwaError AwaClientSession_SetIPCAsNanoMsg(AwaClientSession * session /* ... */);

AwaError AwaClientSession_SetDefaultTimeout(AwaClientSession * session, AwaTimeout timeout);

AwaError AwaClientSession_Connect(AwaClientSession * session);

AwaError AwaClientSession_Refresh(AwaClientSession * session);

bool AwaClientSession_IsObjectDefined(const AwaClientSession * session, AwaObjectID objectID);

const AwaObjectDefinition * AwaClientSession_GetObjectDefinition(const AwaClientSession * session, AwaObjectID objectID);

AwaObjectDefinitionIterator * AwaClientSession_NewObjectDefinitionIterator(const AwaClientSession * session);

AwaError AwaClientSession_Process(AwaClientSession * session, AwaTimeout timeout);

AwaError AwaClientSession_DispatchCallbacks(AwaClientSession * session);

AwaError AwaClientSession_Disconnect(AwaClientSession * session);

AwaError AwaClientSession_Free(AwaClientSession ** session);

AwaError AwaClientSession_PathToIDs(const AwaClientSession * session, const char * path, AwaObjectID * objectID, AwaObjectInstanceID * objectInstanceID, AwaResourceID * resourceID);


/**************************************************************************************************
 * Object & Resource Definition Operation
 *************************************************************************************************/

AwaClientDefineOperation * AwaClientDefineOperation_New(const AwaClientSession * session);

AwaError AwaClientDefineOperation_Add(AwaClientDefineOperation * operation, const AwaObjectDefinition * objectDefinition);

/*
 * @brief Process the Define operation by sending it to the Core.
 *        If successful, the object definition is also added to the session.
 * @param[in] operation The Define operation to process.
 * @param[in] timeout The function will wait at least as long as this value for a response.
 * @return AwaError_Success on success.
 * @return AwaError_Timeout if no response is received after the timeout duration expires.
 * @return Various errors on failure.
 */
AwaError AwaClientDefineOperation_Perform(AwaClientDefineOperation * operation, AwaTimeout timeout);

AwaError AwaClientDefineOperation_Free(AwaClientDefineOperation ** operation);



/**************************************************************************************************
 * Object & Resource Retrieval Operation
 *************************************************************************************************/

AwaClientGetOperation * AwaClientGetOperation_New(const AwaClientSession * session);

AwaError AwaClientGetOperation_AddPath(AwaClientGetOperation * operation, const char * path);

AwaError AwaClientGetOperation_AddPathWithArrayRange(AwaClientGetOperation * operation, const char * path, AwaArrayIndex startIndex, AwaArrayLength indexCount);

AwaError AwaClientGetOperation_Perform(AwaClientGetOperation * operation, AwaTimeout timeout);

AwaError AwaClientGetOperation_Free(AwaClientGetOperation ** operation);

const AwaClientGetResponse * AwaClientGetOperation_GetResponse(const AwaClientGetOperation * operation);

AwaPathIterator * AwaClientGetResponse_NewPathIterator(const AwaClientGetResponse * response);

bool AwaClientGetResponse_ContainsPath(const AwaClientGetResponse * response, const char * path);

const AwaPathResult * AwaClientGetResponse_GetPathResult(const AwaClientGetResponse * response, const char * path);

bool AwaClientGetResponse_HasValue(const AwaClientGetResponse * response, const char * path);

AwaError AwaClientGetResponse_GetValueAsCStringPointer   (const AwaClientGetResponse * response, const char * path, const char ** value);
AwaError AwaClientGetResponse_GetValueAsIntegerPointer   (const AwaClientGetResponse * response, const char * path, const AwaInteger ** value);
AwaError AwaClientGetResponse_GetValueAsFloatPointer     (const AwaClientGetResponse * response, const char * path, const AwaFloat ** value);
AwaError AwaClientGetResponse_GetValueAsBooleanPointer   (const AwaClientGetResponse * response, const char * path, const AwaBoolean ** value);
AwaError AwaClientGetResponse_GetValueAsTimePointer      (const AwaClientGetResponse * response, const char * path, const AwaTime ** value);
AwaError AwaClientGetResponse_GetValueAsObjectLinkPointer(const AwaClientGetResponse * response, const char * path, const AwaObjectLink ** value);
AwaError AwaClientGetResponse_GetValueAsOpaquePointer    (const AwaClientGetResponse * response, const char * path, const AwaOpaque ** value);
AwaError AwaClientGetResponse_GetValueAsOpaque(const AwaClientGetResponse * response, const char * path, AwaOpaque * value);

AwaError AwaClientGetResponse_GetValueAsObjectLink(const AwaClientGetResponse * response, const char * path, AwaObjectLink * value);

AwaError AwaClientGetResponse_GetValuesAsStringArrayPointer    (const AwaClientGetResponse * response, const char * path, const AwaStringArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsIntegerArrayPointer   (const AwaClientGetResponse * response, const char * path, const AwaIntegerArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsFloatArrayPointer     (const AwaClientGetResponse * response, const char * path, const AwaFloatArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsBooleanArrayPointer   (const AwaClientGetResponse * response, const char * path, const AwaBooleanArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsTimeArrayPointer      (const AwaClientGetResponse * response, const char * path, const AwaTimeArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsOpaqueArrayPointer    (const AwaClientGetResponse * response, const char * path, const AwaOpaqueArray ** valueArray);
AwaError AwaClientGetResponse_GetValuesAsObjectLinkArrayPointer(const AwaClientGetResponse * response, const char * path, const AwaObjectLinkArray ** valueArray);
/**************************************************************************************************
 * Object & Resource Value Setting Operation
 *************************************************************************************************/

AwaClientSetOperation * AwaClientSetOperation_New(const AwaClientSession * session);

AwaError AwaClientSetOperation_CreateObjectInstance(AwaClientSetOperation * operation, const char * path);

AwaError AwaClientSetOperation_CreateOptionalResource(AwaClientSetOperation * operation, const char * path);

AwaError AwaClientSetOperation_AddValueAsCString   (AwaClientSetOperation * operation, const char * path, const char * value);
AwaError AwaClientSetOperation_AddValueAsInteger   (AwaClientSetOperation * operation, const char * path, AwaInteger value);
AwaError AwaClientSetOperation_AddValueAsFloat     (AwaClientSetOperation * operation, const char * path, AwaFloat value);
AwaError AwaClientSetOperation_AddValueAsBoolean   (AwaClientSetOperation * operation, const char * path, AwaBoolean value);
AwaError AwaClientSetOperation_AddValueAsTime      (AwaClientSetOperation * operation, const char * path, AwaTime value);
AwaError AwaClientSetOperation_AddValueAsOpaque    (AwaClientSetOperation * operation, const char * path, AwaOpaque value);
AwaError AwaClientSetOperation_AddValueAsObjectLink(AwaClientSetOperation * operation, const char * path, AwaObjectLink value);
AwaError AwaClientSetOperation_AddValueAsStringArray    (AwaClientSetOperation * operation, const char * path, const AwaStringArray * array);
AwaError AwaClientSetOperation_AddValueAsIntegerArray   (AwaClientSetOperation * operation, const char * path, const AwaIntegerArray * array);
AwaError AwaClientSetOperation_AddValueAsFloatArray     (AwaClientSetOperation * operation, const char * path, const AwaFloatArray * array);
AwaError AwaClientSetOperation_AddValueAsBooleanArray   (AwaClientSetOperation * operation, const char * path, const AwaBooleanArray * array);
AwaError AwaClientSetOperation_AddValueAsTimeArray      (AwaClientSetOperation * operation, const char * path, const AwaTimeArray * array);
AwaError AwaClientSetOperation_AddValueAsOpaqueArray    (AwaClientSetOperation * operation, const char * path, const AwaOpaqueArray * array);
AwaError AwaClientSetOperation_AddValueAsObjectLinkArray(AwaClientSetOperation * operation, const char * path, const AwaObjectLinkArray * array);
AwaError AwaClientSetOperation_AddArrayValueAsCString   (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, const char * value);
AwaError AwaClientSetOperation_AddArrayValueAsInteger   (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaInteger value);
AwaError AwaClientSetOperation_AddArrayValueAsFloat     (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaFloat value);
AwaError AwaClientSetOperation_AddArrayValueAsBoolean   (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaBoolean value);
AwaError AwaClientSetOperation_AddArrayValueAsTime      (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaTime value);
AwaError AwaClientSetOperation_AddArrayValueAsOpaque    (AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaOpaque value);
AwaError AwaClientSetOperation_AddArrayValueAsObjectLink(AwaClientSetOperation * operation, const char * path, int resourceInstanceID, AwaObjectLink value);
AwaError AwaClientSetOperation_Perform(AwaClientSetOperation * operation, AwaTimeout timeout);

const AwaClientSetResponse * AwaClientSetOperation_GetResponse(const AwaClientSetOperation * operation);

AwaError AwaClientSetOperation_Free(AwaClientSetOperation ** operation);

AwaPathIterator * AwaClientSetResponse_NewPathIterator(const AwaClientSetResponse * response);

const AwaPathResult * AwaClientSetResponse_GetPathResult(const AwaClientSetResponse * response, const char * path);

bool AwaClientSetResponse_ContainsPath(const AwaClientSetResponse * response, const char * path);


/**************************************************************************************************
 * Object Instance & Resource Deletion Operation
 *************************************************************************************************/

AwaClientDeleteOperation * AwaClientDeleteOperation_New(const AwaClientSession * session);

AwaError AwaClientDeleteOperation_AddPath(AwaClientDeleteOperation * operation, const char * path);

AwaError AwaClientDeleteOperation_AddPathWithArrayRange(AwaClientDeleteOperation * operation, const char * path, AwaArrayIndex startIndex, AwaArrayLength indexCount);

AwaError AwaClientDeleteOperation_Perform(AwaClientDeleteOperation * operation, AwaTimeout timeout);

const AwaClientDeleteResponse * AwaClientDeleteOperation_GetResponse(const AwaClientDeleteOperation * operation);

AwaError AwaClientDeleteOperation_Free(AwaClientDeleteOperation ** operation);

AwaPathIterator * AwaClientDeleteResponse_NewPathIterator(const AwaClientDeleteResponse * response);

const AwaPathResult * AwaClientDeleteResponse_GetPathResult(const AwaClientDeleteResponse * response, const char * path);

bool AwaClientDeleteResponse_ContainsPath(const AwaClientDeleteResponse * response, const char * path);


/**************************************************************************************************
 * Subscription Procedures
 *************************************************************************************************/

AwaClientSubscribeOperation * AwaClientSubscribeOperation_New(const AwaClientSession * session);

AwaError AwaClientSubscribeOperation_AddChangeSubscription(AwaClientSubscribeOperation * operation, AwaClientChangeSubscription * subscription);

AwaError AwaClientSubscribeOperation_AddExecuteSubscription(AwaClientSubscribeOperation * operation, AwaClientExecuteSubscription * subscription);

AwaError AwaClientSubscribeOperation_AddCancelChangeSubscription(AwaClientSubscribeOperation * operation, AwaClientChangeSubscription * subscription);

AwaError AwaClientSubscribeOperation_AddCancelExecuteSubscription(AwaClientSubscribeOperation * operation, AwaClientExecuteSubscription * subscription);

AwaError AwaClientSubscribeOperation_Perform(AwaClientSubscribeOperation * operation, AwaTimeout timeout);

const AwaClientSubscribeResponse * AwaClientSubscribeOperation_GetResponse(const AwaClientSubscribeOperation * operation);

AwaError AwaClientSubscribeOperation_Free(AwaClientSubscribeOperation ** operation); // caller must keep subscription valid during entire observe operation

AwaPathIterator * AwaClientSubscribeResponse_NewPathIterator(const AwaClientSubscribeResponse * response);

const AwaPathResult * AwaClientSubscribeResponse_GetPathResult(const AwaClientSubscribeResponse * response, const char * path);

AwaClientChangeSubscription * AwaClientChangeSubscription_New(const char * path, AwaClientSubscribeToChangeCallback callback, void * context);

const char * AwaClientChangeSubscription_GetPath(AwaClientChangeSubscription * subscription);

AwaError AwaClientChangeSubscription_Free(AwaClientChangeSubscription ** subscription);

AwaClientExecuteSubscription * AwaClientExecuteSubscription_New(const char * path, AwaClientSubscribeToExecuteCallback callback, void * context);

const char * AwaClientExecuteSubscription_GetPath(AwaClientExecuteSubscription * subscription);

AwaError AwaClientExecuteSubscription_Free(AwaClientExecuteSubscription ** subscription);


/**************************************************************************************************
 * ChangeSet Functions for Change Subscriptions
 *************************************************************************************************/

const AwaClientSession * AwaChangeSet_GetClientSession(const AwaChangeSet * changeSet);

#ifdef __cplusplus
}
#endif

#endif // AWA_CLIENT_H