pdcomm::opcua::client
Class
OPC UA client session over one secure channel.
class client : public ownedconnect() discovers the endpoints, opens the secure channel and creates the session; activate the session before sending service requests. begin() queues a complete UA Binary request, poll() moves bytes on the socket and take() returns the response when it has arrived. close() ends the session in an orderly way; destroying an open client aborts the socket instead.
From examples/opcua/opcua_client.cpp:
static std::vector<uint8_t> exchange(ua::client& client, const uint8_t* request, size_t size,
std::chrono::milliseconds timeout) {
const auto id = client.begin(std::vector<uint8_t>(request, request + size));
const auto deadline = std::chrono::steady_clock::now() + timeout;
while (std::chrono::steady_clock::now() < deadline) {
client.poll();
if (auto response = client.take(id)) return response->copy();
std::this_thread::sleep_for(std::chrono::milliseconds(1));
}
throw ua::error(PDCOMM_OPCUA_RUNTIME_ERROR, "Response timed out");
}
// ...
auto config = ua::options();
const auto certificate = load(argv[2]);
auto key = load(argv[3]);
const auto trust = load(argv[4]);
config.policy = policy;
config.mode = mode;
config.timeout_ms = 5000;
config.certificate_der = ua::bytes(certificate);
config.private_key_pem = ua::bytes(key);
config.trusted_server_der = ua::bytes(trust);
auto client = ua::client::connect(argv[1], config);
std::fill(key.begin(), key.end(), static_cast<unsigned char>(0)); // The SDK copied the identity.
client.activate_anonymous();
// ...
const auto size = ua_encode_read(request, sizeof(request), 2, node);
const auto body = exchange(client, request, size, std::chrono::seconds(5));
// ...
client.close();Notes
- Use one client from one thread at a time: a concurrent call throws error with #PDCOMM_OPCUA_BUSY. connect(), discover(), activation and close() block; begin(), poll() and take() never wait for the network. Call poll() regularly while requests are outstanding, or the connection fails after
timeout_ms.
Members
activate_anonymous
Method
Activates the session anonymously (ActivateSession).
void activate_anonymous()Notes
- Throws
error: if the server rejects the token, requests are outstanding or the client is closed.
activate_user_name
Method
Activates the session with a user name and password (ActivateSession).
void activate_user_name(const std::string& name, const std::vector<uint8_t>& secret)See pdcomm_opcua_client_activate_user_name() for the token formats.
Parameters
| Name | Description |
|---|---|
name | UTF-8 user name, 1 to 1024 bytes. |
secret | UTF-8 password, at most 16 KiB. The caller owns it and should wipe it after the call. |
Notes
- Throws
error: if the channel uses SecurityPolicy None, the server rejects the user, requests are outstanding or the client is closed.
begin
Method
Queues one UA Binary service request.
uint32_t begin(const std::vector<uint8_t>& request)See pdcomm_opcua_client_begin() for the supported services and the RequestHeader fields the library replaces.
Parameters
| Name | Description |
|---|---|
request | Complete encoded request, starting with its encoding NodeId; copied during the call. |
Returns
The request ID to pass to take().
Notes
- Throws
error: with #PDCOMM_OPCUA_INVALID_INPUT for an unsupported or invalid request, #PDCOMM_OPCUA_LIMIT when 64 requests are outstanding, or another status when the client is busy or closed.
close
Method
Closes the session and the secure channel in an orderly way.
void close()Take every outstanding response first. The client is closed afterwards even if this call throws, except for #PDCOMM_OPCUA_BUSY.
Notes
- Throws
error: with #PDCOMM_OPCUA_BUSY while requests are outstanding, or another status when the exchange fails or the client is closed.
connect
Method
Connects to a server and creates a session.
static client connect(const std::string& url, const pdcomm_opcua_client_options& config)See pdcomm_opcua_client_connect(). The private key in config is copied during the call; wipe the caller's copy afterwards.
Parameters
| Name | Description |
|---|---|
url | opc.tcp:// endpoint URL. |
config | Options from options() with the identity and trust set. |
Returns
The connected client with a session that is not activated yet.
Notes
- Throws
error: if the ABI version differs, the options are invalid, the endpoint is not advertised, a certificate is rejected or the network fails.
discover
Method
Reads the endpoints of a server without authentication.
static buffer discover(const std::string& url, uint32_t timeout_ms = 10000)See pdcomm_opcua_discover().
Parameters
| Name | Description |
|---|---|
url | opc.tcp:// endpoint URL. |
timeout_ms | Timeout of each network exchange, 1 to 300000 ms. |
Returns
A buffer with the UA Binary GetEndpointsResponse.
Notes
- Throws
error: if the ABI version differs, the URL is invalid or the network fails.
poll
Method
Sends queued bytes and receives arrived responses without blocking.
void poll()Notes
- Throws
error: if the connection fails, including an outstanding request older thantimeout_ms; the client is closed afterwards.
take
Method
Takes the response of a request if it has arrived.
std::optional<response> take(uint32_t request)Parameters
| Name | Description |
|---|---|
request | ID returned by begin(). |
Returns
The validated response, or std::nullopt while it has not arrived. A ServiceFault is returned as a response.
Notes
- Throws
error: for an unknown request ID (#PDCOMM_OPCUA_INVALID_INPUT), an invalid response or a response aborted by the server (#PDCOMM_OPCUA_RUNTIME_ERROR), a full handle registry (#PDCOMM_OPCUA_LIMIT) or a closed client.