Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Network

Macros

#define BJ_NET_NOHINT   BJ_NET_HINT_NONE
#define BJ_RESOLVE_IPV4   BJ_NET_HINT_IPV4
#define BJ_RESOLVE_IPV6   BJ_NET_HINT_IPV6
#define BJ_EXCLUSIVE_BIND   BJ_NET_HINT_EXCLUSIVE_BIND
#define BJ_TCP_DELAY_ACK   BJ_NET_HINT_DELAY_ACK
#define BJ_NONBLOCKING   BJ_NET_HINT_NONBLOCKING
#define BJ_BROADCAST   BJ_NET_HINT_BROADCAST
#define BJ_SHUTDOWN_RECEIVE   BJ_NET_SHUTDOWN_RECEIVE
#define BJ_SHUTDOWN_SEND   BJ_NET_SHUTDOWN_SEND
#define BJ_SHUTDOWN_BOTH   BJ_NET_SHUTDOWN_BOTH
#define BJ_ADDR_STRLEN   46
#define BJ_NET_BACKLOG_DEFAULT   0
#define BJ_NET_BACKLOG_MAX   (-1)

Enumerations

enum  bj_net_hint {
  BJ_NET_HINT_NONE = 0x0 , BJ_NET_HINT_IPV4 = 0x01 , BJ_NET_HINT_IPV6 = 0x02 , BJ_NET_HINT_EXCLUSIVE_BIND = 0x04 ,
  BJ_NET_HINT_DELAY_ACK = 0x08 , BJ_NET_HINT_NONBLOCKING = 0x10 , BJ_NET_HINT_BROADCAST = 0x20
}
enum  bj_net_shutdown { BJ_NET_SHUTDOWN_RECEIVE = 0x01 , BJ_NET_SHUTDOWN_SEND = 0x02 , BJ_NET_SHUTDOWN_BOTH = 0x03 }

Functions

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)

Address Resolution Functions

struct bj_address * bj_resolve_address (const char *host, uint16_t port, uint16_t hints, struct bj_error **error)
size_t bj_address_to_string (const struct bj_address *addr, char *buf, size_t size)
uint16_t bj_address_port (const struct bj_address *addr)
bj_bool bj_address_equals (const struct bj_address *a, const struct bj_address *b)
size_t bj_address_count (const struct bj_address *addr)
bj_bool bj_address_next (struct bj_address *addr)
void bj_address_reset (struct bj_address *addr)
void bj_destroy_address (struct bj_address *addr)

UDP Functions

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)

Datagram Accessors

size_t bj_datagram_address (const struct bj_datagram *dgram, char *buf, size_t size)
uint16_t bj_datagram_port (const struct bj_datagram *dgram)
const void * bj_datagram_data (const struct bj_datagram *dgram)
size_t bj_datagram_length (const struct bj_datagram *dgram)
void bj_destroy_datagram (struct bj_datagram *dgram)

Detailed Description

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.

// Server side: bind to all interfaces on port 8080
bj_tcp_listener* listener = bj_create_tcp_listener(0, 8080, 0, 0, &error);
bj_tcp_stream* client = bj_accept_tcp_stream(listener, UINT32_MAX, &error);
// ...use bj_send_tcp / bj_receive_tcp on `client`...
// Client side: connect to a TCP server
bj_tcp_stream* stream = bj_connect_tcp_stream("localhost", 8080, 0, 5000, &error);
struct bj_tcp_listener bj_tcp_listener
Definition api.h:376
struct bj_tcp_stream bj_tcp_stream
Definition api.h:377
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:

Macro Definition Documentation

◆ BJ_ADDR_STRLEN

#define BJ_ADDR_STRLEN   46

Maximum length of an address string (including null terminator).

Sufficient for both IPv4 (e.g., "255.255.255.255") and IPv6 (e.g., "ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255") addresses.

Examples
net_tcp_nonblocking.c, net_tcp_timeout.c, net_udp_broadcast_recv.c, and net_udp_server.c.

Definition at line 275 of file net.h.

Referenced by main().

◆ BJ_BROADCAST

#define BJ_BROADCAST   BJ_NET_HINT_BROADCAST
Deprecated
Renamed to BJ_NET_HINT_BROADCAST. Removed in 2.0.

Definition at line 142 of file net.h.

◆ BJ_EXCLUSIVE_BIND

#define BJ_EXCLUSIVE_BIND   BJ_NET_HINT_EXCLUSIVE_BIND
Deprecated
Renamed to BJ_NET_HINT_EXCLUSIVE_BIND. Removed in 2.0.

Definition at line 136 of file net.h.

◆ BJ_NET_BACKLOG_DEFAULT

#define BJ_NET_BACKLOG_DEFAULT   0

Default backlog value for bj_create_tcp_listener.

Uses a reasonable implementation-defined default.

Definition at line 282 of file net.h.

◆ BJ_NET_BACKLOG_MAX

#define BJ_NET_BACKLOG_MAX   (-1)

Maximum backlog value for bj_create_tcp_listener.

Uses the system's maximum allowed backlog (SOMAXCONN).

Definition at line 289 of file net.h.

◆ BJ_NET_NOHINT

#define BJ_NET_NOHINT   BJ_NET_HINT_NONE
Deprecated
Renamed to BJ_NET_HINT_NONE. Removed in 2.0.

Definition at line 130 of file net.h.

◆ BJ_NONBLOCKING

#define BJ_NONBLOCKING   BJ_NET_HINT_NONBLOCKING
Deprecated
Renamed to BJ_NET_HINT_NONBLOCKING. Removed in 2.0.

Definition at line 140 of file net.h.

◆ BJ_RESOLVE_IPV4

#define BJ_RESOLVE_IPV4   BJ_NET_HINT_IPV4
Deprecated
Renamed to BJ_NET_HINT_IPV4. Removed in 2.0.

Definition at line 132 of file net.h.

◆ BJ_RESOLVE_IPV6

#define BJ_RESOLVE_IPV6   BJ_NET_HINT_IPV6
Deprecated
Renamed to BJ_NET_HINT_IPV6. Removed in 2.0.

Definition at line 134 of file net.h.

◆ BJ_SHUTDOWN_BOTH

#define BJ_SHUTDOWN_BOTH   BJ_NET_SHUTDOWN_BOTH
Deprecated
Renamed to BJ_NET_SHUTDOWN_BOTH. Removed in 2.0.

Definition at line 267 of file net.h.

◆ BJ_SHUTDOWN_RECEIVE

#define BJ_SHUTDOWN_RECEIVE   BJ_NET_SHUTDOWN_RECEIVE
Deprecated
Renamed to BJ_NET_SHUTDOWN_RECEIVE. Removed in 2.0.

Definition at line 263 of file net.h.

◆ BJ_SHUTDOWN_SEND

#define BJ_SHUTDOWN_SEND   BJ_NET_SHUTDOWN_SEND
Deprecated
Renamed to BJ_NET_SHUTDOWN_SEND. Removed in 2.0.

Definition at line 265 of file net.h.

◆ BJ_TCP_DELAY_ACK

#define BJ_TCP_DELAY_ACK   BJ_NET_HINT_DELAY_ACK
Deprecated
Renamed to BJ_NET_HINT_DELAY_ACK. Removed in 2.0.

Definition at line 138 of file net.h.

Enumeration Type Documentation

◆ 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.

Function Documentation

◆ bj_accept_tcp()

struct bj_tcp_stream * bj_accept_tcp ( struct bj_tcp_listener * listener,
uint32_t ms_timeout,
struct bj_error ** error )
Deprecated
Renamed to bj_accept_tcp_stream. Removed in 2.0.

◆ bj_accept_tcp_stream()

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.

Waits for a client connection up to the specified timeout.

Parameters
listenerThe listener to accept connections on, or 0, which accepts nothing.
ms_timeoutTimeout in milliseconds. 0 = non-blocking, UINT32_MAX = infinite.
errorOptional 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
addrThe address to query, or 0.
Returns
Number of resolved addresses, or 0 if addr is 0.

◆ bj_address_equals()

bj_bool bj_address_equals ( const struct bj_address * a,
const struct bj_address * b )

Compares two addresses for equality.

Parameters
aFirst address, or 0.
bSecond address, or 0.
Returns
BJ_TRUE if addresses are equal, BJ_FALSE if they differ or one is 0.

◆ bj_address_next()

bj_bool bj_address_next ( struct bj_address * addr)

Advances to the next resolved address.

Use this to manually iterate through multiple resolved IPs for fallback on connection failure.

Parameters
addrThe 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
addrThe address to query, or 0.
Returns
Port number in host byte order, or 0 if addr is 0.

◆ bj_address_reset()

void bj_address_reset ( struct bj_address * addr)

Resets address iteration to the first resolved address.

Parameters
addrThe 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 )
Deprecated
Renamed to bj_address_to_string. Removed in 2.0.

◆ 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
addrThe address to query, or 0, which gives 0.
bufBuffer to store the string. May be 0 to query length.
sizeBuffer size.
Returns
Length of address string, or 0 on error.

◆ bj_close_datagram()

void bj_close_datagram ( struct bj_datagram * dgram)
Deprecated
Renamed to bj_destroy_datagram. Removed in 2.0.

◆ bj_close_tcp_listener()

void bj_close_tcp_listener ( struct bj_tcp_listener * listener)
Deprecated
Renamed to bj_destroy_tcp_listener. Removed in 2.0.

◆ bj_close_tcp_stream()

void bj_close_tcp_stream ( struct bj_tcp_stream * stream)
Deprecated
Renamed to bj_destroy_tcp_stream. Removed in 2.0.

◆ bj_close_udp()

void bj_close_udp ( struct bj_udp * udp)
Deprecated
Renamed to bj_destroy_udp. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_connect_tcp_stream. Removed in 2.0.

◆ 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
hostHostname or IP address to connect to, or 0, which connects to nothing and leaves error alone.
portPort number to connect to.
hintAddress family hint. Use 0 for any, BJ_NET_HINT_IPV4 for IPv4 only, or BJ_NET_HINT_IPV6 for IPv6 only.
ms_timeoutAttempt timeout in milliseconds (0 = infinite)
errorOptional 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()

struct bj_tcp_stream * bj_connect_tcp_stream_to ( struct bj_address * addr,
uint16_t hints,
uint32_t ms_timeout,
struct bj_error ** error )

Connects to a pre-resolved address, trying all resolved IPs.

Automatically iterates through all addresses returned by DNS resolution until one succeeds.

Parameters
addrDestination address (from bj_resolve_address), or 0, which connects to nothing.
hintsSocket hints (BJ_NET_HINT_DELAY_ACK, etc.).
ms_timeoutConnection timeout per address in milliseconds.
errorOptional 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()

struct bj_tcp_stream * bj_connect_tcp_to ( struct bj_address * addr,
uint16_t hints,
uint32_t ms_timeout,
struct bj_error ** error )
Deprecated
Renamed to bj_connect_tcp_stream_to. Removed in 2.0.

◆ bj_create_stream_from_tcp()

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.

The functions of Data Stream then read and write the connection, the byte-order ones included:

bj_write_stream_u32_be(s, message_length);
bj_write_stream(s, message, message_length);
struct bj_stream bj_stream
Definition api.h:374
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.
Definition stream.h:136

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
tcpA connected TCP stream, or 0, which gives 0.
flagsBJ_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 )

Creates a TCP listener bound to the specified host and port.

The listener accepts incoming TCP connections via bj_accept_tcp_stream.

Parameters
hostHostname or IP address to bind to. Pass 0 to bind to all interfaces.
portPort number to listen on.
hintAddress family hint. Use 0 for any, BJ_NET_HINT_IPV4 for IPv4 only, or BJ_NET_HINT_IPV6 for IPv6 only.
backlogMaximum pending connections queue size. Use BJ_NET_BACKLOG_DEFAULT for a reasonable default, or BJ_NET_BACKLOG_MAX for the system maximum.
errorOptional error output. May be 0.
Returns
A new TCP listener, or 0 on failure.
See also
bj_accept_tcp_stream To accept incoming connections.
bj_destroy_tcp_listener To close the listener.
Todo
This function does not yet enforce UTF-8 on host. Per ADR 0008, it will.
Examples
net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.

Referenced by main().

◆ 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
hostHostname/IP to bind to. 0 for any interface.
portPort to bind. 0 for ephemeral (system-assigned).
hintsFlags: BJ_NET_HINT_IPV4, BJ_NET_HINT_IPV6, BJ_NET_HINT_NONBLOCKING, BJ_NET_HINT_BROADCAST
errorOptional 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 )
Deprecated
Renamed to bj_datagram_address. Removed in 2.0.

◆ 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
dgramDatagram, or 0, which gives 0.
bufOutput buffer (may be 0 to query length).
sizeBuffer 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)

Gets the data pointer from a datagram.

Parameters
dgramDatagram, or 0, which gives 0.
Returns
Pointer to data, or 0 on error.
Examples
net_udp_broadcast_recv.c, net_udp_client.c, and net_udp_server.c.

Referenced by main().

◆ bj_datagram_len()

size_t bj_datagram_len ( const struct bj_datagram * dgram)
Deprecated
Renamed to bj_datagram_length. Removed in 2.0.

◆ bj_datagram_length()

size_t bj_datagram_length ( const struct bj_datagram * dgram)

Gets the data length from a datagram.

Parameters
dgramDatagram, or 0, which gives 0.
Returns
Data length, or 0 on error.
Examples
net_udp_broadcast_recv.c, net_udp_client.c, and net_udp_server.c.

Referenced by main().

◆ bj_datagram_port()

uint16_t bj_datagram_port ( const struct bj_datagram * dgram)

Gets the sender's port from a datagram.

Parameters
dgramDatagram, or 0, which gives 0.
Returns
Sender port, or 0 on error.
Examples
net_udp_broadcast_recv.c, and net_udp_server.c.

Referenced by main().

◆ bj_destroy_address()

void bj_destroy_address ( struct bj_address * addr)

Frees a resolved address.

0-safe.

Parameters
addrThe address to free. May be 0.

◆ bj_destroy_datagram()

void bj_destroy_datagram ( struct bj_datagram * dgram)

Closes a datagram and frees resources.

0-safe.

Parameters
dgramThe datagram to close. May be 0.
Examples
net_udp_broadcast_recv.c, net_udp_client.c, and net_udp_server.c.

Referenced by main().

◆ bj_destroy_tcp_listener()

void bj_destroy_tcp_listener ( struct bj_tcp_listener * listener)

Closes a TCP listener and releases associated resources.

Safe to call with 0.

Parameters
listenerThe TCP listener to close. May be 0.
Examples
net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.

Referenced by main().

◆ bj_destroy_tcp_stream()

void bj_destroy_tcp_stream ( struct bj_tcp_stream * stream)

Closes a TCP stream and releases associated resources.

Safe to call with 0.

Parameters
streamThe TCP stream to close. May be 0.
Examples
net_tcp_client.c, net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.

Referenced by main().

◆ bj_destroy_udp()

void bj_destroy_udp ( struct bj_udp * udp)

Closes a UDP socket.

0-safe.

Parameters
udpThe UDP socket to close. May be 0.
Examples
net_udp_broadcast_recv.c, net_udp_broadcast_send.c, net_udp_client.c, and net_udp_server.c.

Referenced by main().

◆ bj_disable_tcp_keepalive()

bj_bool bj_disable_tcp_keepalive ( struct bj_tcp_stream * stream)

Turns off TCP keep-alive probes for a stream.

Parameters
streamTCP stream, or 0, which gives BJ_FALSE.
Returns
BJ_TRUE on success.
See also
bj_enable_tcp_keepalive, bj_tcp_has_keepalive

◆ bj_enable_tcp_keepalive()

bj_bool bj_enable_tcp_keepalive ( struct bj_tcp_stream * stream)

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
streamTCP 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()

void bj_free_address ( struct bj_address * addr)
Deprecated
Renamed to bj_destroy_address. Removed in 2.0.

◆ bj_get_tcp_keepalive()

bj_bool bj_get_tcp_keepalive ( struct bj_tcp_stream * stream)
Deprecated
Renamed to bj_tcp_has_keepalive. Removed in 2.0.

◆ bj_get_tcp_recv_timeout()

uint32_t bj_get_tcp_recv_timeout ( struct bj_tcp_stream * stream)
Deprecated
Renamed to bj_tcp_receive_timeout. Removed in 2.0.

◆ bj_get_tcp_send_timeout()

uint32_t bj_get_tcp_send_timeout ( struct bj_tcp_stream * stream)
Deprecated
Renamed to bj_tcp_send_timeout. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_create_tcp_listener. Removed in 2.0.

◆ bj_open_udp()

struct bj_udp * bj_open_udp ( const char * host,
uint16_t port,
uint16_t hints,
struct bj_error ** error )
Deprecated
Renamed to bj_create_udp. Removed in 2.0.

◆ 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
streamThe TCP stream to peek from, or 0, which returns -1.
bufBuffer to store peeked data. 0 returns -1 unless len is 0.
lenMaximum 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
streamThe TCP stream to receive from, or 0, which returns -1.
bufBuffer to store received data. 0 returns -1 unless len is 0.
lenMaximum 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()

struct bj_datagram * bj_receive_udp ( struct bj_udp * udp,
struct bj_error ** error )

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
udpUDP socket, or 0, which receives nothing.
errorOptional 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
hostHostname or IP string to resolve, or 0, which resolves nothing and leaves error alone.
portPort number.
hintsBJ_NET_HINT_IPV4, BJ_NET_HINT_IPV6, or 0 for any.
errorOptional 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
streamThe TCP stream to send on, or 0, which returns -1.
bufBuffer containing data to send. 0 returns -1 unless len is 0.
lenNumber 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
udpUDP socket, or 0, which sends nothing.
hostDestination hostname or IP, or 0, which sends nothing.
portDestination port.
dataData to send. 0 sends nothing unless len is 0.
lenData length.
errorOptional 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
udpUDP socket, or 0, which sends nothing.
addrDestination address (from bj_resolve_address), or 0, which sends nothing.
dataData to send. 0 sends nothing unless len is 0.
lenData length.
errorOptional 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_bool bj_set_tcp_keepalive ( struct bj_tcp_stream * stream,
bj_bool enable )

◆ bj_set_tcp_receive_timeout()

bj_bool bj_set_tcp_receive_timeout ( struct bj_tcp_stream * stream,
uint32_t ms_timeout )

Sets the receive timeout for a TCP stream.

When set, recv operations will timeout after the specified duration.

Parameters
streamTCP stream, or 0, which gives BJ_FALSE.
ms_timeoutTimeout in milliseconds. 0 = no timeout (blocking).
Returns
BJ_TRUE on success.

◆ bj_set_tcp_recv_timeout()

bj_bool bj_set_tcp_recv_timeout ( struct bj_tcp_stream * stream,
uint32_t ms_timeout )
Deprecated
Renamed to bj_set_tcp_receive_timeout. Removed in 2.0.

◆ bj_set_tcp_send_timeout()

bj_bool bj_set_tcp_send_timeout ( struct bj_tcp_stream * stream,
uint32_t ms_timeout )

Sets the send timeout for a TCP stream.

When set, send operations will timeout after the specified duration.

Parameters
streamTCP stream, or 0, which gives BJ_FALSE.
ms_timeoutTimeout in milliseconds. 0 = no timeout (blocking).
Returns
BJ_TRUE on success.

◆ bj_shutdown_tcp()

void bj_shutdown_tcp ( struct bj_tcp_stream * stream,
int mode )

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
streamThe TCP stream to shutdown, or 0, which does nothing.
modeShutdown mode: BJ_NET_SHUTDOWN_RECEIVE, BJ_NET_SHUTDOWN_SEND, or BJ_NET_SHUTDOWN_BOTH.
See also
bj_destroy_tcp_stream To fully close the connection.

◆ bj_tcp_available()

int bj_tcp_available ( struct bj_tcp_stream * stream)

Checks bytes available to read without blocking.

Parameters
streamTCP 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()

bj_bool bj_tcp_has_keepalive ( struct bj_tcp_stream * stream)

Reports whether TCP keep-alive is currently enabled on a stream.

Parameters
streamTCP stream, or 0, which gives BJ_FALSE.
Returns
BJ_TRUE if keep-alive is enabled, BJ_FALSE otherwise.

◆ bj_tcp_listener_port()

uint16_t bj_tcp_listener_port ( const struct bj_tcp_listener * listener)

Get the listening port of the given server.

Parameters
listenerThe listener to get the local port from.
Returns
Listener port number

Will return 0 if listener is 0 or closed.

Examples
net_tcp_nonblocking.c, net_tcp_server.c, and net_tcp_timeout.c.

Referenced by main().

◆ 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
streamThe TCP stream to query, or 0, which gives 0.
bufBuffer to store the address string. May be 0 to query length only.
sizeSize 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 )
Deprecated
Renamed to bj_peek_tcp. Removed in 2.0.

◆ 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
streamThe TCP stream to query, or 0, which gives 0.
bufBuffer to store the address string. May be 0 to query length only.
sizeSize 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()

uint32_t bj_tcp_receive_timeout ( struct bj_tcp_stream * stream)

Gets the current receive timeout.

Parameters
streamTCP 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 )
Deprecated
Renamed to bj_receive_tcp. Removed in 2.0.

◆ bj_tcp_send()

int bj_tcp_send ( struct bj_tcp_stream * stream,
const void * buf,
size_t len )
Deprecated
Renamed to bj_send_tcp. Removed in 2.0.

◆ bj_tcp_send_timeout()

uint32_t bj_tcp_send_timeout ( struct bj_tcp_stream * stream)

Gets the current send timeout.

Parameters
streamTCP stream, or 0, which gives 0.
Returns
Timeout in milliseconds, or 0 if no timeout set.

◆ bj_tcp_shutdown()

void bj_tcp_shutdown ( struct bj_tcp_stream * stream,
int mode )
Deprecated
Renamed to bj_shutdown_tcp. Removed in 2.0.

◆ bj_tcp_wait()

bj_bool bj_tcp_wait ( struct bj_tcp_stream * stream,
uint32_t ms_timeout )
Deprecated
Renamed to bj_wait_tcp. Removed in 2.0.

◆ bj_udp_available()

bj_bool bj_udp_available ( struct bj_udp * udp)
Deprecated
Renamed to bj_udp_has_data. Removed in 2.0.

◆ bj_udp_has_data()

bj_bool bj_udp_has_data ( struct bj_udp * udp)

Checks if a datagram is available without blocking.

Parameters
udpUDP 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
udpUDP socket, or 0, which gives 0.
bufOutput buffer (may be 0 to query length).
sizeBuffer size.
Returns
Address string length, or 0 on error.

◆ bj_udp_local_port()

uint16_t bj_udp_local_port ( const struct bj_udp * udp)

Gets the local port of a UDP socket.

Parameters
udpUDP socket, or 0, which gives 0.
Returns
Local port, or 0 on error.
Examples
net_udp_client.c, and net_udp_server.c.

Referenced by main().

◆ bj_udp_recv()

struct bj_datagram * bj_udp_recv ( struct bj_udp * udp,
struct bj_error ** error )
Deprecated
Renamed to bj_receive_udp. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_send_udp. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_send_udp_to. Removed in 2.0.

◆ bj_udp_wait()

bj_bool bj_udp_wait ( struct bj_udp * udp,
uint32_t ms_timeout )
Deprecated
Renamed to bj_wait_udp. Removed in 2.0.

◆ bj_wait_tcp()

bj_bool bj_wait_tcp ( struct bj_tcp_stream * stream,
uint32_t ms_timeout )

Waits for data to become available on a TCP stream.

Uses select() internally to wait for readability with a timeout.

Parameters
streamTCP stream to wait on, or 0, which gives BJ_FALSE at once.
ms_timeoutTimeout in milliseconds. 0 = non-blocking poll.
Returns
BJ_TRUE if data available, BJ_FALSE on timeout.

◆ bj_wait_udp()

bj_bool bj_wait_udp ( struct bj_udp * udp,
uint32_t ms_timeout )

Waits for data to become available on a UDP socket.

Uses select() internally to wait for readability with a timeout.

Parameters
udpUDP socket, or 0, which gives BJ_FALSE at once.
ms_timeoutTimeout 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().