Package Builders

Functions
DetlefStatus	detlef_package_function_callback (DetlefAccess *a, DetlefHandle handle, size_t index, DetlefFunctionCallback *callback_out, void **data_out)
DetlefStatus	detlef_package_control_callback (DetlefAccess *a, DetlefHandle handle, size_t index, DetlefCallback *callback_out, void **data_out)
DetlefStatus	detlef_type_ref_resolve (DetlefAccess *a, DetlefHandle handle, DetlefHandle *out)
DetlefStatus	detlef_type_ref_named (DetlefAccess *a, DetlefSlice input, DetlefHandle *out)
DetlefStatus	detlef_type_ref_array (DetlefAccess *a, DetlefHandle inner, DetlefHandle *out)
DetlefStatus	detlef_type_ref_optional (DetlefAccess *a, DetlefHandle inner, DetlefHandle *out)
DetlefStatus	detlef_type_ref_info (DetlefAccess *a, DetlefHandle handle, DetlefTypeRefKind *kind, DetlefText *name_out, DetlefHandle *inner)
DetlefStatus	detlef_package_new (DetlefAccess *a, DetlefSlice input, DetlefHandle *out)
DetlefStatus	detlef_package_name (DetlefAccess *a, DetlefHandle handle, DetlefText *out)
DetlefStatus	detlef_package_binding (DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle binding)
DetlefStatus	detlef_package_record (DetlefAccess *a, DetlefHandle handle, DetlefSlice input, const DetlefNamed *fields, size_t count)
DetlefStatus	detlef_package_function (DetlefAccess *a, DetlefHandle handle, DetlefSlice input, const DetlefNamed *params, size_t count, const DetlefNamed *vararg, DetlefFunctionCallback callback, void *data)
DetlefStatus	detlef_package_control (DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefCallback callback, void *data)
DetlefStatus	detlef_package_install (DetlefAccess *a, DetlefHandle handle)
DetlefStatus	detlef_package_count (DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t *out)
DetlefStatus	detlef_package_entry_name (DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, DetlefText *out)
DetlefStatus	detlef_package_binding_get (DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out)
DetlefStatus	detlef_package_member_count (DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, size_t *out, DetlefBool *has_vararg)
DetlefStatus	detlef_package_member (DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, size_t member, DetlefText *name_out, DetlefHandle *type_out)

Detailed Description

Function Documentation

detlef_package_binding()

DetlefStatus detlef_package_binding	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSlice	input,
		DetlefHandle	binding
	)

Add a named value binding to a package builder. The builder retains the value; the supplied handle remains owned by its caller.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Borrowed package builder handle to modify. Not consumed.
input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
binding	Borrowed runtime value handle to bind. Not consumed.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_binding_get()

DetlefStatus detlef_package_binding_get	(	DetlefAccess *	a,
		DetlefHandle	handle,
		size_t	index,
		DetlefHandle *	out
	)

Obtain a separately owned handle to a binding stored in a package builder.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	index	Zero-based binding index.
[out]	out	On success, receives an owned runtime value handle for the selected binding. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_control()

DetlefStatus detlef_package_control	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSlice	input,
		DetlefCallback	callback,
		void *	data
	)

Add a lazy Control to a package builder. Callback code and data must outlive installed registrations.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Borrowed package builder handle to modify. Not consumed.
input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
callback	Synchronous callback. Its code and associated data must remain valid while registered; DETLEF does not free them.
data	Host-owned callback data. Must remain valid while its callback can run; DETLEF never frees it.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_control_callback()

DetlefStatus detlef_package_control_callback	(	DetlefAccess *	a,
		DetlefHandle	handle,
		size_t	index,
		DetlefCallback *	callback_out,
		void **	data_out
	)

Inspect a Control callback and its data pointer in a package builder. Neither pointer is owned by the caller.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	index	Zero-based index in the builder's Control callback registrations.
[out]	callback_out	Receives a borrowed callback pointer or data pointer. Must not be freed by this operation's caller.
[out]	data_out	Receives a borrowed callback pointer or data pointer. Must not be freed by this operation's caller.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_count()

DetlefStatus detlef_package_count	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefPackageSection	kind,
		size_t *	out
	)

Read the number of package entries in the section selected by DETLEF_PACKAGE_*.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	kind	Package section to inspect; use DetlefPackageSection constants.
[out]	out	Receives the number of entries in the selected section.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_entry_name()

DetlefStatus detlef_package_entry_name	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefPackageSection	kind,
		size_t	index,
		DetlefText *	out
	)

Copy a package entry name by section and zero-based index.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	kind	Package section to inspect; use DetlefPackageSection constants.
	index	Zero-based entry index in the selected section.
[out]	out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_function()

DetlefStatus detlef_package_function	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSlice	input,
		const DetlefNamed *	params,
		size_t	count,
		const DetlefNamed *	vararg,
		DetlefFunctionCallback	callback,
		void *	data
	)

Add an eager native Function to a package builder. Parameter types must be TypeRefs; callback code and data remain host-owned.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Borrowed package builder handle to modify. Not consumed.
input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
params	Borrowed parameter names paired with unresolved TypeRef handles. Names and type specifications are copied; handles are not consumed.
count	Number of entries in the supplied array.
vararg	Optional borrowed variadic parameter with an unresolved element TypeRef handle; NULL means no variadic parameter.
callback	Synchronous callback. Its code and associated data must remain valid while registered; DETLEF does not free them.
data	Host-owned callback data. Must remain valid while its callback can run; DETLEF never frees it.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_function_callback()

DetlefStatus detlef_package_function_callback	(	DetlefAccess *	a,
		DetlefHandle	handle,
		size_t	index,
		DetlefFunctionCallback *	callback_out,
		void **	data_out
	)

Inspect a native Function callback and its data pointer in a package builder. Neither pointer is owned by the caller.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	index	Zero-based index in the builder's Function callback registrations.
[out]	callback_out	Receives a borrowed callback pointer or data pointer. Must not be freed by this operation's caller.
[out]	data_out	Receives a borrowed callback pointer or data pointer. Must not be freed by this operation's caller.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_install()

DetlefStatus detlef_package_install	(	DetlefAccess *	a,
		DetlefHandle	handle
	)

Install package records, bindings, Functions, then Controls. Installation does not consume the builder and does not roll back earlier successful registrations on failure.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Borrowed package builder handle to install. Not consumed.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_member()

DetlefStatus detlef_package_member	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefPackageSection	kind,
		size_t	index,
		size_t	member,
		DetlefText *	name_out,
		DetlefHandle *	type_out
	)

Inspect a package field or parameter. For Functions, member equal to the fixed parameter count selects the variadic parameter.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	kind	DETLEF_PACKAGE_RECORDS or DETLEF_PACKAGE_FUNCTIONS. Other sections have no members.
	index	Zero-based record or Function index in the selected section.
	member	Zero-based field or parameter index; a Function's fixed parameter count selects its variadic parameter.
[out]	name_out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().
[out]	type_out	On success, receives an owned unresolved TypeRef handle for the field or parameter. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_member_count()

DetlefStatus detlef_package_member_count	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefPackageSection	kind,
		size_t	index,
		size_t *	out,
		DetlefBool *	has_vararg
	)

Inspect the field or parameter count of a package record or Function. The has_vararg flag indicates whether the Function has a variadic parameter.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
	kind	DETLEF_PACKAGE_RECORDS or DETLEF_PACKAGE_FUNCTIONS. Other sections have no members.
	index	Zero-based record or Function index in the selected section.
[out]	out	Receives the number of fields or fixed parameters; a variadic parameter is counted separately by has_vararg.
[out]	has_vararg	Receives zero or one as described above. No cleanup is required.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_name()

DetlefStatus detlef_package_name	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefText *	out
	)

Copy a package builder's name without consuming it.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed package builder handle. Not consumed.
[out]	out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_new()

DetlefStatus detlef_package_new	(	DetlefAccess *	a,
		DetlefSlice	input,
		DetlefHandle *	out
	)

Create an in-memory package builder with a name. The builder must be released after installation or inspection.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
[out]	out	On success, receives an owned package builder handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_package_record()

DetlefStatus detlef_package_record	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSlice	input,
		const DetlefNamed *	fields,
		size_t	count
	)

Add a record definition to a package builder. Field types must be TypeRef handles, not resolved type descriptors.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Borrowed package builder handle to modify. Not consumed.
input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
fields	Borrowed field names paired with unresolved TypeRef handles. Names and type specifications are copied; handles are not consumed.
count	Number of entries in the supplied array.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_type_ref_array()

DetlefStatus detlef_type_ref_array	(	DetlefAccess *	a,
		DetlefHandle	inner,
		DetlefHandle *	out
	)

Create an array TypeRef from a borrowed inner TypeRef.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	inner	Borrowed unresolved element TypeRef handle. Not consumed.
[out]	out	On success, receives an owned unresolved array TypeRef handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_type_ref_info()

DetlefStatus detlef_type_ref_info	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefTypeRefKind *	kind,
		DetlefText *	name_out,
		DetlefHandle *	inner
	)

Inspect a TypeRef. Named references return their name; array and optional references return an inner TypeRef handle.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed unresolved TypeRef handle. Not consumed.
[out]	kind	Receives the reference's DetlefTypeRefKind constant.
[out]	name_out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().
[out]	inner	On success, receives an owned inner TypeRef handle, or zero for a named reference. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_type_ref_named()

DetlefStatus detlef_type_ref_named	(	DetlefAccess *	a,
		DetlefSlice	input,
		DetlefHandle *	out
	)

Create an unresolved reference to a named type. Package installation resolves it after record registration.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
[out]	out	On success, receives an owned unresolved named TypeRef handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_type_ref_optional()

DetlefStatus detlef_type_ref_optional	(	DetlefAccess *	a,
		DetlefHandle	inner,
		DetlefHandle *	out
	)

Create an optional TypeRef from a borrowed inner TypeRef.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	inner	Borrowed unresolved inner TypeRef handle. Not consumed.
[out]	out	On success, receives an owned unresolved optional TypeRef handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_type_ref_resolve()

DetlefStatus detlef_type_ref_resolve	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefHandle *	out
	)

Resolve a named, array, or optional TypeRef into a resolved type descriptor.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed unresolved TypeRef handle. Not consumed.
[out]	out	On success, receives an owned resolved type descriptor. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.