pdcomm::GemResult

Class

Owned snapshot of one TCP event after GEM processing.

class GemResult

Declared in: #include <pdcomm_gem.hpp>

GemEndpoint::handleEvent() returns a GemResult for every TCP event. Start with info(): GemResultInfo::kind tells you whether the event was a reply to your request (GemResultKind::Response), an incoming request (GemResultKind::Primary), a failure, or not a GEM message at all. GemResultInfo::outcome then selects the typed getter to use, for example statusValue() for GemOutcome::ValuesReceived or eventInfo() for GemOutcome::EventReceived.

The result owns copies of everything it exposes. It stays readable after the original TcpEvent and the endpoint are destroyed, and every returned SecsItem is independently owned.

Typed getters share these errors: PDCOMM_INVALID_STATE when the result is not of the kind the getter needs, PDCOMM_OUT_OF_RANGE for an index past the end, and PDCOMM_INVALID_ARGUMENT when the result is empty (default-constructed or moved from).

endpoint->poll();
while (auto event = endpoint->tcp().nextEvent()) {
    auto result = endpoint->handle(event);
    auto info = result.info();
    if (info.kind != pdcomm::GemResultKind::Ignored) {
        std::cout << "RESULT kind=" << static_cast<unsigned>(info.kind)
                  << " outcome=" << static_cast<unsigned>(info.outcome) << "\n";
        auto body = result.body();
        if (body) std::cout << body.bytes().size() << " body bytes\n";
    }
}

Notes

Move-only RAII wrapper over PdcommGemResult. Getters may run concurrently on one result, but not concurrently with a respond or acknowledge call that takes the same result, or with its destruction.

Members

`GemResult`

Constructor

Creates an empty result that owns no native handle.

GemResult() noexcept = default

Declared in: #include <pdcomm_gem.hpp>

`GemResult`

Constructor

Takes ownership of the native handle owned by other.

GemResult(GemResult &&other) noexcept

Declared in: #include <pdcomm_gem.hpp>

Parameters

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

`GemResult`

Constructor

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

GemResult(const GemResult &) = delete

Declared in: #include <pdcomm_gem.hpp>

`adopt`

Method

Wraps a native result handle and takes ownership of it.

static GemResult adopt(PdcommGemResult *handle) noexcept

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`handle`	Live handle from a C function such as pdcomm_gem_handle_event(), or `nullptr` for an empty result. Nothing else may destroy it afterwards.

Returns

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

`alarmAt`

Method

Returns one alarm of a received S5F1 report or S5F6/S5F8 list.

GemAlarmValue alarmAt(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

The values come from the wire tuple (ALCD, ALID, ALTX); local enabled flags and CEID mappings are not included.

Parameters

Name	Description
`index`	Zero-based alarm position, less than GemAlarmResultInfo::count.

Returns

ALID, category, text and set state.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`alarmInfo`

Method

Summarizes a received S5F1 alarm report or S5F6/S5F8 alarm list.

GemAlarmResultInfo alarmInfo() const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::AlarmReceived, GemOutcome::AlarmListReceived or GemOutcome::EnabledAlarmListReceived.

Returns

Count, report or list flag, W-bit and acknowledgement state.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome.

`body`

Method

Returns a copy of the message body.

SecsItem body() const

Declared in: #include <pdcomm_gem.hpp>

For incoming primaries this is the received body; for replies it is the reply body.

Returns

The body item, or an empty SecsItem when the message had no body (PDCOMM_OUT_OF_RANGE from the C API is mapped to an empty item).

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT when the result is empty, or PDCOMM_ALLOCATION_FAILED when the copy fails.

`commandInfo`

Method

Summarizes a received S2F41 request (equipment) or S2F42 reply (host).

GemCommandResultInfo commandInfo() const

Declared in: #include <pdcomm_gem.hpp>

Request information describes the validation frozen at receipt and stays unchanged after the reply. The HCACK actually sent or received is in GemResultInfo::acknowledgement.

Returns

Parameter and issue counts, validation and completion metadata.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE when the result is not a command request or reply.

`commandIssue`

Method

Returns one parameter issue: a validation issue of a request, or a CPACK entry of a reply.

GemCommandIssueValue commandIssue(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Reply issue names keep their wire format; frozen validation issues use logical names whose numeric form may be normalized.

Parameters

Name	Description
`index`	Zero-based position, less than GemCommandResultInfo::issueCount.

Returns

Name and CPACK code.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`commandName`

Method

Returns the RCMD of a received S2F41 request in its wire format.

SecsItem commandName() const

Declared in: #include <pdcomm_gem.hpp>

Returns

An independently owned name item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind.

`commandParameter`

Method

Returns one (CPNAME, CPVAL) pair of a received S2F41 request.

GemCommandParameterValue commandParameter(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Order and duplicates are kept as received.

Parameters

Name	Description
`index`	Zero-based position, less than GemCommandResultInfo::parameterCount.

Returns

Independently owned name and value items.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`constantChange`

Method

Returns one proposed change of a received S2F15 request.

GemConstantChangeValue constantChange(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

The ID and value keep their wire format and order. The original value is the value at receipt, or absent for an unknown ECID.

Parameters

Name	Description
`index`	Zero-based position, less than GemConstantChangeInfo::changeCount.

Returns

ECID, proposed value and original value.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`constantChangeInfo`

Method

Summarizes a received S2F15 request (equipment) or S2F16 reply (host).

GemConstantChangeInfo constantChangeInfo() const

Declared in: #include <pdcomm_gem.hpp>

For a reply, all request fields are zero; the received EAC is in GemResultInfo::acknowledgement. A host cannot infer physical application from it.

Returns

Change count, validation and application state.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind.

`constantMetadata`

Method

Returns one field of one row of an S2F30 namelist reply received by a host.

SecsItem constantMetadata(size_t index, GemConstantField field) const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::ConstantMetadataReceived. Wire metadata is preserved as received, including empty ASCII markers for absent or unknown values.

Parameters

Name	Description
`index`	Zero-based row position, less than GemResultInfo::entryCount.
`field`	GemConstantField::Id through GemConstantField::Units; GemConstantField::Current is not valid here.

Returns

An independently owned item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for GemConstantField::Current; PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`constantValue`

Method

Returns one value of an S2F14 equipment constant reply received by a host.

GemConstantValue constantValue(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::ConstantValuesReceived. For explicit queries the value comes with the original requested ECID; a request for all values has no IDs on the wire.

Parameters

Name	Description
`index`	Zero-based value position, less than GemResultInfo::entryCount.

Returns

Requested ECID (if any) and value.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`definition`

Method

Alias of statusName().

GemStatusName definition(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based row position.

Returns

SVID, name and units.

Notes

Throws pdcomm::Error: Same statuses as statusName().

`directory`

Method

Alias of directoryGet().

SecsItem directory(size_t index, GemDirectoryField field) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based row position.
`field`	Field to read.

Returns

An independently owned item.

Notes

Throws pdcomm::Error: Same statuses as directoryGet().

`directoryAt`

Method

Returns one row of an S1F22 or S1F24 namelist reply received by a host.

GemDirectoryEntryInfo directoryAt(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::DataDirectoryReceived or GemOutcome::EventDirectoryReceived.

Parameters

Name	Description
`index`	Zero-based row position, less than GemResultInfo::entryCount.

Returns

Row ID and, for event rows, the VID count.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`directoryGet`

Method

Returns one field of one row of an S1F22 or S1F24 namelist reply.

SecsItem directoryGet(size_t index, GemDirectoryField field) const

Declared in: #include <pdcomm_gem.hpp>

Data rows support GemDirectoryField::Name and GemDirectoryField::Units; event rows support GemDirectoryField::Name and GemDirectoryField::VariableIds (a U4 array).

Parameters

Name	Description
`index`	Zero-based row position.
`field`	Field to read.

Returns

An independently owned item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_ARGUMENT for a field the row kind does not have; PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`enhancedCommandAcknowledgements`

Method

Returns the outer acknowledgement list of an enhanced command result.

SecsItem enhancedCommandAcknowledgements() const

Declared in: #include <pdcomm_gem.hpp>

The list is empty for an accepted request, holds the frozen errors for a rejected request, and holds the exact received items for an S2F50 reply.

Returns

An independently owned list item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind.

`enhancedCommandInfo`

Method

Summarizes a received S2F49 request (equipment) or S2F50 reply (host).

GemEnhancedCommandResultInfo enhancedCommandInfo() const

Declared in: #include <pdcomm_gem.hpp>

Request information describes the admission frozen at receipt, even after responding.

Returns

Counts, DATAID, validation and completion metadata.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE when the result is not an enhanced command request or reply.

`enhancedCommandName`

Method

Returns the RCMD of a received S2F49 request.

SecsItem enhancedCommandName() const

Declared in: #include <pdcomm_gem.hpp>

Returns

An independently owned name item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind.

`enhancedCommandObject`

Method

Returns the OBJSPEC of a received S2F49 request.

SecsItem enhancedCommandObject() const

Declared in: #include <pdcomm_gem.hpp>

Returns

An independently owned ASCII item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind.

`enhancedCommandParameter`

Method

Returns one (CPNAME, CEPVAL) pair of a received S2F49 request.

GemCommandParameterValue enhancedCommandParameter(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based position, less than GemEnhancedCommandResultInfo::parameterCount.

Returns

Independently owned name and value items.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a reply or another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`eventInfo`

Method

Returns the header of an S6F11 event report received by a host.

GemEventInfo eventInfo() const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::EventReceived.

Returns

DATAID, CEID, report count and whether S6F12 was sent.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome.

`eventReport`

Method

Returns one report of a received S6F11.

GemEventReport eventReport(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based report position, less than GemEventInfo::reportCount.

Returns

RPTID and value count.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`eventValue`

Method

Returns one value of one report of a received S6F11.

SecsItem eventValue(size_t reportIndex, size_t valueIndex) const

Declared in: #include <pdcomm_gem.hpp>

Event report values carry no VIDs; map positions with your report definitions.

Parameters

Name	Description
`reportIndex`	Zero-based report position.
`valueIndex`	Zero-based value position inside the report.

Returns

An independently owned value item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`info`

Method

Returns the kind, outcome, request kind, codes, token and state of this result.

GemResultInfo info() const

Declared in: #include <pdcomm_gem.hpp>

Valid for every non-empty result.

Returns

Common result information.

Notes

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

`nativeHandle`

Method

Returns the owned native handle for direct C API calls.

PdcommGemResult *nativeHandle() noexcept

Declared in: #include <pdcomm_gem.hpp>

Returns

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

`nativeHandle`

Method

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

const PdcommGemResult *nativeHandle() const noexcept

Declared in: #include <pdcomm_gem.hpp>

Returns

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

`operator bool`

Method

Reports whether the wrapper owns a native result.

explicit operator bool() const noexcept

Declared in: #include <pdcomm_gem.hpp>

Returns

true when a result is owned.

`operator=`

Method

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

GemResult &operator=(GemResult &&other) noexcept

Declared in: #include <pdcomm_gem.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.

GemResult &operator=(const GemResult &) = delete

Declared in: #include <pdcomm_gem.hpp>

`programInfo`

Method

Summarizes a process program request or reply (stream 7, functions 1 to 6, 17 to 20).

GemProgramInfo programInfo() const

Declared in: #include <pdcomm_gem.hpp>

Requests expose received data and local processing state. Replies expose only wire facts; a host cannot infer the peer's storage or durability from them.

Returns

Request kind, counts, acknowledgement and processing state.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for invalid, aborted or unrelated results.

`programItem`

Method

Returns a program ID or body carried by a program result.

SecsItem programItem(GemProgramField field, size_t index = 0) const

Declared in: #include <pdcomm_gem.hpp>

GemProgramField::Id with index reads request IDs or the IDs of an S7F6/S7F20 reply. GemProgramField::Body with index 0 reads the body of an S7F3 request or S7F6 reply.

Parameters

Name	Description
`field`	Which item to read.
`index`	Zero-based ID position, less than GemProgramInfo::idCount; 0 for the body.

Returns

An independently owned item, or an empty item for the body of an S7F6 reply that reports an unknown program.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for a field the result does not carry; PDCOMM_OUT_OF_RANGE for an invalid index.

`queryInfo`

Method

Summarizes a report query request (equipment) or its S6F16/S6F20/S6F22 reply (host).

GemQueryInfo queryInfo() const

Declared in: #include <pdcomm_gem.hpp>

Returns

Query kind, requested ID and counts.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for failed, malformed, aborted or unrelated results.

`queryReport`

Method

Returns one report of an S6F16 reply.

GemQueryReportInfo queryReport(size_t reportIndex) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`reportIndex`	Zero-based report position, less than GemQueryInfo::reportCount.

Returns

RPTID and value count.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE when the result is not an S6F16 reply; PDCOMM_OUT_OF_RANGE for an invalid index.

`queryValue`

Method

Returns one value of a report query reply.

GemQueryValue queryValue(size_t reportIndex, size_t valueIndex) const

Declared in: #include <pdcomm_gem.hpp>

For S6F16 use both indexes. For S6F20 and S6F22 reportIndex must be 0. Only S6F22 values carry their VID.

Parameters

Name	Description
`reportIndex`	Report position for S6F16; 0 otherwise.
`valueIndex`	Zero-based value position.

Returns

VID (S6F22 only) and value item.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`spoolError`

Method

Returns one rejected stream of an S2F44 reply received by a host.

GemSpoolError spoolError(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based position, less than GemSpoolInfo::errorCount.

Returns

Stream, STRACK and the rejected functions.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`spoolInfo`

Method

Summarizes a spool request, reply or delivery result.

GemSpoolInfo spoolInfo() const

Declared in: #include <pdcomm_gem.hpp>

Processing fields describe the last operation on this result; use GemEndpoint::spoolState() for the current queue state.

Returns

Request kind, command, durability, proof and processing flags.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for results that are not spool control, request, reply or delivery results.

`spoolSelection`

Method

Returns one stream selection of a received S2F43 request or an S2F60 reply.

GemSpoolSelection spoolSelection(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based position, less than GemSpoolInfo::selectionCount.

Returns

Stream and selected functions; an empty function list selects every registered primary of the stream.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another result kind; PDCOMM_OUT_OF_RANGE for an invalid index.

`statusName`

Method

Returns one row of an S1F12 status variable namelist reply.

GemStatusName statusName(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::NamesReceived. Names and units are copied as length-delimited ASCII, so embedded NUL bytes are kept.

Parameters

Name	Description
`index`	Zero-based row position, less than GemResultInfo::entryCount.

Returns

SVID, name and units.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`statusValue`

Method

Returns one status value of an S1F4 reply.

GemStatusValue statusValue(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Requires GemOutcome::ValuesReceived. For a request with explicit SVIDs, values keep the request order and carry their ID; a request for all values yields no IDs because the wire has none.

Parameters

Name	Description
`index`	Zero-based value position, less than GemResultInfo::entryCount.

Returns

The value and its requested SVID, if known.

Notes

Throws pdcomm::Error: PDCOMM_INVALID_STATE for another outcome; PDCOMM_OUT_OF_RANGE for an invalid index.

`value`

Method

Alias of statusValue().

GemStatusValue value(size_t index) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`index`	Zero-based value position.

Returns

The value and its requested SVID, if known.

Notes

Throws pdcomm::Error: Same statuses as statusValue().

`value`

Method

Alias of eventValue().

SecsItem value(size_t reportIndex, size_t valueIndex) const

Declared in: #include <pdcomm_gem.hpp>

Parameters

Name	Description
`reportIndex`	Zero-based report position.
`valueIndex`	Zero-based value position inside the report.

Returns

An independently owned value item.

Notes

Throws pdcomm::Error: Same statuses as eventValue().

`~GemResult`

Method

Releases the native handle with pdcomm_gem_result_destroy().

~GemResult()

Declared in: #include <pdcomm_gem.hpp>

An empty result releases nothing. Items already returned by getters stay valid.