client.h File Reference

#include <open62541/types.h>
#include <open62541/common.h>
#include <open62541/util.h>
#include <open62541/plugin/log.h>
#include <open62541/plugin/eventloop.h>
#include <open62541/plugin/securitypolicy.h>

Go to the source code of this file.

Data Structures
struct	UA_ClientConfig

Macros
#define	UA_Client_removeRepeatedCallback(server, callbackId)    UA_Client_removeCallback(server, callbackId);

Typedefs
typedef struct UA_ClientConfig	UA_ClientConfig
typedef void(*	UA_ClientAsyncServiceCallback) (UA_Client *client, void *userdata, UA_UInt32 requestId, void *response)
typedef void(*	UA_ClientCallback) (UA_Client *client, void *data)

Functions
UA_EXPORT UA_StatusCode	UA_ClientConfig_copy (UA_ClientConfig const *src, UA_ClientConfig *dst)
UA_EXPORT void	UA_ClientConfig_delete (UA_ClientConfig *config)
UA_EXPORT void	UA_ClientConfig_clear (UA_ClientConfig *config)
UA_EXPORT UA_Client *	UA_Client_new (void)
UA_Client *	UA_Client_newWithConfig (const UA_ClientConfig *config)
void UA_THREADSAFE	UA_Client_getState (UA_Client *client, UA_SecureChannelState *channelState, UA_SessionState *sessionState, UA_StatusCode *connectStatus)
UA_EXPORT UA_ClientConfig *	UA_Client_getConfig (UA_Client *client)
void	UA_Client_delete (UA_Client *client)
UA_EXPORT UA_StatusCode	UA_Client_getConnectionAttribute (UA_Client *client, const UA_QualifiedName key, UA_Variant *outValue)
UA_EXPORT UA_StatusCode UA_THREADSAFE	UA_Client_getConnectionAttributeCopy (UA_Client *client, const UA_QualifiedName key, UA_Variant *outValue)
UA_EXPORT UA_StatusCode	UA_Client_getConnectionAttribute_scalar (UA_Client *client, const UA_QualifiedName key, const UA_DataType *type, void *outValue)
UA_StatusCode UA_THREADSAFE	__UA_Client_connect (UA_Client *client, UA_Boolean async)
UA_StatusCode	UA_Client_startListeningForReverseConnect (UA_Client *client, const UA_String *listenHostnames, size_t listenHostnamesLength, UA_UInt16 port)
UA_StatusCode UA_THREADSAFE	UA_Client_disconnect (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_disconnectAsync (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_disconnectSecureChannel (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_disconnectSecureChannelAsync (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_getSessionAuthenticationToken (UA_Client *client, UA_NodeId *authenticationToken, UA_ByteString *serverNonce)
UA_StatusCode UA_THREADSAFE	UA_Client_activateCurrentSession (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_activateCurrentSessionAsync (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_activateSession (UA_Client *client, const UA_NodeId authenticationToken, const UA_ByteString serverNonce)
UA_StatusCode UA_THREADSAFE	UA_Client_activateSessionAsync (UA_Client *client, const UA_NodeId authenticationToken, const UA_ByteString serverNonce)
UA_StatusCode UA_THREADSAFE	UA_Client_getEndpoints (UA_Client *client, const char *serverUrl, size_t *endpointDescriptionsSize, UA_EndpointDescription **endpointDescriptions)
UA_StatusCode UA_THREADSAFE	UA_Client_findServers (UA_Client *client, const char *serverUrl, size_t serverUrisSize, UA_String *serverUris, size_t localeIdsSize, UA_String *localeIds, size_t *registeredServersSize, UA_ApplicationDescription **registeredServers)
UA_StatusCode UA_THREADSAFE	UA_Client_findServersOnNetwork (UA_Client *client, const char *serverUrl, UA_UInt32 startingRecordId, UA_UInt32 maxRecordsToReturn, size_t serverCapabilityFilterSize, UA_String *serverCapabilityFilter, size_t *serverOnNetworkSize, UA_ServerOnNetwork **serverOnNetwork)
void UA_THREADSAFE	__UA_Client_Service (UA_Client *client, const void *request, const UA_DataType *requestType, void *response, const UA_DataType *responseType)
UA_StatusCode UA_THREADSAFE	__UA_Client_AsyncService (UA_Client *client, const void *request, const UA_DataType *requestType, UA_ClientAsyncServiceCallback callback, const UA_DataType *responseType, void *userdata, UA_UInt32 *requestId)
UA_EXPORT UA_THREADSAFE UA_StatusCode	UA_Client_cancelByRequestHandle (UA_Client *client, UA_UInt32 requestHandle, UA_UInt32 *cancelCount)
UA_EXPORT UA_THREADSAFE UA_StatusCode	UA_Client_cancelByRequestId (UA_Client *client, UA_UInt32 requestId, UA_UInt32 *cancelCount)
UA_StatusCode UA_THREADSAFE	UA_Client_modifyAsyncCallback (UA_Client *client, UA_UInt32 requestId, void *userdata, UA_ClientAsyncServiceCallback callback)
UA_StatusCode UA_THREADSAFE	UA_Client_run_iterate (UA_Client *client, UA_UInt32 timeout)
UA_StatusCode UA_THREADSAFE	UA_Client_renewSecureChannel (UA_Client *client)
UA_StatusCode UA_THREADSAFE	UA_Client_addTimedCallback (UA_Client *client, UA_ClientCallback callback, void *data, UA_DateTime date, UA_UInt64 *callbackId)
UA_StatusCode UA_THREADSAFE	UA_Client_addRepeatedCallback (UA_Client *client, UA_ClientCallback callback, void *data, UA_Double interval_ms, UA_UInt64 *callbackId)
UA_StatusCode UA_THREADSAFE	UA_Client_changeRepeatedCallbackInterval (UA_Client *client, UA_UInt64 callbackId, UA_Double interval_ms)
void UA_THREADSAFE	UA_Client_removeCallback (UA_Client *client, UA_UInt64 callbackId)
UA_EXPORT const UA_DataType *	UA_Client_findDataType (UA_Client *client, const UA_NodeId *typeId)

Macro Definition Documentation

UA_Client_removeRepeatedCallback

#define UA_Client_removeRepeatedCallback	(		server,
			callbackId
	)		UA_Client_removeCallback(server, callbackId);

Definition at line 786 of file client.h.

Typedef Documentation

UA_ClientAsyncServiceCallback

typedef void(* UA_ClientAsyncServiceCallback) (UA_Client *client, void *userdata, UA_UInt32 requestId, void *response)

Definition at line 684 of file client.h.

UA_ClientCallback

typedef void(* UA_ClientCallback) (UA_Client *client, void *data)

Definition at line 741 of file client.h.

UA_ClientConfig

typedef struct UA_ClientConfig UA_ClientConfig

Definition at line 32 of file client.h.

Function Documentation

__UA_Client_AsyncService()

UA_StatusCode UA_THREADSAFE __UA_Client_AsyncService	(	UA_Client *	client,
		const void *	request,
		const UA_DataType *	requestType,
		UA_ClientAsyncServiceCallback	callback,
		const UA_DataType *	responseType,
		void *	userdata,
		UA_UInt32 *	requestId
	)

__UA_Client_connect()

UA_StatusCode UA_THREADSAFE __UA_Client_connect	(	UA_Client *	client,
		UA_Boolean	async
	)

Connect with the client configuration.

For the async connection, finish connecting via UA_Client_run_iterate (or manually running a configured external EventLoop).

__UA_Client_Service()

void UA_THREADSAFE __UA_Client_Service	(	UA_Client *	client,
		const void *	request,
		const UA_DataType *	requestType,
		void *	response,
		const UA_DataType *	responseType
	)

Don't use this function.

Use the type versions below instead.

UA_Client_activateCurrentSession()

UA_StatusCode UA_THREADSAFE UA_Client_activateCurrentSession

(

UA_Client *

client

)

Re-activate the current session.

A change of prefered locales can be done by updating the client configuration.

UA_Client_activateCurrentSessionAsync()

UA_StatusCode UA_THREADSAFE UA_Client_activateCurrentSessionAsync

(

UA_Client *

client

)

Async version of UA_Client_activateCurrentSession.

UA_Client_activateSession()

UA_StatusCode UA_THREADSAFE UA_Client_activateSession	(	UA_Client *	client,
		const UA_NodeId	authenticationToken,
		const UA_ByteString	serverNonce
	)

Activate an already created Session.

This allows a Session to be transferred from a different client instance. The AuthenticationToken and ServerNonce must be provided for this. Both can be retrieved for an activated Session with UA_Client_getSessionAuthenticationToken.

The UserIdentityToken used for authentication must be identical to the original activation of the Session. The UserIdentityToken is set in the client configuration.

Note the noNewSession option if there should not be a new Session automatically created when this one closes.

UA_Client_activateSessionAsync()

UA_StatusCode UA_THREADSAFE UA_Client_activateSessionAsync	(	UA_Client *	client,
		const UA_NodeId	authenticationToken,
		const UA_ByteString	serverNonce
	)

Async version of UA_Client_activateSession.

UA_Client_addRepeatedCallback()

UA_StatusCode UA_THREADSAFE UA_Client_addRepeatedCallback	(	UA_Client *	client,
		UA_ClientCallback	callback,
		void *	data,
		UA_Double	interval_ms,
		UA_UInt64 *	callbackId
	)

Add a callback for cyclic repetition to the client.

Parameters

client	The client object.
callback	The callback that shall be added.
data	Data that is forwarded to the callback.
interval_ms	The callback shall be repeatedly executed with the given interval (in ms). The interval must be positive. The first execution occurs at now() + interval at the latest.
callbackId	Set to the identifier of the repeated callback. This can be used to cancel the callback later on. If the pointer is null, the identifier is not set.

Returns

Upon success, UA_STATUSCODE_GOOD is returned. An error code otherwise.

UA_Client_addTimedCallback()

UA_StatusCode UA_THREADSAFE UA_Client_addTimedCallback	(	UA_Client *	client,
		UA_ClientCallback	callback,
		void *	data,
		UA_DateTime	date,
		UA_UInt64 *	callbackId
	)

Add a callback for execution at a specified time.

If the indicated time lies in the past, then the callback is executed at the next iteration of the server's main loop.

Parameters

client	The client object.
callback	The callback that shall be added.
data	Data that is forwarded to the callback.
date	The timestamp for the execution time.
callbackId	Set to the identifier of the repeated callback. This can be used to cancel the callback later on. If the pointer is null, the identifier is not set.

Returns

Upon success, UA_STATUSCODE_GOOD is returned. An error code otherwise.

UA_Client_cancelByRequestHandle()

UA_EXPORT UA_THREADSAFE UA_StatusCode UA_Client_cancelByRequestHandle	(	UA_Client *	client,
		UA_UInt32	requestHandle,
		UA_UInt32 *	cancelCount
	)

Cancel all dispatched requests with the given requestHandle.

The number if cancelled requests is returned by the server. The output argument cancelCount is not set if NULL.

UA_Client_cancelByRequestId()

UA_EXPORT UA_THREADSAFE UA_StatusCode UA_Client_cancelByRequestId	(	UA_Client *	client,
		UA_UInt32	requestId,
		UA_UInt32 *	cancelCount
	)

Map the requestId to the requestHandle used for that request and call the Cancel service for that requestHandle.

UA_Client_changeRepeatedCallbackInterval()

UA_StatusCode UA_THREADSAFE UA_Client_changeRepeatedCallbackInterval	(	UA_Client *	client,
		UA_UInt64	callbackId,
		UA_Double	interval_ms
	)

UA_Client_delete()

void UA_Client_delete

(

UA_Client *

client

)

(Disconnect and) delete the client

UA_Client_disconnect()

UA_StatusCode UA_THREADSAFE UA_Client_disconnect

(

UA_Client *

client

)

Disconnect and close a connection to the selected server.

Disconnection is always performed async (without blocking).

UA_Client_disconnectAsync()

UA_StatusCode UA_THREADSAFE UA_Client_disconnectAsync

(

UA_Client *

client

)

Disconnect async.

Run UA_Client_run_iterate until the callback notifies that all connections are closed.

UA_Client_disconnectSecureChannel()

UA_StatusCode UA_THREADSAFE UA_Client_disconnectSecureChannel

(

UA_Client *

client

)

Disconnect the SecureChannel but keep the Session intact (if it exists).

UA_Client_disconnectSecureChannelAsync()

UA_StatusCode UA_THREADSAFE UA_Client_disconnectSecureChannelAsync

(

UA_Client *

client

)

Disconnect the SecureChannel but keep the Session intact (if it exists).

This is an async operation. Iterate the client until the SecureChannel was fully cleaned up.

UA_Client_findDataType()

UA_EXPORT const UA_DataType * UA_Client_findDataType	(	UA_Client *	client,
		const UA_NodeId *	typeId
	)

Lookup a datatype by its NodeId.

Takes the custom types in the client configuration into account. Return NULL if none found.

UA_Client_findServers()

UA_StatusCode UA_THREADSAFE UA_Client_findServers	(	UA_Client *	client,
		const char *	serverUrl,
		size_t	serverUrisSize,
		UA_String *	serverUris,
		size_t	localeIdsSize,
		UA_String *	localeIds,
		size_t *	registeredServersSize,
		UA_ApplicationDescription **	registeredServers
	)

Gets a list of all registered servers at the given server.

You can pass an optional filter for serverUris. If the given server is not registered, an empty array will be returned. If the server is registered, only that application description will be returned.

Additionally you can optionally indicate which locale you want for the server name in the returned application description. The array indicates the order of preference. A server may have localized names.

Parameters

client	to use. Must be connected to the same endpoint given in serverUrl or otherwise in disconnected state.
serverUrl	url to connect (for example "opc.tcp://localhost:4840")
serverUrisSize	Optional filter for specific server uris
serverUris	Optional filter for specific server uris
localeIdsSize	Optional indication which locale you prefer
localeIds	Optional indication which locale you prefer
registeredServersSize	size of returned array, i.e., number of found/registered servers
registeredServers	array containing found/registered servers

Returns

Indicates whether the operation succeeded or returns an error code

UA_Client_findServersOnNetwork()

UA_StatusCode UA_THREADSAFE UA_Client_findServersOnNetwork	(	UA_Client *	client,
		const char *	serverUrl,
		UA_UInt32	startingRecordId,
		UA_UInt32	maxRecordsToReturn,
		size_t	serverCapabilityFilterSize,
		UA_String *	serverCapabilityFilter,
		size_t *	serverOnNetworkSize,
		UA_ServerOnNetwork **	serverOnNetwork
	)

Get a list of all known server in the network.

Only supported by LDS servers.

Parameters

client	to use. Must be connected to the same endpoint given in serverUrl or otherwise in disconnected state.
serverUrl	url to connect (for example "opc.tcp://localhost:4840")
startingRecordId	optional. Only return the records with an ID higher or equal the given. Can be used for pagination to only get a subset of the full list
maxRecordsToReturn	optional. Only return this number of records
serverCapabilityFilterSize	optional. Filter the returned list to only get servers with given capabilities, e.g. "LDS"
serverCapabilityFilter	optional. Filter the returned list to only get servers with given capabilities, e.g. "LDS"
serverOnNetworkSize	size of returned array, i.e., number of known/registered servers
serverOnNetwork	array containing known/registered servers

Returns

Indicates whether the operation succeeded or returns an error code

UA_Client_getConfig()

UA_EXPORT UA_ClientConfig * UA_Client_getConfig

(

UA_Client *

client

)

Get the client configuration.

UA_Client_getConnectionAttribute()

UA_EXPORT UA_StatusCode UA_Client_getConnectionAttribute	(	UA_Client *	client,
		const UA_QualifiedName	key,
		UA_Variant *	outValue
	)

Returns a shallow copy of the attribute.

Don't _clear or _delete the value variant. Don't use the value after returning the control flow to the client. Also don't use this in a multi-threaded application.

UA_Client_getConnectionAttribute_scalar()

UA_EXPORT UA_StatusCode UA_Client_getConnectionAttribute_scalar	(	UA_Client *	client,
		const UA_QualifiedName	key,
		const UA_DataType *	type,
		void *	outValue
	)

Returns NULL if the attribute is not defined or not a scalar or not of the right datatype.

Otherwise a shallow copy of the scalar value is created at the target location of the void pointer. Hence don't use this in a multi-threaded application.

UA_Client_getConnectionAttributeCopy()

UA_EXPORT UA_StatusCode UA_THREADSAFE UA_Client_getConnectionAttributeCopy	(	UA_Client *	client,
		const UA_QualifiedName	key,
		UA_Variant *	outValue
	)

Return a deep copy of the attribute.

UA_Client_getEndpoints()

UA_StatusCode UA_THREADSAFE UA_Client_getEndpoints	(	UA_Client *	client,
		const char *	serverUrl,
		size_t *	endpointDescriptionsSize,
		UA_EndpointDescription **	endpointDescriptions
	)

Gets a list of endpoints of a server.

Parameters

client	to use. Must be connected to the same endpoint given in serverUrl or otherwise in disconnected state.
serverUrl	url to connect (for example "opc.tcp://localhost:4840")
endpointDescriptionsSize	size of the array of endpoint descriptions
endpointDescriptions	array of endpoint descriptions that is allocated by the function (you need to free manually)

Returns

Indicates whether the operation succeeded or returns an error code

UA_Client_getSessionAuthenticationToken()

UA_StatusCode UA_THREADSAFE UA_Client_getSessionAuthenticationToken	(	UA_Client *	client,
		UA_NodeId *	authenticationToken,
		UA_ByteString *	serverNonce
	)

Get the AuthenticationToken and ServerNonce required to activate the current Session on a different SecureChannel.

UA_Client_getState()

void UA_THREADSAFE UA_Client_getState	(	UA_Client *	client,
		UA_SecureChannelState *	channelState,
		UA_SessionState *	sessionState,
		UA_StatusCode *	connectStatus
	)

Returns the current state.

All arguments except client can be NULL.

UA_Client_modifyAsyncCallback()

UA_StatusCode UA_THREADSAFE UA_Client_modifyAsyncCallback	(	UA_Client *	client,
		UA_UInt32	requestId,
		void *	userdata,
		UA_ClientAsyncServiceCallback	callback
	)

Set new userdata and callback for an existing request.

Parameters

client	Pointer to the UA_Client
requestId	RequestId of the request, which was returned by __UA_Client_AsyncService before
userdata	The new userdata
callback	The new callback

Returns

UA_StatusCode UA_STATUSCODE_GOOD on success UA_STATUSCODE_BADNOTFOUND when no request with requestId is found.

UA_Client_new()

UA_EXPORT UA_Client * UA_Client_new

(

void

)

Create a new client with a default configuration that adds plugins for networking, security, logging and so on.

See client_config_default.h for more detailed options.

The default configuration can be used as the starting point to adjust the client configuration to individual needs. UA_Client_new is implemented in the /plugins folder under the CC0 license. Furthermore the client confiugration only uses the public server API.

Returns

Returns the configured client or NULL if an error occurs.

UA_Client_newWithConfig()

UA_Client * UA_Client_newWithConfig

(

const UA_ClientConfig *

config

)

Creates a new client.

Moves the config into the client with a shallow copy. The config content is cleared together with the client.

UA_Client_removeCallback()

void UA_THREADSAFE UA_Client_removeCallback	(	UA_Client *	client,
		UA_UInt64	callbackId
	)

UA_Client_renewSecureChannel()

UA_StatusCode UA_THREADSAFE UA_Client_renewSecureChannel

(

UA_Client *

client

)

Force the manual renewal of the SecureChannel.

This is useful to renew the SecureChannel during a downtime when no time-critical operations are performed. This method is asynchronous. The renewal is triggered (the OPN message is sent) but not completed. The OPN response is handled with UA_Client_run_iterate or a synchronous service-call operation.

Returns

The return value is UA_STATUSCODE_GOODCALLAGAIN if the SecureChannel has not elapsed at least 75% of its lifetime. Otherwise the connectStatus is returned.

UA_Client_run_iterate()

UA_StatusCode UA_THREADSAFE UA_Client_run_iterate	(	UA_Client *	client,
		UA_UInt32	timeout
	)

Listen on the network and process arriving asynchronous responses in the background.

Internal housekeeping, renewal of SecureChannels and subscription management is done as well.

UA_Client_startListeningForReverseConnect()

UA_StatusCode UA_Client_startListeningForReverseConnect	(	UA_Client *	client,
		const UA_String *	listenHostnames,
		size_t	listenHostnamesLength,
		UA_UInt16	port
	)

Sets up a listening socket for incoming reverse connect requests by OPC UA servers.

After the first server has connected, the listening socket is removed. The client state callback is also used for reverse connect. An implementation could for example issue a new call to UA_Client_startListeningForReverseConnect after the server has closed the connection. If the client is connected to any server while UA_Client_startListeningForReverseConnect is called, the connection will be closed.

The reverse connect is closed by calling the standard disconnect functions like for a "normal" connection that was initiated by the client. Calling one of the connect methods will also close the listening socket and the connection to the remote server.

UA_ClientConfig_clear()

UA_EXPORT void UA_ClientConfig_clear

(

UA_ClientConfig *

config

)

UA_ClientConfig_copy()

UA_EXPORT UA_StatusCode UA_ClientConfig_copy	(	UA_ClientConfig const *	src,
		UA_ClientConfig *	dst
	)

UA_ClientConfig_delete()

UA_EXPORT void UA_ClientConfig_delete

(

UA_ClientConfig *

config

)