opcua.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file opcua.h
 * @brief OPC UA Binary server: handshake + SecureChannel + Session + Read/Write + Browse (PROTOCORE_ENABLE_OPCUA).
 *
 * OPC UA (IEC 62541) is large; this is built in increments. **Increment 1** is the
 * foundation every OPC UA server needs:
 *   - the OPC UA Binary built-in-type codec (little-endian writer/reader for
 *     Boolean, integers, Float/Double, String, ByteString - bounds-checked, the
 *     basis for every later structure/service),
 *   - the UA-TCP connection protocol (UACP) message framing
 *     (`MessageType` + chunk byte + `MessageSize`), and
 *   - the **Hello / Acknowledge** handshake (OPC UA Part 6 §7.1.2): parse a
 *     client `HEL`, negotiate buffer sizes, emit an `ACK`.
 *
 * The codec + framing + handshake are pure and host-tested; protocore_opcua_rx() is the
 * ProtoConn::PROTO_OPCUA TCP data handler (ESP32) - `listen(4840, ProtoConn::PROTO_OPCUA)` and a client
 * gets through the handshake. Session and the Read service are later increments.
 * SecurityPolicy is None (no encryption) for now.
 *
 * **Increment 2** adds the SecureChannel: NodeId / ExtensionObject / DateTime
 * encoding on top of the increment-1 codec, then parsing an `OpenSecureChannel`
 * (OPN) request and answering with an `OpenSecureChannelResponse` - the server
 * assigns a SecureChannelId + security token (SecurityPolicy None, OPC UA Part 6
 * §7.1.3 / Part 4 §5.5.2).
 *
 * **Increment 3** adds the Session: `MSG` (secure conversation) service calls
 * dispatched by their body TypeId - `CreateSession` (the server assigns a SessionId
 * and AuthenticationToken) and `ActivateSession` (OPC UA Part 4 §5.6).
 *
 * **Increment 4** adds the `Read` service (OPC UA Part 4 §5.10): scalar Variant +
 * DataValue encoding and a registered resolver that maps a NodeId/attribute to a
 * value - the first service that returns live data.
 *
 * **Increment 5** adds the `Browse` service (OPC UA Part 4 §5.8.2) via a registered
 * resolver (ReferenceDescription / QualifiedName / LocalizedText encoding) and
 * `CloseSession`; CloseSecureChannel arrives as a `CLO` message and closes the slot.
 *
 * Later increments add `GetEndpoints` + a `ServiceFault` fallback (so standard
 * clients interoperate) and the `Write` service (DataValue/Variant decode + a
 * registered write resolver). Verified end to end with python asyncua.
 *
 * No heap, no stdlib.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_OPCUA_H
#define PROTOCORE_OPCUA_H
 
#include "protocore_config.h" // the entry point: protocore_types.h for the widths
 
#if PROTOCORE_ENABLE_OPCUA
 
PROTOCORE_BEGIN_DECLS
 
// ---------------------------------------------------------------------------
// OPC UA Binary built-in type codec (little-endian; OPC UA Part 6 §5.2)
// ---------------------------------------------------------------------------
 
/** @brief Bounds-checked little-endian writer. */
typedef struct
{
    uint8_t *o;
    size_t cap;
    size_t n;
    proto_bool ok;
} UaWriter;
void protocore_ua_w_u8(UaWriter *w, uint8_t v);
void protocore_ua_w_u16(UaWriter *w, uint16_t v);
void protocore_ua_w_u32(UaWriter *w, uint32_t v);
void protocore_ua_w_u64(UaWriter *w, uint64_t v);
void protocore_ua_w_i32(UaWriter *w, int32_t v);
void protocore_ua_w_f32(UaWriter *w, float v);
void protocore_ua_w_f64(UaWriter *w, double v);
void protocore_ua_w_bool(UaWriter *w, proto_bool v);
/** @brief Encode a String/ByteString: int32 length (-1 = null) then the bytes. */
void protocore_ua_w_string(UaWriter *w, const char *s, int32_t len);
 
/** @brief Bounds-checked little-endian reader; @c err latches on underrun. */
typedef struct
{
    const uint8_t *p;
    size_t len;
    size_t off;
    proto_bool err;
} UaReader;
uint8_t protocore_ua_r_u8(UaReader *r);
uint16_t protocore_ua_r_u16(UaReader *r);
uint32_t protocore_ua_r_u32(UaReader *r);
uint64_t protocore_ua_r_u64(UaReader *r);
int32_t protocore_ua_r_i32(UaReader *r);
float protocore_ua_r_f32(UaReader *r);
double protocore_ua_r_f64(UaReader *r);
proto_bool protocore_ua_r_bool(UaReader *r);
/**
 * @brief Decode a String/ByteString into @p out (NUL-terminated, bounded).
 * @param out_len  set to the decoded length (or -1 for a null string).
 * @return false on underrun or if the value does not fit @p cap.
 */
proto_bool protocore_ua_r_string(UaReader *r, char *out, size_t cap, int32_t *out_len);
 
// ---------------------------------------------------------------------------
// UA-TCP (UACP) message framing
// ---------------------------------------------------------------------------
 
/** @brief Parsed UACP message header (8 bytes). */
typedef struct
{
    char type[3];  ///< "HEL" / "ACK" / "ERR" / "OPN" / "MSG" / "CLO".
    char chunk;    ///< 'F' final, 'C' intermediate, 'A' abort.
    uint32_t size; ///< total message size including this 8-byte header.
} UaMsgHeader;
 
/** @brief Parse the 8-byte UACP header from @p buf (need >= 8 bytes). */
proto_bool protocore_opcua_parse_header(const uint8_t *buf, size_t len, UaMsgHeader *h);
 
// ---------------------------------------------------------------------------
// Hello / Acknowledge handshake (OPC UA Part 6 §7.1.2)
// ---------------------------------------------------------------------------
 
/** @brief Decoded Hello message body. */
typedef struct
{
    uint32_t protocol_version;
    uint32_t recv_buf_size;
    uint32_t send_buf_size;
    uint32_t max_msg_size;
    uint32_t max_chunk_count;
} OpcUaHello;
 
/** @brief Parse a complete `HEL` message (header + body). @return true if valid. */
proto_bool protocore_opcua_parse_hello(const uint8_t *msg, size_t len, OpcUaHello *out);
 
/**
 * @brief Build the `ACK` reply to a parsed Hello, negotiating buffer sizes down
 *        to the server's PROTOCORE_OPCUA_BUF limit.
 * @return total ACK message bytes written to @p out, or 0 if it does not fit.
 */
size_t protocore_opcua_build_ack(const OpcUaHello *hello, uint8_t *out, size_t cap);
 
// Common transport-level status codes for a UACP ERR message (OPC UA Part 6 §7.1.2.4).
#define PROTOCORE_OPCUA_BAD_TCP_MESSAGE_TYPE_INVALID 0x807E0000u
#define PROTOCORE_OPCUA_BAD_TCP_MESSAGE_TOO_LARGE 0x80800000u
#define PROTOCORE_OPCUA_BAD_TCP_NOT_ENOUGH_RESOURCES 0x80810000u
#define PROTOCORE_OPCUA_BAD_TCP_INTERNAL_ERROR 0x80820000u
 
/**
 * @brief Build a transport-level `ERR` message (the reply a server sends before closing when the handshake
 *        fails): `ERR F <size> <error:UInt32> <reason:String>`. @p error_code is an OPC UA StatusCode
 *        (PROTOCORE_OPCUA_BAD_TCP_*); @p reason is a short UTF-8 diagnostic (may be null for a null String).
 * @return total ERR message bytes written to @p out, or 0 on a null buffer / overflow.
 */
size_t protocore_opcua_build_error(uint32_t error_code, const char *reason, uint8_t *out, size_t cap);
 
// ---------------------------------------------------------------------------
// NodeId / ExtensionObject / DateTime (OPC UA Part 6 §5.2.2)
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeId (the only kind the SecureChannel service needs). */
typedef struct
{
    uint16_t ns;        ///< NamespaceIndex.
    uint32_t id;        ///< Numeric identifier.
    proto_bool numeric; ///< false for a String/Guid/ByteString id (value skipped on read).
} UaNodeId;
 
/** @brief Encode a numeric NodeId, picking the smallest of the TwoByte/FourByte/Numeric forms. */
void protocore_ua_w_nodeid_numeric(UaWriter *w, uint16_t ns, uint32_t id);
 
/**
 * @brief Decode a NodeId. Numeric forms fill @p out; String/Guid/ByteString ids
 *        are skipped (out->numeric=false). Latches @c err on an unknown form.
 */
proto_bool protocore_ua_r_nodeid(UaReader *r, UaNodeId *out);
 
/** @brief Convert a Unix epoch (seconds) to an OPC UA DateTime (100 ns ticks since 1601), 0 for <= 0. */
int64_t protocore_opcua_filetime_from_unix(int64_t unix_seconds);
 
/** @brief Numeric NodeIds (namespace 0) the SecureChannel service uses (binary encoding ids). */
#define OPCUA_ID_OPEN_REQ 446  ///< OpenSecureChannelRequest_Encoding_DefaultBinary.
#define OPCUA_ID_OPEN_RESP 449 ///< OpenSecureChannelResponse_Encoding_DefaultBinary.
 
/** @brief SecurityPolicy "None" URI (no signing/encryption). */
#define OPCUA_POLICY_NONE_URI "http://opcfoundation.org/UA/SecurityPolicy#None"
 
// ---------------------------------------------------------------------------
// SecureChannel - OpenSecureChannel (OPN), SecurityPolicy None
// ---------------------------------------------------------------------------
 
/** @brief Fields extracted from an OpenSecureChannelRequest we need to reply. */
typedef struct
{
    uint32_t secure_channel_id;           ///< 0 on a fresh issue; non-zero on renew.
    uint32_t sequence_number;             ///< Client SequenceHeader SequenceNumber.
    uint32_t request_id;                  ///< Client SequenceHeader RequestId (echoed).
    uint32_t request_handle;              ///< RequestHeader RequestHandle (echoed).
    uint32_t client_protocol_version;     ///< ClientProtocolVersion.
    uint32_t security_token_request_type; ///< 0 = Issue, 1 = Renew.
    uint32_t message_security_mode;       ///< 1 = None, 2 = Sign, 3 = SignAndEncrypt.
    uint32_t requested_lifetime;          ///< RequestedLifetime (ms).
} OpcUaOpenChannel;
 
/** @brief Parse a complete `OPN` message (SecurityPolicy None). @return true if valid. */
proto_bool protocore_opcua_parse_open(const uint8_t *msg, size_t len, OpcUaOpenChannel *out);
 
/**
 * @brief Build the `OPN` OpenSecureChannelResponse to a parsed request.
 * @param req        the parsed request (RequestId/RequestHandle are echoed).
 * @param channel_id SecureChannelId the server assigns/keeps.
 * @param token_id   security TokenId the server issues.
 * @param seq_number server SequenceNumber for this message.
 * @param now_ft     OPC UA DateTime for the response/token timestamps (0 = unset).
 * @param lifetime   RevisedLifetime (ms) granted to the token.
 * @return total OPN message bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_open_response(const OpcUaOpenChannel *req, uint32_t channel_id, uint32_t token_id,
                                           uint32_t seq_number, int64_t now_ft, uint32_t lifetime, uint8_t *out,
                                           size_t cap);
 
// ---------------------------------------------------------------------------
// Session - CreateSession / ActivateSession (MSG service calls, SecurityPolicy None)
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeIds (namespace 0) for the Session services (binary encoding ids). */
#define OPCUA_ID_CREATE_SESSION_REQ 461    ///< CreateSessionRequest_Encoding_DefaultBinary.
#define OPCUA_ID_CREATE_SESSION_RESP 464   ///< CreateSessionResponse_Encoding_DefaultBinary.
#define OPCUA_ID_ACTIVATE_SESSION_REQ 467  ///< ActivateSessionRequest_Encoding_DefaultBinary.
#define OPCUA_ID_ACTIVATE_SESSION_RESP 470 ///< ActivateSessionResponse_Encoding_DefaultBinary.
 
/** @brief Common fields of a `MSG` (secure conversation) service request. */
typedef struct
{
    uint32_t secure_channel_id; ///< SecureChannelId (echoed in the response).
    uint32_t token_id;          ///< SymmetricSecurityHeader TokenId.
    uint32_t sequence_number;   ///< SequenceHeader SequenceNumber.
    uint32_t request_id;        ///< SequenceHeader RequestId (echoed in the response).
    uint32_t type_id;           ///< Body TypeId NodeId (numeric id; 0 if non-numeric).
    uint32_t request_handle;    ///< RequestHeader RequestHandle (echoed in the response).
} OpcUaMsg;
 
/**
 * @brief Parse a `MSG` envelope: security + sequence headers, body TypeId, and the
 *        leading RequestHeader (every service request starts with one).
 * @return true if valid. @p out->type_id selects the service to dispatch.
 */
proto_bool protocore_opcua_parse_msg(const uint8_t *msg, size_t len, OpcUaMsg *out);
 
/** @brief Identity the server advertises in GetEndpoints / CreateSession endpoint descriptions. */
typedef struct
{
    const char *endpoint_url;     ///< e.g. "opc.tcp://192.168.1.85:4840".
    const char *application_uri;  ///< server ApplicationUri.
    const char *application_name; ///< server ApplicationName (display text).
} OpcUaServerInfo;
 
/**
 * @brief Build a `MSG` CreateSessionResponse (SecurityPolicy None): assign a SessionId
 *        and AuthenticationToken and advertise one None endpoint in ServerEndpoints so
 *        a client's endpoint validation matches GetEndpoints.
 * @param req             the parsed request (TokenId/RequestId/RequestHandle echoed).
 * @param session_id      numeric SessionId identifier the server assigns (namespace 1).
 * @param auth_token      numeric AuthenticationToken the server assigns (namespace 1).
 * @param revised_timeout RevisedSessionTimeout (ms).
 * @param info            server identity for the advertised endpoint (may be null for defaults).
 * @param seq             server SequenceNumber for this message.
 * @param now_ft          OPC UA DateTime for the response timestamp (0 = unset).
 * @return total MSG bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_create_session_response(const OpcUaMsg *req, uint32_t session_id, uint32_t auth_token,
                                                     double revised_timeout, const OpcUaServerInfo *info, uint32_t seq,
                                                     int64_t now_ft, uint8_t *out, size_t cap);
 
/**
 * @brief Build a `MSG` ActivateSessionResponse (SecurityPolicy None): ServiceResult Good,
 *        empty ServerNonce / Results / DiagnosticInfos.
 * @return total MSG bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_activate_session_response(const OpcUaMsg *req, uint32_t seq, int64_t now_ft, uint8_t *out,
                                                       size_t cap);
 
// ---------------------------------------------------------------------------
// Read service (MSG, SecurityPolicy None) + Variant / DataValue encoding
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeIds (namespace 0) for the Read service (binary encoding ids). */
#define OPCUA_ID_READ_REQ 631  ///< ReadRequest_Encoding_DefaultBinary.
#define OPCUA_ID_READ_RESP 634 ///< ReadResponse_Encoding_DefaultBinary.
 
/** @brief The OPC UA Attribute id a Read usually wants (the node's Value). */
#define OPCUA_ATTR_VALUE 13
 
/** @brief StatusCodes the Read service returns. */
#define OPCUA_STATUS_GOOD 0x00000000u
#define OPCUA_STATUS_BAD_NODE_ID_UNKNOWN 0x80340000u
 
/** @brief OPC UA built-in type ids for the scalar Variants the Read service encodes. */
typedef enum PROTO_ENUM_PACKED
{
    OPCUA_VAR_NULL = 0,
    OPCUA_VAR_BOOL = 1,
    OPCUA_VAR_INT32 = 6,
    OPCUA_VAR_UINT32 = 7,
    OPCUA_VAR_INT64 = 8,
    OPCUA_VAR_UINT64 = 9,
    OPCUA_VAR_FLOAT = 10,
    OPCUA_VAR_DOUBLE = 11,
    OPCUA_VAR_STRING = 12,
} OpcUaVariantType;
 
/** @brief A scalar OPC UA Variant value (the supported built-in types). */
typedef struct
{
    OpcUaVariantType type; ///< 0 = null Variant.
    proto_bool b;          ///< OPCUA_VAR_BOOL.
    int32_t i32;           ///< OPCUA_VAR_INT32.
    uint32_t u32;          ///< OPCUA_VAR_UINT32.
    int64_t i64;           ///< OPCUA_VAR_INT64.
    uint64_t u64;          ///< OPCUA_VAR_UINT64.
    float f32;             ///< OPCUA_VAR_FLOAT.
    double f64;            ///< OPCUA_VAR_DOUBLE.
    const char *str;       ///< OPCUA_VAR_STRING (referenced, not copied).
    int32_t str_len;       ///< string length (-1 = null string).
} OpcUaVariant;
 
/** @brief Encode a scalar Variant: encoding byte (built-in type id) then the value. */
void protocore_ua_w_variant(UaWriter *w, const OpcUaVariant *v);
 
/** @brief Encode a DataValue: a value/status mask byte then the Variant and/or StatusCode. */
void protocore_ua_w_datavalue(UaWriter *w, const OpcUaVariant *v, uint32_t status);
 
/**
 * @brief Decode a scalar Variant. A decoded OPCUA_VAR_STRING points into the source
 *        buffer (keep it alive). Non-scalar/array Variants latch @c err.
 */
proto_bool protocore_ua_r_variant(UaReader *r, OpcUaVariant *out);
 
/**
 * @brief Decode a DataValue: the mask byte, then (if present) the Variant value and
 *        StatusCode; SourceTimestamp/ServerTimestamp (and picoseconds) are skipped.
 * @param out_value filled with the value (type 0 if no value field present).
 * @param out_status set to the StatusCode (0 if not present).
 */
proto_bool protocore_ua_r_datavalue(UaReader *r, OpcUaVariant *out_value, uint32_t *out_status);
 
/** @brief One NodeId + attribute the client wants to read (a ReadValueId). */
typedef struct
{
    uint16_t ns;
    uint32_t id;
    proto_bool numeric;
    uint32_t attribute;
} OpcUaReadItem;
 
/** @brief Parsed ReadRequest: the MSG envelope plus the (bounded) NodesToRead list. */
typedef struct
{
    OpcUaMsg msg;   ///< envelope + RequestHeader (type_id = ReadRequest).
    uint32_t total; ///< nodes requested (may exceed the captured count).
    uint32_t count; ///< nodes captured (clamped to PROTOCORE_OPCUA_READ_MAX).
    OpcUaReadItem items[PROTOCORE_OPCUA_READ_MAX];
} OpcUaReadRequest;
 
/** @brief Parse a `MSG` ReadRequest. @return true if valid. */
proto_bool protocore_opcua_parse_read(const uint8_t *msg, size_t len, OpcUaReadRequest *out);
 
/**
 * @brief Build a `MSG` ReadResponse: one DataValue per captured NodesToRead entry.
 * @param values   per-node values (values[i] paired with req->items[i]); null type = no value.
 * @param statuses per-node StatusCodes (0 = Good).
 * @return total MSG bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_read_response(const OpcUaReadRequest *req, const OpcUaVariant *values,
                                           const uint32_t *statuses, uint32_t seq, int64_t now_ft, uint8_t *out,
                                           size_t cap);
 
/**
 * @brief Application Read resolver: fill @p out for (ns, id, attribute). Return false
 *        for an unknown node/attribute (the server answers BadNodeIdUnknown).
 */
typedef proto_bool (*OpcUaReadHandler)(uint16_t ns, uint32_t id, uint32_t attribute, OpcUaVariant *out);
 
/** @brief Register the Read resolver the ProtoConn::PROTO_OPCUA server calls for each ReadRequest node. */
void protocore_opcua_set_read_handler(OpcUaReadHandler fn);
 
/** @brief The Read resolver registered above, or null while none is. */
OpcUaReadHandler protocore_opcua_read_handler(void);
 
// ---------------------------------------------------------------------------
// Browse service + Close (MSG, SecurityPolicy None)
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeIds (namespace 0) for Browse / Close services (binary encoding ids). */
#define OPCUA_ID_BROWSE_REQ 527         ///< BrowseRequest_Encoding_DefaultBinary.
#define OPCUA_ID_BROWSE_RESP 530        ///< BrowseResponse_Encoding_DefaultBinary.
#define OPCUA_ID_CLOSE_SESSION_REQ 473  ///< CloseSessionRequest_Encoding_DefaultBinary.
#define OPCUA_ID_CLOSE_SESSION_RESP 476 ///< CloseSessionResponse_Encoding_DefaultBinary.
 
/** @brief Common NodeClass / ReferenceType / TypeDefinition ids (namespace 0) for Browse results. */
#define OPCUA_NODECLASS_OBJECT 1
#define OPCUA_NODECLASS_VARIABLE 2
#define OPCUA_REFTYPE_ORGANIZES 35
#define OPCUA_REFTYPE_HAS_PROPERTY 46
#define OPCUA_REFTYPE_HAS_COMPONENT 47
/** @brief The reference an add-in hangs off its host by (Part 3): how DI and Machinery attach Identification. */
#define OPCUA_REFTYPE_HAS_ADDIN 17604
#define OPCUA_TYPEDEF_BASE_OBJECT 58
/** @brief The type of a plain container of other nodes, as every published model types its folders. */
#define OPCUA_TYPEDEF_FOLDER 61
#define OPCUA_TYPEDEF_BASE_DATA_VARIABLE 63
#define OPCUA_TYPEDEF_PROPERTY 68
 
// ---------------------------------------------------------------------------
// The NamespaceArray
// ---------------------------------------------------------------------------
//
// Part 3 sec 8.2.2: a NodeId's NamespaceIndex is an index into the server's NamespaceArray, and
// index 0 is always the OPC UA core namespace. The index is the SERVER's, not a model's, so a model
// states the URI it publishes and the server answers with the index that URI got. Two models loaded
// together therefore cannot both claim index 1, which is what a per-model compile-time constant did.
 
/** @brief How many namespaces beyond the core one this server can hold. */
#ifndef PROTOCORE_OPCUA_NAMESPACES
#define PROTOCORE_OPCUA_NAMESPACES 4
#endif
 
/** @brief Index 0 of every server's NamespaceArray (Part 3 sec 8.2.2). */
#define OPCUA_CORE_NS_URI "http://opcfoundation.org/UA/"
 
/** @brief The longest namespace URI a compare walks. */
#ifndef PROTOCORE_OPCUA_NS_URI_MAX
#define PROTOCORE_OPCUA_NS_URI_MAX 128
#endif
 
/** @brief The namespace URI a register names. */
typedef struct
{
    const char *uri; ///< the model's namespace URI, referenced and not copied
} OpcUaNamespaceArgs;
 
/**
 * @brief Register @p uri and report the index it holds, adding it if it is not there yet.
 *
 * Reports 0 when the table is full: index 0 is the core namespace, which no model owns, so a caller
 * that lands there knows it did not get one.
 */
uint16_t protocore_opcua_namespace_index(const char *uri);
 
/** @brief The URI at @p index, or NULL past the end of the array. */
const char *protocore_opcua_namespace_uri(uint16_t index);
 
/** @brief How many namespaces the array holds, the core one included. */
uint16_t protocore_opcua_namespace_count(void);
 
/** @brief Encode a QualifiedName: NamespaceIndex (UInt16) + Name (String). */
void protocore_ua_w_qualifiedname(UaWriter *w, uint16_t ns, const char *name);
 
/** @brief Encode a LocalizedText: a present-fields mask then the optional Locale / Text Strings. */
void protocore_ua_w_localizedtext(UaWriter *w, const char *locale, const char *text);
 
/** @brief One reference (ReferenceDescription) returned by a Browse. Strings are referenced, not copied. */
typedef struct
{
    uint32_t ref_type_id;     ///< ReferenceType NodeId numeric id (e.g. OPCUA_REFTYPE_ORGANIZES).
    proto_bool is_forward;    ///< IsForward.
    uint16_t target_ns;       ///< target NodeId namespace.
    uint32_t target_id;       ///< target NodeId numeric id.
    uint16_t browse_name_ns;  ///< BrowseName namespace.
    const char *browse_name;  ///< BrowseName.Name.
    const char *display_name; ///< DisplayName text.
    uint32_t node_class;      ///< NodeClass (e.g. OPCUA_NODECLASS_VARIABLE).
    uint16_t type_def_ns;     ///< TypeDefinition namespace index; 0 for the core types below.
    uint32_t type_def_id;     ///< TypeDefinition NodeId numeric id (e.g. OPCUA_TYPEDEF_BASE_DATA_VARIABLE).
} OpcUaReference;
 
/** @brief Encode a ReferenceDescription. */
void protocore_ua_w_reference(UaWriter *w, const OpcUaReference *ref);
 
/** @brief One NodeId the client wants to browse (a BrowseDescription). */
typedef struct
{
    uint16_t ns;
    uint32_t id;
    proto_bool numeric;
} OpcUaBrowseItem;
 
/** @brief Parsed BrowseRequest: the MSG envelope plus the (bounded) NodesToBrowse list. */
typedef struct
{
    OpcUaMsg msg;
    uint32_t total;
    uint32_t count;
    OpcUaBrowseItem items[PROTOCORE_OPCUA_BROWSE_MAX];
} OpcUaBrowseRequest;
 
/** @brief Parse a `MSG` BrowseRequest. @return true if valid. */
proto_bool protocore_opcua_parse_browse(const uint8_t *msg, size_t len, OpcUaBrowseRequest *out);
 
/**
 * @brief Application Browse resolver: write up to @p max references for (ns, id) into
 *        @p out. @return the count written, or -1 for an unknown node (the server
 *        answers BadNodeIdUnknown for that BrowseResult).
 */
typedef int32_t (*OpcUaBrowseHandler)(uint16_t ns, uint32_t id, OpcUaReference *out, uint32_t max);
 
/** @brief Register the Browse resolver the ProtoConn::PROTO_OPCUA server calls for each browsed node. */
void protocore_opcua_set_browse_handler(OpcUaBrowseHandler fn);
 
/** @brief The Browse resolver registered above, or null while none is. */
OpcUaBrowseHandler protocore_opcua_browse_handler(void);
 
/**
 * @brief Build a `MSG` BrowseResponse: one BrowseResult per browsed node, each with the
 *        references the @p handler returns (up to PROTOCORE_OPCUA_REF_MAX).
 * @return total MSG bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_browse_response(const OpcUaBrowseRequest *req, OpcUaBrowseHandler handler, uint32_t seq,
                                             int64_t now_ft, uint8_t *out, size_t cap);
 
/** @brief Build a `MSG` CloseSessionResponse (ResponseHeader only, ServiceResult Good). */
size_t protocore_opcua_build_close_session_response(const OpcUaMsg *req, uint32_t seq, int64_t now_ft, uint8_t *out,
                                                    size_t cap);
 
// ---------------------------------------------------------------------------
// GetEndpoints + ServiceFault (third-party client interop)
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeIds (namespace 0) for GetEndpoints / ServiceFault (binary encoding ids). */
#define OPCUA_ID_GET_ENDPOINTS_REQ 428  ///< GetEndpointsRequest_Encoding_DefaultBinary.
#define OPCUA_ID_GET_ENDPOINTS_RESP 431 ///< GetEndpointsResponse_Encoding_DefaultBinary.
#define OPCUA_ID_SERVICE_FAULT 397      ///< ServiceFault_Encoding_DefaultBinary.
 
/** @brief StatusCode for an unsupported service (returned in a ServiceFault). */
#define OPCUA_STATUS_BAD_SERVICE_UNSUPPORTED 0x800B0000u
 
/** @brief Encode one EndpointDescription (SecurityMode/Policy None, one Anonymous user-token policy). */
void protocore_ua_w_endpoint_description(UaWriter *w, const OpcUaServerInfo *info);
 
/** @brief Build a `MSG` GetEndpointsResponse advertising a single SecurityPolicy None endpoint. */
size_t protocore_opcua_build_get_endpoints_response(const OpcUaMsg *req, const OpcUaServerInfo *info, uint32_t seq,
                                                    int64_t now_ft, uint8_t *out, size_t cap);
 
/**
 * @brief Build a `MSG` ServiceFault (TypeId i=397) - a bare ResponseHeader carrying
 *        @p service_result, the reply for an unsupported/unknown service request.
 */
size_t protocore_opcua_build_service_fault(const OpcUaMsg *req, uint32_t service_result, uint32_t seq, int64_t now_ft,
                                           uint8_t *out, size_t cap);
 
/** @brief Set the endpoint URL the ProtoConn::PROTO_OPCUA server advertises (GetEndpoints / CreateSession). */
void protocore_opcua_set_endpoint_url(const char *url);
 
// ---------------------------------------------------------------------------
// Write service (MSG, SecurityPolicy None)
// ---------------------------------------------------------------------------
 
/** @brief Numeric NodeIds (namespace 0) for the Write service (binary encoding ids). */
#define OPCUA_ID_WRITE_REQ 673  ///< WriteRequest_Encoding_DefaultBinary.
#define OPCUA_ID_WRITE_RESP 676 ///< WriteResponse_Encoding_DefaultBinary.
 
/** @brief StatusCode for a node/attribute that cannot be written. */
#define OPCUA_STATUS_BAD_NOT_WRITABLE 0x803B0000u
 
/** @brief One value the client wants to write (a WriteValue). */
typedef struct
{
    uint16_t ns;
    uint32_t id;
    proto_bool numeric;
    uint32_t attribute;
    OpcUaVariant value; ///< the DataValue's Variant (string values point into the source buffer).
} OpcUaWriteItem;
 
/** @brief Parsed WriteRequest: the MSG envelope plus the (bounded) NodesToWrite list. */
typedef struct
{
    OpcUaMsg msg;
    uint32_t total;
    uint32_t count;
    OpcUaWriteItem items[PROTOCORE_OPCUA_WRITE_MAX];
} OpcUaWriteRequest;
 
/** @brief Parse a `MSG` WriteRequest. @return true if valid. */
proto_bool protocore_opcua_parse_write(const uint8_t *msg, size_t len, OpcUaWriteRequest *out);
 
/**
 * @brief Build a `MSG` WriteResponse: one StatusCode per NodesToWrite entry.
 * @param results per-node StatusCodes (0 = Good); may be null (all Good).
 * @return total MSG bytes written, or 0 if it does not fit @p cap.
 */
size_t protocore_opcua_build_write_response(const OpcUaWriteRequest *req, const uint32_t *results, uint32_t seq,
                                            int64_t now_ft, uint8_t *out, size_t cap);
 
/**
 * @brief Application Write resolver: apply @p value to (ns, id, attribute) and return a
 *        StatusCode (0 = Good). Return a Bad code (e.g. OPCUA_STATUS_BAD_NODE_ID_UNKNOWN
 *        or OPCUA_STATUS_BAD_NOT_WRITABLE) to reject the write.
 */
typedef uint32_t (*OpcUaWriteHandler)(uint16_t ns, uint32_t id, uint32_t attribute, const OpcUaVariant *value);
 
/** @brief Register the Write resolver the ProtoConn::PROTO_OPCUA server calls for each WriteRequest node. */
void protocore_opcua_set_write_handler(OpcUaWriteHandler fn);
 
// ---------------------------------------------------------------------------
// ESP32 TCP server (ProtoConn::PROTO_OPCUA data handler)
// ---------------------------------------------------------------------------
 
/**
 * @brief ProtoConn::PROTO_OPCUA data handler: handshake, SecureChannel, Session, Read.
 *
 * Dispatched by the session layer for connections accepted on an OPC UA listener
 * (`listen(4840, ProtoConn::PROTO_OPCUA)`). Drains framed messages from the slot's rx ring:
 * `HEL` -> negotiated `ACK`, `OPN` -> OpenSecureChannelResponse (SecurityPolicy
 * None), `MSG` GetEndpoints/CreateSession/ActivateSession/Read/Write/Browse/
 * CloseSession -> their responses (Read/Write/Browse call the registered resolvers;
 * an unknown service draws a ServiceFault), `CLO` (CloseSecureChannel) -> close.
 */
void protocore_opcua_rx(uint8_t slot);
 
/** @brief The OPC UA ProtoHandler (accessor; nullptr on host builds; installed by the builtins list). */
struct ProtoHandler;
const struct ProtoHandler *protocore_opcua_protocore_handler(void);
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_ENABLE_OPCUA
 
#endif // PROTOCORE_OPCUA_H