|
| struct bj_tcp_listener * | bj_create_tcp_listener (const char *host, uint16_t port, uint16_t hint, int backlog, struct bj_error **error) |
| struct bj_tcp_stream * | bj_connect_tcp_stream (const char *host, uint16_t port, uint16_t hint, uint32_t ms_timeout, struct bj_error **error) |
| struct bj_tcp_stream * | bj_connect_tcp_stream_to (struct bj_address *addr, uint16_t hints, uint32_t ms_timeout, struct bj_error **error) |
| struct bj_tcp_stream * | bj_accept_tcp_stream (struct bj_tcp_listener *listener, uint32_t ms_timeout, struct bj_error **error) |
| int | bj_receive_tcp (struct bj_tcp_stream *stream, void *buf, size_t len) |
| int | bj_peek_tcp (struct bj_tcp_stream *stream, void *buf, size_t len) |
| int | bj_send_tcp (struct bj_tcp_stream *stream, const void *buf, size_t len) |
| void | bj_shutdown_tcp (struct bj_tcp_stream *stream, int mode) |
| bj_bool | bj_enable_tcp_keepalive (struct bj_tcp_stream *stream) |
| bj_bool | bj_disable_tcp_keepalive (struct bj_tcp_stream *stream) |
| bj_bool | bj_tcp_has_keepalive (struct bj_tcp_stream *stream) |
| bj_bool | bj_wait_tcp (struct bj_tcp_stream *stream, uint32_t ms_timeout) |
| bj_bool | bj_set_tcp_receive_timeout (struct bj_tcp_stream *stream, uint32_t ms_timeout) |
| uint32_t | bj_tcp_receive_timeout (struct bj_tcp_stream *stream) |
| bj_bool | bj_set_tcp_send_timeout (struct bj_tcp_stream *stream, uint32_t ms_timeout) |
| uint32_t | bj_tcp_send_timeout (struct bj_tcp_stream *stream) |
| struct bj_stream * | bj_create_stream_from_tcp (struct bj_tcp_stream *tcp, uint32_t flags) |
| void | bj_destroy_tcp_stream (struct bj_tcp_stream *stream) |
| void | bj_destroy_tcp_listener (struct bj_tcp_listener *listener) |
| size_t | bj_tcp_peer_address (const struct bj_tcp_stream *stream, char *buf, size_t size) |
| size_t | bj_tcp_local_address (const struct bj_tcp_stream *stream, char *buf, size_t size) |
| uint16_t | bj_tcp_listener_port (const struct bj_tcp_listener *listener) |
| int | bj_tcp_available (struct bj_tcp_stream *stream) |
| size_t | bj_address_string (const struct bj_address *addr, char *buf, size_t size) |
| void | bj_free_address (struct bj_address *addr) |
| struct bj_tcp_listener * | bj_listen_tcp (const char *host, uint16_t port, uint16_t hint, int backlog, struct bj_error **error) |
| struct bj_tcp_stream * | bj_connect_tcp (const char *host, uint16_t port, uint16_t hint, uint32_t ms_timeout, struct bj_error **error) |
| struct bj_tcp_stream * | bj_connect_tcp_to (struct bj_address *addr, uint16_t hints, uint32_t ms_timeout, struct bj_error **error) |
| struct bj_tcp_stream * | bj_accept_tcp (struct bj_tcp_listener *listener, uint32_t ms_timeout, struct bj_error **error) |
| int | bj_tcp_recv (struct bj_tcp_stream *stream, void *buf, size_t len) |
| int | bj_tcp_peek (struct bj_tcp_stream *stream, void *buf, size_t len) |
| int | bj_tcp_send (struct bj_tcp_stream *stream, const void *buf, size_t len) |
| void | bj_tcp_shutdown (struct bj_tcp_stream *stream, int mode) |
| bj_bool | bj_set_tcp_keepalive (struct bj_tcp_stream *stream, bj_bool enable) |
| bj_bool | bj_get_tcp_keepalive (struct bj_tcp_stream *stream) |
| bj_bool | bj_tcp_wait (struct bj_tcp_stream *stream, uint32_t ms_timeout) |
| bj_bool | bj_set_tcp_recv_timeout (struct bj_tcp_stream *stream, uint32_t ms_timeout) |
| uint32_t | bj_get_tcp_recv_timeout (struct bj_tcp_stream *stream) |
| uint32_t | bj_get_tcp_send_timeout (struct bj_tcp_stream *stream) |
| void | bj_close_tcp_stream (struct bj_tcp_stream *stream) |
| void | bj_close_tcp_listener (struct bj_tcp_listener *listener) |
| struct bj_udp * | bj_open_udp (const char *host, uint16_t port, uint16_t hints, struct bj_error **error) |
| void | bj_close_udp (struct bj_udp *udp) |
| int | bj_udp_send (struct bj_udp *udp, const char *host, uint16_t port, const void *data, size_t len, struct bj_error **error) |
| int | bj_udp_send_to (struct bj_udp *udp, const struct bj_address *addr, const void *data, size_t len, struct bj_error **error) |
| struct bj_datagram * | bj_udp_recv (struct bj_udp *udp, struct bj_error **error) |
| bj_bool | bj_udp_available (struct bj_udp *udp) |
| bj_bool | bj_udp_wait (struct bj_udp *udp, uint32_t ms_timeout) |
| size_t | bj_datagram_addr (const struct bj_datagram *dgram, char *buf, size_t size) |
| size_t | bj_datagram_len (const struct bj_datagram *dgram) |
| void | bj_close_datagram (struct bj_datagram *dgram) |
|
| struct bj_udp * | bj_create_udp (const char *host, uint16_t port, uint16_t hints, struct bj_error **error) |
| void | bj_destroy_udp (struct bj_udp *udp) |
| int | bj_send_udp (struct bj_udp *udp, const char *host, uint16_t port, const void *data, size_t len, struct bj_error **error) |
| int | bj_send_udp_to (struct bj_udp *udp, const struct bj_address *addr, const void *data, size_t len, struct bj_error **error) |
| struct bj_datagram * | bj_receive_udp (struct bj_udp *udp, struct bj_error **error) |
| bj_bool | bj_udp_has_data (struct bj_udp *udp) |
| bj_bool | bj_wait_udp (struct bj_udp *udp, uint32_t ms_timeout) |
| uint16_t | bj_udp_local_port (const struct bj_udp *udp) |
| size_t | bj_udp_local_address (const struct bj_udp *udp, char *buf, size_t size) |
Talk to other programs over a network: TCP for streams, UDP for datagrams.
This subsystem lets your program send and receive data over a network. The network plumbing is the same on every platform Banjo supports (the same code runs on Linux, macOS, and Windows), but you should know what kind of communication you want, because the choice changes the API quite a lot.
TCP: ordered, reliable stream of bytes
TCP is what most programs mean by "a network connection." One side listens on a port; the other side connects to that port. Once the handshake completes, both sides exchange bytes through a stream: the OS guarantees that whatever you send arrives in order, with no duplicates, no losses, and nothing extra inserted. Use TCP for anything that's fundamentally "send a message, wait for a reply" or "stream a chunk of data": HTTP, chat protocols, file transfer.
struct bj_tcp_listener bj_tcp_listener
struct bj_tcp_stream bj_tcp_stream
struct bj_tcp_stream * bj_connect_tcp_stream(const char *host, uint16_t port, uint16_t hint, uint32_t ms_timeout, struct bj_error **error)
Connects to a TCP server at the specified host and port.
struct bj_tcp_stream * bj_accept_tcp_stream(struct bj_tcp_listener *listener, uint32_t ms_timeout, struct bj_error **error)
Accepts an incoming connection on a TCP listener with timeout.
struct bj_tcp_listener * bj_create_tcp_listener(const char *host, uint16_t port, uint16_t hint, int backlog, struct bj_error **error)
Creates a TCP listener bound to the specified host and port.
To read and write a connection with the functions of Data Stream, such as the byte-order readers, wrap it with bj_create_stream_from_tcp.
UDP: best-effort datagrams
UDP is the opposite trade-off. There's no connection: each send puts one packet on the wire and each recv returns one packet. Packets can arrive out of order, can be duplicated, or not arrive at all. The OS doesn't try to fix any of that; it's faster and lower-latency, and you build whatever reliability you need on top yourself. Use UDP for real-time games, voice and video, or LAN broadcast / discovery (one message to "anyone on
the network who's listening").
See the net_tcp_*.c and net_udp_*.c examples for runnable versions of both styles, plus broadcast and non-blocking patterns.
Resolving names to addresses
Before you can connect to "example.com", the name has to be turned into an actual IP address. The OS handles that for you, but you can hint which kind of address you want with the resolve flags:
◆ BJ_ADDR_STRLEN
| #define BJ_ADDR_STRLEN 46 |
◆ BJ_BROADCAST
◆ BJ_EXCLUSIVE_BIND
◆ BJ_NET_BACKLOG_DEFAULT
| #define BJ_NET_BACKLOG_DEFAULT 0 |
◆ BJ_NET_BACKLOG_MAX
| #define BJ_NET_BACKLOG_MAX (-1) |
◆ BJ_NET_NOHINT
◆ BJ_NONBLOCKING
◆ BJ_RESOLVE_IPV4
◆ BJ_RESOLVE_IPV6
◆ BJ_SHUTDOWN_BOTH
◆ BJ_SHUTDOWN_RECEIVE
◆ BJ_SHUTDOWN_SEND
◆ BJ_TCP_DELAY_ACK
◆ bj_net_hint
Hint flags for network operations.
These flags can be combined with bitwise OR to configure socket behaviour.
| Enumerator |
|---|
| BJ_NET_HINT_NONE | No hint provided.
|
| BJ_NET_HINT_IPV4 | Restrict address resolution to IPv4.
|
| BJ_NET_HINT_IPV6 | Restrict address resolution to IPv6.
|
| BJ_NET_HINT_EXCLUSIVE_BIND | Disable address reuse.
|
| BJ_NET_HINT_DELAY_ACK | Enable Nagle's algorithm.
|
| BJ_NET_HINT_NONBLOCKING | Non-blocking mode.
|
| BJ_NET_HINT_BROADCAST | Enable UDP broadcast (SO_BROADCAST).
|
Definition at line 119 of file net.h.
◆ bj_net_shutdown
Shutdown mode for bj_shutdown_tcp.
| Enumerator |
|---|
| BJ_NET_SHUTDOWN_RECEIVE | Shutdown receive operations.
|
| BJ_NET_SHUTDOWN_SEND | Shutdown send operations.
|
| BJ_NET_SHUTDOWN_BOTH | Shutdown both send and receive.
|
Definition at line 256 of file net.h.
◆ bj_accept_tcp()
◆ bj_accept_tcp_stream()
Accepts an incoming connection on a TCP listener with timeout.
Waits for a client connection up to the specified timeout.
- Parameters
-
| listener | The listener to accept connections on, or 0, which accepts nothing. |
| ms_timeout | Timeout in milliseconds. 0 = non-blocking, UINT32_MAX = infinite. |
| error | Optional error output, set to BJ_ERROR_NETWORK_TIMEOUT on timeout. May be 0. |
- Returns
- A new TCP stream for the accepted connection, or 0 on timeout/failure.
- See also
- bj_create_tcp_listener To create a listener.
-
bj_destroy_tcp_stream To close the accepted connection.
- Examples
- net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.
Referenced by main().
◆ bj_address_count()
| size_t bj_address_count |
( |
const struct bj_address * | addr | ) |
|
Returns number of resolved addresses.
DNS resolution may return multiple IPs for a single hostname.
- Parameters
-
| addr | The address to query, or 0. |
- Returns
- Number of resolved addresses, or 0 if addr is 0.
◆ bj_address_equals()
Compares two addresses for equality.
- Parameters
-
| a | First address, or 0. |
| b | Second address, or 0. |
- Returns
- BJ_TRUE if addresses are equal, BJ_FALSE if they differ or one is 0.
◆ bj_address_next()
Advances to the next resolved address.
Use this to manually iterate through multiple resolved IPs for fallback on connection failure.
- Parameters
-
| addr | The address to advance, or 0, which gives BJ_FALSE. |
- Returns
- BJ_TRUE if advanced to next, BJ_FALSE if no more addresses.
◆ bj_address_port()
| uint16_t bj_address_port |
( |
const struct bj_address * | addr | ) |
|
Gets the port from a resolved address.
- Parameters
-
| addr | The address to query, or 0. |
- Returns
- Port number in host byte order, or 0 if addr is 0.
◆ bj_address_reset()
Resets address iteration to the first resolved address.
- Parameters
-
| addr | The address to reset, or 0, which does nothing. |
◆ bj_address_string()
| size_t bj_address_string |
( |
const struct bj_address * | addr, |
|
|
char * | buf, |
|
|
size_t | size ) |
◆ bj_address_to_string()
| size_t bj_address_to_string |
( |
const struct bj_address * | addr, |
|
|
char * | buf, |
|
|
size_t | size ) |
Gets the IP address string from a resolved address.
- Parameters
-
| addr | The address to query, or 0, which gives 0. |
| buf | Buffer to store the string. May be 0 to query length. |
| size | Buffer size. |
- Returns
- Length of address string, or 0 on error.
◆ bj_close_datagram()
◆ bj_close_tcp_listener()
◆ bj_close_tcp_stream()
◆ bj_close_udp()
| void bj_close_udp |
( |
struct bj_udp * | udp | ) |
|
◆ bj_connect_tcp()
| struct bj_tcp_stream * bj_connect_tcp |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hint, |
|
|
uint32_t | ms_timeout, |
|
|
struct bj_error ** | error ) |
◆ bj_connect_tcp_stream()
| struct bj_tcp_stream * bj_connect_tcp_stream |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hint, |
|
|
uint32_t | ms_timeout, |
|
|
struct bj_error ** | error ) |
Connects to a TCP server at the specified host and port.
Resolves the hostname and attempts to connect. If multiple addresses are returned by DNS, each is tried until one succeeds.
- Parameters
-
| host | Hostname or IP address to connect to, or 0, which connects to nothing and leaves error alone. |
| port | Port number to connect to. |
| hint | Address family hint. Use 0 for any, BJ_NET_HINT_IPV4 for IPv4 only, or BJ_NET_HINT_IPV6 for IPv6 only. |
| ms_timeout | Attempt timeout in milliseconds (0 = infinite) |
| error | Optional error output. May be 0. |
- Returns
- A new TCP stream, or 0 on failure.
- See also
- bj_send_tcp To send data.
-
bj_receive_tcp To receive data.
-
bj_destroy_tcp_stream To close the connection.
- Todo
- This function does not yet enforce UTF-8 on
host. Per ADR 0008, it will.
- Examples
- net_tcp_client.c.
Referenced by main().
◆ bj_connect_tcp_stream_to()
Connects to a pre-resolved address, trying all resolved IPs.
Automatically iterates through all addresses returned by DNS resolution until one succeeds.
- Parameters
-
| addr | Destination address (from bj_resolve_address), or 0, which connects to nothing. |
| hints | Socket hints (BJ_NET_HINT_DELAY_ACK, etc.). |
| ms_timeout | Connection timeout per address in milliseconds. |
| error | Optional error output. May be 0. |
- Returns
- TCP stream, or 0 on failure.
- See also
- bj_resolve_address To create the address.
-
bj_connect_tcp_stream For hostname-based connection.
◆ bj_connect_tcp_to()
◆ bj_create_stream_from_tcp()
Turns a connected TCP stream into a bj_stream.
The functions of Data Stream then read and write the connection, the byte-order ones included:
struct bj_stream bj_stream
struct bj_stream * bj_create_stream_from_tcp(struct bj_tcp_stream *tcp, uint32_t flags)
Turns a connected TCP stream into a bj_stream.
bj_bool bj_write_stream_u32_be(struct bj_stream *stream, uint32_t value)
Writes a big-endian uint32_t.
size_t bj_write_stream(struct bj_stream *stream, const void *data, size_t count)
Writes bytes at the cursor, over those already there.
@ BJ_STREAM_READ_WRITE
The stream reads and writes.
The stream cannot seek, its length is 0, and its position counts the bytes it moved. A read waits until all its bytes arrive; when it gets fewer, its status is BJ_STREAM_STATUS_END if the peer closed, BJ_STREAM_STATUS_NOT_READY if the receive timeout of tcp expired, and BJ_STREAM_STATUS_ERROR otherwise.
The stream borrows tcp: destroying it leaves the connection open, and the connection must outlive it.
- Parameters
-
| tcp | A connected TCP stream, or 0, which gives 0. |
| flags | BJ_STREAM_READ, BJ_STREAM_WRITE or both; anything else gives 0. |
- Returns
- A new bj_stream, or 0.
◆ bj_create_tcp_listener()
| struct bj_tcp_listener * bj_create_tcp_listener |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hint, |
|
|
int | backlog, |
|
|
struct bj_error ** | error ) |
◆ bj_create_udp()
| struct bj_udp * bj_create_udp |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hints, |
|
|
struct bj_error ** | error ) |
Opens a UDP socket bound to the specified port.
- Parameters
-
| host | Hostname/IP to bind to. 0 for any interface. |
| port | Port to bind. 0 for ephemeral (system-assigned). |
| hints | Flags: BJ_NET_HINT_IPV4, BJ_NET_HINT_IPV6, BJ_NET_HINT_NONBLOCKING, BJ_NET_HINT_BROADCAST |
| error | Optional error output. May be 0. |
- Returns
- New UDP socket, or 0 on failure.
- Todo
- This function does not yet enforce UTF-8 on
host. Per ADR 0008, it will.
- Examples
- net_udp_broadcast_recv.c, net_udp_broadcast_send.c, net_udp_client.c, and net_udp_server.c.
Referenced by main().
◆ bj_datagram_addr()
| size_t bj_datagram_addr |
( |
const struct bj_datagram * | dgram, |
|
|
char * | buf, |
|
|
size_t | size ) |
◆ bj_datagram_address()
| size_t bj_datagram_address |
( |
const struct bj_datagram * | dgram, |
|
|
char * | buf, |
|
|
size_t | size ) |
Gets the sender's address from a datagram.
- Parameters
-
| dgram | Datagram, or 0, which gives 0. |
| buf | Output buffer (may be 0 to query length). |
| size | Buffer size. |
- Returns
- Address string length, or 0 on error.
- Examples
- net_udp_broadcast_recv.c, and net_udp_server.c.
Referenced by main().
◆ bj_datagram_data()
| const void * bj_datagram_data |
( |
const struct bj_datagram * | dgram | ) |
|
◆ bj_datagram_len()
| size_t bj_datagram_len |
( |
const struct bj_datagram * | dgram | ) |
|
◆ bj_datagram_length()
| size_t bj_datagram_length |
( |
const struct bj_datagram * | dgram | ) |
|
◆ bj_datagram_port()
| uint16_t bj_datagram_port |
( |
const struct bj_datagram * | dgram | ) |
|
◆ bj_destroy_address()
| void bj_destroy_address |
( |
struct bj_address * | addr | ) |
|
Frees a resolved address.
0-safe.
- Parameters
-
| addr | The address to free. May be 0. |
◆ bj_destroy_datagram()
◆ bj_destroy_tcp_listener()
◆ bj_destroy_tcp_stream()
◆ bj_destroy_udp()
| void bj_destroy_udp |
( |
struct bj_udp * | udp | ) |
|
◆ bj_disable_tcp_keepalive()
◆ bj_enable_tcp_keepalive()
Turns on TCP keep-alive probes for a stream.
When enabled, the OS sends periodic probes on idle connections to detect dead peers. If no response is received, the connection is terminated.
- Parameters
-
| stream | TCP stream, or 0, which gives BJ_FALSE. |
- Returns
- BJ_TRUE on success.
- Note
- Keep-alive timing is controlled by the implementation.
- See also
- bj_disable_tcp_keepalive, bj_tcp_has_keepalive
◆ bj_free_address()
◆ bj_get_tcp_keepalive()
◆ bj_get_tcp_recv_timeout()
| uint32_t bj_get_tcp_recv_timeout |
( |
struct bj_tcp_stream * | stream | ) |
|
◆ bj_get_tcp_send_timeout()
| uint32_t bj_get_tcp_send_timeout |
( |
struct bj_tcp_stream * | stream | ) |
|
◆ bj_listen_tcp()
| struct bj_tcp_listener * bj_listen_tcp |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hint, |
|
|
int | backlog, |
|
|
struct bj_error ** | error ) |
◆ bj_open_udp()
| struct bj_udp * bj_open_udp |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hints, |
|
|
struct bj_error ** | error ) |
◆ bj_peek_tcp()
| int bj_peek_tcp |
( |
struct bj_tcp_stream * | stream, |
|
|
void * | buf, |
|
|
size_t | len ) |
Peek at incoming data without consuming it.
Like bj_receive_tcp but data remains in the buffer for subsequent reads. Useful for protocol parsing where you need to inspect headers.
- Parameters
-
| stream | The TCP stream to peek from, or 0, which returns -1. |
| buf | Buffer to store peeked data. 0 returns -1 unless len is 0. |
| len | Maximum number of bytes to peek. |
- Returns
- Number of bytes peeked, 0 if connection closed, or -1 on error.
- See also
- bj_receive_tcp
◆ bj_receive_tcp()
| int bj_receive_tcp |
( |
struct bj_tcp_stream * | stream, |
|
|
void * | buf, |
|
|
size_t | len ) |
Receives data from a TCP stream.
Reads up to len bytes from the stream into buf. Blocks until data is available or the connection is closed.
- Parameters
-
| stream | The TCP stream to receive from, or 0, which returns -1. |
| buf | Buffer to store received data. 0 returns -1 unless len is 0. |
| len | Maximum number of bytes to receive. |
- Returns
- Number of bytes received, 0 if connection closed, or -1 on error.
- See also
- bj_peek_tcp
- Examples
- net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.
Referenced by main().
◆ bj_receive_udp()
Receives a datagram from the UDP socket.
If BJ_NET_HINT_NONBLOCKING was set and no data available, returns 0 without error. If blocking, waits until a datagram arrives.
- Parameters
-
| udp | UDP socket, or 0, which receives nothing. |
| error | Optional error output. May be 0. |
- Returns
- Received datagram (caller must close), or 0 if no data/error. Check error to distinguish: 0 + no error = no data available.
- Examples
- net_udp_broadcast_recv.c, net_udp_client.c, and net_udp_server.c.
Referenced by main().
◆ bj_resolve_address()
| struct bj_address * bj_resolve_address |
( |
const char * | host, |
|
|
uint16_t | port, |
|
|
uint16_t | hints, |
|
|
struct bj_error ** | error ) |
Resolves a hostname to a network address.
The returned address can be used with bj_connect_tcp_stream_to and bj_send_udp_to to avoid repeated DNS lookups.
- Parameters
-
| host | Hostname or IP string to resolve, or 0, which resolves nothing and leaves error alone. |
| port | Port number. |
| hints | BJ_NET_HINT_IPV4, BJ_NET_HINT_IPV6, or 0 for any. |
| error | Optional error output. May be 0. |
- Returns
- Resolved address, or 0 on failure.
- See also
- bj_destroy_address To free the address.
-
bj_address_next To iterate through multiple resolved IPs.
- Todo
- This function does not yet enforce UTF-8 on
host. Per ADR 0008, it will.
◆ bj_send_tcp()
| int bj_send_tcp |
( |
struct bj_tcp_stream * | stream, |
|
|
const void * | buf, |
|
|
size_t | len ) |
Sends data over a TCP stream.
Sends up to len bytes from buf over the stream.
- Parameters
-
| stream | The TCP stream to send on, or 0, which returns -1. |
| buf | Buffer containing data to send. 0 returns -1 unless len is 0. |
| len | Number of bytes to send. |
- Returns
- Number of bytes sent, or -1 on error.
- Examples
- net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.
Referenced by main().
◆ bj_send_udp()
| int bj_send_udp |
( |
struct bj_udp * | udp, |
|
|
const char * | host, |
|
|
uint16_t | port, |
|
|
const void * | data, |
|
|
size_t | len, |
|
|
struct bj_error ** | error ) |
Sends a datagram to the specified destination.
Resolves hostname internally on each call.
- Parameters
-
| udp | UDP socket, or 0, which sends nothing. |
| host | Destination hostname or IP, or 0, which sends nothing. |
| port | Destination port. |
| data | Data to send. 0 sends nothing unless len is 0. |
| len | Data length. |
| error | Optional error output. May be 0. |
- Returns
- Bytes sent, or -1 on error. A 0 argument that sends nothing gives -1 and leaves error alone.
- Todo
- This function does not yet enforce UTF-8 on
host. Per ADR 0008, it will.
- Examples
- net_udp_broadcast_send.c, net_udp_client.c, and net_udp_server.c.
Referenced by main().
◆ bj_send_udp_to()
| int bj_send_udp_to |
( |
struct bj_udp * | udp, |
|
|
const struct bj_address * | addr, |
|
|
const void * | data, |
|
|
size_t | len, |
|
|
struct bj_error ** | error ) |
Sends a datagram to a pre-resolved address (no DNS lookup).
More efficient than bj_send_udp when sending many packets to the same destination, as it avoids repeated DNS lookups.
- Parameters
-
| udp | UDP socket, or 0, which sends nothing. |
| addr | Destination address (from bj_resolve_address), or 0, which sends nothing. |
| data | Data to send. 0 sends nothing unless len is 0. |
| len | Data length. |
| error | Optional error output. May be 0. |
- Returns
- Bytes sent, or -1 on error. A 0 argument that sends nothing gives -1 and leaves error alone.
- See also
- bj_resolve_address To create the address.
-
bj_send_udp For hostname-based sending.
◆ bj_set_tcp_keepalive()
◆ bj_set_tcp_receive_timeout()
Sets the receive timeout for a TCP stream.
When set, recv operations will timeout after the specified duration.
- Parameters
-
| stream | TCP stream, or 0, which gives BJ_FALSE. |
| ms_timeout | Timeout in milliseconds. 0 = no timeout (blocking). |
- Returns
- BJ_TRUE on success.
◆ bj_set_tcp_recv_timeout()
◆ bj_set_tcp_send_timeout()
Sets the send timeout for a TCP stream.
When set, send operations will timeout after the specified duration.
- Parameters
-
| stream | TCP stream, or 0, which gives BJ_FALSE. |
| ms_timeout | Timeout in milliseconds. 0 = no timeout (blocking). |
- Returns
- BJ_TRUE on success.
◆ bj_shutdown_tcp()
Shuts down part or all of a TCP connection.
Gracefully shuts down the send and/or receive side of the connection without closing the socket.
- Parameters
-
- See also
- bj_destroy_tcp_stream To fully close the connection.
◆ bj_tcp_available()
Checks bytes available to read without blocking.
- Parameters
-
| stream | TCP stream, or 0, which gives -1. |
- Returns
- Bytes available (>=0), or -1 on error/closed connection.
- Examples
- net_tcp_nonblocking.c.
Referenced by main().
◆ bj_tcp_has_keepalive()
Reports whether TCP keep-alive is currently enabled on a stream.
- Parameters
-
| stream | TCP stream, or 0, which gives BJ_FALSE. |
- Returns
- BJ_TRUE if keep-alive is enabled, BJ_FALSE otherwise.
◆ bj_tcp_listener_port()
◆ bj_tcp_local_address()
| size_t bj_tcp_local_address |
( |
const struct bj_tcp_stream * | stream, |
|
|
char * | buf, |
|
|
size_t | size ) |
Gets the local address of a TCP stream.
Writes the local IP address as a string into buf. Works like snprintf: returns the length of the address string regardless of buffer size.
- Parameters
-
| stream | The TCP stream to query, or 0, which gives 0. |
| buf | Buffer to store the address string. May be 0 to query length only. |
| size | Size of the buffer in bytes. |
- Returns
- Length of the address string (excluding null terminator), or 0 on error. If the return value is >= size, the output was truncated.
- See also
- BJ_ADDR_STRLEN For the recommended buffer size.
-
bj_tcp_peer_address To get the remote address.
◆ bj_tcp_peek()
| int bj_tcp_peek |
( |
struct bj_tcp_stream * | stream, |
|
|
void * | buf, |
|
|
size_t | len ) |
◆ bj_tcp_peer_address()
| size_t bj_tcp_peer_address |
( |
const struct bj_tcp_stream * | stream, |
|
|
char * | buf, |
|
|
size_t | size ) |
Gets the remote address of a TCP stream.
Writes the peer's IP address as a string into buf. Works like snprintf: returns the length of the address string regardless of buffer size.
- Parameters
-
| stream | The TCP stream to query, or 0, which gives 0. |
| buf | Buffer to store the address string. May be 0 to query length only. |
| size | Size of the buffer in bytes. |
- Returns
- Length of the address string (excluding null terminator), or 0 on error. If the return value is >= size, the output was truncated.
- See also
- BJ_ADDR_STRLEN For the recommended buffer size.
-
bj_tcp_local_address To get the local address.
- Examples
- net_tcp_nonblocking.c, and net_tcp_timeout.c.
Referenced by main().
◆ bj_tcp_receive_timeout()
Gets the current receive timeout.
- Parameters
-
| stream | TCP stream, or 0, which gives 0. |
- Returns
- Timeout in milliseconds, or 0 if no timeout set.
◆ bj_tcp_recv()
| int bj_tcp_recv |
( |
struct bj_tcp_stream * | stream, |
|
|
void * | buf, |
|
|
size_t | len ) |
◆ bj_tcp_send()
| int bj_tcp_send |
( |
struct bj_tcp_stream * | stream, |
|
|
const void * | buf, |
|
|
size_t | len ) |
◆ bj_tcp_send_timeout()
Gets the current send timeout.
- Parameters
-
| stream | TCP stream, or 0, which gives 0. |
- Returns
- Timeout in milliseconds, or 0 if no timeout set.
◆ bj_tcp_shutdown()
◆ bj_tcp_wait()
◆ bj_udp_available()
◆ bj_udp_has_data()
Checks if a datagram is available without blocking.
- Parameters
-
| udp | UDP socket, or 0, which gives BJ_FALSE. |
- Returns
- BJ_TRUE if data available, BJ_FALSE otherwise.
◆ bj_udp_local_address()
| size_t bj_udp_local_address |
( |
const struct bj_udp * | udp, |
|
|
char * | buf, |
|
|
size_t | size ) |
Gets the local address of a UDP socket (snprintf-style).
- Parameters
-
| udp | UDP socket, or 0, which gives 0. |
| buf | Output buffer (may be 0 to query length). |
| size | Buffer size. |
- Returns
- Address string length, or 0 on error.
◆ bj_udp_local_port()
| uint16_t bj_udp_local_port |
( |
const struct bj_udp * | udp | ) |
|
◆ bj_udp_recv()
◆ bj_udp_send()
| int bj_udp_send |
( |
struct bj_udp * | udp, |
|
|
const char * | host, |
|
|
uint16_t | port, |
|
|
const void * | data, |
|
|
size_t | len, |
|
|
struct bj_error ** | error ) |
◆ bj_udp_send_to()
| int bj_udp_send_to |
( |
struct bj_udp * | udp, |
|
|
const struct bj_address * | addr, |
|
|
const void * | data, |
|
|
size_t | len, |
|
|
struct bj_error ** | error ) |
◆ bj_udp_wait()
◆ bj_wait_tcp()
Waits for data to become available on a TCP stream.
Uses select() internally to wait for readability with a timeout.
- Parameters
-
| stream | TCP stream to wait on, or 0, which gives BJ_FALSE at once. |
| ms_timeout | Timeout in milliseconds. 0 = non-blocking poll. |
- Returns
- BJ_TRUE if data available, BJ_FALSE on timeout.
◆ bj_wait_udp()
Waits for data to become available on a UDP socket.
Uses select() internally to wait for readability with a timeout.
- Parameters
-
| udp | UDP socket, or 0, which gives BJ_FALSE at once. |
| ms_timeout | Timeout in milliseconds. 0 = non-blocking poll. |
- Returns
- BJ_TRUE if data available, BJ_FALSE on timeout.
- Examples
- net_udp_broadcast_recv.c, and net_udp_client.c.
Referenced by main().