moqfetch.h File Reference

draft-ietf-moq-transport-18/19/22 FETCH: the FETCH (19 10.12, 22 9.11) and FETCH_OK (19 10.13, 22 9.12) control messages, and the fetch data stream (19 11.4.4, 22 11.4): the FETCH_HEADER and the fetch Objects with their Serialization Flags, including the End of Range markers (19 11.4.4.2). More...

#include "app/moqt/ctl/moqctl.h"

Go to the source code of this file.

Data Structures
struct	moqfetch_fetch
	FETCH (10.12.3 Figure 15). More...
struct	moqfetch_req
	Version-neutral FETCH request, an upper set of draft-19's Standalone + Joining split and draft-22's single Track Namespace/Name + LOCATION_FILTER parameter form. More...
struct	moqfetch_fill
	draft-22 SS9.20.15 FILL_PARAMETERS value (Number of Parameters + Parameters, the FETCH parameter scope), decoded into the fields a fill fetch stream needs: the range (LOCATION_FILTER, SS9.20.9 – type 0x00 or a zero-length value mean "no filter", ruling Q-02; an absent parameter in a non-empty value sets inherit, SS3.4), the Group Order (GROUP_ORDER 0x2 = Descending) and FILL_TIMEOUT as a varint of milliseconds. More...
struct	moqfetch_ok
	FETCH_OK (10.13 Figure 16). More...
struct	moqfetch_seq
	The "prior Object" state threaded through one fetch stream. More...
struct	moqfetch_obj
	One fetch Object or End of Range marker, with every field resolved to its absolute value. More...

Macros
#define	MOQFETCH_T_FETCH   0x16ULL
	Control message type of FETCH (19 10.12).
#define	MOQFETCH_T_FETCH_OK   0x18ULL
	Control message type of FETCH_OK (19 10.13).
#define	MOQFETCH_ERR_INVALID_JOINING_REQUEST_ID   MOQCTL_ERR_INVALID_JOINING_REQUEST_ID
	REQUEST_ERROR code for a Joining Fetch naming no subscription of the session (10.12.2; registry 15.11.2).
#define	MOQFETCH_STANDALONE   0x1ULL
	Fetch Type (10.12 Table 6); any other value is a VIOLATION.
#define	MOQFETCH_RELATIVE_JOINING   0x2ULL
	Joining Fetch whose Joining Start counts groups back from the joined subscription's Largest Group (10.12.2).
#define	MOQFETCH_ABSOLUTE_JOINING   0x3ULL
	Joining Fetch whose Joining Start is an absolute Group ID (10.12.2).
#define	MOQFETCH_OBJ_GROUP_END   (~0ULL)
	Inclusive End Object meaning "through the last Object of the group" – draft-19's End Location Object 0 (10.13) in the inclusive model.
#define	MOQFETCH_F_SUBGROUP_MASK   0x03ULL
	Serialization Flags (11.4.4.1 Tables 8/9, 11.4.4 Table 7).
#define	MOQFETCH_F_OBJECT   0x04ULL
	Object ID Delta present; absent means prior Object ID + 1.
#define	MOQFETCH_F_GROUP   0x08ULL
	Group ID Delta present; absent means the prior Object's group.
#define	MOQFETCH_F_PRIORITY   0x10ULL
	Publisher Priority present; absent means the prior Object's.
#define	MOQFETCH_F_PROPS   0x20ULL
	Object Properties (Length + KVPs) present.
#define	MOQFETCH_F_DATAGRAM   0x40ULL
	Datagram-preference Object: no Subgroup ID, subgroup bits ignored.
#define	MOQFETCH_EOR_NONEXISTENT   0x8CULL
	End of Non-Existent Range marker (11.4.4.2).
#define	MOQFETCH_EOR_UNKNOWN   0x10CULL
	End of Unknown Range marker (11.4.4.2).
#define	MOQFETCH_EOR_TIMED_OUT   0x20CULL
	draft-22 SS11.4.1 End of Timed-Out Range; accepted only when moqfetch_seq.eor_timed_out is set.

Functions
int	moqfetch_fetch_take (int ver, wired_span body, moqfetch_fetch *out)
	Decodes a FETCH body in draft ver's layout (standalone vs joining fields chosen by Fetch Type).
int	moqfetch_fetch_encode (wired_mspan buf, usz *off, const moqfetch_fetch *m)
	Encodes m as a FETCH body (no type/length framing) at *off.
int	moqfetch_req19_take (int ver, wired_span body, moqfetch_req *out)
	Decodes a draft-19 FETCH body (10.12) into the version-neutral model.
int	moqfetch_req19_encode (wired_mspan buf, usz *off, const moqfetch_req *m)
	Encodes m as a draft-19 FETCH body.
int	moqfetch_req22_take (wired_span body, moqfetch_req *out)
	Decodes a draft-22 FETCH body (SS "FETCH"): Request ID, Track Namespace, Track Name, then Parameters.
int	moqfetch_req22_encode (wired_mspan buf, usz *off, const moqfetch_req *m)
	Encodes m as a draft-22 FETCH body; range goes out as a LOCATION_FILTER parameter (SS9.20.9).
int	moqfetch_fill_take (wired_span value, moqfetch_fill *out)
	Decodes a FILL_PARAMETERS value (a zero-length one is "no parameters").
int	moqfetch_fill_put (wired_mspan buf, usz *off, const moqfetch_fill *f)
	Encodes f as a FILL_PARAMETERS value; a fill without a filter sends LOCATION_FILTER type 0x00 (SS9.20.9 None), never an empty list.
int	moqfetch_ok_take (int ver, wired_span body, moqfetch_ok *out)
	Decodes a FETCH_OK body in draft ver's layout.
int	moqfetch_ok_encode (wired_mspan buf, usz *off, const moqfetch_ok *m)
	Encodes m as a FETCH_OK body with m->end written as is (draft-22 inclusive form; moqfetch_ok19_encode for draft-19).
moqctl_loc	moqfetch_end19_incl (moqctl_loc wire)
	draft-19 End Location (last Object + 1, Object 0 = whole group) to the inclusive model and back (draft-22 SS9.12 is inclusive on the wire).
moqctl_loc	moqfetch_end19_wire (moqctl_loc incl)
	Inverse of moqfetch_end19_incl: inclusive end to the draft-19 wire End Location (MOQFETCH_OBJ_GROUP_END becomes Object 0).
moqctl_loc	moqfetch_req_end (const moqctl_rangeloc *r, moqctl_loc largest)
	The inclusive end of a FETCH range r, in the same model: a whole end group (MOQCTL_REK_GROUP) is Object MOQFETCH_OBJ_GROUP_END, an open end is largest (draft-22 SS9.20.9: an omitted FETCH end is Largest Object).
int	moqfetch_ok19_encode (wired_mspan buf, usz *off, const moqfetch_ok *m)
	FETCH_OK encode with m->end held inclusive, converted to the draft-19 wire form (moqfetch_end19_wire).
int	moqfetch_hdr_take (wired_span buf, usz *off, u64 *request_id)
	FETCH_HEADER (11.4.4 Figure 26): Type 0x5 then Request ID.
int	moqfetch_hdr_put (wired_mspan buf, usz *off, u64 request_id)
	Writes FETCH_HEADER (Type 0x5, Request ID) at *off.
int	moqfetch_obj_take (wired_span buf, usz *off, moqfetch_seq *seq, moqfetch_obj *out)
	Decodes one fetch Object / End of Range and advances *seq.
int	moqfetch_obj_put (wired_mspan buf, usz *off, moqfetch_seq *seq, const moqfetch_obj *o)
	Encodes o with the wire fields o->flags selects (deltas computed from *seq), then advances *seq exactly as moqfetch_obj_take would.
int	moqfetch_obj_take_head (wired_span buf, usz *off, moqfetch_seq *seq, moqfetch_obj *out)
	moqfetch_obj_take for an Object whose payload may not all be in buf yet: MOQCTL_OK once every field through the Payload Length is, with *off at the first payload byte and out->payload {that byte, the whole Payload Length} – only the bytes buf holds past *off are readable.
int	moqfetch_obj_put_head (wired_mspan buf, usz *off, moqfetch_seq *seq, const moqfetch_obj *o)
	moqfetch_obj_put without the payload bytes: the fields and a Payload Length of o->payload.n (o->payload.p is not read); the payload follows on the wire as is.

Detailed Description

draft-ietf-moq-transport-18/19/22 FETCH: the FETCH (19 10.12, 22 9.11) and FETCH_OK (19 10.13, 22 9.12) control messages, and the fetch data stream (19 11.4.4, 22 11.4): the FETCH_HEADER and the fetch Objects with their Serialization Flags, including the End of Range markers (19 11.4.4.2).

Takes with a ver argument decode that draft's layout.

Message takes decode one whole Message Body (the bytes moqctl_peek_type framed) and return MOQCTL_OK, MOQCTL_VIOLATION (malformed, or a Length mismatch – see moqctl_body_end) or MOQCTL_PARAMS_KVFMT. Stream takes return MOQCTL_OK / MOQCTL_INSUFFICIENT (need more stream bytes) / MOQCTL_VIOLATION and leave *off (and the sequence) unchanged unless OK. Encoders return 1 ok, 0 if buf is too small (*off may then have advanced).

Function Documentation

moqfetch_fetch_encode()

int moqfetch_fetch_encode	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_fetch *	m )

Encodes m as a FETCH body (no type/length framing) at *off.

Parameters

buf	output buffer
off	write offset, advanced past the body
m	message to encode

Returns

1 ok, 0 if buf is too small

moqfetch_fetch_take()

int moqfetch_fetch_take	(	int	ver,
		wired_span	body,
		moqfetch_fetch *	out )

Decodes a FETCH body in draft ver's layout (standalone vs joining fields chosen by Fetch Type).

Same return contract as the file note.

Parameters

ver	MOQVER_* id of the session
body	one whole Message Body
out	decoded message; views point into body

Returns

MOQCTL_OK, MOQCTL_VIOLATION or MOQCTL_PARAMS_KVFMT

moqfetch_fill_put()

int moqfetch_fill_put	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_fill *	f )

Encodes f as a FILL_PARAMETERS value; a fill without a filter sends LOCATION_FILTER type 0x00 (SS9.20.9 None), never an empty list.

Returns 1 ok, 0 if buf is too small (*off may then have advanced).

moqfetch_fill_take()

int moqfetch_fill_take	(	wired_span	value,
		moqfetch_fill *	out )

Decodes a FILL_PARAMETERS value (a zero-length one is "no parameters").

The Parameters must fill value exactly; same return contract as moqfetch_fetch_take.

moqfetch_hdr_put()

int moqfetch_hdr_put	(	wired_mspan	buf,
		usz *	off,
		u64	request_id )

Writes FETCH_HEADER (Type 0x5, Request ID) at *off.

Parameters

buf	output buffer
off	write offset, advanced past the header
request_id	Request ID of the FETCH this stream answers

Returns

1 ok, 0 if buf is too small

moqfetch_hdr_take()

int moqfetch_hdr_take	(	wired_span	buf,
		usz *	off,
		u64 *	request_id )

FETCH_HEADER (11.4.4 Figure 26): Type 0x5 then Request ID.

A Type other than 0x5 is a VIOLATION.

moqfetch_obj_put()

int moqfetch_obj_put	(	wired_mspan	buf,
		usz *	off,
		moqfetch_seq *	seq,
		const moqfetch_obj *	o )

Encodes o with the wire fields o->flags selects (deltas computed from *seq), then advances *seq exactly as moqfetch_obj_take would.

The flags must agree with seq (an omitted field must equal what the prior Object implies); 0 also for an invalid flags value.

moqfetch_obj_take()

int moqfetch_obj_take	(	wired_span	buf,
		usz *	off,
		moqfetch_seq *	seq,
		moqfetch_obj *	out )

Decodes one fetch Object / End of Range and advances *seq.

VIOLATION on: Serialization Flags >= 128 other than the two End of Range values, a first Object missing Group ID Delta or Object ID Delta, a flag referencing a prior Subgroup/Priority that does not exist, a Group or Object ID out of 0..2^64-1. An End of Range carries the absolute Group ID and Object ID only (11.4.4.2).

moqfetch_obj_take_head()

int moqfetch_obj_take_head	(	wired_span	buf,
		usz *	off,
		moqfetch_seq *	seq,
		moqfetch_obj *	out )

moqfetch_obj_take for an Object whose payload may not all be in buf yet: MOQCTL_OK once every field through the Payload Length is, with *off at the first payload byte and out->payload {that byte, the whole Payload Length} – only the bytes buf holds past *off are readable.

An End of Range decodes as with moqfetch_obj_take.

moqfetch_ok19_encode()

int moqfetch_ok19_encode	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_ok *	m )

FETCH_OK encode with m->end held inclusive, converted to the draft-19 wire form (moqfetch_end19_wire).

moqfetch_ok_encode is the draft-22 form (wire == model); a draft-19 decode applies moqfetch_end19_incl to moqfetch_ok_take's end.

moqfetch_ok_encode()

int moqfetch_ok_encode	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_ok *	m )

Encodes m as a FETCH_OK body with m->end written as is (draft-22 inclusive form; moqfetch_ok19_encode for draft-19).

Parameters

buf	output buffer
off	write offset, advanced past the body
m	message to encode

Returns

1 ok, 0 if buf is too small

moqfetch_ok_take()

int moqfetch_ok_take	(	int	ver,
		wired_span	body,
		moqfetch_ok *	out )

Decodes a FETCH_OK body in draft ver's layout.

Parameters

ver	MOQVER_* id of the session
body	one whole Message Body
out	decoded message; views point into body

Returns

MOQCTL_OK, MOQCTL_VIOLATION or MOQCTL_PARAMS_KVFMT

moqfetch_req19_encode()

int moqfetch_req19_encode	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_req *	m )

Encodes m as a draft-19 FETCH body.

Returns 0 (nothing written) for a Standalone range d19 cannot carry (ek UNBOUNDED or sk not ABS), else 0 only if buf is too small.

moqfetch_req19_take()

int moqfetch_req19_take	(	int	ver,
		wired_span	body,
		moqfetch_req *	out )

Decodes a draft-19 FETCH body (10.12) into the version-neutral model.

A Standalone Fetch's Start/End Location pair is normalized into range (End Location's "+1, Object 0 = whole group" quirk resolved here); a Joining Fetch leaves range zeroed. Same return contract as moqfetch_fetch_take.

moqfetch_req22_encode()

int moqfetch_req22_encode	(	wired_mspan	buf,
		usz *	off,
		const moqfetch_req *	m )

Encodes m as a draft-22 FETCH body; range goes out as a LOCATION_FILTER parameter (SS9.20.9).

Parameters

buf	output buffer
off	write offset, advanced past the body
m	request to encode (joining fields are not carried)

Returns

1 ok, 0 if buf is too small

moqfetch_req22_take()

int moqfetch_req22_take	(	wired_span	body,
		moqfetch_req *	out )

Decodes a draft-22 FETCH body (SS "FETCH"): Request ID, Track Namespace, Track Name, then Parameters.

is_joining is always 0. range is the LOCATION_FILTER parameter (0x21) if present, else "fetch everything" (sk=ABS, start_group=0, start_object=0, ek=UNBOUNDED) per SS9.20.9's "If omitted from FETCH ..., the fetch ... is unfiltered". Same return contract as moqfetch_fetch_take.