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


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.

ByteString
~~~~~~~~~~

  An array ot bytes. In LUA represented as 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 = {
      ns = 1,
      Name = "Node Name"
    }

.. _node_id_type:

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/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
*********************

**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/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/node_id.lua>`__

**StatusCode**
  Error code.

.. _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 Fields
**************

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

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

  * DataValue
  * Variant
  * ExtensionObject


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"
      }
    }
  }

.. _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)
    }


.. _extension_object_type:

ExtensionObject
~~~~~~~~~~~~~~~

  ExtensionObject is a structure that can be used to represent complex data
  structures.

  Also it is used when the same field can be of different types.F or example there are
  different set of attributes for different types of nodes. In fhis case ExtensionObject
  a field with attributes can contain one of: ObjectAttributes, VariableAttributes, MethodAttributes, etc.

  Extension objects represented as a table with two fields:

    * **TypeId** - NodeId of the type of the object
    * **Body** - A table with fields that represent the object's data.

  .. note::

      If structure of is not known for current server/client then body considered
      to be opaque and can be one of the following types:

        * ByteString
        * XML string
        * JSON string

      In this case parsing of body is not performed automatically
      and should be done manually by a developer

  Example:

  .. code-block:: lua

    local extensionObject = {
      TypeId = {ns=0, id="i=1"},
      Body = {
        UInt32 = 100
      }
    }

    local extensionObject = {
      TypeId = {ns=0, id="i=1"},
      Body = {
        UInt32 = 100
      }
    }

  .. note::

    The Body field can be any Variant type.

Requests
--------

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