==========
Data Types
==========


.. _node_id_type:

Node Identifiers (NodeID)
-------------------------

A Node identifier is encoded as a string with the following syntax:

  [ns=<**namespace_index**>;]<**type**>=<**value**>

**namesace_index**
  Unsigned 16-bit integer.
  Should be omitted if the namespace is zero.

**type**
  The Identifier's type encoded as a string:

    * i - Integer
    * s - string
    * g - GUID
    * b - opaque byte string

**value**
  Identifier encoded as string depending on type:

    * i - In decimal form
    * s - UTF-8 string
    * g - GUID with small letters of hexademical numbers
    * b - opaque base64 encoded string.

Examples:

  .. literalinclude:: examples/node_id.lua
      :language: lua
      :lines: 4-20

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


Additional details can be found in the official `OPCUA reference <https://reference.opcfoundation.org/v104/Core/docs/Part6/5.3.1/#5.3.1.10>`_

Encoding and decoding NodeID string notation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**toString(id, ns)**
  | **id** - identifier value: can be number, string, GUID, array or bytes
  | **ns** - namespace index number or nil
  | returns string with encoded NodeID

**toString( {id=<value>[, ns=<number>]} )**
  | **id**  - identifier value: can be number, string, GUID, array oy bytes.
  | **ns**  - namespace index number or nil.
  | returns string with encoded NodeID

Examples:

  .. literalinclude:: examples/node_id.lua
      :language: lua
      :lines: 25-71

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


**fromString(string)**
  | **string** - encoded NodeID
  | **return** - table with fields: **ns** - namepsace index, **id** - value

Examples:

  .. literalinclude:: examples/node_id.lua
      :language: lua
      :lines: 77-117

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


.. _variant_type:

Variant
-------

All values in OPC-UA can be represented with the universal data
structure Variant. Variants can represent either a scalar value or a
multidimensional array. Multidimensional arrays can
only be of one type in Lua. A Variant is represented as a table
with one field, where the key defines type of the value stored in the table.

Variant example
~~~~~~~~~~~~~~~


.. code-block:: lua

  local uint32 = {
    UInt32 = 0
  }

  local uint32_array = {
    UInt32 = {1,2,3,4,5,6,7}
  }


  local localized_text = {
    LocalizedText = {
      Locale = "en-US",
      Text = "This is a text string"
    }
  }
  local localized_text_array = {
    LocalizedText = {
      { #1
        Locale = "en-US",
        Text = "This is a text string"
      },
      { #2
        Text = "This is a text string without locale"
      }
    }
  }

The fields you may set in a Variant table
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * Byte
  * Sbyte
  * Int16
  * UInt16
  * Int32
  * UInt32
  * Int64
  * UInt64
  * Float
  * Double

  * DateTime
  * Guid
  * LocalizedText
  * QualifiedName
  * NodeId
  * StatusCode
  * String
  * QualifiedName

  * DataValue
  * Variant
  * ExtensionObject

OPC-UA Types
------------

  **Sbyte**
    Signed 8-bit integer

  **Byte**
    Unsigned 8-bit integer

  **Int16**
    Signed 16-bit integer

  **UInt16**
    Unsigned 16-bit integer

  **Int32**
    Signed 32-bit integer

  **UInt32**
    Unsigned 32-bit integer

  **Int64**
    Signed 64-bit integer

  **UInt64**
    Unsigned 64-bit integer

  **Float**
    Real 32-bit number

  **Double**
    Real 64-bit number

  **DateTime**
    Real 64-bit number. Represents milliseconds since Jan. 1, 1970.

  **String**
    String.

  **Guid**
    Guid in form of table:

    .. code-block:: lua

      local guid = {
        Data1 = 0x123456, -- uint32
        Data2 = 0x1234,   -- uint16
        Data3 = 0x1234,   -- uint16
        Data4 = 0x23,     -- byte
        Data5 = 0x23,     -- byte
        Data6 = 0x21,     -- byte
        Data7 = 0x21,     -- byte
        Data8 = 0x21,     -- byte
        Data9 = 0x21,     -- byte
        Data10 = 0x21,    -- byte
        Data11 = 0x21     -- byte
      }

    *TBD* - String representaion

.. _localized_text_type:

  **LocalizedText**
    Localized text. A table with two fields:
      * locale - optional locale name. The default locale is used if nil
      * text - string with content

    Example:

    .. code-block:: lua

      local localizedText = {
        locale = "en-US",
        text = "This is localized text"
      }

      local localizedText = {
        text = "This is localized text"
      }

.. _qualified_name_type:

  **QualifiedName**
    Qualified Name is the service identifier of a node, which consist of a namespace
    index and text label.

    .. code-block:: lua

      local qualifiedName = {
        nsi = 1,
        name = "Node Name"
      }

  **NodeID**
    Identifier of a node. Explaned in :ref:`node_id_type`

  **StatusCode**
    Error code.

.. _data_value_type:

  **DataValue**
    Complete variable value.

    .. code-block:: lua

      local dataValue = {
        Value = {UInt32 = 100}, -- Variant(v.Value)
        StatusCode = ua.StatusCode.Good, -- StatusCode (Optional)
        SourceTimestamp = os.time(), -- DateTime (Optional)
        ServerTimestamp = os.time(), -- DateTime (Optional)
        SourcePicoseconds = 0, -- UInt16 (Optional)
        ServerPicoseconds = 0, -- UInt16 (Optional)
      }

  **Variant**
    Explained in section :ref:`variant_type`

  **ExtensionObject**
    Any data type that can be encoded with OPC-UA encoding schemas (binary, XML, Json).

    .. code-block:: lua

      local extensionObject = {
        typeId = "i=7617", -- (NodeId) DataType node that represent encoding.
        body = {0,1,2,3,4,5} -- (ByteString) Encoded value (binary, XML, JSON)
      }

activateSessionResponse
-----------------------

  **ServerNonce**
    A random number that should not be reused.

  **Results[]**
    list of SatusCodes

addNodesResponse
----------------

  **Rresults[]** (array)

    **StatusCode**
      StatusCode for the added Node

    **AddedNodeId**
      Server assigned NodeId for the added Node. The NodeId is nil if the operation failed.

browseParameters
----------------

  **RequestedMaxReferencesPerNode**
    Maximum number of reference types that will be processed. Zero - unlimited
  **NodesToBrowse[]** Array of nodes to browse:
    **NodeId** (:ref:`NodeId<node_id_type>`)
      The identifier of a node to browse
    **ReferenceTypeId** :ref:`NodeId<node_id_type>`
      Reference type identifier
    **BrowseDirection** ua.Types.BrowseDirection
      Browsing direction
    **nodeClassMask** ua.Types.NodeClass
      The class of nodes to include in the response
    **ResultMask** ua.Types.BrowseResultMask
      A mask that specifies the set of data to include in the response
    **IncludeSubtypes** Boolean
      If 1 then all subtypes of the specified ReferenceTypeId will be followed

browseResult
------------

**Results[]** (array)
  The result is provided as a Lua table. Every element index corresponds to
  an element in the request.

  **StatusCode**
    The 'status' of browsing the requested node.
  **References**
    Array of references.

    **NodeId** (:ref:`NodeId<node_id_type>`)
      Node identifier
    **ReferenceTypeId** (:ref:`NodeId<node_id_type>`)
      Reference type identifier
    **IsForward** (Boolean)
      Browsing direction
    **BrowseName** (:ref:`QualifiedName<qualified_name_type>`)
      Service name of a node
    **DisplayName** (:ref:`LocalizedText<localized_text_type>`)
      User labe of a node
    **NodeClass** (Int32)
      Node class
    **TypeDefinition** (:ref:`NodeId<node_id_type>`)
      The node's type definition

closeSecureChannelResponse
--------------------------
  Empty table

closeSessionResponse
--------------------
  Empty table

createSessionResponse
---------------------
  **ResponseHeader**

  **SessionId** (:ref:`node_id_type`)
    A unique NodeId assigned by the Server to the Session.

  **AuthenticationToken** (:ref:`node_id_type`)
    A unique identifier assigned by the Server to the Session

  **RevisedSessionTimeout** (double)
    Actual maximum number of milliseconds that a Session shall remain open without activity.

  **ServerNonce** (bytestring)
    A random number that should never be used in any other request.

  **ServerCertificate**
    The Application Instance Certificate issued to the Server

  **ServerEndpoints**
    List of Endpoints that the Server supports.

  **ServerSignature**
    This is a signature generated with the private key associated with the serverCertificate.

  **MaxRequestMessageSize** (uint32)
    The maximum size, in bytes, for the body of any request message.

findServersResponse
-------------------

 **Servers[]**
    List of Servers that meet criteria specified in the request.

      **ApplicationUri**

      **ProductUri**

      **ApplicationName**

      **ApplicationType**

      **GatewayServerUri**

      **DiscoveryProfileUri**

      **DiscoveryUrls**

getEndpointsResponse
--------------------
  **Endpoints[]**

      **EndpointUrl**

      **Server**

      **ServerCertificate**

      **SecurityMode**

      **SecurityPolicyUri**

      **UserIdentityTokens**

      **TransportProfileUri**

      **SecurityLevel**

openSecureChannelResponse
-------------------------

  **ResponseHeader**

  **SecurityToken**
    **ChannelId** (uint32)
      A unique identifier for the SecureChannel.
    **TokenId** (uint32)
      A unique identifier for a single SecurityToken within the channel.
    **CreatedAt** (dateTime)
      The time when the SecurityToken was created.
    **RevisedLifetime** (uint32)
      The lifetime of the SecurityToken in milliseconds.


readResponse
------------

  **Results[]** (dataValue)
    List of Attribute values

writeResponse
-------------

  **Results[]** (statusCode)
    List of results for the Nodes to write