LIBDER_OBJ(3)

NAME
libder_obj, libder_obj_alloc, libder_obj_alloc_simple, libder_obj_free, libder_obj_append, libder_obj_child, libder_obj_next, libder_obj_type, libder_obj_type_simple, libder_obj_data, libder_obj_dump - inspecting and creating libder objects

LIBRARY
libder

SYNOPSIS
#include <libder.h>
struct libder_object *
libder_obj_alloc(struct libder_ctx *ctx, struct libder_tag *type, const uint8_t *data, size_t datasz);
struct libder_object *
libder_obj_alloc_simple(struct libder_ctx *ctx, uint8_t type, const uint8_t *data, size_t datasz);
void
libder_obj_free(struct libder_object *ctx);
bool
libder_obj_append(struct libder_object *parent, struct libder_object *child);
struct libder_object *
libder_obj_child(const struct libder_object *obj, size_t which);
struct libder_object *
libder_obj_next(const struct libder_object *obj);
DER_FOREACH_CHILD(struct libder_obj *iter, struct libder_obj *obj);
DER_FOREACH_CHILD_SAFE(struct libder_obj *iter, struct libder_obj *obj, struct libder_obj *tmp);
struct libder_tag *
libder_obj_type(const struct libder_object *obj);
uint8_t
libder_obj_type_simple(const struct libder_object *obj);
const uint8_t *
libder_obj_data(const struct libder_object *obj, size_t *sz);
void
libder_obj_dump(const struct libder_object *obj, FILE *fp);

DESCRIPTION
The libder_obj family of functions may be used by the application to create its own objects and object hierarchy, rather than reading them from an existing stream.

The libder_obj_alloc() and libder_obj_alloc_simple() functions allocate a new object with the specified type and data. Most applications will likely prefer to use the “simple” variant to avoid having to manage a libder_type(3) lifecycle and associated boilerplate. The base variant remains around for when libder_type(3) grows the necessary API to create arbitrarily large tags.

The libder_obj_append() function is used to append obj to the parent object's children. For example, to add an object to a sequence.

The libder_obj_child() and libder_obj_next() functions are used to iterate through the children of obj. The which argument to libder_obj_child() specifies the index of the child requested, starting at 0. The DER_FOREACH_CHILD() and DER_FOREACH_CHILD_SAFE() macros are provided for convenience. The difference between these two is that it is safe to free the iterator in the DER_FOREACH_CHILD_SAFE() loop body.

The libder_obj_type() and libder_obj_type_simple() functions are used to get the type information about an obj. As usual, the “simple” variant will return the one-byte encoding of a tag between 0 and 30. If the tag is actually larger than 30, then all of the lower 5 bits will be set to indicate that it's a long tag, and that the application should have used libder_obj_type() instead.

The libder_obj_data() function returns a pointer to the data from obj, and updates *sz with the data's size. Note that the data is not copied out here, the application is responsible for making its own copy of the returned buffer.

The libder_obj_dump() function is a debugging function that likely shouldn't be used. A human readable representation of the provided obj will be written to the stream fp.

SEE ALSO
libder(3), libder_read(3), libder_type(3), libder_write(3)