ANSI C UA Server SDK  1.5.1.313
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules Pages
UaClientDiscovery

Data Structures

struct  UaClient_Discovery
 The UaClient_Discovery structure manages a UA Client side discovery functionality. More...
 

Typedefs

typedef OpcUa_Void(* UaClient_Discovery_FindServers_CB )(const UaClient_Discovery *a_pDiscovery, OpcUa_ResponseHeader *a_pResponseHeader, OpcUa_Int32 a_NoOfServers, OpcUa_ApplicationDescription *a_pServers, OpcUa_Void *a_pUserData)
 Asynchronous callback function for calls to UaClient_Discovery_BeginFindServers. More...
 
typedef OpcUa_Void(* UaClient_Discovery_GetEndpoints_CB )(const UaClient_Discovery *a_pDiscovery, OpcUa_ResponseHeader *a_pResponseHeader, OpcUa_Int32 a_NoOfEndpoints, OpcUa_EndpointDescription *a_pEndpoints, OpcUa_Void *a_pUserData)
 Asynchronous callback function for calls to UaClient_Discovery_BeginGetEndpoints. More...
 

Functions

OpcUa_StatusCode UaClient_Discovery_BeginFindServers (UaClient_Discovery *a_pDiscovery, UaClient_ServiceSettings *a_pServiceSettings, const OpcUa_String *a_pEndpointUrl, OpcUa_Int32 a_NoOfLocaleIds, const OpcUa_String *a_pLocaleIds, OpcUa_Int32 a_NoOfServerUris, const OpcUa_String *a_pServerUris, UaClient_Discovery_FindServers_CB a_pfCallback, OpcUa_Void *a_pUserData)
 Asynchronous call to return the Servers known to a Server or Discovery Server. More...
 
OpcUa_StatusCode UaClient_Discovery_BeginGetEndpoints (UaClient_Discovery *a_pDiscovery, UaClient_ServiceSettings *a_pServiceSettings, const OpcUa_String *a_pEndpointUrl, OpcUa_Int32 a_NoOfLocaleIds, const OpcUa_String *a_pLocaleIds, OpcUa_Int32 a_NoOfProfileUris, const OpcUa_String *a_pProfileUris, UaClient_Discovery_GetEndpoints_CB a_pfCallback, OpcUa_Void *a_pUserData)
 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...
 

Detailed Description

Typedef Documentation

typedef OpcUa_Void(* UaClient_Discovery_FindServers_CB)(const UaClient_Discovery *a_pDiscovery, OpcUa_ResponseHeader *a_pResponseHeader, OpcUa_Int32 a_NoOfServers, OpcUa_ApplicationDescription *a_pServers, OpcUa_Void *a_pUserData)

Asynchronous callback function for calls to UaClient_Discovery_BeginFindServers.

Parameters
a_pDiscoveryThe discovery that was used for the service invocation.
a_pResponseHeaderGeneral information about the response like ServiceResult and diagnostics.
a_NoOfServersNumber of elements in a_pServers.
a_pServersList of Servers that meet criteria specified in the request.
This list is empty if no servers meet the criteria.
a_pUserDataThe user data that was passed to UaClient_Discovery_BeginFindServers.
typedef OpcUa_Void(* UaClient_Discovery_GetEndpoints_CB)(const UaClient_Discovery *a_pDiscovery, OpcUa_ResponseHeader *a_pResponseHeader, OpcUa_Int32 a_NoOfEndpoints, OpcUa_EndpointDescription *a_pEndpoints, OpcUa_Void *a_pUserData)

Asynchronous callback function for calls to UaClient_Discovery_BeginGetEndpoints.

Parameters
a_pDiscoveryThe discovery that was used for the service invocation.
a_pResponseHeaderGeneral information about the response like ServiceResult and diagnostics.
a_NoOfEndpointsNumber of elements in a_pEndpoints.
a_pEndpointsList of Endpoints that meet criteria specified in the request.
This list is empty if no Endpoints meet the criteria
a_pUserDataThe user data that was passed to UaClient_Discovery_BeginGetEndpoints.

Function Documentation

OpcUa_StatusCode UaClient_Discovery_BeginFindServers ( UaClient_Discovery a_pDiscovery,
UaClient_ServiceSettings a_pServiceSettings,
const OpcUa_String *  a_pEndpointUrl,
OpcUa_Int32  a_NoOfLocaleIds,
const OpcUa_String *  a_pLocaleIds,
OpcUa_Int32  a_NoOfServerUris,
const OpcUa_String *  a_pServerUris,
UaClient_Discovery_FindServers_CB  a_pfCallback,
OpcUa_Void *  a_pUserData 
)

Asynchronous call to return the Servers known to a Server or Discovery Server.

The Client may reduce the number of results returned by specifying filter criteria. A Discovery Server returns an empty list if no Servers match the criteria specified by the client.

Every Server shall provide a Discovery Endpoint that supports this Service. The Server shall always return a record that describes itself, however in some cases more than one record may be returned. Gateway Servers shall return a record for each Server that they provide access to plus (optionally) a record that allows the Gateway Server to be accessed as an ordinary OPC UA Server. Non-transparent redundant Servers shall provide a record for each Server in the redundant set.

Every Server shall have a globally unique identifier called the ServerUri. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. The ServerUri returned by this Service shall be the same value that appears in index 0 of the ServerArray property (see Part 5 of the OPC UA Specification). The ServerUri is returned as the applicationUri field in the OpcUa_ApplicationDescription.

Every Server shall also have a human readable identifier, called the ServerName, which is not necessarily globally unique. This identifier may be available in multiple locales.

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 shall not require any message security but it may require transport layer security.

Some Servers may be accessed via a Gateway Server and shall have a value specified for gatewayServerUri in their OpcUa_ApplicationDescription. The discoveryUrls provided in ApplicationDescription shall belong to the Gateway Server. Some Discovery Servers may return multiple records for the same Server if that Server can be accessed via multiple paths.

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.

The DiscoveryUrl returned by this Service is ambiguous if there are multiple TransportProfiles (e.g. UA XML or UA Binary encoding) associated with the URL scheme. Clients that support multiple TransportProfiles should attempt to use alternate TransportProfiles if the first choice does not succeed.

Parameters
a_pDiscoveryThe discovery to use for the service invocation.
a_pServiceSettingsThe general service settings like timeout. See UaClient_ServiceSettings for details.
a_pEndpointUrlThe 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.
a_NoOfLocaleIdsNumber of elements in a_pLocaleIds.
a_pLocaleIdsList of locales to use.
The server should return the applicationName in the OpcUa_ApplicationDescription using one of locales specified. 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.
a_NoOfServerUrisNumber of elements in a_pServerUris.
a_pServerUrisList of servers to return.
All known servers are returned if the list is empty.
A serverUri matches the applicationUri from the OpcUa_ApplicationDescription.
a_pfCallbackThe callback function to use when the async call completes.
a_pUserDataThe user data that is passed to the callback function.
Returns
OpcUa_Good if the invocation succeeded, an appropriate error code otherwise.
OpcUa_StatusCode UaClient_Discovery_BeginGetEndpoints ( UaClient_Discovery a_pDiscovery,
UaClient_ServiceSettings a_pServiceSettings,
const OpcUa_String *  a_pEndpointUrl,
OpcUa_Int32  a_NoOfLocaleIds,
const OpcUa_String *  a_pLocaleIds,
OpcUa_Int32  a_NoOfProfileUris,
const OpcUa_String *  a_pProfileUris,
UaClient_Discovery_GetEndpoints_CB  a_pfCallback,
OpcUa_Void *  a_pUserData 
)

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 OpcUa_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 Certificates 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.

Parameters
a_pDiscoveryThe discovery to use for the service invocation.
a_pServiceSettingsThe general service settings like timeout. See UaClient_ServiceSettings for details.
a_pEndpointUrlThe 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.
a_NoOfLocaleIdsNumber of elements in a_pLocaleIds.
a_pLocaleIdsList 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.
a_NoOfProfileUrisNumber of elements in a_pProfileUris.
a_pProfileUrisList 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.
a_pfCallbackThe callback function to use when the async call completes.
a_pUserDataThe user data that is passed to the callback function.
Returns
OpcUa_Good if the invocation succeeded, an appropriate error code otherwise.