pdcomm_tcp_request
Function
Submits a primary data message.
PdcommStatus pdcomm_tcp_request(PdcommTcpEndpoint *endpoint, uint8_t stream, uint8_t function, uint8_t wait, const uint8_t *body, size_t body_length, PdcommTcpToken *out_token)The body is validated against PdcommTcpOptions::item_limits and copied, so you can release it when the call returns. With wait set to 1 (W-bit), the endpoint opens a transaction: the matching reply arrives as a #PDCOMM_TCP_RECEIVED event with is_reply set, or the transaction ends with a #PDCOMM_TCP_FAILED event. With wait set to 0, no reply is tracked and a #PDCOMM_TCP_W0_WRITTEN event reports when the frame was written. Success means only that the message was queued.
Parameters
| Name | Description |
|---|---|
endpoint | Live endpoint in the #PDCOMM_TCP_SELECTED state. |
stream | SECS-II stream, 0 to 127. |
function | SECS-II function; must be odd (a primary). With wait set to 1 it must not be 255, because the reply function would overflow. |
wait | 1 to set the W-bit and expect a reply, or 0. |
body | One complete encoded SECS-II item, or NULL with body_length 0 for a message without a body. |
body_length | Number of bytes at body; at most PdcommTcpOptions::max_frame_bytes minus 14. |
out_token | Receives the transaction token; set to all zeros first, so it is all zeros after every failure. Must not be NULL. |
Returns
#PDCOMM_OK when the message was queued; #PDCOMM_INVALID_ARGUMENT when out_token or endpoint is NULL, body is NULL with a nonzero length, wait is greater than 1, stream is greater than 127, or function is even or is 255 with a W-bit; #PDCOMM_INVALID_DATA when the body is not exactly one valid SECS-II item (including a truncated one); #PDCOMM_LIMIT_EXCEEDED when the body exceeds item_limits or does not fit in a frame, or the system bytes are exhausted; #PDCOMM_INVALID_STATE when the endpoint is not SELECTED; #PDCOMM_BACKPRESSURE when an event is staged, all transaction slots are in use, a queue is full, or the endpoint is stopping; #PDCOMM_POISONED.
Notes
- Cancelling a transaction whose frame is partially written closes the connection; bytes already on the wire are not retracted.