peer.h

#include <modkit/peer.h>19 functions · 3 structs · 5 enums · 5 typedefs · 2 macros

Transport-agnostic networking: hosts, peers, delivery channels.

An L1 "session" layer over the platform transport backends. Game code talks to an mk_host (a server OR a client endpoint) that produces mk_peers and exchanges messages on numbered channels with a chosen delivery guarantee. The same event-loop code runs on both client and server. mk_host_t* host = mk_host_create(&(mk_host_desc){ .role = MK_HOST_SERVER, .transport = MK_TRANSPORT_UDP, .bind_addr = "0.0.0.0", .port = 7777, .max_peers = 256, .channel_count = 2, .channels = { {MK_DELIVERY_UNRELIABLE_SEQUENCED}, {MK_DELIVERY_RELIABLE_ORDERED} }, .app_protocol_id = 0xCAFE0001, }); mk_peer_event ev; while (mk_host_service(host, &ev, 0)) { if (ev.type == MK_PEER_EVENT_RECEIVE) handle(ev.peer, ev.channel, ev.data, ev.len); } Unlike the raw UDP in net.h, message boundaries ARE preserved: every MK_PEER_EVENT_RECEIVE is exactly one mk_peer_send from the other side. The data pointer is owned by the host and is valid only until the next mk_host_service() call on that host (copy it if you need to keep it).

Functions

`mk_host_broadcast`function

void mk_host_broadcast(mk_host_t *host, uint8_t channel, const void *data, uint32_t len)

Perform the host broadcast operation.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.
`channel`	`uint8_t`	Value for channel.
`data`	`const void *`	Data buffer.
`len`	`uint32_t`	Value for len.

`mk_host_broadcast_except`function

void mk_host_broadcast_except(mk_host_t *host, mk_peer_t *except, uint8_t channel, const void *data, uint32_t len)

Perform the host broadcast except operation.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.
`except`	`mk_peer_t *`	Value for except.
`channel`	`uint8_t`	Value for channel.
`data`	`const void *`	Data buffer.
`len`	`uint32_t`	Value for len.

`mk_host_connect`function

mk_peer_t * mk_host_connect(mk_host_t *host, const char *remote, uint16_t port)

Client: initiate a connection.

Returns a peer in the CONNECTING state; a

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.
`remote`	`const char *`	Value for remote.
`port`	`uint16_t`	Value for port.

Returns A borrowed pointer, or NULL when unavailable. MK_PEER_EVENT_CONNECT (or DISCONNECT on failure) follows from service().

`mk_host_connect_url`function

mk_peer_t * mk_host_connect_url(mk_host_t *host, const char *url)

Client: connect a WebSocket host using an absolute ws:// or wss:// URL.

The URL may include a path, query, explicit port, or bracketed IPv6 address. Returns NULL for an invalid URL, non-client host, or non-WebSocket transport.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.
`url`	`const char *`	Value for URL.

Returns A borrowed pointer, or NULL when unavailable.

`mk_host_create`function

mk_host_t * mk_host_create(const mk_host_desc *desc)

Create host.

Parameter	Type	Description
`desc`	`const mk_host_desc *`	Configuration descriptor.

Returns A borrowed pointer, or NULL when unavailable.

`mk_host_destroy`function

void mk_host_destroy(mk_host_t *host)

Destroy the host.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.

`mk_host_peer_count`function

uint32_t mk_host_peer_count(mk_host_t *host)

Number of peers currently attached to a host.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.

Returns The resulting value.

`mk_host_peer_first`function

mk_peer_t * mk_host_peer_first(mk_host_t *host)

First attached peer, or NULL.

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.

Returns A borrowed pointer, or NULL when unavailable.

`mk_host_service`function

int mk_host_service(mk_host_t *host, mk_peer_event *out, uint32_t timeout_ms)

Pump the network and dequeue ONE event.

Call repeatedly until it returns 0. Drives the transport event loop. timeout_ms 0 = non-blocking (clients/frame

Parameter	Type	Description
`host`	`mk_host_t *`	Value for host.
`out`	`mk_peer_event *`	Value for out.
`timeout_ms`	`uint32_t`	Value for timeout ms.

Returns The resulting value. loop); >0 may block up to that long waiting for I/O (headless server tick).

`mk_peer_address`function

bool mk_peer_address(mk_peer_t *peer, char *host, size_t cap, uint16_t *port)

Perform the peer address operation.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.
`host`	`char *`	Value for host.
`cap`	`size_t`	Value for cap.
`port`	`uint16_t *`	Value for port.

Returns True when the operation succeeds.

`mk_peer_disconnect`function

void mk_peer_disconnect(mk_peer_t *peer, mk_disconnect_reason_t reason)

Perform the peer disconnect operation.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.
`reason`	`mk_disconnect_reason_t`	Value for reason.

`mk_peer_get_user`function

uint64_t mk_peer_get_user(mk_peer_t *peer)

Get user from the peer.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.

Returns The resulting value.

`mk_peer_get_user_ptr`function

void * mk_peer_get_user_ptr(mk_peer_t *peer)

Get user ptr from the peer.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.

Returns A borrowed pointer, or NULL when unavailable.

`mk_peer_host`function

mk_host_t * mk_peer_host(mk_peer_t *peer)

Perform the peer host operation.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.

Returns A borrowed pointer, or NULL when unavailable.

`mk_peer_next`function

mk_peer_t * mk_peer_next(mk_peer_t *peer)

Next peer in the host's list, or NULL at the end.

The iteration is invalidated by mk_host_service(), which is when

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.

Returns A borrowed pointer, or NULL when unavailable. disconnected peers are retired; re-walk it rather than holding pointers.

`mk_peer_rtt_ms`function

uint32_t mk_peer_rtt_ms(mk_peer_t *peer)

0 if unknown

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.

Returns The resulting value. 0 if unknown

`mk_peer_send`function

bool mk_peer_send(mk_peer_t *peer, uint8_t channel, const void *data, uint32_t len)

Send peer.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.
`channel`	`uint8_t`	Value for channel.
`data`	`const void *`	Data buffer.
`len`	`uint32_t`	Value for len.

Returns True when the operation succeeds.

`mk_peer_set_user`function

void mk_peer_set_user(mk_peer_t *peer, uint64_t user)

Set user on the peer.

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.
`user`	`uint64_t`	Caller-provided context.

`mk_peer_set_user_ptr`function

void mk_peer_set_user_ptr(mk_peer_t *peer, void *ptr)

A second, pointer-sized slot of per-peer application state.

One uint64 is

Parameter	Type	Description
`peer`	`mk_peer_t *`	Value for peer.
`ptr`	`void *`	Value for ptr. not enough once a peer carries both a platform identity and an app object.

Structs

`mk_channel_desc`struct

Data for channel desc.

Field	Type	Description
`delivery`	`mk_delivery_t`	The delivery.
`kcp_sndwnd`	`uint16_t`	UDP/KCP only; 0 = backend default.
`kcp_rcvwnd`	`uint16_t`	The kcp rcvwnd.

`mk_host_desc`struct

Data for host desc.

Field	Type	Description
`role`	`mk_host_role_t`	The role.
`transport`	`mk_transport_t`	The transport.
`bind_addr`	`const char *`	server bind (NULL/"0.0.0.0"); client unused
`port`	`uint16_t`	The port.
`max_peers`	`uint32_t`	server capacity; 0 -> 1
`channel_count`	`uint8_t`	The channel count.
`channels`	`mk_channel_desc`	The channels.
`app_protocol_id`	`uint32_t`	rejects clients with a different id

`mk_peer_event`struct

Data for peer event.

Field	Type	Description
`type`	`mk_peer_event_type_t`	The type.
`peer`	`mk_peer_t *`	who the event is about
`channel`	`uint8_t`	RECEIVE: which channel.
`reason`	`mk_disconnect_reason_t`	DISCONNECT only.
`data`	`const void *`	RECEIVE: one message; valid until next service().
`len`	`uint32_t`	The len.

Enums

`mk_delivery_t`enum

Values for delivery.

Value	Description
`MK_DELIVERY_UNRELIABLE`	raw datagram; may drop/reorder
`MK_DELIVERY_UNRELIABLE_SEQUENCED`	drops stale; never out-of-order
`MK_DELIVERY_RELIABLE_ORDERED`	TCP-like: all messages, in order.

`mk_disconnect_reason_t`enum

Values for disconnect reason.

Value	Description
`MK_DISCONNECT_NORMAL`	Selects normal.
`MK_DISCONNECT_TIMEOUT`	Selects timeout.
`MK_DISCONNECT_PROTOCOL_MISMATCH`	Selects protocol mismatch.
`MK_DISCONNECT_SERVER_FULL`	Selects server full.
`MK_DISCONNECT_TRANSPORT_ERROR`	Selects transport error.

`mk_host_role_t`enum

Values for host role.

Value	Description
`MK_HOST_SERVER`	Accept incoming peers.
`MK_HOST_CLIENT`	Initiate an outgoing peer connection.

`mk_peer_event_type_t`enum

Values for peer event type.

Value	Description
`MK_PEER_EVENT_NONE`	Selects none.
`MK_PEER_EVENT_CONNECT`	Selects connect.
`MK_PEER_EVENT_DISCONNECT`	Selects disconnect.
`MK_PEER_EVENT_RECEIVE`	Selects receive.

`mk_transport_t`enum

Values for transport.

Value	Description
`MK_TRANSPORT_UDP`	native UDP; per-channel raw or KCP (reliable)
`MK_TRANSPORT_TCP`	native TCP; reliable-ordered only
`MK_TRANSPORT_WS`	native WebSocket (libhv)
`MK_TRANSPORT_WS_WEB`	browser WebSocket via emscripten (client only)
`MK_TRANSPORT_AUTO`	WS_WEB on web, else UDP.

Typedefs

`mk_channel_desc`typedef

typedef struct mk_channel_desc mk_channel_desc

Data for channel desc.

`mk_host_desc`typedef

typedef struct mk_host_desc mk_host_desc

Data for host desc.

`mk_host_t`typedef

typedef struct mk_host mk_host_t

opaque endpoint (server or client)

`mk_peer_event`typedef

typedef struct mk_peer_event mk_peer_event

Data for peer event.

`mk_peer_t`typedef

typedef struct mk_peer mk_peer_t

opaque connection, owned by its host

Macros

`MK_MAX_CHANNELS`define

MK_MAX_CHANNELS

Maximum supported channels.

`MK_NET_PROTOCOL_VERSION`define

MK_NET_PROTOCOL_VERSION

Wire protocol version, exchanged in the handshake.

Bump on any framing or handshake change; peers with a different version are rejected.

peer.h

Functions

mk_host_broadcastfunction

mk_host_broadcast_exceptfunction

mk_host_connectfunction

mk_host_connect_urlfunction

mk_host_createfunction

mk_host_destroyfunction

mk_host_peer_countfunction

mk_host_peer_firstfunction

mk_host_servicefunction

mk_peer_addressfunction

mk_peer_disconnectfunction

mk_peer_get_userfunction

mk_peer_get_user_ptrfunction

mk_peer_hostfunction

mk_peer_nextfunction

mk_peer_rtt_msfunction

mk_peer_sendfunction

mk_peer_set_userfunction

mk_peer_set_user_ptrfunction

Structs

mk_channel_descstruct

mk_host_descstruct

mk_peer_eventstruct

Enums

mk_delivery_tenum

mk_disconnect_reason_tenum

mk_host_role_tenum

mk_peer_event_type_tenum

mk_transport_tenum

Typedefs

mk_channel_desctypedef

mk_host_desctypedef

mk_host_ttypedef

mk_peer_eventtypedef

mk_peer_ttypedef

Macros

MK_MAX_CHANNELSdefine

MK_NET_PROTOCOL_VERSIONdefine

`mk_host_broadcast`function

`mk_host_broadcast_except`function

`mk_host_connect`function

`mk_host_connect_url`function

`mk_host_create`function

`mk_host_destroy`function

`mk_host_peer_count`function

`mk_host_peer_first`function

`mk_host_service`function

`mk_peer_address`function

`mk_peer_disconnect`function

`mk_peer_get_user`function

`mk_peer_get_user_ptr`function

`mk_peer_host`function

`mk_peer_next`function

`mk_peer_rtt_ms`function

`mk_peer_send`function

`mk_peer_set_user`function

`mk_peer_set_user_ptr`function

`mk_channel_desc`struct

`mk_host_desc`struct

`mk_peer_event`struct

`mk_delivery_t`enum

`mk_disconnect_reason_t`enum

`mk_host_role_t`enum

`mk_peer_event_type_t`enum

`mk_transport_t`enum

`mk_channel_desc`typedef

`mk_host_desc`typedef

`mk_host_t`typedef

`mk_peer_event`typedef

`mk_peer_t`typedef

`MK_MAX_CHANNELS`define

`MK_NET_PROTOCOL_VERSION`define