High Performance OPC UA Server SDK
1.3.1.248
|
The UA Client Library can be used to write UA Client applications. More...
Modules | |
UA Client Services | |
UA Client Session | |
These functions are used internally to create a connection. | |
UA Client Simple Browse | |
UA Client Subscription | |
UA Discovery Module | |
Data Structures | |
struct | ua_client |
The client context represents one client connection. More... | |
struct | ua_client_callbacks |
Callback table for ua_client instances. More... | |
struct | ua_auth_usernamepassword |
Username/password authentication details. More... | |
struct | ua_auth_x509 |
struct | ua_auth_credentials |
Authentication credentials used in ActivateSession service call. More... | |
struct | ua_service_settings |
Settings for UA service calls. More... | |
Typedefs | |
typedef void(* | ua_client_connect_cb) (struct ua_client *client, void *cb_data, int result, ua_statuscode statuscode) |
Callback for ua_client_begin_connect. | |
typedef void(* | ua_client_disconnect_cb) (struct ua_client *client, void *cb_data, int result, ua_statuscode statuscode) |
Callback for ua_client_begin_disconnect. | |
typedef int(* | ua_client_invoke_cb) (struct ua_client *client, int result, struct ua_responseheader *rh, void *response, void *request, void *cb_data) |
Callback for ua_client_begin_invoke. | |
typedef void(* | ua_client_connection_state_changed_cb) (struct ua_client *client, enum ua_client_connection_state status) |
The connection status callback is called every time the connection state is changing. More... | |
typedef enum ua_client_connect_action(* | ua_client_connection_error_cb) (struct ua_client *client, enum ua_client_connect_step step, int client_error, ua_statuscode statuscode) |
The connection error callback is called whenever an error occurs. More... | |
Enumerations | |
enum | ua_client_connection_state { UA_CLIENT_CONNECTION_STATE_DISCONNECTED = 0, UA_CLIENT_CONNECTION_STATE_CONNECTED, UA_CLIENT_CONNECTION_STATE_RECONNECTING, UA_CLIENT_CONNECTION_STATE_SESSION_CREATED, UA_CLIENT_CONNECTION_STATE_SESSION_DELETED, UA_CLIENT_CONNECTION_STATE_SESSION_FIRST } |
Possible connection states of the client. More... | |
enum | ua_client_connect_action { UA_CLIENT_CONNECT_ACTION_DEFAULT = 0, UA_CLIENT_CONNECT_ACTION_RETRY, UA_CLIENT_CONNECT_ACTION_ABORT, UA_CLIENT_CONNECT_ACTION_ASYNC } |
Actions how to continue in case of a connection error. More... | |
enum | ua_client_connect_step { UA_CLIENT_CONNECT_STEP_INVALID = 0, UA_CLIENT_CONNECT_STEP_OPEN_CHANNEL, UA_CLIENT_CONNECT_STEP_CREATE_SESSION, UA_CLIENT_CONNECT_STEP_ACTIVATE_SESSION, UA_CLIENT_CONNECT_STEP_INITIAL_READ } |
Connection steps at which erros can occur. More... | |
enum | ua_authentication_type { UA_AUTH_ANONYMOUS, UA_AUTH_USERNAMEPASSWORD, UA_AUTH_X509 } |
Modes for the client to authenticate. More... | |
Functions | |
struct ua_client * | ua_client_create (struct uaapplication *app) |
Dynamically allocates and initializes a client context. More... | |
int | ua_client_init (struct ua_client *client, struct uaapplication *app) |
Initializes the given UA Client Context. More... | |
int | ua_client_cleanup (struct ua_client *client) |
Frees all resources of the given client context allocated with ua_client_init. More... | |
int | ua_client_delete (struct ua_client *client) |
Frees all resources of the given client context allocated with ua_client_create. More... | |
int | ua_client_set_callbacks (struct ua_client *client, struct ua_client_callbacks *callbacks) |
Sets the callback interface for the give client context. More... | |
static void | ua_client_callbacks_init (struct ua_client_callbacks *callbacks) |
initializes the given callback interface. More... | |
int | ua_client_set_userdata (struct ua_client *client, void *data) |
Attach arbitrary userdata to the client that can be accessed via ua_client_get_userdata. More... | |
void * | ua_client_get_userdata (struct ua_client *client) |
Get the data set with ua_client_set_userdata. | |
enum ua_client_connection_state | ua_client_get_connection_state (struct ua_client *client) |
Returns the current state of the given client context. More... | |
const char * | ua_client_connection_state_to_string (enum ua_client_connection_state state) |
Converts the state enum into a string for creating human readable traces. More... | |
const char * | ua_client_connect_step_to_string (enum ua_client_connect_step step) |
Converts the step enum into a string for creating human readable traces. More... | |
int | ua_client_connect_abort (struct ua_client *client) |
This function may only be called after the application returned UA_CLIENT_CONNECT_ACTION_ASYNC in a callback function. More... | |
int | ua_client_connect_retry (struct ua_client *client) |
This function may only be called after the application returned UA_CLIENT_CONNECT_ACTION_ASYNC in a callback function. More... | |
uint32_t | ua_client_get_unique_request_handle (struct ua_client *client) |
Create a unique request handle for use in ua_service_settings. More... | |
int | ua_client_set_default_call_timeout (struct ua_client *client, uint32_t ms) |
Set the default call timeout to use when no ua_service_settings are given. More... | |
int | ua_client_set_default_return_diagnostics (struct ua_client *client, uint32_t bitmask) |
Set the default return diagnostics to use when no ua_service_settings are given. More... | |
int | ua_client_set_default_keep_request (struct ua_client *client, bool keep) |
Set the default keep request value to use when no ua_service_settings are given. More... | |
int | ua_client_set_publishing_timeout (struct ua_client *client, uint32_t ms) |
Set the call timeout for publish requests. More... | |
int | ua_client_set_securechannel_lifetime (struct ua_client *client, uint32_t ms) |
Set the secure channel lifetime to use when connecting or renewing the secure channel. More... | |
int | ua_client_set_session_timeout (struct ua_client *client, double ms) |
Set the session timeout in milliseconds used in the CreateSessionRequest. More... | |
double | ua_client_get_revised_session_timeout (struct ua_client *client) |
Get the revised session timeout received in the CreateSessionResponse. More... | |
uint32_t | ua_client_get_revised_securechannel_lifetime (struct ua_client *client) |
Get the revised secure channel liftime received in the OpenSecureChannelResponse. More... | |
int | ua_client_set_watchdog_interval (struct ua_client *client, uint32_t ms) |
Set the interval for the watchdog read. More... | |
int | ua_client_set_watchdog_timeout (struct ua_client *client, uint32_t ms) |
Set the timeout for the watchdog read. More... | |
int | ua_client_set_reconnect_delay (struct ua_client *client, uint32_t ms) |
Set the reconnect delay. More... | |
int | ua_client_set_automatic_reconnect (struct ua_client *client, bool reconnect) |
Enable/disable automatic reconnect. More... | |
int | ua_client_set_credentials (struct ua_client *client, struct ua_auth_credentials *credentials) |
Sets authentication credentials. More... | |
int | ua_client_set_security (struct ua_client *client, uint32_t client_certificate_store, unsigned char *client_certificate_id, uint32_t num_client_chain_elements, struct ua_bytestring *client_chain_elements, const struct ua_bytestring *server_certificate, enum ua_messagesecuritymode security_mode, enum ua_security_policy_id security_policy) |
Configures the client for secure connetions. More... | |
int | ua_client_set_security_from_endpointdescription (struct ua_client *client, uint32_t client_certificate_store, unsigned char *client_certificate_id, uint32_t num_client_chain_elements, struct ua_bytestring *client_chain_elements, const struct ua_endpointdescription *endpoint_desc) |
This is a convenience wrapper for ua_client_set_security, which creates settings based on given the ua_endpointdescription. More... | |
int | ua_client_begin_connect (struct ua_client *client, const char *endpoint_url, ua_client_connect_cb cb, void *cb_data) |
Try to connect to the given server. More... | |
int | ua_client_begin_disconnect (struct ua_client *client, ua_client_disconnect_cb cb, void *cb_data) |
Disconnects from the server. More... | |
int | ua_client_begin_invoke (struct ua_client *client, struct ua_service_settings *settings, void *request, unsigned int type_id, ua_client_invoke_cb cb, void *cb_data) |
Generic UA service call function. More... | |
static void | ua_client_service_settings_init (struct ua_service_settings *settings) |
Initializes the given ua_service_settings struct. More... | |
static void | ua_auth_credentials_init (struct ua_auth_credentials *auth_credentials) |
Initialize authentication credentials. | |
static void | ua_auth_credentials_clear (struct ua_auth_credentials *auth_credentials) |
Clear authentication credentials. | |
The UA Client Library can be used to write UA Client applications.
This can be a standalone client, or client which is integrated within an OPC UA Server.
For a first introduction into the UA Client Library, please read the client_gettingstarted tutorial. For a general overview about the client's state machine, connection loss detection and subscription recovery, please take a look at the Sample Client application.
typedef enum ua_client_connect_action(* ua_client_connection_error_cb) (struct ua_client *client, enum ua_client_connect_step step, int client_error, ua_statuscode statuscode) |
The connection error callback is called whenever an error occurs.
The return value can be used to control the handling of that error by the SDK.
typedef void(* ua_client_connection_state_changed_cb) (struct ua_client *client, enum ua_client_connection_state status) |
The connection status callback is called every time the connection state is changing.
This can be used to monitor the connection status.connection status
Actions how to continue in case of a connection error.
Enumerator | |
---|---|
UA_CLIENT_CONNECT_ACTION_DEFAULT | Continue with the configured default behaviour. |
UA_CLIENT_CONNECT_ACTION_RETRY | Force a retry of the connect. |
UA_CLIENT_CONNECT_ACTION_ABORT | Abort connecting to the server. |
UA_CLIENT_CONNECT_ACTION_ASYNC | Return the result asynchronous, use ua_client_connect_abort or ua_client_connect_retry to trigger the respective action. |
Connection steps at which erros can occur.
Possible connection states of the client.
int ua_client_begin_connect | ( | struct ua_client * | client, |
const char * | endpoint_url, | ||
ua_client_connect_cb | cb, | ||
void * | cb_data | ||
) |
Try to connect to the given server.
When the synchronous call succeeds the asynchronous result of the connect is delivered by callback, there are two ways:
client | Client context. |
endpoint_url | The server's endpoint to use. |
cb | The connect callback that is called when the operation is complete. |
cb_data | Optional callback data which gets passed to the configured callback. |
int ua_client_begin_disconnect | ( | struct ua_client * | client, |
ua_client_disconnect_cb | cb, | ||
void * | cb_data | ||
) |
Disconnects from the server.
Like in ua_client_begin_connect when the synchronous call succeeds the asynchronous result of the connect is delivered by callback, there are again two ways:
Disconnect may fail for different reasons, e.g. a network disconnect or the server has already deleted the session. In all cases the SDK will continue the disconnect and and close the network connection, so after the disconnect is finished the client object can be deleted.
client | Client context. |
cb | The disconnect callback that is called when the operation is complete. |
cb_data | Optional callback data which gets passed to the configured callback. |
int ua_client_begin_invoke | ( | struct ua_client * | client, |
struct ua_service_settings * | settings, | ||
void * | request, | ||
unsigned int | type_id, | ||
ua_client_invoke_cb | cb, | ||
void * | cb_data | ||
) |
Generic UA service call function.
For typesafe functions see UA Client Services
client | The client context. |
settings | Optional service settings. |
request | Pointer to services request structure. This function creates a shallow copy of the request, so the struct can be on the stack, but members must be allocated with ipc_malloc. When this function succeeds, it takes ownership of the struct members and the caller must not access or free it. However, members may be detached again from the request in the callback, if the keep_request setting is true. |
type_id | Service type id. |
cb | Pointer to callback function. |
cb_data | Callback data which you will get back in the callback. |
The SDK takes ownership of the request
structure if the invoke operation succeeds. It must not be freed by the caller. If the operation fails it must be cleared by the caller, though.
Any service result will be returned in the callback.
|
inlinestatic |
initializes the given callback interface.
int ua_client_cleanup | ( | struct ua_client * | client | ) |
Frees all resources of the given client context allocated with ua_client_init.
This function must not be called from within a callback of that client instance.
Before calling this function all subscriptions associated with this client instance must be freed first.
This function will fail if the client is not disconnected.
int ua_client_connect_abort | ( | struct ua_client * | client | ) |
This function may only be called after the application returned UA_CLIENT_CONNECT_ACTION_ASYNC in a callback function.
It will no longer try to connect to the server as if UA_CLIENT_CONNECT_ACTION_ABORT was returned in the callback.
int ua_client_connect_retry | ( | struct ua_client * | client | ) |
This function may only be called after the application returned UA_CLIENT_CONNECT_ACTION_ASYNC in a callback function.
It will retry to connect to the server as if UA_CLIENT_CONNECT_ACTION_RETRY was returned in the callback.
const char* ua_client_connect_step_to_string | ( | enum ua_client_connect_step | step | ) |
Converts the step enum into a string for creating human readable traces.
const char* ua_client_connection_state_to_string | ( | enum ua_client_connection_state | state | ) |
Converts the state enum into a string for creating human readable traces.
struct ua_client* ua_client_create | ( | struct uaapplication * | app | ) |
Dynamically allocates and initializes a client context.
The maximum number of clients instances can be configured in appconfig, setting client.num_clients.
Must be freed with ua_client_delete when no longer needed.
app | The UA application instance. |
int ua_client_delete | ( | struct ua_client * | client | ) |
Frees all resources of the given client context allocated with ua_client_create.
This function must not be called from within a callback of that client instance.
Before calling this function all subscriptions associated with this client instance must be freed first.
This function will fail if the client is not disconnected.
enum ua_client_connection_state ua_client_get_connection_state | ( | struct ua_client * | client | ) |
Returns the current state of the given client context.
uint32_t ua_client_get_revised_securechannel_lifetime | ( | struct ua_client * | client | ) |
Get the revised secure channel liftime received in the OpenSecureChannelResponse.
double ua_client_get_revised_session_timeout | ( | struct ua_client * | client | ) |
Get the revised session timeout received in the CreateSessionResponse.
uint32_t ua_client_get_unique_request_handle | ( | struct ua_client * | client | ) |
Create a unique request handle for use in ua_service_settings.
The returned handle is above 1.000.000 and not used in any other request. However due to the limited range of uint32_t it will overflow at some point, but it is extremely unlikely there is still another request using this number.
int ua_client_init | ( | struct ua_client * | client, |
struct uaapplication * | app | ||
) |
Initializes the given UA Client Context.
client | Client context. |
app | The UA application instance. |
Must be freed with ua_client_cleanup when no longer needed.
|
inlinestatic |
Initializes the given ua_service_settings struct.
int ua_client_set_automatic_reconnect | ( | struct ua_client * | client, |
bool | reconnect | ||
) |
Enable/disable automatic reconnect.
It is still possible to override the set behavior by implementing the ua_client_connection_error_cb callback.
int ua_client_set_callbacks | ( | struct ua_client * | client, |
struct ua_client_callbacks * | callbacks | ||
) |
Sets the callback interface for the give client context.
int ua_client_set_credentials | ( | struct ua_client * | client, |
struct ua_auth_credentials * | credentials | ||
) |
Sets authentication credentials.
This must be called before creating a connection.
client | Client context. |
credentials | The credentials to use for the next connect call. |
int ua_client_set_default_call_timeout | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the default call timeout to use when no ua_service_settings are given.
ms | Call timeout in milliseconds |
int ua_client_set_default_keep_request | ( | struct ua_client * | client, |
bool | keep | ||
) |
Set the default keep request value to use when no ua_service_settings are given.
int ua_client_set_default_return_diagnostics | ( | struct ua_client * | client, |
uint32_t | bitmask | ||
) |
Set the default return diagnostics to use when no ua_service_settings are given.
int ua_client_set_publishing_timeout | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the call timeout for publish requests.
Publish requests are stored in the server until subscription data becomes available, so it is recommended to set a higher call timeout as usual for these requests.
ms | Publish timeout in milliseconds |
int ua_client_set_reconnect_delay | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the reconnect delay.
When the client gets disconnected it will try to reconnect after that delay.
ms | Reconnect delay in milliseconds. |
int ua_client_set_securechannel_lifetime | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the secure channel lifetime to use when connecting or renewing the secure channel.
ms | Lifetime in milliseconds |
int ua_client_set_security | ( | struct ua_client * | client, |
uint32_t | client_certificate_store, | ||
unsigned char * | client_certificate_id, | ||
uint32_t | num_client_chain_elements, | ||
struct ua_bytestring * | client_chain_elements, | ||
const struct ua_bytestring * | server_certificate, | ||
enum ua_messagesecuritymode | security_mode, | ||
enum ua_security_policy_id | security_policy | ||
) |
Configures the client for secure connetions.
By default the client will connect with SecurityPolicy None.
client | Client context. |
client_certificate_store | The PKI Store to use. |
client_certificate_id | The client's certificate ID. |
num_client_chain_elements | Number of CA certificates, which are the issuer of the client certificate. |
client_chain_elements | Array of CA certificates (DER encoded). |
server_certificate | The server's certificate. Can be retrieved using ua_client_discovery_begin_get_endpoints. |
security_mode | The security mode to use. UA_MESSAGESECURITYMODE_SIGN or UA_MESSAGESECURITYMODE_SIGNANDENCRYPT. |
security_policy | The security policy to use. |
int ua_client_set_security_from_endpointdescription | ( | struct ua_client * | client, |
uint32_t | client_certificate_store, | ||
unsigned char * | client_certificate_id, | ||
uint32_t | num_client_chain_elements, | ||
struct ua_bytestring * | client_chain_elements, | ||
const struct ua_endpointdescription * | endpoint_desc | ||
) |
This is a convenience wrapper for ua_client_set_security, which creates settings based on given the ua_endpointdescription.
The endpoint description provides all server side information and you only need to configure the client side certificate.
client | Client context. |
client_certificate_store | The PKI Store to use. |
client_certificate_id | The client's certificate ID. |
num_client_chain_elements | Number of CA certificates, which are the issuer of the client certificate. |
client_chain_elements | Array of CA certificates (DER encoded). |
endpoint_desc | The endpoint description to use. This is the information the was returned by the server's GetEndpoints service call. |
int ua_client_set_session_timeout | ( | struct ua_client * | client, |
double | ms | ||
) |
Set the session timeout in milliseconds used in the CreateSessionRequest.
This value will be used in all subsequent CreateSessionRequests, no matter what the server revises.
int ua_client_set_userdata | ( | struct ua_client * | client, |
void * | data | ||
) |
Attach arbitrary userdata to the client that can be accessed via ua_client_get_userdata.
This is especially usefull to access some kind of application context in callbacks.
int ua_client_set_watchdog_interval | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the interval for the watchdog read.
When the client does not receive any message from the server for the given interval it will start a watchdog read.
ms | Watchdog interval in milliseconds. |
int ua_client_set_watchdog_timeout | ( | struct ua_client * | client, |
uint32_t | ms | ||
) |
Set the timeout for the watchdog read.
If the watchdog read does not return after the given timeout the client will assume the connection as broken and disconnect.
ms | Timeout for watchdog read in milliseconds |