Client API reference
====================

Constructor
-----------

A client is created by calling:

**ua.newClient(config)**
    **config**
        Configuration table

    Example:

    .. literalinclude:: examples/client/client_connect.lua
        :language: lua
        :lines: 1-14

    `Full source <_static/client/client_connect.lua>`__

Client configuration table
~~~~~~~~~~~~~~~~~~~~~~~~~~

**config** - a table with the following:
    **applicationName** (string)
        The client's application name
    **applicationUri** (string)
        application URI
    **productUri**
        Product URI
    **securePolicies** (table)
        List of polices that is used to secure messages
        See the :ref:`config_table` for details.
    **cosocketMode** (bool)
        Flag that sets client in cosockets mode aka asynchronous mode.
    **bufferSize** (uint32, optional,default=8192)
        Size of internal buffer used for sending and receiving messages.
    **logging** (table, optional)
        Optional client logging. No logging is performed if not set.
        See the :ref:`config_table` for details.

Example:

    .. literalinclude:: examples/client/client_connect.lua
        :language: lua
        :lines: 3-12

    `Full source <_static/client/client_connect.lua>`__

Methods
-------


A client created by calling ua.newClient() has the following methods:

connect
~~~~~~~

**client:connect(endpointUrl[, transportProfile][, connectCallback])**
    **endpointUrl** (string)
        OPCUA server endpoint URL.
        it is possible to use the following formats:

        * opc.tcp://hostname:port/path
        * opc.http://hostname:port/path
        * opc.https://hostname:port/path

        Some servers might require 'http(s)://' scheme instead of 'opc.http(s)://'.

    **transportProfile** (string)
        Transport profile to use.
        It is defines encoding of sending and receiving messages. There are two
        kinds of encoding is possible to specify: binary and JSON.

        This parameter is omitted client will use binary encoding.

        Possible values:
            * ua.Types.TranportProfileUri.TcpBinary is used wotn 'opc.tcp' scheme
            * ua.Types.TranportProfileUri.HttpsBinary
            * ua.Types.TranportProfileUri.HttpsJon

    **connectCallback**
        function that will be called on success or error.

    **Result:**
        error

    Example:

    .. literalinclude:: examples/client/client_connect_callback.lua
        :language: lua
        :lines: 17-34

    `Full source <_static/client/client_connect_callback.lua>`__

    Example without callback:

    .. literalinclude:: examples/client/client_connect.lua
        :language: lua
        :lines: 14-22

    `Full source <_static/client/client_connect.lua>`__

    Exampls of connecting to server over HTTP and with JSON encoding:

    .. literalinclude:: examples/client/client_connect_https_json.lua
        :language: lua
        :lines: 16-22

    `Full source <_static/client/client_connect_https_json.lua>`__


openSecureChannel
~~~~~~~~~~~~~~~~~

**client:openSecureChannel(timeout[, msgCallback])**
    Open new secure channel. The client must open at least one channel.

    **timeout**
        How long a channel should be alive/active (in milliseconds).
    **msgCallback**
        `Message callback`_
    **Result**
            :ref:`openSecureChannelResponse`, error

    The client will automatically refresh when the channel has been established.

    Callback example:

    .. literalinclude:: examples/client/client_open_secure_channel_callback.lua
        :language: lua
        :lines: 16-42

    `Full source <_static/client/client_open_secure_channel_callback.lua>`__

    Blocking example (no callback):

    .. literalinclude:: examples/client/client_open_secure_channel.lua
        :language: lua
        :lines: 26-31

    `Full source <_static/client/client_open_secure_channel.lua>`__

findServers
~~~~~~~~~~~

**client:findServers(params[, msgCallback])**
        Get the list of the servers known to a Server or Discovery Server

    **params** table with fields:
        **endpointUrl** (string, optional)
            Endpoint URL.
        **localeIds[]** (string, optional)
            List of locales to use. The Server should return the applicationName in the ApplicationDescription using one of locales specified.
        **serverUris[]** (string, optional)
            The List of servers to return. All known servers are returned if the list is empty.

        **msgCallback** - `Message callback`_

        **Result**: :ref:`findServersResponse`, error

    Example:

    .. literalinclude:: examples/client/client_find_servers.lua
        :language: lua
        :lines: 32-50

    `Full source <_static/client/client_find_servers.lua>`__

getEndpoints
~~~~~~~~~~~~

**client:getEndpoints(params[, msgCallback])**
    Returns the Endpoints supported by a Server and all of the configuration
    information required to establish a SecureChannel and a Session.

    **params** a table with the following fields:
        **endpointUrl** (string, optional)
            The network address the Client used when accessing the DiscoveryEndpoint.
        **localeIds[]** (string, optional)
            List of locales to use. Specifies the locale to use when returning human readable strings.
        **profileUris[]** (string, optional)
            List of Transport Profiles that the returned Endpoints support.

    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`getEndpointsResponse`,error

    Example:

    .. literalinclude:: examples/client/client_get_endpoints.lua
        :language: lua
        :lines: 32-50

    `Full source <_static/client/client_get_endpoints.lua>`__

createSession
~~~~~~~~~~~~~

**client:createSession(name, timeoutMs[, msgCallback])**
    This Service is used by an OPC UA Client when creating a Session. The Server returns two values which uniquely identifies the Session.

    **params** a table with the following fields:
        **name** (string)
            Human readable string identifying the Session.
        **timeoutMs** (double)
            Requested maximum number of milliseconds that a Session should remain open without activity.

    **msgCallback** `Message callback`_

    **Result** :ref:`createSessionResponse`, error

    Example:

    .. literalinclude:: examples/client/client_create_session.lua
        :language: lua
        :lines: 35-44

    `Full source <_static/client/client_create_session.lua>`__

activateSession
~~~~~~~~~~~~~~~

**client:activateSession([msgCallback])**
    Activate previously created session.

    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`activateSessionResponse`, error

    Example:

    .. literalinclude:: examples/client/client_create_session.lua
        :language: lua
        :lines: 48-52

    `Full source <_static/client/client_create_session.lua>`__

browse
~~~~~~

**client:browse([params| nodeId | nodeId[]] [, msgCallback])**
    This Service is used for discovering the References of a specified Node.

    **nodeId** (:ref:`NodeId<node_id_type>`)
        id of the node to browse.
    **nodeId[]** (:ref:`NodeId<node_id_type>`)
        list of node IDs to browse
    **params** (table)
        :ref:`browseParameters`
    **msgCallback**
            `Message callback`_
    **Result**
        :ref:`Browsing Result<browseResult>`,error

    Example:

    .. literalinclude:: examples/client/client_browse.lua
        :language: lua
        :lines: 63-77

    `Full source <_static/client/client_browse.lua>`__

read
~~~~

**client:read(params[, msgCallback])**
    Read one or more Attributes of one or more Nodes.

    **params** (table)
        **NodesToRead[]:** (table)
            **NodeId** (:ref:`NodeId<node_id_type>`)
            node identifier
            **AttributeId** (:ref:`attribute`)
            attribute to read
    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`readResponse`,error

    Example:

    .. literalinclude:: examples/client/client_read.lua
        :language: lua
        :lines: 45-61

    `Full source <_static/client/client_read.lua>`__

write
~~~~~

**client:write(params[, msgCallback])**
    This Service is used when writing values to one or more Attributes of one or more Nodes.

    **params** (table)
        **NodesToWrite[]** (table)

            **NodeId** (:ref:`NodeId<node_id_type>`)
            node identifier

            **AttributeId** (:ref:`attribute`)
            attribute to read

            **Value** (:ref:`DataValue<data_value_type>`)
            New value of attribute
    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`writeResponse`,error

    Example:

    .. literalinclude:: examples/client/client_write.lua
        :language: lua
        :lines: 45-64

    `Full source <_static/client/client_write.lua>`__

addNodes
~~~~~~~~

**client:addNodes(params[, msgCallback])**
    Add one or more Nodes into the AddressSpace hierarchy.

    **params** (table)
        **NodesToAdd[]** (table)
            **ParentNodeId** (NodeId)
                Parent's node identifier.
            **ReferenceTypeId** (NodeId)
                Parent's reference type identifier.
            **RequestedNewNodeId** (NodeId)
                NodeID for the new node.
                The actual identifier will be automatically assigned by server if NodeId equals ua.NodeId.Null.
            **BrowseName** (QualifiedName)
                Internal name for the node. This name is used in the
                TranslateBrowsePathsToNodeIdsservice to resolve NodeId by
                path from some nodes.
            **NodeClass**  (ua.Types.NodeClass)
                Node class: Variable, Object, DataType. Only Variable node
                class is currently supported.
            **DisplayName** (LocalizedText)
                Clients use this attribute if they want to display the name
                of the node to the user. Can be localized.
            **Description** (LocalizedText)
                The optional description attribute explains the meaning of
                the node using localised text.
            **WriteMask** (UInt32)
                Bit mask. Every bit defines ability to change corresponding
                attribute.
            **UserWriteMask** (UInt32)
                Bit mask. Every bit defines ability to change corresponding
                attribute for current user.
            **Value** (:ref:`variant_type`)
                Initial value of a variable node.
            **DataType** (:ref:node_id_type)
                Identifier of a node of type NodeClass DataType that describes the structure of a
                value. For example encoding/decoding in binary, json, xml formats. This
                may be an ID of a node of simple type (Int32, UInt,Float, etc), or
                complex structures (for example certificate, ApplicationDescription,
                BuildInfo).
            **ValueRank** (Int32)
                The value rank for the field.
                It shall be Scalar (-1) or a fixed rank Array (>=1).
                There are next predefined values:

                * ScalarOrOneDimension = -3,
                * Any = -2,
                * Scalar = -1,
                * OneOrMoreDimensions = 0,
                * OneDimension = 1,

                Greater values are number of dimensions: 2(matrix),3,4..

            **ArrayDimensions[]** (UInt32)
                Array dimensions of the value. For example: {2,2} describes
                square matrix with size 2*2.
            **AccessLevel** (type Byte)
                Defines the node attributes access mask.
            **UserAccessLevel** (type Byte)
                Current user's write mask.
            **MinimumSamplingInterval** (type Double)
                TODO
            **Historizing** (boolean)
                TODO

    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`addNodesResponse`,error

    Example:

    .. literalinclude:: examples/client/client_add_nodes.lua
        :language: lua
        :lines: 51-80

    `Full source <_static/client/client_add_nodes.lua>`__

translateBrowsePaths
~~~~~~~~~~~~~~~~~~~~

**client:translateBrowsePaths(params[, msgCallback])**
    This Service is used when requesting that the Server translates one or more browse paths to NodeIds.

    **msgCallback**
        `Message callback`_

**client:closeSession([msgCallback])**
    Terminate an active Session.

    **msgCallback**
        `Message callback`_
    **Result**
        :ref:`closeSessionResponse`,error

    Example:

    .. literalinclude:: examples/client/client_create_session.lua
        :language: lua
        :lines: 55-58

    `Full source <_static/client/client_create_session.lua>`__

closeSecureChannel
~~~~~~~~~~~~~~~~~~

**client:closeSecureChannel()**
    Terminate a SecureChannel.

    **Result**
        :ref:`closeSecureChannelResponse`,error


disconnect
~~~~~~~~~~

**client:disconnect()**
    Close the client's server socket connection. Calling this method also closes any open channel.

    **Result**
        error

Message callback
~~~~~~~~~~~~~~~~

**msgCallback(response, err)**
    Callback function that is called when the request has been completed.

    **response**
        Data received from server in response to corresponding request.
    **err**
        Any error that occured during processing of request.