@spec dec_str(binary()) :: {binary(), binary()}

Decode a compressed string, returning {string, rest}.

@spec enc_str(binary()) :: binary()

Encode a string with URP compressed-length prefix.

@spec enc_str_iodata(binary()) :: iodata()

Like enc_str/1 but returns iodata to avoid copying large payloads.

@spec is_reply?(binary()) :: boolean()

True if the frame is a reply (long header, no REQUEST flag). Everything else (long-header request or short-header) is a request.

@spec null_ctx() :: binary()

Null CurrentContext reference: empty OID (0x00) + cache sentinel (0xFFFF).

@spec one_way?(non_neg_integer()) :: boolean()

True if the given func_id is release (one-way, no reply expected).

Per the URP spec, release (func_id 2) is the only one-way call we'll encounter from soffice. Sending a reply to a one-way call is a protocol violation.

@spec parse_any_string_reply(binary()) :: {:ok, String.t()} | {:error, String.t()}

Parse a reply returning any(string) — extracts the string value.

@spec parse_exception(binary()) :: String.t() | nil

Extract a human-readable error message from an exception reply.

UNO exceptions are Any values containing a struct. The first member of all exception structs is Message (string). Returns the message string, or a fallback if parsing fails.

@spec parse_int32_reply(binary()) :: {:ok, integer()} | {:error, String.t()}

Parse a reply returning a single signed 32-bit integer.

@spec parse_interface_reply(binary()) :: {:ok, String.t()} | {:error, String.t()}

Parse a reply returning a single interface reference (OID string).

@spec parse_qi_reply(binary()) :: {:ok, String.t()} | {:error, String.t()}

Parse a queryInterface reply — extracts OID from any(XInterface) return value.

@spec parse_read_bytes_reply(binary()) :: {:ok, binary()} | {:error, String.t()}

Parse a readBytes reply — return value (long) + out param (sequence<byte>).

@spec parse_request(binary()) :: %{
  func_id: non_neg_integer(),
  body: binary(),
  type_cache: non_neg_integer() | nil,
  tid: binary() | nil
}

Parse an incoming request, extracting func_id, body, and one_way flag.

Handles both long headers (LONGHEADER set, REQUEST set) and short headers (LONGHEADER not set — func_id in lower 6 bits, all cached values reused).

one_way is true when the sender does not expect a reply (MOREFLAGS absent or MUSTREPLY not set). One-way calls like release must not receive replies.

@spec parse_string_sequence_reply(binary()) ::
  {:ok, [String.t()]} | {:error, String.t()}

Parse a reply returning sequence<string>.

@spec property(String.t(), non_neg_integer(), iodata()) :: iodata()

Encode a UNO PropertyValue struct.

@spec recv_frame(:gen_tcp.socket(), timeout(), pos_integer()) :: binary()

Receive a single URP block, returning the payload.

Raises if the block contains more than one message (the C++ writer always sends count=1, but the spec allows count>1).

@spec reply() :: binary()

Build a void reply (LONGHEADER only).

@spec reply(binary()) :: binary()

Build a reply with body.

@spec reply_with_tid(binary()) :: binary()

Build a void reply with explicit TID (for cross-thread replies).

@spec reply_with_tid(binary(), binary()) :: binary()

Build a reply with body and explicit TID (for cross-thread replies).

@spec request(
  non_neg_integer(),
  keyword()
) :: binary()

Build a URP request header with automatic flag computation.

Options:

• :type — {:new, type_name, cache_idx} or {:cached, cache_idx}
• :oid — {oid_string, cache_idx}
• :tid — {tid_bytes, cache_idx}

Omitting an option reuses the value from the previous message on the wire.

@spec send_frame(:gen_tcp.socket(), iodata()) :: :ok

Send a single URP block: <<size::32, count::32, payload>>.

@spec type_cached(non_neg_integer()) :: binary()

Reference a type already in the peer's cache.

@spec type_new(String.t(), non_neg_integer()) :: iodata()

Register a new interface type in the peer's cache.