From 62481d1cd30c78b90747370b620b26f0dd8ebae8 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 16 Mar 2012 16:29:16 +0000 Subject: Improve documentation. Use char* for strings. --- lv2/lv2plug.in/ns/ext/atom/forge.h | 166 ++++++++++++++++++++++--------------- 1 file changed, 99 insertions(+), 67 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext/atom') diff --git a/lv2/lv2plug.in/ns/ext/atom/forge.h b/lv2/lv2plug.in/ns/ext/atom/forge.h index 981d2b4..a19c131 100644 --- a/lv2/lv2plug.in/ns/ext/atom/forge.h +++ b/lv2/lv2plug.in/ns/ext/atom/forge.h @@ -61,12 +61,15 @@ typedef void* LV2_Atom_Forge_Sink_Handle; typedef intptr_t LV2_Atom_Forge_Ref; /** Sink function for writing output. See lv2_atom_forge_set_sink(). */ -typedef LV2_Atom_Forge_Ref (*LV2_Atom_Forge_Sink)( - LV2_Atom_Forge_Sink_Handle handle, const void* buf, uint32_t size); +typedef LV2_Atom_Forge_Ref +(*LV2_Atom_Forge_Sink)(LV2_Atom_Forge_Sink_Handle handle, + const void* buf, + uint32_t size); /** Function for resolving a reference. See lv2_atom_forge_set_sink(). */ -typedef LV2_Atom* (*LV2_Atom_Forge_Deref_Func)( - LV2_Atom_Forge_Sink_Handle handle, LV2_Atom_Forge_Ref ref); +typedef LV2_Atom* +(*LV2_Atom_Forge_Deref_Func)(LV2_Atom_Forge_Sink_Handle handle, + LV2_Atom_Forge_Ref ref); /** A stack frame used for keeping track of nested Atom containers. */ typedef struct _LV2_Atom_Forge_Frame { @@ -104,6 +107,53 @@ typedef struct { LV2_URID Vector; } LV2_Atom_Forge; +static inline void +lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size); + +/** + Initialise @p forge. + + URIs will be mapped using @p map and stored, a reference to @p map itself is + not held. +*/ +static inline void +lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map) +{ + lv2_atom_forge_set_buffer(forge, NULL, 0); + forge->stack = NULL; + forge->Blank = map->map(map->handle, LV2_ATOM__Blank); + forge->Bool = map->map(map->handle, LV2_ATOM__Bool); + forge->Double = map->map(map->handle, LV2_ATOM__Double); + forge->Float = map->map(map->handle, LV2_ATOM__Float); + forge->Int32 = map->map(map->handle, LV2_ATOM__Int32); + forge->Int64 = map->map(map->handle, LV2_ATOM__Int64); + forge->Literal = map->map(map->handle, LV2_ATOM__Literal); + forge->Path = map->map(map->handle, LV2_ATOM__Path); + forge->Property = map->map(map->handle, LV2_ATOM__Property); + forge->Resource = map->map(map->handle, LV2_ATOM__Resource); + forge->Sequence = map->map(map->handle, LV2_ATOM__Sequence); + forge->String = map->map(map->handle, LV2_ATOM__String); + forge->Tuple = map->map(map->handle, LV2_ATOM__Tuple); + forge->URI = map->map(map->handle, LV2_ATOM__URI); + forge->URID = map->map(map->handle, LV2_ATOM__URID); + forge->Vector = map->map(map->handle, LV2_ATOM__Vector); +} + +static inline LV2_Atom* +lv2_atom_forge_deref(LV2_Atom_Forge* forge, LV2_Atom_Forge_Ref ref) +{ + if (forge->buf) { + return (LV2_Atom*)ref; + } else { + return forge->deref(forge->handle, ref); + } +} + +/** + @name Object Stack + @{ +*/ + /** Push a stack frame. This is done automatically by container functions (which take a stack frame @@ -129,6 +179,20 @@ lv2_atom_forge_pop(LV2_Atom_Forge* forge, LV2_Atom_Forge_Frame* frame) forge->stack = frame->parent; } +/** Return true iff the top of the stack has the given type. */ +static inline bool +lv2_atom_forge_top_is(LV2_Atom_Forge* forge, uint32_t type) +{ + return forge->stack && + lv2_atom_forge_deref(forge, forge->stack->ref)->type == type; +} + +/** + @} + @name Output Configuration + @{ +*/ + /** Set the output buffer where @p forge will write atoms. */ static inline void lv2_atom_forge_set_buffer(LV2_Atom_Forge* forge, uint8_t* buf, size_t size) @@ -171,43 +235,10 @@ lv2_atom_forge_set_sink(LV2_Atom_Forge* forge, } /** - Initialise @p forge. - - URIs will be mapped using @p map and stored, a reference to @p map itself is - not held. + @} + @name Low Level Output + @{ */ -static inline void -lv2_atom_forge_init(LV2_Atom_Forge* forge, LV2_URID_Map* map) -{ - lv2_atom_forge_set_buffer(forge, NULL, 0); - forge->stack = NULL; - forge->Blank = map->map(map->handle, LV2_ATOM__Blank); - forge->Bool = map->map(map->handle, LV2_ATOM__Bool); - forge->Double = map->map(map->handle, LV2_ATOM__Double); - forge->Float = map->map(map->handle, LV2_ATOM__Float); - forge->Int32 = map->map(map->handle, LV2_ATOM__Int32); - forge->Int64 = map->map(map->handle, LV2_ATOM__Int64); - forge->Literal = map->map(map->handle, LV2_ATOM__Literal); - forge->Path = map->map(map->handle, LV2_ATOM__Path); - forge->Property = map->map(map->handle, LV2_ATOM__Property); - forge->Resource = map->map(map->handle, LV2_ATOM__Resource); - forge->Sequence = map->map(map->handle, LV2_ATOM__Sequence); - forge->String = map->map(map->handle, LV2_ATOM__String); - forge->Tuple = map->map(map->handle, LV2_ATOM__Tuple); - forge->URI = map->map(map->handle, LV2_ATOM__URI); - forge->URID = map->map(map->handle, LV2_ATOM__URID); - forge->Vector = map->map(map->handle, LV2_ATOM__Vector); -} - -static inline LV2_Atom* -lv2_atom_forge_deref(LV2_Atom_Forge* forge, LV2_Atom_Forge_Ref ref) -{ - if (forge->buf) { - return (LV2_Atom*)ref; - } else { - return forge->deref(forge->handle, ref); - } -} /** Write raw output. This is used internally, but is also useful for writing @@ -255,6 +286,25 @@ lv2_atom_forge_write(LV2_Atom_Forge* forge, const void* data, uint32_t size) return out; } +/** Write a null-terminated string body. */ +static inline LV2_Atom_Forge_Ref +lv2_atom_forge_string_body(LV2_Atom_Forge* forge, + const char* str, + uint32_t len) +{ + LV2_Atom_Forge_Ref out = lv2_atom_forge_raw(forge, str, len); + if (out && (out = lv2_atom_forge_raw(forge, "", 1))) { + lv2_atom_forge_pad(forge, len + 1); + } + return out; +} + +/** + @} + @name Atom Output + @{ +*/ + /** Write an atom:Atom header. */ static inline LV2_Atom_Forge_Ref lv2_atom_forge_atom(LV2_Atom_Forge* forge, uint32_t size, uint32_t type) @@ -263,14 +313,6 @@ lv2_atom_forge_atom(LV2_Atom_Forge* forge, uint32_t size, uint32_t type) return lv2_atom_forge_raw(forge, &a, sizeof(a)); } -/** Return true iff the top of the stack has the given type. */ -static inline bool -lv2_atom_forge_top_is(LV2_Atom_Forge* forge, uint32_t type) -{ - return forge->stack && - lv2_atom_forge_deref(forge, forge->stack->ref)->type == type; -} - /** Write a primitive (fixed-size) atom. */ static inline LV2_Atom_Forge_Ref lv2_atom_forge_primitive(LV2_Atom_Forge* forge, const LV2_Atom* a) @@ -330,25 +372,11 @@ lv2_atom_forge_urid(LV2_Atom_Forge* forge, LV2_URID id) return lv2_atom_forge_primitive(forge, &a.atom); } -/** Write a string body. Used internally. */ -static inline LV2_Atom_Forge_Ref -lv2_atom_forge_string_body(LV2_Atom_Forge* forge, - const uint8_t* str, - uint32_t len) -{ - LV2_Atom_Forge_Ref out = 0; - if ( (out = lv2_atom_forge_raw(forge, str, len)) - && (out = lv2_atom_forge_raw(forge, "", 1))) { - lv2_atom_forge_pad(forge, len + 1); - } - return out; -} - /** Write an atom compatible with atom:String. Used internally. */ static inline LV2_Atom_Forge_Ref lv2_atom_forge_typed_string(LV2_Atom_Forge* forge, uint32_t type, - const uint8_t* str, + const char* str, uint32_t len) { const LV2_Atom_String a = { { len + 1, type } }; @@ -365,7 +393,7 @@ lv2_atom_forge_typed_string(LV2_Atom_Forge* forge, /** Write an atom:String. Note that @p str need not be NULL terminated. */ static inline LV2_Atom_Forge_Ref -lv2_atom_forge_string(LV2_Atom_Forge* forge, const uint8_t* str, uint32_t len) +lv2_atom_forge_string(LV2_Atom_Forge* forge, const char* str, uint32_t len) { return lv2_atom_forge_typed_string(forge, forge->String, str, len); } @@ -376,14 +404,14 @@ lv2_atom_forge_string(LV2_Atom_Forge* forge, const uint8_t* str, uint32_t len) a mapped URI, use lv2_atom_forge_urid(). */ static inline LV2_Atom_Forge_Ref -lv2_atom_forge_uri(LV2_Atom_Forge* forge, const uint8_t* uri, uint32_t len) +lv2_atom_forge_uri(LV2_Atom_Forge* forge, const char* uri, uint32_t len) { return lv2_atom_forge_typed_string(forge, forge->URI, uri, len); } /** Write an atom:Path. Note that @p path need not be NULL terminated. */ static inline LV2_Atom_Forge_Ref -lv2_atom_forge_path(LV2_Atom_Forge* forge, const uint8_t* path, uint32_t len) +lv2_atom_forge_path(LV2_Atom_Forge* forge, const char* path, uint32_t len) { return lv2_atom_forge_typed_string(forge, forge->Path, path, len); } @@ -391,7 +419,7 @@ lv2_atom_forge_path(LV2_Atom_Forge* forge, const uint8_t* path, uint32_t len) /** Write an atom:Literal. */ static inline LV2_Atom_Forge_Ref lv2_atom_forge_literal(LV2_Atom_Forge* forge, - const uint8_t* str, + const char* str, uint32_t len, uint32_t datatype, uint32_t lang) @@ -580,6 +608,10 @@ lv2_atom_forge_beat_time(LV2_Atom_Forge* forge, double beats) return lv2_atom_forge_write(forge, &beats, sizeof(beats)); } +/** + @} +*/ + #ifdef __cplusplus } /* extern "C" */ #endif -- cgit v1.2.1