This interface enables an application to interact with the resources hosted by the LWM2M Client Core. More...

#include "common.h"

Include dependency graph for client.h:

Typedefs
typedef void(*	AwaClientSubscribeToChangeCallback) (const AwaChangeSet changeSet, void context)
	A user-specified callback handler for a Change Subscription which will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity has changed since the subscription's session callbacks were last dispatched. More...

typedef void(*	AwaClientSubscribeToExecuteCallback) (const AwaExecuteArguments arguments, void context)
	A user-specified callback handler for an Execute Subscription which will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity has been executed since the subscription's session callbacks were last dispatched. More...

Functions
AwaClientSession *	AwaClientSession_New (void)
	Initialise a new session of the Awa subsystem. More...

AwaError	AwaClientSession_SetIPCAsUDP (AwaClientSession session, const char address, uint16_t port)
	Configure the IPC mechanism used by the API to communicate with the Core. More...

AwaError	AwaClientSession_SetDefaultTimeout (AwaClientSession *session, AwaTimeout timeout)
	Set IPC connect timeout. More...

AwaError	AwaClientSession_Connect (AwaClientSession *session)
	Connect a session (configured with an IPC mechanism) to the Core. More...

AwaError	AwaClientSession_Refresh (AwaClientSession *session)
	Object and Resource Definitions are assembled by the application and sent to the client daemon for storage (a process called "Define"). More...

bool	AwaClientSession_IsObjectDefined (const AwaClientSession *session, AwaObjectID objectID)
	Determines whether the specified session holds a valid definition for the given object. More...

const AwaObjectDefinition *	AwaClientSession_GetObjectDefinition (const AwaClientSession *session, AwaObjectID objectID)
	Retrieves an object definition instance corresponding to the object identified by the given object ID. More...

AwaObjectDefinitionIterator *	AwaClientSession_NewObjectDefinitionIterator (const AwaClientSession *session)
	Retrieves a new object definition iterator that can be used to iterate through the set of defined objects within the context of the given session. More...

AwaError	AwaClientSession_Process (AwaClientSession *session, AwaTimeout timeout)
	Process any incoming requests from the LWM2M Client. More...

AwaError	AwaClientSession_DispatchCallbacks (AwaClientSession *session)
	Invoke any callbacks scheduled since this function was last called. More...

AwaError	AwaClientSession_Disconnect (AwaClientSession *session)
	When a session is no longer required, or if the application intends to sleep for some time, the session can be disconnected from the Core. More...

AwaError	AwaClientSession_Free (AwaClientSession **session)
	Shut down an existing session, freeing any allocated memory. More...

AwaError	AwaClientSession_PathToIDs (const AwaClientSession session, const char path, AwaObjectID objectID, AwaObjectInstanceID objectInstanceID, AwaResourceID *resourceID)
	Paths are used to identify objects, object instances and resources within the data model. More...

AwaClientDefineOperation *	AwaClientDefineOperation_New (const AwaClientSession *session)
	Allocate and return a pointer to a new Define operation, that can be used to define Objects and Resources. More...

AwaError	AwaClientDefineOperation_Add (AwaClientDefineOperation operation, const AwaObjectDefinition objectDefinition)
	Add an Object Definition to an existing Define operation, so that the client will create a suitable definition for this new object type. More...

AwaError	AwaClientDefineOperation_Perform (AwaClientDefineOperation *operation, AwaTimeout timeout)

AwaError	AwaClientDefineOperation_Free (AwaClientDefineOperation **operation)
	Clean up a Define operation, freeing all allocated resources. More...

AwaClientGetOperation *	AwaClientGetOperation_New (const AwaClientSession *session)
	Allocate and return a pointer to a new Get operation, that can be used to retrieve resource values from the Core. More...

AwaError	AwaClientGetOperation_AddPath (AwaClientGetOperation operation, const char path)
	Adds a path of interest to a Get operation, as a request to retrieve all resources at or covered by this path from the Core. More...

AwaError	AwaClientGetOperation_AddPathWithArrayRange (AwaClientGetOperation operation, const char path, AwaArrayIndex startIndex, AwaArrayLength indexCount)
	Add a resource path to a multiple-instance resource and specify a range of resource instances to retrieve. More...

AwaError	AwaClientGetOperation_Perform (AwaClientGetOperation *operation, AwaTimeout timeout)
	Process the Get operation by sending it to the Core. More...

AwaError	AwaClientGetOperation_Free (AwaClientGetOperation **operation)
	Clean up a Get operation, freeing all allocated resources. More...

const AwaClientGetResponse *	AwaClientGetOperation_GetResponse (const AwaClientGetOperation *operation)
	Obtain a Get Response instance from a processed Get operation. More...

AwaPathIterator *	AwaClientGetResponse_NewPathIterator (const AwaClientGetResponse *response)
	Create a new Path Iterator for a Get Response, used to iterate through the list of resource paths retrieved by the corresponding Get operation. More...

bool	AwaClientGetResponse_ContainsPath (const AwaClientGetResponse response, const char path)
	Test if the Get Response has the specified path (resource, object instance or object) present. More...

const AwaPathResult *	AwaClientGetResponse_GetPathResult (const AwaClientGetResponse response, const char path)
	Retrieve a path result from a Get Response relating to a write to that path retrieved by the corresponding Get Operation. More...

bool	AwaClientGetResponse_HasValue (const AwaClientGetResponse response, const char path)
	Test if the Get Response has a value for the specified resource path. More...

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)
	Retrieve an opaque resource's value from a Get Response. More...

AwaError	AwaClientGetResponse_GetValueAsObjectLink (const AwaClientGetResponse response, const char path, AwaObjectLink *value)
	Retrieve an object link resource's value from a Get Response. More...

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)

AwaClientSetOperation *	AwaClientSetOperation_New (const AwaClientSession *session)
	Allocate and return a pointer to a new Set Operation, that can be used to set resource values. More...

AwaError	AwaClientSetOperation_CreateObjectInstance (AwaClientSetOperation operation, const char path)
	Adds an object or object instance path to a Set Operation, as a request to create an Object Instance. More...

AwaError	AwaClientSetOperation_CreateOptionalResource (AwaClientSetOperation operation, const char path)
	Adds a resource path to a Set Operation, as a request to create an optional Resource. More...

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)
	Process the Set Operation by sending it to the Core. More...

const AwaClientSetResponse *	AwaClientSetOperation_GetResponse (const AwaClientSetOperation *operation)
	Obtain a Set Response instance from a processed Set Operation. More...

AwaError	AwaClientSetOperation_Free (AwaClientSetOperation **operation)
	Clean up a Set Operation, freeing all allocated resources. More...

AwaPathIterator *	AwaClientSetResponse_NewPathIterator (const AwaClientSetResponse *response)
	Create a new Path Iterator for a Set Response, used to iterate through the list of paths returned in the response of the corresponding Set Operation. More...

const AwaPathResult *	AwaClientSetResponse_GetPathResult (const AwaClientSetResponse response, const char path)
	Retrieve a path result from a Set Response relating to a write to that path retrieved by the corresponding Set Operation. More...

bool	AwaClientSetResponse_ContainsPath (const AwaClientSetResponse response, const char path)
	Test if the Set Response has the specified path to a resource or object present. More...

AwaClientDeleteOperation *	AwaClientDeleteOperation_New (const AwaClientSession *session)
	Allocate and return a pointer to a new Delete operation, that can be used to delete optional resources, resource instances, and object instances. More...

AwaError	AwaClientDeleteOperation_AddPath (AwaClientDeleteOperation operation, const char path)
	Adds a path to a Delete operation, as a request to delete the specified resource or object instance. More...

AwaError	AwaClientDeleteOperation_AddPathWithArrayRange (AwaClientDeleteOperation operation, const char path, AwaArrayIndex startIndex, AwaArrayLength indexCount)
	Add a path to a multiple-instance resource and specify a range of resource instances to delete. More...

AwaError	AwaClientDeleteOperation_Perform (AwaClientDeleteOperation *operation, AwaTimeout timeout)
	Process the Delete operation by sending it to the Core. More...

const AwaClientDeleteResponse *	AwaClientDeleteOperation_GetResponse (const AwaClientDeleteOperation *operation)
	Obtain a Delete Response instance from a processed Delete operation. More...

AwaError	AwaClientDeleteOperation_Free (AwaClientDeleteOperation **operation)
	Shut down an existing operation, freeing any allocated memory. More...

AwaPathIterator *	AwaClientDeleteResponse_NewPathIterator (const AwaClientDeleteResponse *response)
	Create a new Path Iterator for a Delete Response, used to iterate through the list of resource paths retrieved by the corresponding Delete operation. More...

const AwaPathResult *	AwaClientDeleteResponse_GetPathResult (const AwaClientDeleteResponse response, const char path)
	Retrieve a path result from a Delete Response relating to a subscription to that path retrieved by the corresponding Delete operation. More...

bool	AwaClientDeleteResponse_ContainsPath (const AwaClientDeleteResponse response, const char path)
	Test if the Delete Response has the specified path (object instance or object) present. More...

AwaClientSubscribeOperation *	AwaClientSubscribeOperation_New (const AwaClientSession *session)
	Allocate and return a pointer to a new Subscribe operation, that can be used to subscribe to executions of resources and changes to objects, object instances and resource values from the Core. More...

AwaError	AwaClientSubscribeOperation_AddChangeSubscription (AwaClientSubscribeOperation operation, AwaClientChangeSubscription subscription)
	Adds a Change Subscription of interest to a Subscribe operation, as a request to be notified of changes to the subscribed entity from the Core. More...

AwaError	AwaClientSubscribeOperation_AddExecuteSubscription (AwaClientSubscribeOperation operation, AwaClientExecuteSubscription subscription)
	Adds a Execute Subscription of interest to a Subscribe operation, as a request to be notified of executions of the subscribed entity from the Core. More...

AwaError	AwaClientSubscribeOperation_AddCancelChangeSubscription (AwaClientSubscribeOperation operation, AwaClientChangeSubscription subscription)
	Adds a Cancel flag to a Change Subscription in a specified Subscribe operation, as a request to cancel being notified of changes to the subscribed entity from the Core. More...

AwaError	AwaClientSubscribeOperation_AddCancelExecuteSubscription (AwaClientSubscribeOperation operation, AwaClientExecuteSubscription subscription)
	Adds a Cancel flag to a Execute Subscription in a specified Subscribe operation, as a request to cancel being notified of executions of the subscribed entity from the Core. More...

AwaError	AwaClientSubscribeOperation_Perform (AwaClientSubscribeOperation *operation, AwaTimeout timeout)
	Process the Subscribe operation by sending it to the Core, notifying the Core to begin or cancel subscription to changes and executions of the subscribed entities inside the specified Subscribe operation. More...

const AwaClientSubscribeResponse *	AwaClientSubscribeOperation_GetResponse (const AwaClientSubscribeOperation *operation)
	Obtain a Subscribe Response instance from a processed Subscribe operation. More...

AwaError	AwaClientSubscribeOperation_Free (AwaClientSubscribeOperation **operation)
	Clean up a Subscribe operation, freeing all allocated resources. More...

AwaPathIterator *	AwaClientSubscribeResponse_NewPathIterator (const AwaClientSubscribeResponse *response)
	Create a new Path Iterator for a Subscribe Response, used to iterate through the list of paths relating to results of subscriptions retrieved by the corresponding Subscribe operation. More...

const AwaPathResult *	AwaClientSubscribeResponse_GetPathResult (const AwaClientSubscribeResponse response, const char path)
	Retrieve a path result from a Subscribe Response relating to a subscription to that path retrieved by the corresponding Subscribe operation. More...

AwaClientChangeSubscription *	AwaClientChangeSubscription_New (const char path, AwaClientSubscribeToChangeCallback callback, void context)
	Allocate and return a pointer to a new Change Subscription, that can be used to subscribe to changes on either a resource, object instance or object. More...

const char *	AwaClientChangeSubscription_GetPath (AwaClientChangeSubscription *subscription)
	Retrieve the path from a Change subscription. More...

AwaError	AwaClientChangeSubscription_Free (AwaClientChangeSubscription **subscription)
	Shut down a Change Subscription, freeing any allocated memory. More...

AwaClientExecuteSubscription *	AwaClientExecuteSubscription_New (const char path, AwaClientSubscribeToExecuteCallback callback, void context)
	Allocate and return a pointer to a new Execute Subscription, that can be used to subscribe to executions of a resource, or all resources of an object instance or object. More...

const char *	AwaClientExecuteSubscription_GetPath (AwaClientExecuteSubscription *subscription)
	Retrieve the path from a Execute subscription. More...

AwaError	AwaClientExecuteSubscription_Free (AwaClientExecuteSubscription **subscription)
	Shut down an Execute Subscription, freeing any allocated memory. More...

const AwaClientSession *	AwaChangeSet_GetClientSession (const AwaChangeSet *changeSet)
	Retrieve the corresponding session for a ChangeSet. More...

Detailed Description

This interface enables an application to interact with the resources hosted by the LWM2M Client Core.

The Core may be running as a separate process (daemon), or it may be linked with the application directly.

The Core hosts resources within a data model based on Objects, Object Instances and Resources. Please consult the LWM2M specification for details of this model.

A Management Application may interact with the Client via LWM2M, accessing the same resources. Therefore it is essential that both the Client Application and Management Application are aware of the same data model.

It is recommended that registered IDs are used for objects that conform to registered LWM2M objects such as IPSO objects.

Typedef Documentation

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

A user-specified callback handler for a Change Subscription which will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity has changed since the subscription's session callbacks were last dispatched.

Warning: Do NOT process any operations while inside a change callback!

Parameters

[in]	changeSet	A pointer to a valid ChangeSet.
[in]	context	A pointer to user-specified data passed to AwaClientChangeSubscription_New

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

A user-specified callback handler for an Execute Subscription which will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity has been executed since the subscription's session callbacks were last dispatched.

Warning: Do NOT process any operations while inside an execute callback!

Parameters

[in]	arguments	A pointer to arguments passed to the execution
[in]	context	A pointer to user-specified data passed to AwaClientChangeSubscription_New

Function Documentation

AwaClientSession* AwaClientSession_New ( void )

Initialise a new session of the Awa subsystem.

A Session is required for interaction with the Awa Core. Operations to interact with Core resources are created in the context of a session, however the session must be connected before an operation can be processed. The session is owned by the caller and should eventually be freed with AwaClientSession_Free.

Returns: Pointer to a new client session.; NULL on error.

Examples:: client-defineset-example.c, client-definition-iterator-example.c, client-delete-example.c, client-get-array-example.c, client-get-contains-path-example.c, client-get-example.c, client-set-array-example.c, client-set-create-example.c, client-set-example.c, client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

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

Configure the IPC mechanism used by the API to communicate with the Core.

This function configures the mechanism to use UDP with the Core located at the specified address and port.

Parameters

[in]	session	Pointer to the session that is to be configured.
[in]	address	Specifies the IP address or hostname to use to connect with the Core.
[in]	port	Specifies the Port number to use to connect with the Core.

Returns: AwaError_Success on success.; AwaError_IPCError if an IPC error occurs.; AwaError_SessionInvalid if the specified session is invalid.

AwaError AwaClientSession_SetDefaultTimeout	(	AwaClientSession *	session,
		AwaTimeout	timeout
	)

Set IPC connect timeout.

Used internally by AwaClientSession_Connect and AwaClientSession_Disconnect.

Parameters

[in]	session	Pointer to a valid client session.
[in]	timeout	The time within which an IPC session Connect must complete to avoid timeout. It must be greater than 0.

Returns: AwaError_Success on success.; Various errors on failure.

AwaError AwaClientSession_Connect ( AwaClientSession * session )

Connect a session (configured with an IPC mechanism) to the Core.

A session must be connected before operations can be processed.

Parameters

[in] session Pointer to an IPC-configured session.

Returns: AwaError_Success on success.; Various errors on failure.

Examples:: client-defineset-example.c, client-definition-iterator-example.c, client-delete-example.c, client-get-array-example.c, client-get-contains-path-example.c, client-get-example.c, client-set-array-example.c, client-set-create-example.c, client-set-example.c, client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaError AwaClientSession_Refresh ( AwaClientSession * session )

Object and Resource Definitions are assembled by the application and sent to the client daemon for storage (a process called "Define").

After successful definition, the application can shut down and the daemon will retain the definitions. Later, an application may wish to interact with these objects and resources. In order to do this in a type-safe manner, the Session must be aware of the definitions. Definitions will be held by the Session if DefineObject/DefineResource functions were used to successfully define objects and resources. If not, then the definitions must be retrieved with AwaClientSession_Refresh.

Parameters

[in] session A pointer to a valid session instance.

Returns: AwaError_Success on success.; AwaError_SessionInvalid if the specified session is invalid.

bool AwaClientSession_IsObjectDefined	(	const AwaClientSession *	session,
		AwaObjectID	objectID
	)

Determines whether the specified session holds a valid definition for the given object.

A session will hold a valid definition if the Core has a valid definition at the time the session was connected, or if a successful Define operation has been performed for this object.

Parameters

[in]	session	Pointer to a connected session.
[in]	objectID	Identifies the object for which the query is targeted.

Returns: True if object is defined.; False if object is not defined, or if the session is invalid.

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

Retrieves an object definition instance corresponding to the object identified by the given object ID.

The object definition is owned by the session and should not be freed by the caller.

Parameters

[in]	session	Pointer to a connected session.
[in]	objectID	Identifies the object for which the query is targeted.

Returns: A const pointer to an object definition instance, if it exists.; NULL if a definition for the object specified does not exist.

AwaObjectDefinitionIterator* AwaClientSession_NewObjectDefinitionIterator ( const AwaClientSession * session )

Retrieves a new object definition iterator that can be used to iterate through the set of defined objects within the context of the given session.

The iterator is owned by the caller and should eventually be freed with AwaObjectDefinitionIterator_Free.

Parameters

[in] session Pointer to a connected session.

Returns: A pointer to an object definition iterator, if the session is valid.; NULL if the session is not valid.

Examples:: client-definition-iterator-example.c.

AwaError AwaClientSession_Process	(	AwaClientSession *	session,
		AwaTimeout	timeout
	)

Process any incoming requests from the LWM2M Client.

Callbacks are scheduled on the session but are not invoked.

Parameters

[in]	session	Pointer to a connected session.
[in]	timeout	The function will wait at least as long as this value for a response.

Returns: AwaError_Success on success.; AwaError_Timeout if no response is received after the timeout duration expires.; Various errors on failure.

Examples:: client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaError AwaClientSession_DispatchCallbacks ( AwaClientSession * session )

Invoke any callbacks scheduled since this function was last called.

Parameters

[in] session Pointer to a connected session.

Returns: AwaError_Success on success.; Various errors on failure.

Examples:: client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaError AwaClientSession_Disconnect ( AwaClientSession * session )

When a session is no longer required, or if the application intends to sleep for some time, the session can be disconnected from the Core.

This maintains object and resource definition information, but prevents the processing of operations, or the reception of subscription notifications. The session can be reconnected to the Core with AwaClientSession_Connect. If a connected session is freed, it is automatically disconnected.

Parameters

[in] session Pointer to a connected session.

Returns: AwaError_Success on success.; AwaError_IPCError if the session is not configured.; AwaError_SessionNotConnected if the session is not connected.; AwaError_SessionInvalid if the session is invalid.

Examples:: client-defineset-example.c, client-definition-iterator-example.c, client-delete-example.c, client-get-array-example.c, client-get-contains-path-example.c, client-get-example.c, client-set-array-example.c, client-set-create-example.c, client-set-example.c, client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaError AwaClientSession_Free ( AwaClientSession ** session )

Shut down an existing session, freeing any allocated memory.

This function should eventually be called on every session to avoid a memory leak. If the session is connected, it will automatically be disconnected first.

Parameters

[in,out] session A pointer to a session pointer that will be set to NULL.

Returns: AwaError_Success on success.; AwaError_SessionInvalid if the session is not valid.

Examples:: client-defineset-example.c, client-definition-iterator-example.c, client-delete-example.c, client-get-array-example.c, client-get-contains-path-example.c, client-get-example.c, client-set-array-example.c, client-set-create-example.c, client-set-example.c, client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

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

Paths are used to identify objects, object instances and resources within the data model.

This function converts a path to equivalent object, object instance and resource IDs.

Parameters

[in]	session	Pointer to a valid session.
[in]	path	Resource path to convert.
[out]	objectID	Pointer to Object ID for result, or NULL to ignore.
[out]	objectInstanceID	Pointer to Object Instance ID for result, or NULL to ignore.
[out]	resourceID	Pointer to Resource ID for result, or NULL to ignore.

Returns: AwaError_Success on success; AwaError_PathInvalid if path is not in the correct form.; AwaError_PathNotFound if path is correctly formed but does not correspond with a defined entity.

AwaClientDefineOperation* AwaClientDefineOperation_New ( const AwaClientSession * session )

Allocate and return a pointer to a new Define operation, that can be used to define Objects and Resources.

The operation is owned by the caller and should eventually be freed with AwaClientDefineOperation_Free.

Object and Resource Definitions are assembled by the application and sent to the client daemon for storage (a process called "Define"). After successful definition, the application can shut down and the daemon will retain the definitions.

Later, an application may wish to interact with these objects and resources. In order to do this in a type-safe manner, the Session must be aware of the definition. Definitions will be held by the Session if DefineObject/DefineResource functions were used to successfully define objects and resources. If not, then the definition must be retrieved with SessionRefresh.

Parameters

[in] session A pointer to a valid session.

Returns: Pointer to a newly allocated Define operation instance.; NULL on failure.

Examples:: client-defineset-example.c.

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

Add an Object Definition to an existing Define operation, so that the client will create a suitable definition for this new object type.

Multiple object definitions can be added to a single Define operation provided they correspond to different objects. An existing object definition cannot be redefined via this API. Note: A copy of the Object Definition is made, therefore all resources in the object definition must be defined before calling this function, if all are to be included.

Parameters

[in]	operation	Pointer to a valid Define operation.
[in]	objectDefinition	Pointer to a valid Object Definition.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid or NULL.; AwaError_DefinitionInvalid if the object definition is invalid or NULL.; AwaError_AlreadyDefined if a definition already exists for the new object definition.

Examples:: client-defineset-example.c.

AwaError AwaClientDefineOperation_Perform	(	AwaClientDefineOperation *	operation,
		AwaTimeout	timeout
	)

Examples:: client-defineset-example.c.

AwaError AwaClientDefineOperation_Free ( AwaClientDefineOperation ** operation )

Clean up a Define operation, freeing all allocated resources.

Once freed, the operation is no longer valid.

Parameters

[in,out] operation A pointer to a Define operation pointer that will be set to NULL.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is not valid.

Examples:: client-defineset-example.c.

AwaClientGetOperation* AwaClientGetOperation_New ( const AwaClientSession * session )

Allocate and return a pointer to a new Get operation, that can be used to retrieve resource values from the Core.

Get operations can be loaded with one or more paths of interest, corresponding to resources or trees of resources that the application wishes to retrieve. When processed, the response is made available via AwaClientGetOperation_GetResponse and will contain the resources returned by the Core in response to the query. The Get operation is owned by the caller and should eventually be freed with AwaClientGetOperation_Free.

Parameters

[in] session A pointer to a valid session.

Returns: Pointer to a newly allocated Get operation instance.; NULL on failure.

Examples:: client-get-array-example.c, client-get-contains-path-example.c, and client-get-example.c.

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

Adds a path of interest to a Get operation, as a request to retrieve all resources at or covered by this path from the Core.

Adding an object path will retrieve all resources held by all object instances of this object. Adding an object instance path will retrieve all resources held by this object instance. Adding a resource path will retrieve that specific resource. Multiple-instance resources are retrieved in their entirety (the entire array is retrieved), however array ranges can be retrieved with AwaClientGetOperation_AddPathWithArrayRange. Adding a path that does not correspond to any resources in the Core will result in the subsequent GetResponse lacking resources for that path.

Parameters

[in]	operation	The Get operation to add the path of interest to.
[in]	path	The path of the resource, object instance or object requested for retrieval.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the path specified is not a valid data model path.

Examples:: client-get-array-example.c, client-get-contains-path-example.c, and client-get-example.c.

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

Add a resource path to a multiple-instance resource and specify a range of resource instances to retrieve.

The path must correspond to a resource path; object and object instance paths are not permitted. Only valid instances in this range are retrieved - unpopulated instances are ignored - so the number of instances in the GetResponse may be less than the width of the range.

Parameters

[in]	operation	The Get operation to add the multiple-instance resource path to.
[in]	path	The path of the multiple-instance resource to retrieve.
[in]	startIndex	Array index to begin retrieval from.
[in]	indexCount	Number of array indices to retrieve, including unpopulated indices.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the path specified is not a valid data model path.; AwaError_AddInvalid if the path specified is not suitable for this function.

AwaError AwaClientGetOperation_Perform	(	AwaClientGetOperation *	operation,
		AwaTimeout	timeout
	)

Process the Get operation by sending it to the Core.

If successful, the response can be obtained with AwaClientGetOperation_GetResponse and queried for retrieved resource values.

Parameters

[in]	operation	The Get operation to process.
[in]	timeout	The function will wait at least as long as this value for a response.

Returns: AwaError_Success on success.; AwaError_Timeout if no response is received after the timeout duration expires.; Various errors on failure.

Examples:: client-get-array-example.c, client-get-contains-path-example.c, and client-get-example.c.

AwaError AwaClientGetOperation_Free ( AwaClientGetOperation ** operation )

Clean up a Get operation, freeing all allocated resources.

Once freed, the operation is no longer valid. Note: freeing a Get operation will invalidate all derived Get Response instances, and any Opaque or CString pointers retrieved from an associated Get Response.

Parameters

[in,out] operation A pointer to a Get operation pointer that will be set to NULL.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is not valid.

Examples:: client-get-array-example.c, client-get-contains-path-example.c, and client-get-example.c.

const AwaClientGetResponse* AwaClientGetOperation_GetResponse ( const AwaClientGetOperation * operation )

Obtain a Get Response instance from a processed Get operation.

This may be queried directly by path to obtain the resource values returned by the Core. A Path iterator can be used to obtain a list of all resource paths provided by the Get Response. The Get Response is owned by the Get operation and should not be freed by the caller.

Parameters

[in] operation The processed Get operation to obtain the Get response from.

Returns: Pointer to AwaClientGetResponse if operation is valid and has a valid response.; NULL if the operation is invalid, or has no valid response (may not have been processed).

Examples:: client-get-array-example.c, client-get-contains-path-example.c, and client-get-example.c.

AwaPathIterator* AwaClientGetResponse_NewPathIterator ( const AwaClientGetResponse * response )

Create a new Path Iterator for a Get Response, used to iterate through the list of resource paths retrieved by the corresponding Get operation.

The resulting iterator is owned by the caller and should eventually be freed with AwaPathIterator_Free. This function can only be successful after a Get operation has been successfully processed.

Parameters

[in] response A pointer to the Get Response to search.

Returns: A pointer to a new PathIterator instance on success.; NULL on failure.

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

Test if the Get Response has the specified path (resource, object instance or object) present.

If the Get Response contains paths beyond the specified path, the path will be considered present. This function can only be successful after a Get operation has been successfully processed.

Parameters

[in]	response	A pointer to a valid Get Response.
[in]	path	The path with which to query the Get Response.

Returns: True if the Get Response contains the specified resource path.; False if the Get Response does not contain the specified resource path, or if the path is invalid.

Examples:: client-get-contains-path-example.c.

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

Retrieve a path result from a Get Response relating to a write to that path retrieved by the corresponding Get Operation.

Querying the path result will allow the caller to determine the status of a request to define objects and resources.

Parameters

[in]	response	A pointer to the Get Response to search.
[in]	path	A path to an entity that was written to.

Returns: NULL if no definition exists in the Get response for the specified path, or if the response, path or result is NULL.; Pointer to PathResult instance. Do not free.

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

Test if the Get Response has a value for the specified resource path.

If the Get Response contains a value for the specified path, and the Resource Type is known, it can be retrieved with the appropriate AwaClientGetResponse_GetValueAs_ function. This function can only be successful after a Get operation has been successfully processed.

Parameters

[in]	response	A pointer to a valid Get Response.
[in]	path	The path with which to query the Get Response.

Returns: True if the Get Response contains a value for the specified resource path.; False if the Get Response does not contain a value for the specified resource path, or if the path is invalid.

Examples:: client-get-contains-path-example.c.

AwaError AwaClientGetResponse_GetValueAsOpaque	(	const AwaClientGetResponse *	response,
		const char *	path,
		AwaOpaque *	value
	)

Retrieve an opaque resource's value from a Get Response.

The resource is identified by the path. This function can only be successful after a Get operation has been successfully processed. A pointer to a AwaOpaque struct is passed in and populated by the function. The data pointer within the AwaOpaque struct is only valid as long as the Get operation remains valid. If the operation is freed, the data pointer is immediately invalid and should not be used or dereferenced.

Parameters

[in]	response	The current Get Response to retrieve the value from.
[in]	path	The path of the opaque resource requested for retrieval.
[in,out]	value	A pointer to a AwaOpaque struct that will be modified to refer to the requested opaque value.

Returns: AwaError_Success on success.; AwaError_TypeMismatch if the resource type corresponding to the specified path is not of type AwaResourceType_Opaque.; AwaError_PathNotFound if the specified resource path is not covered by the Get Response.; AwaError_OperationInvalid if the specified operation is invalid or NULL.; AwaError_PathInvalid if the specified path is invalid or does not correspond to a resource path.

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

Retrieve an object link resource's value from a Get Response.

The resource is identified by the path. This function can only be successful after a Get operation has been successfully processed. A pointer to a AwaObjectLink struct is passed in and populated by the function.

Parameters

[in]	response	The current Get Response to retrieve the value from.
[in]	path	The path of the object link resource requested for retrieval.
[in,out]	value	A pointer to a AwaObjectLink struct that will be modified to hold the requested object link value.

Returns: AwaError_Success on success.; AwaError_TypeMismatch if the resource type corresponding to the specified path is not of type AwaResourceType_ObjectLink.; AwaError_PathNotFound if the specified resource path is not covered by the Get Response.; AwaError_OperationInvalid if the specified operation is invalid or NULL.; AwaError_PathInvalid if the specified path is invalid or does not correspond to a resource path.

AwaClientSetOperation* AwaClientSetOperation_New ( const AwaClientSession * session )

Allocate and return a pointer to a new Set Operation, that can be used to set resource values.

Optional resources can be created, taking the default value or set to a new value. New object instances can be created, automatically creating all covered mandatory resources. Set Operations can be loaded with one or more resource paths with corresponding value. The Set Operation is owned by the caller and should eventually be freed with AwaClientSetOperation_Free.

Parameters

[in] session A pointer to a valid session.

Returns: A pointer to a newly allocated Set Operation instance.; NULL on failure.

Examples:: client-set-array-example.c, client-set-create-example.c, client-set-example.c, and client-subscribe-to-change-example.c.

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

Adds an object or object instance path to a Set Operation, as a request to create an Object Instance.

The target object must support creation of a new object instance, such as supporting multiple instances, or an optional instance that does not exist. When the operation is processed, if the object instance ID is specified in the path, the object instance requested will be created (or an error returned if it already exists). If the object instance ID is not specified in the path, the ID will be automatically assigned by the Core if the instance can be created.

Parameters

[in]	operation	The Set Operation to add the path of interest to.
[in]	path	The path of the object or object instance requested for object instance creation.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the specified path is invalid.

Examples:: client-set-array-example.c, and client-set-create-example.c.

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

Adds a resource path to a Set Operation, as a request to create an optional Resource.

When the operation is processed, if the path refers to an optional resource that does not exist, the resource will be created. The resource will have the default value assigned, if not set to another value in the same operation.

Parameters

[in]	operation	The Set Operation to add the path of interest to.
[in]	path	The path of the resource requested for optional resource creation.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the specified path is invalid.

Examples:: client-set-array-example.c, and client-set-create-example.c.

AwaError AwaClientSetOperation_Perform	(	AwaClientSetOperation *	operation,
		AwaTimeout	timeout
	)

Process the Set Operation by sending it to the Core.

Parameters

[in]	operation	The Set Operation to process.
[in]	timeout	The function will wait at least as long as this value for a response.

Returns: AwaError_Success on success.; AwaError_Timeout if no response is received after the timeout duration expires.; Various errors on failure.

Examples:: client-set-array-example.c, client-set-create-example.c, client-set-example.c, and client-subscribe-to-change-example.c.

const AwaClientSetResponse* AwaClientSetOperation_GetResponse ( const AwaClientSetOperation * operation )

Obtain a Set Response instance from a processed Set Operation.

This may be iterated through to determine whether the set operation succeeded for the requested paths. The Set Response is owned by the Set Operation and should not be freed by the caller.

Parameters

[in] operation The processed Set Operation to obtain the Set response from.

Returns: Pointer to AwaClientSetResponse if operation is valid and has a valid response.; NULL if the operation is invalid, or has no valid response (may not have been processed).

AwaError AwaClientSetOperation_Free ( AwaClientSetOperation ** operation )

Clean up a Set Operation, freeing all allocated resources.

Once freed, the operation is no longer valid.

Parameters

[in,out] operation A pointer to a Set Operation pointer that will be set to NULL.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is not valid.

Examples:: client-set-array-example.c, client-set-create-example.c, client-set-example.c, and client-subscribe-to-change-example.c.

AwaPathIterator* AwaClientSetResponse_NewPathIterator ( const AwaClientSetResponse * response )

Create a new Path Iterator for a Set Response, used to iterate through the list of paths returned in the response of the corresponding Set Operation.

The resulting iterator is owned by the caller and should eventually be freed with AwaPathIterator_Free. This function can only be successful after a Set Operation has been successfully processed.

Parameters

[in] response A pointer to the Set Response to search.

Returns: A pointer to a new PathIterator instance on success.; NULL on failure.

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

Retrieve a path result from a Set Response relating to a write to that path retrieved by the corresponding Set Operation.

Querying the path result will allow the caller to determine the status of a request to define objects and resources.

Parameters

[in]	response	A pointer to the Set Response to search.
[in]	path	A path to an entity that was written to.

Returns: NULL if no definition exists in the Set response for the specified path, or if the response, path or result is NULL.; Pointer to PathResult instance. Do not free.

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

Test if the Set Response has the specified path to a resource or object present.

If the Set Response contains paths beyond the specified path, the path will be considered present.

Parameters

[in]	response	A pointer to a valid Set Response.
[in]	path	The path with which to query the Set Response.

Returns: True if the Set Response contains the specified resource path.; False if the Set Response does not contain the specified resource path, or if the path is invalid.

AwaClientDeleteOperation* AwaClientDeleteOperation_New ( const AwaClientSession * session )

Allocate and return a pointer to a new Delete operation, that can be used to delete optional resources, resource instances, and object instances.

Parameters

[in] session A pointer to a valid session instance.

Returns: A pointer to a newly allocated Delete operation instance, or NULL on failure.

Examples:: client-delete-example.c.

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

Adds a path to a Delete operation, as a request to delete the specified resource or object instance.

Parameters

[in]	operation	A pointer to a valid delete operation.
[in]	path	The path of the resource, resource instance or object instance requested to delete.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the specified path is invalid.; AwaError_NotDefined if the specified path refers to an object or resource that is not defined.

Examples:: client-delete-example.c.

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

Add a path to a multiple-instance resource and specify a range of resource instances to delete.

Parameters

[in]	operation	The Delete operation to add a delete request to.
[in]	path	The path of the resource to delete.
[in]	startIndex	Array index to begin deletion from.
[in]	indexCount	Number of array indices to delete, including missing items.

Returns: AwaError_Success on success.; AwaError_AddInvalid if startIndex is negative, indexCount is less than one or greater than AWA_MAX_ID; AwaError_OperationInvalid if the operation is invalid.; AwaError_PathInvalid if the specified path is invalid.; AwaError_NotDefined if the specified path refers to an object or resource that is not defined.

AwaError AwaClientDeleteOperation_Perform	(	AwaClientDeleteOperation *	operation,
		AwaTimeout	timeout
	)

Process the Delete operation by sending it to the Core.

Parameters

[in]	operation	The Delete operation to process.
[in]	timeout	The function will wait at least as long as this value for a response.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_Timeout if no response is received after the timeout duration expires.; Various errors on failure.

Examples:: client-delete-example.c.

const AwaClientDeleteResponse* AwaClientDeleteOperation_GetResponse ( const AwaClientDeleteOperation * operation )

Obtain a Delete Response instance from a processed Delete operation.

This may be iterated through to determine whether the delete operation succeeded for the requested paths. The Delete Response is owned by the Delete operation and should not be freed by the caller.

Parameters

[in] operation The processed Delete operation to obtain the Delete response from.

Returns: Pointer to AwaClientDeleteResponse if operation is valid and has a valid response.; NULL if the operation is invalid, or has no valid response (may not have been processed).

AwaError AwaClientDeleteOperation_Free ( AwaClientDeleteOperation ** operation )

Shut down an existing operation, freeing any allocated memory.

This function should eventually be called on every operation to avoid a memory leak. Any pointers from GetValueAs*Pointer() functions will be invalid after this call.

Parameters

[in,out] operation A pointer to a operation pointer, which will be set to NULL by this function.

Returns: AwaError_Success on success; Error_OperationInvalid if the operation is not valid.

Examples:: client-delete-example.c.

AwaPathIterator* AwaClientDeleteResponse_NewPathIterator ( const AwaClientDeleteResponse * response )

Create a new Path Iterator for a Delete Response, used to iterate through the list of resource paths retrieved by the corresponding Delete operation.

The resulting iterator is owned by the caller and should eventually be freed with AwaPathIterator_Free. This function can only be successful after a Delete operation has been successfully processed.

Parameters

[in] response A pointer to the Delete Response to search.

Returns: A pointer to a new PathIterator instance on success.; NULL on failure.

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

Retrieve a path result from a Delete Response relating to a subscription to that path retrieved by the corresponding Delete operation.

Querying the path result will allow the caller to determine the status of a request to delete an object or object instance.

Parameters

[in]	response	A pointer to the Delete Response to search.
[in]	path	A path to an entity that was requested to be deleted.

Returns: NULL if no definition exists in the Delete response for the specified path, or if the response, path or result is NULL.; Pointer to PathResult instance. Do not free.

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

Test if the Delete Response has the specified path (object instance or object) present.

If the Delete Response contains paths beyond the specified path, the path will be considered present. This function can only be successful after a Delete operation has been successfully processed.

Parameters

[in]	response	A pointer to a valid Delete Response.
[in]	path	The path with which to query the Delete Response.

Returns: True if the Delete Response contains the specified resource path.; False if the Delete Response does not contain the specified resource path, or if the path is invalid.

AwaClientSubscribeOperation* AwaClientSubscribeOperation_New ( const AwaClientSession * session )

Allocate and return a pointer to a new Subscribe operation, that can be used to subscribe to executions of resources and changes to objects, object instances and resource values from the Core.

Subscribe operations can be loaded with one or more paths of interest, corresponding to resources or trees of resources that the application wishes to subscribe to. When processed, the response is made available via AwaClientSubscribeOperation_GetResponse and will contain result information for each of the paths returned by the Core in response to the query. The Subscribe operation is owned by the caller and should eventually be freed with AwaClientSubscribeOperation_Free.

Parameters

[in] session A pointer to a valid session.

Returns: Pointer to a newly allocated Subscribe operation instance.; NULL on failure.

Examples:: client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaError AwaClientSubscribeOperation_AddChangeSubscription	(	AwaClientSubscribeOperation *	operation,
		AwaClientChangeSubscription *	subscription
	)

Adds a Change Subscription of interest to a Subscribe operation, as a request to be notified of changes to the subscribed entity from the Core.

Parameters

[in]	operation	The Subscribe operation to add the path of interest to.
[in]	subscription	A valid Change subscription to an entity of interest.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_SubscriptionInvalid if the subscription is invalid.

Examples:: client-subscribe-to-change-example.c.

AwaError AwaClientSubscribeOperation_AddExecuteSubscription	(	AwaClientSubscribeOperation *	operation,
		AwaClientExecuteSubscription *	subscription
	)

Adds a Execute Subscription of interest to a Subscribe operation, as a request to be notified of executions of the subscribed entity from the Core.

Parameters

[in]	operation	The Subscribe operation to add the path of interest to.
[in]	subscription	A valid Execute subscription to an entity of interest.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_SubscriptionInvalid if the subscription is invalid.

Examples:: client-subscribe-to-execute-example.c.

AwaError AwaClientSubscribeOperation_AddCancelChangeSubscription	(	AwaClientSubscribeOperation *	operation,
		AwaClientChangeSubscription *	subscription
	)

Adds a Cancel flag to a Change Subscription in a specified Subscribe operation, as a request to cancel being notified of changes to the subscribed entity from the Core.

Parameters

[in]	operation	The Subscribe operation to add the path of interest to.
[in]	subscription	A valid Change subscription to an entity of interest.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_SubscriptionInvalid if the subscription is invalid.

Examples:: client-subscribe-to-change-example.c.

AwaError AwaClientSubscribeOperation_AddCancelExecuteSubscription	(	AwaClientSubscribeOperation *	operation,
		AwaClientExecuteSubscription *	subscription
	)

Adds a Cancel flag to a Execute Subscription in a specified Subscribe operation, as a request to cancel being notified of executions of the subscribed entity from the Core.

Parameters

[in]	operation	The Subscribe operation to add the path of interest to.
[in]	subscription	A valid Execute subscription to an entity of interest.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is invalid.; AwaError_SubscriptionInvalid if the subscription is invalid.

Examples:: client-subscribe-to-execute-example.c.

AwaError AwaClientSubscribeOperation_Perform	(	AwaClientSubscribeOperation *	operation,
		AwaTimeout	timeout
	)

Process the Subscribe operation by sending it to the Core, notifying the Core to begin or cancel subscription to changes and executions of the subscribed entities inside the specified Subscribe operation.

If successful, the response can be obtained with AwaClientSubscribeOperation_GetResponse and queried for path results, each of which relate to the result of a single request to begin or cancel a subscription.

Parameters

[in]	operation	The Subscribe operation to process.
[in]	timeout	The function will wait at least as long as this value for a response.

Returns: AwaError_Success on success.; AwaError_Timeout if no response is received after the timeout duration expires.; Various errors on failure.

Examples:: client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

const AwaClientSubscribeResponse* AwaClientSubscribeOperation_GetResponse ( const AwaClientSubscribeOperation * operation )

Obtain a Subscribe Response instance from a processed Subscribe operation.

This may be queried directly by path to obtain results of a subscription request returned by the Core. A Path iterator can be used to obtain a list of all subscription paths provided by the Subscribe Response. The Subscribe Response is owned by the Subscribe operation and should not be freed by the caller.

Parameters

[in] operation The processed Subscribe operation to obtain the Subscribe response from.

Returns: Pointer to AwaClientSubscribeResponse if operation is valid and has a valid response.; NULL if the operation is invalid, or has no valid response (may not have been processed).

AwaError AwaClientSubscribeOperation_Free ( AwaClientSubscribeOperation ** operation )

Clean up a Subscribe operation, freeing all allocated resources.

Once freed, the operation is no longer valid. Note: freeing a Subscribe operation will invalidate all derived Subscribe Response instances.

Parameters

[in,out] operation A pointer to a Subscribe operation pointer that will be set to NULL.

Returns: AwaError_Success on success.; AwaError_OperationInvalid if the operation is not valid.

Examples:: client-subscribe-to-change-example.c, and client-subscribe-to-execute-example.c.

AwaPathIterator* AwaClientSubscribeResponse_NewPathIterator ( const AwaClientSubscribeResponse * response )

Create a new Path Iterator for a Subscribe Response, used to iterate through the list of paths relating to results of subscriptions retrieved by the corresponding Subscribe operation.

The resulting iterator is owned by the caller and should eventually be freed with AwaPathIterator_Free. This function can only be successful after a Subscribe operation has been successfully processed.

Parameters

[in] response A pointer to the Subscribe Response to search.

Returns: A pointer to a new PathIterator instance on success.; NULL on failure.

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

Retrieve a path result from a Subscribe Response relating to a subscription to that path retrieved by the corresponding Subscribe operation.

Querying the path result will allow the caller to determine the status of a request to begin or cancel a subscription to an entity.

Parameters

[in]	response	A pointer to the Subscribe Response to search.
[in]	path	A path to an entity that was subscribed to.

Returns: NULL if no subscription exists in the subscribe response for the specified path, or if the response, path or result is NULL.; Pointer to PathResult instance. Do not free.

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

Allocate and return a pointer to a new Change Subscription, that can be used to subscribe to changes on either a resource, object instance or object.

The specified callback function will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity has changed since the session callbacks were last dispatched. The Change Subscription will not be active until it is added to a subscribe operation and performed. Operations can be created within a callback, but they cannot be performed. The Change Subscription is owned by the caller and should eventually be freed with AwaClientChangeSubscription_Free.

Parameters

[in]	path	The path of the resource, object instance or object to subscribe to.
[in]	callback	Pointer to function to call when the entity specified by path is created, changed or deleted.
[in]	context	A pointer to a user specified object for use in the change callback

Returns: A pointer to a newly allocated Change Subscription instance.; NULL on failure.

Examples:: client-subscribe-to-change-example.c.

const char* AwaClientChangeSubscription_GetPath ( AwaClientChangeSubscription * subscription )

Retrieve the path from a Change subscription.

Parameters

[in] subscription A valid Change subscription.

Returns: The subscription's path if the subscription is valid.; NULL if the subscription is not valid.

AwaError AwaClientChangeSubscription_Free ( AwaClientChangeSubscription ** subscription )

Shut down a Change Subscription, freeing any allocated memory.

This function should eventually be called on every operation to avoid a memory leak.

Parameters

[in,out] subscription A pointer to a Change Subscription pointer, which will be set to NULL by this function.

Returns: AwaError_Success on success; AwaError_SubscriptionInvalid if the operation is not valid.

Examples:: client-subscribe-to-change-example.c.

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

Allocate and return a pointer to a new Execute Subscription, that can be used to subscribe to executions of a resource, or all resources of an object instance or object.

The specified callback function will be fired on AwaClientSession_DispatchCallbacks if the subscribed entity or its children have been executed since the session callbacks were last dispatched. The Execute Subscription will not be active until it is added to a subscribe operation and performed. The Execute Subscription is owned by the caller and should eventually be freed with AwaClientExecuteSubscription_Free.

Parameters

[in]	path	The path of the resource, object instance or object to subscribe to.
[in]	callback	Pointer to function to call when the entity specified by path or its children are executed.
[in]	context	A pointer to a user specified object for use in the change callback

Returns: A pointer to a newly allocated Change Subscription instance.; NULL on failure.

Examples:: client-subscribe-to-execute-example.c.

const char* AwaClientExecuteSubscription_GetPath ( AwaClientExecuteSubscription * subscription )

Retrieve the path from a Execute subscription.

Parameters

[in] subscription A valid Execute subscription.

Returns: The subscription's path if the subscription is valid.; NULL if the subscription is not valid.

AwaError AwaClientExecuteSubscription_Free ( AwaClientExecuteSubscription ** subscription )

Shut down an Execute Subscription, freeing any allocated memory.

This function should eventually be called on every operation to avoid a memory leak.

Parameters

[in,out] subscription A pointer to an Execute Subscription pointer, which will be set to NULL by this function.

Returns: AwaError_Success on success; Error_OperationInvalid if the operation is not valid.

Examples:: client-subscribe-to-execute-example.c.

const AwaClientSession* AwaChangeSet_GetClientSession ( const AwaChangeSet * changeSet )

Retrieve the corresponding session for a ChangeSet.

This function is only valid for a ChangeSet connected to a client session.

Parameters

[in] changeSet A pointer to a valid ChangeSet.

Returns: The session for the given ChangeSet.; NULL if the ChangeSet is invalid.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation