pdcomm_tcp_create
Function
Creates an HSMS endpoint.
PdcommStatus pdcomm_tcp_create(const char *address, size_t address_length, const PdcommTcpOptions *options, PdcommTcpEndpoint **out)The address and options are validated and copied. A passive endpoint binds its listening socket during this call; an active endpoint performs no I/O until pdcomm_tcp_poll() runs a connection attempt. The new endpoint is in the #PDCOMM_TCP_STOPPED state.
Parameters
| Name | Description |
|---|---|
address | Numeric socket address as UTF-8 text without a NUL terminator, such as 127.0.0.1:5000 or [::1]:5000. Host names are not resolved. The peer address in active mode; the local listening address in passive mode, where port 0 selects an ephemeral port each time the socket is bound (read it back with pdcomm_tcp_local_address()). |
address_length | Number of bytes at address. |
options | Endpoint configuration; see ::PdcommTcpOptions. |
out | Receives the new endpoint. Set to NULL before any other check, so it is NULL after every failure. |
Returns
#PDCOMM_OK on success; #PDCOMM_INVALID_ARGUMENT when out or options is NULL, options->struct_size or options->item_limits.struct_size is too small, version is not #PDCOMM_TCP_OPTIONS_VERSION, reserved is nonzero, mode is unknown, the address is not a numeric socket address, a timer, max_write_frames, max_io_chunk, max_application_events, or poll_budget is zero, or max_frame_bytes or max_write_bytes is below 14; #PDCOMM_LIMIT_EXCEEDED when max_events is below 72, max_write_bytes is below max_frame_bytes, or max_application_bytes is below max_frame_bytes minus 14; #PDCOMM_IO_ERROR when the passive listening socket cannot be bound; #PDCOMM_LICENSE_REQUIRED when no license grants the secs-gem module. The license is checked after the pointer, structure, mode and address arguments and before the timer and queue limits are validated and any socket is bound; nothing is created; #PDCOMM_ALLOCATION_FAILED or #PDCOMM_INTERNAL_ERROR.
Notes
- Ownership: release the endpoint with pdcomm_tcp_destroy().
outmust not overlapaddressoroptions.