asdf/extension.h

struct asdf_software_t

Metadata describing a piece of software involved in producing an ASDF file

This corresponds to the core/software schema and is used to record any software that produced or contributed to a file – including libasdf itself, which records its own asdf_software_t in the file’s asdf_library metadata. It is most relevant to extension authors, who pass a pointer to one of these to ASDF_REGISTER_EXTENSION to document the software that implements their extension. See Extending libasdf with extension types.

const char *name

Name of the software

const asdf_version_t *version

Version of the software; see asdf_version_t

const char *author

Optional author of the software

const char *homepage

Optional homepage URL for the software

typedef struct asdf_value *(*asdf_extension_serialize_t)(asdf_file_t *file, const void *obj, const void *userdata)

Serialize a native object into an asdf_value_t

Param file:

The asdf_file_t* the value is created for

Param obj:

The native object to serialize

Param userdata:

The extension’s userdata

Return:

The new asdf_value_t*, or NULL on failure

typedef asdf_value_err_t (*asdf_extension_deserialize_t)(asdf_value_t *value, const void *userdata, void **out)

Deserialize an asdf_value_t into a native object

Param value:

The raw asdf_value_t* read from the file

Param userdata:

The extension’s userdata

Param out:

Set to the newly allocated native object on success

Return:

ASDF_VALUE_OK on success, otherwise an error code

typedef _Bool (*asdf_extension_copy_t)(asdf_file_t *file, const void *src, void *dst)

Deep-copy a native object into caller-provided storage

The generated asdf_<ext>_copy/asdf_<ext>_copy_into wrappers zero dst before this is called, and on failure they call the extension’s deinit method on dst to unwind any partial work. An implementation therefore only needs to populate dst and, on failure, return false (the sole assumed failure mode being out-of-memory).

Param file:

A handle to the file to which the object belongs

Param src:

The native object to copy

Param dst:

Pre-zeroed storage to copy src into

Return:

true on success, false on failure

typedef void (*asdf_extension_deinit_t)(void *obj)

De-initialize a native object produced by an asdf_extension_deserialize_t

This frees any resources owned by obj’s fields but must not free obj itself–its storage may be embedded, an array element, or static. Freeing the object’s own storage is done by the generated asdf_<ext>_destroy. It must be safe to call on a zero-initialized object and on a partially-initialized object left behind by a failed asdf_extension_copy_t.

Param obj:

The native object whose fields to de-initialize

typedef void (*asdf_extension_method_t)(void)

Generic method-pointer type for reserved asdf_extension_vtab_t slots

ASDF_EXTENSION_VTAB_MAX_METHODS

Total number of method slots in asdf_extension_vtab_t (used + reserved)

ASDF_EXTENSION_VTAB_METHODS

Number of currently-defined asdf_extension_vtab_t methods

Bump this when adding new methods to the vtab.

struct asdf_extension_vtab_t

Table of the methods implementing an extension’s behavior

Extension authors define one of these statically and pass a pointer to it to ASDF_REGISTER_EXTENSION.

asdf_extension_serialize_t serialize

Serializer for the extension type, or NULL if it cannot be written

asdf_extension_deserialize_t deserialize

Deserializer for the extension type

asdf_extension_copy_t copy

Deep-copy method, or NULL for a shallow copy

asdf_extension_deinit_t deinit

Method to de-initialize objects produced by deserialize

asdf_extension_method_t _reserved[ASDF_EXTENSION_VTAB_MAX_METHODS - ASDF_EXTENSION_VTAB_METHODS]

Reserved for future methods; keeps the ABI stable as methods are added

type asdf_extension_t

Struct representing a registered libasdf extension

void asdf_extension_register(asdf_extension_t *ext)

Register an extension with the library

This is normally called automatically by the constructor that ASDF_REGISTER_EXTENSION generates, and rarely needs to be called directly.

Parameters:
const asdf_extension_t *asdf_extension_get(asdf_file_t *file, const char *tag)

Look up a registered extension by its tag

Parameters:

  • file – The asdf_file_t* for the file

  • tag – The tag string the extension was registered under

Returns:

The matching asdf_extension_t*, or NULL if no extension is registered for tag

asdf_tag_t *asdf_tag_parse(const char *tag)

Parse a tag string of the form "name" or "name-version" into an asdf_tag_t

Parameters:

  • tag – The tag string to parse

Returns:

A newly allocated asdf_tag_t * owned by the caller (free it with asdf_tag_destroy), or NULL on failure

void asdf_tag_destroy(asdf_tag_t *tag)

Free a tag returned by asdf_tag_parse

Parameters:

  • tag – The asdf_tag_t * to free

ASDF_REGISTER_EXTENSION(extname, type, software, vtab, userdata, ...)

Define and register an extension type

Generates the full family of public accessors for an extension type and a constructor that registers the extension with libasdf automatically at load time. Place it in a single .c file; use ASDF_DECLARE_EXTENSION in a header to expose the generated functions to other translation units. See Extending libasdf with extension types for a complete walkthrough.

The generated functions are named after extname: asdf_get_<extname>, asdf_set_<extname>, asdf_is_<extname>, asdf_value_is_<extname>, asdf_value_as_<extname>, asdf_value_of_<extname>, asdf_<extname>_copy, asdf_<extname>_copy_into, asdf_<extname>_array_copy, asdf_<extname>_deinit, and asdf_<extname>_destroy.

One or more YAML tags are passed as trailing arguments; the extension is registered for each of them, so a single extension can handle several versions of the same schema. At least one tag is required. When an object of this type is serialized it is written with the first tag listed, so put the preferred tag first. Values read from a file and left unmodified keep the tag they were read with.

Parameters:

  • extname – Base name for the generated functions (need not match the C type)

  • type – The C type the extension deserializes to (e.g. asdf_foo_t)

  • software – Pointer to an asdf_software_t describing the software that implements the extension

  • vtab – Pointer to an asdf_extension_vtab_t holding the extension’s callbacks

  • userdata – Optional void * passed through to the callbacks, or NULL

  • ... – One or more YAML tag strings the extension is registered for

ASDF_DECLARE_EXTENSION(extname, type)

Declare the public API generated by ASDF_REGISTER_EXTENSION

Place this in a header to expose an extension’s generated functions (the asdf_get_<extname>/asdf_set_<extname>/etc. family listed under ASDF_REGISTER_EXTENSION) to other translation units. extname and type must match those passed to ASDF_REGISTER_EXTENSION.

Parameters:

  • extname – Base name used for the generated functions

  • type – The C type the extension deserializes to