pdcomm_gem_equipment_respond_enhanced_command

Function

Sends the S2F50 Enhanced Remote Command Acknowledge for a received S2F49.

PdcommStatus pdcomm_gem_equipment_respond_enhanced_command(PdcommTcpEndpoint *endpoint, PdcommGemResult *result, uint8_t decision, const PdcommSecsItem *acknowledgements, PdcommGemCommandReply *reply)

Declared in: #include <pdcomm_gem_enhanced_commands.h>

Admission, validation errors, limits, and the completion CEID were frozen at receipt. Decisions use the PDCOMM_GEM_COMMAND_* HCACK values 0 to 6.

• When admission rejected the request, its original HCACK and frozen acknowledgement entries are sent; acknowledgements is ignored.
• When admission accepted the request, decision is sent. Decision #PDCOMM_GEM_COMMAND_PARAMETER_ERRORS requires acknowledgements to be an outer List item; every other decision requires NULL.

Each outer entry is L[CPNAME, ACK]. ACK is a U1 scalar CEPACK from 0 to 4, a List of U1 scalar CEPACK values, or a List of nested L[CPNAME, ACK] entries. Every outer entry needs at least one nonzero CEPACK, the total number of nonzero values must not exceed max_errors, and the whole response must fit the wire limits. An empty outer List with decision 3 is valid. Names, order, and zero-code positions are sent as given and are not matched against the request.

The whole response is prepared before it is sent. Only a successful send sets responded and reply_sent. After a failure reply is cleared and the result stays retryable: retry the same acknowledgement and never re-execute completed work. Start deferred work only after an HCACK 4 response was accepted. An actual HCACK 0 or 4 may return the completion CEID; report that event separately.

Parameters

Name	Description
endpoint	The Equipment endpoint that produced result.
result	Request result with outcome #PDCOMM_GEM_ENHANCED_COMMAND_RECEIVED.
decision	HCACK to send for an accepted request, 0 to 6.
acknowledgements	Outer List of acknowledgement entries for decision 3; NULL for every other decision. Copied into the message.
reply	Caller storage; set reply->struct_size before the call. Cleared first and written on success.

Returns

#PDCOMM_OK when S2F50 was queued; #PDCOMM_INVALID_ARGUMENT when endpoint, result, or reply is NULL, reply->struct_size is too small, decision is above 6, result is not an enhanced command result, acknowledgements does not match the decision, or an entry is malformed (wrong shape, invalid name, CEPACK above 4, or an outer entry without a nonzero CEPACK); #PDCOMM_LIMIT_EXCEEDED when the nonzero CEPACK count exceeds max_errors, a name exceeds max_identifier_bytes, or the message exceeds the item limits; #PDCOMM_INVALID_STATE when result is a Host reply, the endpoint has no GEM Equipment, or communication is not COMMUNICATING; #PDCOMM_STALE_TOKEN when the request came from another endpoint, an older connection generation or selection, was already answered, or its reply slot is no longer open; #PDCOMM_BACKPRESSURE when a TCP event is staged or the TCP queue is full; #PDCOMM_ALLOCATION_FAILED; #PDCOMM_POISONED when the endpoint is poisoned or a panic was contained; or another TCP reply status, as for pdcomm_tcp_reply().

Notes

• Thread safety: this call mutates result. Do not run it concurrently with getters on the same result or with pdcomm_gem_result_destroy().