pdcomm::SecsItem

Class

Owned, immutable SECS-II data item (SEMI E5 section 9).

class SecsItem

Declared in: #include <pdcomm.hpp>

A SecsItem is either a list of child items or a primitive value in one of the SECS-II formats (PDCOMM_SECS_ASCII, PDCOMM_SECS_BINARY, PDCOMM_SECS_U4, and so on). Primitive payloads are the raw wire bytes: numeric values are big-endian, and ASCII bytes must be 0 to 127. Each item stores the PdcommSecsLimits it was created with and uses them again for children and encoding.

Items are values, not views: every factory and getter returns an independent copy, so releasing a parent never invalidates a child, and items returned by GEM results stay valid after the result and endpoint are gone.

const std::vector<uint8_t> temperature = {0x41, 0xac, 0, 0};  // F4 21.5
auto value = pdcomm::SecsItem::primitive(PDCOMM_SECS_F4, temperature, limits);
auto lot = pdcomm::SecsItem::primitive(
    PDCOMM_SECS_ASCII, std::vector<uint8_t>{'L', 'O', 'T', '-', '0', '0', '1'}, limits);
auto pair = pdcomm::SecsItem::list({&value, &lot}, limits);
std::vector<uint8_t> wire = pair.bytes();  // encoded L[2] F4 A

Notes

Move-only RAII wrapper over PdcommSecsItem. A default-constructed or moved-from item is empty; test it with operator bool. Read-only calls (info(), child(), bytes(), payload()) may run concurrently on one item, but destruction must not race with them.

Members

`SecsItem`

Constructor

Creates an empty item that owns no native handle.

SecsItem() noexcept = default

Declared in: #include <pdcomm.hpp>

Use an empty item to mean "no value", for example when a GEM result has no body.

`SecsItem`

Constructor

Takes ownership of the native handle owned by other.

SecsItem(SecsItem &&other) noexcept

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`other`	Source wrapper; it becomes empty.

`SecsItem`

Constructor

Copying is disabled; the wrapper exclusively owns its native handle.

SecsItem(const SecsItem &) = delete

Declared in: #include <pdcomm.hpp>

`adopt`

Method

Wraps a native item handle and takes ownership of it.

static SecsItem adopt(PdcommSecsItem *handle) noexcept

Declared in: #include <pdcomm.hpp>

Use this to manage a handle returned by a C function such as pdcomm_secs_decode().

Parameters

Name	Description
`handle`	Live handle to own, or `nullptr` for an empty item. It must not be owned or destroyed by anything else afterwards.

Returns

A wrapper that destroys handle when it goes out of scope.

`bytes`

Method

Encodes the item into SECS-II wire format.

std::vector<uint8_t> bytes() const

Declared in: #include <pdcomm.hpp>

Item headers use the minimal length-byte count; primitive payload bytes are kept as is.

Returns

The complete encoded item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT when the item is empty.

`child`

Method

Returns a copy of one child of a list item.

SecsItem child(size_t index) const

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`index`	Zero-based child position.

Returns

An independent copy of the child; releasing this list does not affect it.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT when the item is empty or is not a list; PDCOMM_OUT_OF_RANGE when index is not less than the child count.

`decode`

Method

Decodes exactly one encoded SECS-II item from a vector.

static SecsItem decode(const std::vector<uint8_t> &data, const PdcommSecsLimits &limits, size_t *errorOffset = nullptr)

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`data`	Encoded item bytes.
`limits`	Limits the decoded tree must satisfy; they are stored in the item.
`errorOffset`	Optional output that receives the failing field offset.

Returns

The decoded item.

Notes

Throws pdcomm::Error: Same statuses as the pointer-and-length overload of decode().

`decode`

Method

Decodes exactly one encoded SECS-II item.

static SecsItem decode(const uint8_t *data, size_t length, const PdcommSecsLimits &limits, size_t *errorOffset = nullptr)

Declared in: #include <pdcomm.hpp>

The input must hold one complete item with no trailing bytes. The decoded values are copied, so data can be released after the call.

Parameters

Name	Description
`data`	Encoded item bytes.
`length`	Number of bytes at `data`.
`limits`	Limits the decoded tree must satisfy; they are stored in the item.
`errorOffset`	Optional output. On a decode failure it receives the offset of the start of the field that failed, not of the first missing byte.

Returns

The decoded item.

Notes

Throws pdcomm::Error: PDCOMM_TRUNCATED when the input ends early (including nullptr with length 0); PDCOMM_INVALID_DATA for malformed headers, widths, non-ASCII text or trailing data; PDCOMM_LIMIT_EXCEEDED when limits are exceeded; PDCOMM_INVALID_ARGUMENT for invalid pointers or a too-small limits.struct_size.

`info`

Method

Describes the item's format and size.

PdcommSecsInfo info() const

Declared in: #include <pdcomm.hpp>

Returns

A PdcommSecsInfo with format (a PDCOMM_SECS_* code), count (children for a list, elements for a primitive), encoded_length, node_count and depth.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT when the item is empty.

`list`

Method

Creates a list item that contains copies of children.

static SecsItem list(const std::vector<const SecsItem *> &children, const PdcommSecsLimits &limits)

Declared in: #include <pdcomm.hpp>

The children are copied after the aggregate size, item count and depth are checked against limits. The caller keeps ownership of the original items.

Parameters

Name	Description
`children`	Items to copy, in order. An empty vector creates an empty list. Every pointer must refer to a non-empty item.
`limits`	Limits for the whole new tree; they are stored in the item.

Returns

The new list item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for a nullptr or empty child; PDCOMM_LIMIT_EXCEEDED when the tree exceeds limits.

`list`

Method

Creates a list item that contains copies of children.

static SecsItem list(std::initializer_list<const SecsItem *> children, const PdcommSecsLimits &limits)

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`children`	Items to copy, in order. Every pointer must refer to a non-empty item.
`limits`	Limits for the whole new tree; they are stored in the item.

Returns

The new list item.

Notes

Throws pdcomm::Error: Same statuses as the vector overload of list().

`nativeHandle`

Method

Returns the owned native handle for direct C API calls.

PdcommSecsItem *nativeHandle() noexcept

Declared in: #include <pdcomm.hpp>

Returns

The handle, or nullptr for an empty item. Ownership stays with this wrapper.

`nativeHandle`

Method

Returns the owned native handle for read-only C API calls.

const PdcommSecsItem *nativeHandle() const noexcept

Declared in: #include <pdcomm.hpp>

Returns

The handle, or nullptr for an empty item. Ownership stays with this wrapper.

`operator bool`

Method

Reports whether the wrapper owns a native item.

explicit operator bool() const noexcept

Declared in: #include <pdcomm.hpp>

Returns

true when an item is owned; false for an empty or moved-from item.

`operator=`

Method

Releases the current handle, then takes ownership of the handle owned by other.

SecsItem &operator=(SecsItem &&other) noexcept

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`other`	Source wrapper; it becomes empty.

Returns

This wrapper.

`operator=`

Method

Copy assignment is disabled; the wrapper exclusively owns its native handle.

SecsItem &operator=(const SecsItem &) = delete

Declared in: #include <pdcomm.hpp>

`payload`

Method

Copies the raw payload bytes of a primitive item.

std::vector<uint8_t> payload() const

Declared in: #include <pdcomm.hpp>

Returns

The payload in wire order; empty for an empty primitive value.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT when the item is empty or is a list, because lists have no primitive payload.

`primitive`

Method

Creates a primitive item from a payload vector.

static SecsItem primitive(uint8_t format, const std::vector<uint8_t> &data, const PdcommSecsLimits &limits)

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`format`	SECS-II format code; `PDCOMM_SECS_LIST` is rejected.
`data`	Payload in wire order (big-endian for numbers); may be empty.
`limits`	Limits for the item; they are stored in the item.

Returns

The new item.

Notes

Throws pdcomm::Error: Same statuses as the pointer-and-length overload of primitive().

`primitive`

Method

Creates a primitive item from raw payload bytes.

static SecsItem primitive(uint8_t format, const uint8_t *data, size_t length, const PdcommSecsLimits &limits)

Declared in: #include <pdcomm.hpp>

Parameters

Name	Description
`format`	SECS-II format code such as `PDCOMM_SECS_U4` or `PDCOMM_SECS_ASCII`. `PDCOMM_SECS_LIST` is rejected; use list() instead.
`data`	Payload in wire order (big-endian for numbers). May be `nullptr` when `length` is 0, which creates an empty value.
`length`	Payload size in bytes. It must be a multiple of the format's element width.
`limits`	Limits for the item; they are stored in the item.

Returns

The new item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for an unknown or list format; PDCOMM_INVALID_DATA for a length that is not a multiple of the element width or for ASCII bytes above 127; PDCOMM_LIMIT_EXCEEDED when limits are exceeded.

`~SecsItem`

Method

Releases the native handle with pdcomm_secs_destroy().

~SecsItem()

Declared in: #include <pdcomm.hpp>

An empty item releases nothing.