mk_net_capabilitiesfunction
mk_net_capabilities_t mk_net_capabilities(void)Return the capabilities supported by the current target at runtime.
Returns The resulting handle or value.
net.h
#include <modkit/net.h>23 functions · 13 structs · 5 enums · 20 typedefs · 3 macros
Poll-driven TCP and UDP networking primitives.
Networking is asynchronous. Backend threads and browser callbacks only enqueue work; user callbacks run from mk_net_poll() on the thread that initialized the subsystem.
Functions
mk_net_desc_initfunction
mk_net_desc mk_net_desc_init(void)Return limits of 4096 pending events and 16 MiB of pending payload data.
Returns The resulting value.
mk_net_initfunction
mk_result mk_net_init(const mk_net_desc *desc)Initialize networking and make the calling thread its owner.
| Parameter | Type | Description |
|---|---|---|
desc | const mk_net_desc * | Runtime limits, or NULL for mk_net_desc_init() defaults. |
Returns MK_SUCCESS, or an initialization/state error.
mk_net_is_initializedfunction
bool mk_net_is_initialized(void)Return whether the networking runtime is initialized.
Returns True when the condition holds.
mk_net_last_errorfunction
mk_net_error mk_net_last_error(void)Return the calling thread's most recent immediate networking error.
Returns The resulting value.
mk_net_pollfunction
uint32_t mk_net_poll(uint32_t timeout_ms, uint32_t max_events)Deliver a snapshot of pending events.
| Parameter | Type | Description |
|---|---|---|
timeout_ms | uint32_t | Maximum wait when no event is ready; zero is non-blocking. |
max_events | uint32_t | Maximum callbacks to deliver; zero drains the snapshot. |
Returns Number of callbacks delivered.
mk_net_shutdownfunction
void mk_net_shutdown(void)Close all networking resources and discard pending events.
mk_tcp_closefunction
mk_result mk_tcp_close(mk_tcp_t connection)Close a TCP connection; any queued CLOSED event remains deliverable.
| Parameter | Type | Description |
|---|---|---|
connection | mk_tcp_t | Value for connection. |
Returns MK_SUCCESS or an error result.
mk_tcp_connectfunction
mk_result mk_tcp_connect(const mk_tcp_connect_desc *desc, mk_tcp_t *out_connection)Start an asynchronous TCP connection and return its handle.
| Parameter | Type | Description |
|---|---|---|
desc | const mk_tcp_connect_desc * | Configuration descriptor. |
out_connection | mk_tcp_t * | Receives the connection. |
Returns MK_SUCCESS or an error result.
mk_tcp_connect_desc_initfunction
mk_tcp_connect_desc mk_tcp_connect_desc_init(void)Return 10-second, 4-MiB defaults with TCP_NODELAY and keepalive enabled.
Returns The resulting value.
mk_tcp_listenfunction
mk_result mk_tcp_listen(const mk_tcp_listen_desc *desc, mk_tcp_listener_t *out_listener)Create and start a native TCP listener.
| Parameter | Type | Description |
|---|---|---|
desc | const mk_tcp_listen_desc * | Configuration descriptor. |
out_listener | mk_tcp_listener_t * | Receives the listener. |
Returns MK_SUCCESS or an error result.
mk_tcp_listen_desc_initfunction
mk_tcp_listen_desc mk_tcp_listen_desc_init(void)Return all-interface, 1024-client, 4-MiB listener defaults.
Returns The resulting value.
mk_tcp_listener_closefunction
mk_result mk_tcp_listener_close(mk_tcp_listener_t listener)Stop a listener and close its accepted connections.
| Parameter | Type | Description |
|---|---|---|
listener | mk_tcp_listener_t | Value for listener. |
Returns MK_SUCCESS or an error result.
mk_tcp_listener_portfunction
uint16_t mk_tcp_listener_port(mk_tcp_listener_t listener)Return the listener's bound port, including an automatically selected port.
| Parameter | Type | Description |
|---|---|---|
listener | mk_tcp_listener_t | Value for listener. |
Returns The resulting value.
mk_tcp_listener_validfunction
bool mk_tcp_listener_valid(mk_tcp_listener_t handle)Return whether a TCP listener handle is nonzero.
| Parameter | Type | Description |
|---|---|---|
handle | mk_tcp_listener_t | Value for handle. |
Returns True when the operation succeeds.
mk_tcp_sendfunction
mk_result mk_tcp_send(mk_tcp_t connection, const void *data, size_t size)Queue bytes for transmission without blocking.
| Parameter | Type | Description |
|---|---|---|
connection | mk_tcp_t | Value for connection. |
data | const void * | Data buffer. |
size | size_t | Size in bytes. |
Returns MK_SUCCESS or an error result.
mk_tcp_validfunction
bool mk_tcp_valid(mk_tcp_t handle)Return whether a TCP connection handle is nonzero.
| Parameter | Type | Description |
|---|---|---|
handle | mk_tcp_t | Value for handle. |
Returns True when the operation succeeds.
mk_udp_closefunction
mk_result mk_udp_close(mk_udp_t socket)Close a UDP socket and invalidate its handle.
| Parameter | Type | Description |
|---|---|---|
socket | mk_udp_t | Value for socket. |
Returns MK_SUCCESS or an error result.
mk_udp_desc_initfunction
mk_udp_desc mk_udp_desc_init(void)Return an all-interface descriptor with a 65507-byte datagram limit.
Returns The resulting value.
mk_udp_openfunction
mk_result mk_udp_open(const mk_udp_desc *desc, mk_udp_t *out_socket)Create and bind a native UDP socket.
| Parameter | Type | Description |
|---|---|---|
desc | const mk_udp_desc * | Configuration descriptor. |
out_socket | mk_udp_t * | Receives the socket. |
Returns MK_SUCCESS or an error result.
mk_udp_portfunction
uint16_t mk_udp_port(mk_udp_t socket)Return the socket's bound port, including an automatically selected port.
| Parameter | Type | Description |
|---|---|---|
socket | mk_udp_t | Value for socket. |
Returns The resulting value.
mk_udp_send_tofunction
mk_result mk_udp_send_to(mk_udp_t socket, const mk_net_address *destination, const void *data, size_t size)Send one datagram to a numeric address or DNS hostname.
| Parameter | Type | Description |
|---|---|---|
socket | mk_udp_t | Value for socket. |
destination | const mk_net_address * | Value for destination. |
data | const void * | Data buffer. |
size | size_t | Size in bytes. |
Returns MK_SUCCESS or an error result.
mk_udp_validfunction
bool mk_udp_valid(mk_udp_t handle)Return whether a UDP socket handle is nonzero.
| Parameter | Type | Description |
|---|---|---|
handle | mk_udp_t | Value for handle. |
Returns True when the operation succeeds.
Structs
mk_net_addressstruct
Numeric address used by UDP events and sends.
| Field | Type | Description |
|---|---|---|
host | char | Numeric IPv4 or IPv6 address without brackets. |
port | uint16_t | Host-order port number. |
ipv6 | bool | True when host contains an IPv6 address. |
mk_net_descstruct
Process-wide networking runtime limits.
| Field | Type | Description |
|---|---|---|
max_queued_events | uint32_t | Pending callback limit; zero uses the default. |
max_queued_bytes | size_t | Pending payload-byte limit; zero uses the default. |
mk_net_errorstruct
Detailed error information returned in events and by mk_net_last_error().
| Field | Type | Description |
|---|---|---|
code | mk_net_error_code | Portable error category. |
platform_code | int32_t | Backend/native error code, or zero if unavailable. |
message | char | Null-terminated diagnostic text. |
mk_tcp_connect_descstruct
Descriptor for an asynchronous TCP client connection.
| Field | Type | Description |
|---|---|---|
host | const char * | DNS name or numeric address; required. |
port | uint16_t | Remote port; must be nonzero. |
connect_timeout_ms | uint32_t | Connect timeout; zero uses 10 seconds. |
max_send_queue_bytes | size_t | Pending-send limit; zero uses 4 MiB. |
no_delay | bool | Enable TCP_NODELAY. |
keepalive | bool | Enable TCP keepalive. |
callback | mk_tcp_event_fn | Required connection callback. |
user_data | void * | Opaque value passed to callback. |
mk_tcp_eventstruct
Data delivered to a TCP callback from mk_net_poll().
| Field | Type | Description |
|---|---|---|
type | mk_tcp_event_type | Event kind. |
connection | mk_tcp_t | Connection associated with the event. |
listener | mk_tcp_listener_t | Accepting listener, or invalid for clients. |
peer | mk_net_address | Remote numeric address when known. |
data | const void * | Received bytes for MK_TCP_EVENT_DATA. |
size | size_t | Number of bytes in data. |
error | mk_net_error | Close/error detail; code is NONE on success. |
mk_tcp_handlestruct
Generational handle for a TCP connection.
| Field | Type | Description |
|---|---|---|
id | uint32_t | Opaque identifier; zero is invalid. |
mk_tcp_listen_descstruct
Descriptor for a native TCP listener.
| Field | Type | Description |
|---|---|---|
bind_address | const char * | Local address; NULL means all IPv4 interfaces. |
port | uint16_t | Local port; zero selects an available port. |
max_connections | uint32_t | Connection limit; zero uses 1024. |
max_send_queue_bytes | size_t | Per-client send limit; zero uses 4 MiB. |
no_delay | bool | Enable TCP_NODELAY on accepted connections. |
keepalive | bool | Enable keepalive on accepted connections. |
callback | mk_tcp_event_fn | Required listener/connection callback. |
user_data | void * | Opaque value passed to callback. |
mk_tcp_listener_handlestruct
Generational handle for a TCP listener.
| Field | Type | Description |
|---|---|---|
id | uint32_t | Opaque identifier; zero is invalid. |
mk_tls_client_configstruct
Optional TLS trust configuration for an HTTPS or WSS client.
| Field | Type | Description |
|---|---|---|
trust | mk_tls_trust_mode | Trust policy; defaults to MK_TLS_TRUST_DEFAULT. |
ca_pem | const void * | PEM CA bundle used by custom trust modes. |
ca_pem_size | size_t | CA bundle size in bytes; a trailing NUL is optional. |
mk_tls_server_configstruct
In-memory credentials for a native HTTPS or WSS server.
| Field | Type | Description |
|---|---|---|
certificate_pem | const void * | PEM certificate or certificate chain. |
certificate_pem_size | size_t | Certificate data size in bytes. |
private_key_pem | const void * | PEM private key matching the certificate. |
private_key_pem_size | size_t | Private-key data size in bytes. |
mk_udp_descstruct
Descriptor for a native UDP socket.
| Field | Type | Description |
|---|---|---|
bind_address | const char * | Local address; NULL means all IPv4 interfaces. |
port | uint16_t | Local port; zero selects an available port. |
max_datagram_size | size_t | Retained byte limit; zero uses 65507. |
allow_broadcast | bool | Enable IPv4 broadcast sends. |
callback | mk_udp_event_fn | Required socket callback. |
user_data | void * | Opaque value passed to callback. |
mk_udp_eventstruct
Data delivered to a UDP callback from mk_net_poll().
| Field | Type | Description |
|---|---|---|
type | mk_udp_event_type | Event kind. |
socket | mk_udp_t | Receiving socket. |
source | mk_net_address | Datagram source address. |
data | const void * | Received bytes for DATAGRAM events. |
size | size_t | Bytes retained in data. |
original_size | size_t | Wire size before application truncation. |
dropped_datagrams | uint64_t | Cumulative drops reported by OVERFLOW. |
truncated | bool | True if original_size exceeded size. |
error | mk_net_error | Error detail for ERROR/OVERFLOW events. |
mk_udp_handlestruct
Generational handle for a UDP socket.
| Field | Type | Description |
|---|---|---|
id | uint32_t | Opaque identifier; zero is invalid. |
Enums
mk_net_capabilityenum
Runtime networking capability bits.
| Value | Description |
|---|---|
MK_NET_CAP_TCP | Raw TCP clients are available. |
MK_NET_CAP_TCP_SERVER | Raw TCP listeners are available. |
MK_NET_CAP_UDP | UDP sockets are available. |
MK_NET_CAP_HTTP_CLIENT | HTTP/HTTPS clients are available. |
MK_NET_CAP_HTTP_SERVER | HTTP/HTTPS servers are available. |
MK_NET_CAP_WEBSOCKET_CLIENT | WebSocket clients are available. |
MK_NET_CAP_WEBSOCKET_SERVER | WebSocket servers are available. |
MK_NET_CAP_TLS | HTTPS and WSS are available. |
MK_NET_CAP_CUSTOM_CA | Client CA bundles can be supplied. |
MK_NET_CAP_CUSTOM_WS_HEADERS | WS handshake headers can be supplied. |
mk_net_error_codeenum
Portable category for the most recent networking failure.
| Value | Description |
|---|---|
MK_NET_ERROR_NONE | No networking error. |
MK_NET_ERROR_CANCELLED | Operation was cancelled by the application. |
MK_NET_ERROR_TIMEOUT | Connection or operation timed out. |
MK_NET_ERROR_DNS | Hostname resolution failed. |
MK_NET_ERROR_CONNECT | Connect, bind, or transport setup failed. |
MK_NET_ERROR_TLS | TLS configuration or negotiation failed. |
MK_NET_ERROR_PROTOCOL | Malformed or unsupported protocol data. |
MK_NET_ERROR_LIMIT | Configured resource or body limit was reached. |
MK_NET_ERROR_QUEUE_FULL | A bounded event or send queue was full. |
MK_NET_ERROR_CLOSED | The transport closed before completion. |
MK_NET_ERROR_PLATFORM | Platform restriction or native API failure. |
mk_tcp_event_typeenum
TCP connection event kind.
| Value | Description |
|---|---|
MK_TCP_EVENT_CONNECTED | An outgoing connection is ready. |
MK_TCP_EVENT_ACCEPTED | A listener accepted a connection. |
MK_TCP_EVENT_DATA | A byte-stream chunk was received. |
MK_TCP_EVENT_CLOSED | The connection closed; terminal event. |
mk_tls_trust_modeenum
Certificate-authority policy for native HTTPS and WSS clients.
| Value | Description |
|---|---|
MK_TLS_TRUST_DEFAULT | Trust ModKit's embedded public roots. |
MK_TLS_TRUST_DEFAULT_PLUS_CUSTOM | Trust public roots and ca_pem. |
MK_TLS_TRUST_CUSTOM_ONLY | Trust only ca_pem. |
MK_TLS_TRUST_INSECURE | Disable peer verification; testing only. |
mk_udp_event_typeenum
UDP socket event kind.
| Value | Description |
|---|---|
MK_UDP_EVENT_DATAGRAM | A datagram was received. |
MK_UDP_EVENT_OVERFLOW | One or more datagrams were dropped by limits. |
MK_UDP_EVENT_ERROR | A transport error occurred. |
Typedefs
mk_net_addresstypedef
typedef struct mk_net_address mk_net_addressNumeric address used by UDP events and sends.
mk_net_capabilities_ttypedef
typedef uint64_t mk_net_capabilities_tBitmask returned by mk_net_capabilities().
mk_net_desctypedef
typedef struct mk_net_desc mk_net_descProcess-wide networking runtime limits.
mk_net_errortypedef
typedef struct mk_net_error mk_net_errorDetailed error information returned in events and by mk_net_last_error().
mk_net_error_codetypedef
typedef enum mk_net_error_code mk_net_error_codePortable category for the most recent networking failure.
mk_tcp_connect_desctypedef
typedef struct mk_tcp_connect_desc mk_tcp_connect_descDescriptor for an asynchronous TCP client connection.
mk_tcp_eventtypedef
typedef struct mk_tcp_event mk_tcp_eventData delivered to a TCP callback from mk_net_poll().
mk_tcp_event_fntypedef
typedef void(*) mk_tcp_event_fn(const mk_tcp_event *event, void *user_data)TCP event callback invoked by mk_net_poll() on the owner thread.
mk_tcp_event_typetypedef
typedef enum mk_tcp_event_type mk_tcp_event_typeTCP connection event kind.
mk_tcp_listen_desctypedef
typedef struct mk_tcp_listen_desc mk_tcp_listen_descDescriptor for a native TCP listener.
mk_tcp_listener_ttypedef
typedef struct mk_tcp_listener_handle mk_tcp_listener_tGenerational handle for a TCP listener.
mk_tcp_ttypedef
typedef struct mk_tcp_handle mk_tcp_tGenerational handle for a TCP connection.
mk_tls_client_configtypedef
typedef struct mk_tls_client_config mk_tls_client_configOptional TLS trust configuration for an HTTPS or WSS client.
mk_tls_server_configtypedef
typedef struct mk_tls_server_config mk_tls_server_configIn-memory credentials for a native HTTPS or WSS server.
mk_tls_trust_modetypedef
typedef enum mk_tls_trust_mode mk_tls_trust_modeCertificate-authority policy for native HTTPS and WSS clients.
mk_udp_desctypedef
typedef struct mk_udp_desc mk_udp_descDescriptor for a native UDP socket.
mk_udp_eventtypedef
typedef struct mk_udp_event mk_udp_eventData delivered to a UDP callback from mk_net_poll().
mk_udp_event_fntypedef
typedef void(*) mk_udp_event_fn(const mk_udp_event *event, void *user_data)UDP event callback invoked by mk_net_poll() on the owner thread.
mk_udp_event_typetypedef
typedef enum mk_udp_event_type mk_udp_event_typeUDP socket event kind.
mk_udp_ttypedef
typedef struct mk_udp_handle mk_udp_tGenerational handle for a UDP socket.
Macros
MK_TCP_INVALIDdefine
MK_TCP_INVALIDInvalid TCP connection handle.
MK_TCP_LISTENER_INVALIDdefine
MK_TCP_LISTENER_INVALIDInvalid TCP listener handle.
MK_UDP_INVALIDdefine
MK_UDP_INVALIDInvalid UDP socket handle.