Asynchronous call to get the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session. More...

#include <getendpointsrequest.h>

Data Fields
struct ua_string	endpoint_url
	The network address that the Client used to access the Discovery Endpoint. More...

struct ua_string *	locale_ids
	List of locales to use. More...

int32_t	num_locale_ids
	Number of elements in ua_getendpointsrequest::locale_ids.

struct ua_string *	profile_uris
	List of Transport Profile that the returned Endpoints shall support. More...

int32_t	num_profile_uris
	Number of elements in ua_getendpointsrequest::profile_uris.

Related Functions
void	ua_getendpointsrequest_init (struct ua_getendpointsrequest *t)
	Initialize an ua_getendpointsrequest struct with a valid value. More...

void	ua_getendpointsrequest_clear (struct ua_getendpointsrequest *t)
	Clear all resources alloctated in an ua_getendpointsrequest struct. More...

int	ua_getendpointsrequest_compare (const struct ua_getendpointsrequest a, const struct ua_getendpointsrequest b)
	Compare two ua_getendpointsrequest structs. More...

int	ua_getendpointsrequest_copy (struct ua_getendpointsrequest dst, const struct ua_getendpointsrequest src)
	Create a copy of a ua_getendpointsrequest struct. More...

static int	ua_getendpointsrequest_resize_locale_ids_array (struct ua_getendpointsrequest *val, int32_t new_len)
	Resize the locale_ids array of a ua_getendpointsrequest struct. More...

static int	ua_getendpointsrequest_resize_profile_uris_array (struct ua_getendpointsrequest *val, int32_t new_len)
	Resize the profile_uris array of a ua_getendpointsrequest struct. More...

Detailed Description

Asynchronous call to get the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session.

This Service shall not require any message security, but it may require transport layer security.

A Client may reduce the number of results returned by specifying filter criteria based on LocaleIds and Transport Profile URIs. The Server returns an empty list if no Endpoints match the criteria specified by the client.

A Server may support multiple security configurations for the same Endpoint. In this situation, the Server shall return separate ua_endpointdescription records for each available configuration.

Clients should treat each of these configurations as distinct Endpoints, even if the physical URL happens to be the same.

The security configuration for an Endpoint has four components:

Server application instance certificate
Message Security Mode
Security Policy
Supported User Identity Tokens

The ApplicationInstanceCertificate is used to secure the OpenSecureChannel request. The MessageSecurityMode and the SecurityPolicy tell the Client how to secure messages sent via the SecureChannel. The UserIdentityTokens tell the client which type of user credentials shall be passed to the Server in the ActivateSession request.

If the securityPolicyUri is NONE and none of the UserTokenPolicies requires encryption, the Client shall ignore the ApplicationInstanceCertificate.

Each EndpointDescription also specifies a URI for the Transport Profile that the Endpoint supports. The Transport Profiles specify information such as message encoding format and protocol version and are defined in Part 7 of the OPC UA Specification. Clients shall fetch the Server’s SoftwareCertificates if they want to discover the complete list of Profiles supported by the Server.

Messages are secured by applying standard cryptography algorithms to the messages before they are sent over the network. The exact set of algorithms used depends on the SecurityPolicy for the Endpoint. Part 7 of the OPC UA Specification defines Profiles for common SecurityPolicies and assigns a unique URI to them. It is expected that applications have built in knowledge of the SecurityPolicies that they support. As a result, only the Profile URI for the SecurityPolicy is specified in the EndpointDescription. A Client cannot connect to an Endpoint that does not support a SecurityPolicy that it recognizes.

An EndpointDescription may specify that the message security mode is NONE. This configuration is not recommended unless the applications are communicating on a physically isolated network where the risk of intrusion is extremely small. If the message security is NONE, it is possible for Clients to deliberately or accidentally hijack Sessions created by other Clients.

A Server may have multiple HostNames. For this reason, the Client shall pass the URL it used to connect to the Endpoint to this Service. The implementation of this Service shall use this information to return responses that are accessible to the Client via the provided URL.

This Service can be used without security and it is therefore vulnerable to Denial Of Service (DOS) attacks. A Server should minimize the amount of processing required to send the response for this Service. This can be achieved by preparing the result in advance. The Server should also add a short delay before starting processing of a request during high traffic conditions.

Some of the EndpointDescriptions returned in a response shall specify the Endpoint information for a Gateway Server that can be used to access another Server. In these situations, the gatewayServerUri is specified in the EndpointDescription and all security checks used to verify certificate s shall use the gatewayServerUri instead of the serverUri.

To connect to a Server via the gateway, the Client shall first establish a SecureChannel with the Gateway Server. Then the Client shall call the CreateSession service and pass the serverUri specified in the EndpointDescription to the Gateway Server. The Gateway Server shall then connect to the underlying Server on behalf of the Client.

Friends And Related Function Documentation

void ua_getendpointsrequest_clear ( struct ua_getendpointsrequest * t )

Frees allocated memory like arrays and resets numeric values. The ua_getendpointsrequest struct itself is not freed and must be freed by the caller if required. This function always succeeds for a valid ua_getendpointsrequest struct, that was validly decoded or initilized by ua_getendpointsrequest_init.

int ua_getendpointsrequest_compare	(	const struct ua_getendpointsrequest *	a,
		const struct ua_getendpointsrequest *	b
	)

Compares the content of the ua_getendpointsrequest struct a to the content of the ua_getendpointsrequest struct b. If a is smaller than b, an integer less than zero is returned, if a is bigger than b, an integer greater than zero is returned. If both structs are equal zero is returned.

This function creates a total order on ua_getendpointsrequest structs, so it is well suited to not only determine equality, but also sort multiple instances of this struct.

int ua_getendpointsrequest_copy	(	struct ua_getendpointsrequest *	dst,
		const struct ua_getendpointsrequest *	src
	)

Copy all fields from struct ua_getendpointsrequest src to dst. Creates a deep copy so all content is recusively copied and both src and dst can be used and must be freed separately.

dst is not cleared before the copy operation, so it must not have any allocated data. It may or may not be initilized by the caller before copy.

Returns: Zero on success or ua_statuscode on failure.

void ua_getendpointsrequest_init ( struct ua_getendpointsrequest * t )

After initialization the fields of the struct are set to valid and consistent values and can safley be accessed. An initialized ua_getendpointsrequest struct can also be passed to ua_getendpointsrequest_clear. This function will always succeed as long as an ua_getendpointsrequest struct is passed to it.

static int ua_getendpointsrequest_resize_locale_ids_array	(	struct ua_getendpointsrequest *	val,
		int32_t	new_len
	)

Depending on new_len and the current size of the array, the array will be created, increased, decreased or deleted. In case array members are removed these are cleared properly, new array members are initialized with zero.

Parameters

new_len New length of the locale_ids array in number of members.

Returns: Zero on success or ua_statuscode on failure.

static int ua_getendpointsrequest_resize_profile_uris_array	(	struct ua_getendpointsrequest *	val,
		int32_t	new_len
	)

Depending on new_len and the current size of the array, the array will be created, increased, decreased or deleted. In case array members are removed these are cleared properly, new array members are initialized with zero.

Parameters

new_len New length of the profile_uris array in number of members.

Returns: Zero on success or ua_statuscode on failure.

Field Documentation

endpoint_url

The network address that the Client used to access the Discovery Endpoint.

The Server uses this information for diagnostics and to determine what URLs to return in the response.

The Server should return a suitable default URL if it does not recognize the HostName in the URL.

locale_ids

List of locales to use.

Specifies the locale to use when returning human readable strings.

If the server supports more than one of the requested locales, the server shall use the locale that appears first in this list. If the server does not support any of the requested locales, it chooses an appropriate default locale.

The server chooses an appropriate default locale if this list is empty.

profile_uris

List of Transport Profile that the returned Endpoints shall support.

Part 7 of the OPC UA Specification defines URIs for the Transport Profiles.

All Endpoints are returned if the list is empty.

The documentation for this struct was generated from the following files:

C:/work/embeddedstack/src/uabase/service/getendpointsrequest.h
C:/work/embeddedstack/src/uabase/service/getendpointsrequest.c

Data Fields

Related Functions

Detailed Description

Friends And Related Function Documentation

Field Documentation