Asynchronous Watching

The following functions allow to asynchronously watch for changes to an item:

NXLIB_WATCH_CALLBACK

typedef void (*NXLIB_WATCH_CALLBACK)(int32_t result, int32_t handle, const char *currentValuePath, void *userData)

A callback for asynchronous watches. Executed when an asynchronous watch succeeds or gets canceled.

If the registration function returned a valid handle, the callback function is guaranteed to be executed at least once, even if the operation gets canceled. If the operation gets canceled (either from nxLibCancelWatch or when the NxLib gets finalized) the function will be called with result set to NxLibOperationCanceled.

A non-permanent callback gets executed exactly once with result set to either a successful or a non-successful return code. A permanent callback gets executed exactly once with result set to a non-successful return code after any number of executions with a successful return code.

The function gets called from an unspecified thread of the NxLib. It should not perform much work in this thread to avoid blocking other accesses and watches in the NxLib.

Using the NxLib from the callback is not allowed when result is NxLibOperationCanceled and the NxLib is getting finalized at the same time.

The behavior is undefined if exceptions escape from the callback.

Param result

An error code describing the result of the watch. NxLibOperationSucceeded if the watch condition was satisfied. NxLibItemInexistent if the NxLib item was removed. NxLibOperationCanceled if the operation was canceled.

Param handle

A handle for the asynchronous watch. Can be used to cancel the watch with nxLibCancelWatch.

Param currentValuePath

A path to a special JSON item that contains the value of the watched item directly after it was changed. The value can be read through the normal NxLib API. Values in this path are read-only and only available from the callback. If there is no JSON value to access (e.g. because result is not NxLibOperationSucceeded), any access to the path will return an NxLibItemInexistent error code. In NxLibRemote this parameter is currently not supported and always contains an inexistent path.

Param userData

The user data that was given to the function setting up the asynchronous watch.

nxLibWatchForChange

int32_t nxLibWatchForChange(int32_t *result, const char *itemPath, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for any change to the specified item, i.e. a change of value or item type. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibWatchForType

int32_t nxLibWatchForType(int32_t *result, const char *itemPath, int32_t type, int32_t watchForEqual, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for the type of the specified item to change. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • type – The constant corresponding to the type to watch for. See also nxLibGetType().

  • watchForEqual – When true, the function watches until the item has the specified type, otherwise it watches until the item has a different type than the one specified.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibWatchForBoolValue

int32_t nxLibWatchForBoolValue(int32_t *result, const char *itemPath, int32_t value, int32_t watchForEqual, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for the specified item to contain a specific boolean value. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • value – The value to watch for.

  • watchForEqual – When true, the function watches until the item has the specified value, otherwise it watches until the item has a different value than the one specified.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibWatchForIntValue

int32_t nxLibWatchForIntValue(int32_t *result, const char *itemPath, int32_t value, int32_t watchForEqual, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for the specified item to contain a specific integer value. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • value – The value to watch for.

  • watchForEqual – When true, the function watches until the item has the specified value, otherwise it watches until the item has a different value than the one specified.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibWatchForDoubleValue

int32_t nxLibWatchForDoubleValue(int32_t *result, const char *itemPath, double value, int32_t watchForEqual, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for the specified item to contain a specific double value. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • value – The value to watch for.

  • watchForEqual – When true, the function watches until the item has the specified value, otherwise it watches until the item has a different value than the one specified.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibWatchForStringValue

int32_t nxLibWatchForStringValue(int32_t *result, const char *itemPath, const char *value, int32_t watchForEqual, int32_t permanent, NXLIB_WATCH_CALLBACK callback, void *userData)

Watch for the specified item to contain a specific string value. The function only sets up the callback and returns immediately afterwards.

The callback will be executed when the item changes or when the watch is canceled. See NXLIB_WATCH_CALLBACK for details.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibInvalidParameters - One, multiple, or a combination of parameters are invalid.

    • NxLibItemInexistent - The item at the given path does not exist.

    • NxLibItemPathInvalid - The given path contains forbidden characters.

    • NxLibItemTypeNotCompatible - The item type you tried to read is of another type than you specified or the item you tried to write cannot be overwritten with the type you specified because its structure is locked.

  • itemPath – The path of the item to watch for.

  • value – The value to watch for.

  • watchForEqual – When true, the function watches until the item has the specified value, otherwise it watches until the item has a different value than the one specified.

  • permanent – Whether to continue watching for further changes after the first change. The callback gets executed once for each change.

  • callback – The callback to execute when the item changes or the watch gets canceled.

  • userData – Additional user data to pass to the callback.

Returns

A handle for the asynchronous watch. Can be passed to nxLibCancelWatch to cancel the watch. When the operation fails it returns NXLIB_INVALID_WATCH_HANDLE alongside the error code.

nxLibCancelWatch

void nxLibCancelWatch(int32_t *result, int32_t handle)

Cancel the asynchronous watch with the given handle. The callback for the asynchronous watch is executed once with an NxLibOperationCanceled error code.

Parameters

  • result – A pointer to a variable for the return code of the operation. The following function specific return codes can occur:

    • NxLibItemInexistent - The item at the given path does not exist.

  • handle – The handle for the asynchronous watch returned by the function which started it.