c11n: Check-in [bbd03114b6]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

SHA1 Hash:	bbd03114b6024cf876b8492839c9b7b97d5b1c04
Date:	2008-11-14 18:02:53
User:	stephan
Comment:	minor doc re-orgs

Changes

hide diffs unified diffs patch

Changes to include/s11n.net/c11n/c11n.h

--- Old (7799fac2c567514e)
+++ New (da50eb6636dbb0a4)
 #ifndef S11N_NET_C11N_H_INCLUDED
 #define S11N_NET_C11N_H_INCLUDED 1
 /** @page c11n_page_main c11n: generic serialization library for C
        c11n_marshaller_api.
        implData can be used to store private data required by the
        implementation functions. Note that because the "self" argument
        of all of the members is const, the implData object is
-       necessarily also const.
+       also const.
        The reason for this member is because C99's "strict aliasing"
        rules won't let us legally treat a (c11n_marshaller*) as-a
        (c11n_marshaller_some_subclass*) - even if we know that they're
        the same object (at the same address), C99 explicitly specifies
        "c11n_marshaller_pod_api".
     */
     void const * implData;
 };
 typedef struct c11n_marshaller_api c11n_marshaller_api;
@@ > / 1159 @@
+/**
+   c11n_marshaller_api_init is an empty c11n_marshaller_api
+   object which has non-null, but useless, member functions.
+*/
 extern const c11n_marshaller_api c11n_marshaller_api_init;
 /**
    C11N_MARSHALLER_API_INIT is used to initialize a shared/static
    c11n_marshaller_api object. The parameters are:
 CLEAR,					\
 DTOR,					\
 ISA,\
 DATA\
+}
+/**
+   C11N_MARSHALLER_API_INIT is a variant of C11N_MARSHALLER_API_INIT_FULL,
+   minus the ISA and DATA parameters of the latter macro.
+*/
 #define C11N_MARSHALLER_API_INIT(N,SER,DES,CREATE,CLEAR,DTOR) \
     C11N_MARSHALLER_API_INIT_FULL(N,SER,DES,CREATE,CLEAR,DTOR,c11n_marshaller_api_is_a,0)
 /**
    @struct c11n_marshaller
    exact algorithms used for de/serializing a certain type, and a
    different marshaller object is required for each type we want to
    make Cerializable.
    Support for de/serializing new types involves implementing a
-   c11n_marshaller instance or creating a custom struct which has a
+   c11n_marshaller instance which has a
-   c11n_marshaller_api object (named api) as its first member. One
+   const c11n_marshaller_api pointer (named api) as its first member. One
    should then create a shared object instance of that type, which
    client code can pass to c11n_serialize() and c11n_deserialize().
    One way to create such an instance is:
    Add the following to your public API (or some scope where all
    of your client code can see it):
 @code
-   extern const c11n_marshaller myMarshaller;
+   extern const c11n_marshaller MyType_c11n;
 @endcode
    Then initialize that object somewhere in your private implementation:
 @code
-   static const c11n_marshaller_api myMarshaller_api =
+   static const c11n_marshaller_api MyType_c11n_api =
    C11N_MARSHALLER_API_INIT(
    "MyType",
    MyType_serialize,
    MyType_deserialize,
    MyType_create,
+   MyType_clear,
    MyType_destroy);
-   static const c11n_marshaller myMarshaller = {
+   static const c11n_marshaller MyType_c11n = {&MyType_c11n_api};
@@ 1231 / &myMarshaller_api / | @@
@@ 1232 / ... custom members go here ... / | @@
@@ 1233 / }; / | @@
 @endcode
     It is also possible to create extended marshaller types, for those
-    which need access to some other metadata. The only hard
+    which need access to some other metadata. This is primarily useful
-    requirement is that the custom marshaller type have, as their very
+    when de/serialization algorithms need to share some static
-    first member, a c11n_marshaller_api object named api. For example:
+    information, e.g. a version number, a sscanf()/printf() conversion
     specifier, or some such. For examples of this see c11n.c and
-    @code
+    search for "c11n_marshaller_pod_api_".
@@ 1242 / struct myExtendedMarshaller { / | @@
@@ 1243 / c11n_marshaller_api const * api; / | @@
@@ 1244 / int version; / | @@
@@ 1245 / ... whatever ... / | @@
@@ 1246 / }; / | @@
@@ 1247 / @endcode / | @@
@@ 1248 / | @@
@@ 1249 / and then initialize it as above, but adding values for your own / | @@
@@ 1250 / entries. / | @@
@@ 1251 / | @@
@@ 1252 / Inside the myExtendedMarshaller->api functions we can cast the / | @@
@@ 1253 / (c11n_marshaller*) to a (myExtendedMarshaller*) to get at the / | @@
@@ 1254 / extended members. This is primarily useful when de/serialization / | @@
@@ 1255 / algorithms need to share some static information, e.g. a version / | @@
@@ 1256 / number, a sscanf()/printf() conversion specifier, or some such. / | @@
 */
 typedef struct c11n_marshaller {
     /**
        Common marshaller data used by the core library. For custom
        marshaller the first member MUST be a const pointer
     /* any custom members of similar structs must go after this point. */
 } c11n_marshaller;
 /**
-   A default is_a() implementation for c11n_marshaller classes.  It
+   A default c11n_marshaller_api::is_a() implementation for
-   returns the result of c11n_compare_str(self->api->classname,classname), or false if either
+   c11n_marshaller classes.  It returns the result of
-   self is 0.
+   c11n_compare_str(self->api->classname,classname), or false if
@@ | / 1267 / either self or classname is 0. @@
  */
 bool c11n_marshaller_api_is_a( c11n_marshaller const * self, c11n_const_string_t classname );
 /**
-   A default clear() implementation for c11n_marshaller classes. It
+   A default c11n_marshaller_api::clear() implementation for c11n_marshaller classes. It
    does nothing.
 */
 void c11n_marshaller_api_clear( c11n_marshaller const * self, void * v );
 /**
-   A default destroy() implementation for c11n_marshaller classes. It
+   A default c11n_marshaller_api::destroy() implementation for c11n_marshaller classes. It
    calls self->api->clear(self,v) then calls free(v).
 */
 void c11n_marshaller_api_destroy( c11n_marshaller const * self, void * v );
 /**
-   A placeholder serialize() implementation for c11n_marshaller
+   A placeholder c11n_marshaller_api::serialize() implementation for c11n_marshaller
    classes. It does nothing and returns false.
 */
 bool c11n_marshaller_api_serialize( c11n_marshaller const * self,
 				    c11n_node * dest,
 				    void const * src );
 /**
-   A placeholder deserialize() implementation for c11n_marshaller
+   A placeholder c11n_marshaller_api::deserialize() implementation for c11n_marshaller
    classes. It does nothing and returns false.
 */
 bool c11n_marshaller_api_deserialize( c11n_marshaller const * self,
 				      c11n_node const * src,
 				      void * dest );
-/**
-   A marshaller instance for de/serializing objects of type int. Note,
-   however, that it is always much more efficient to store ints as
-   node properties, as opposed to as full-fledged (traited)
-   Cerializables.
@@ 1310 / < @@
-   Sample usage:
@@ 1312 / < @@
-   @code
-   // Serialize:
-   int const src = 42;
-   c11n_serialize( destNode, c11n_marshaller_pod_int, &src );
@@ 1317 / < @@
-   // Deserialize:
-   int dest = 0;
-   c11n_deserialize( srcNode, c11n_marshaller_pod_int, &dest );
-   @endcode
@@ 1322 / < @@
-   But the saner thing to do in most cases is to store simple
-   PODs as properties of some parent c11n_node:
@@ 1325 / < @@
-   @code
-   int const src = 42;
-   c11n_node_prop_set_fe( destNode, "myInt", "%d", src );
-   @endcode
@@ 1330 / < @@
-   as that has creates much less output when saved.
-*/
-extern const c11n_marshaller * c11n_marshaller_pod_int;
@@ 1334 / < @@
-/**
-   A marshaller instance for de/serializing objects of type unsigned int.
-   See c11n_marshaller_pod_int for more details and sample usage.
-*/
-extern const c11n_marshaller * c11n_marshaller_pod_uint;
@@ 1340 / < @@
-/**
-   A marshaller instance for de/serializing objects of type long.
-   See c11n_marshaller_pod_int for more details and sample usage.
-*/
-extern const c11n_marshaller * c11n_marshaller_pod_long;
@@ 1346 / < @@
-/**
-   A marshaller instance for de/serializing objects of type unsigned long.
-   See c11n_marshaller_pod_int for more details and sample usage.
-*/
-extern const c11n_marshaller * c11n_marshaller_pod_ulong;
@@ 1352 / < @@
-/**
-   A marshaller instance for de/serializing objects of type double.
-   See c11n_marshaller_pod_int for more details and sample usage.
-*/
-extern const c11n_marshaller * c11n_marshaller_pod_double;
@@ 1358 / < @@
-/**
-   DON'T USE! It can't work safely for some common cases.
@@ 1361 / < @@
-   A marshaller instance for de/serializing objects of type double.
-   The string value deserialized by api->deserialize()
-   will not be a copy, but will be a pointer to the data stored
-   within the c11n_node we are deserializing from. Thus if
-   you need to keep the string around longer than the corresponding
-   c11n_node, copy it.
@@ 1368 / < @@
-   Example usage:
-   @code
-   // Serialize:
-   c11n_const_string_t src = "This is a string.";
-   c11n_serialize( destNode, c11n_marshaller_pod_string, src );
@@ 1374 / < @@
-   // Deserialize:
-   c11n_const_string_t dest = 0;
-   if( c11n_deserialize( srcNode, c11n_marshaller_pod_string, &dest ) )
-   { // note the POINTER to dest here -->-->-->-->-->-->-->-^^^^^
-       // Now dest points to a copy of the deserialized string value
-       // of srcNode. Copy it here if you need it after srcNode goes
-       // out of your scope.
-   }
-   @endcode
@@ 1384 / < @@
-   BUG WARNING: this marshaller instance cannot work with
-   c11n_deserialize_new() because this object requires that
-   deserialization take a pointer to a pointer, which
-   c11n_deserialize_new() cannot generically handle. It also
-   cannot work with c11n_load_serializable() because it cannot
-   know how big of a string to allocate (and then cannot generically
-   handle the pointer-to-pointer part).
-*/
-//extern const c11n_marshaller * c11n_marshaller_pod_string;
@@ 1394 / < @@
-#if 0
-struct c11n_s_proxy_cstring
-{
-    c11n_marshaller_api api;
-    char * string;
-};
-typedef struct c11n_s_proxy_cstring c11n_s_proxy_cstring;
-extern const c11n_s_proxy_cstring c11n_s_proxy_cstring_init;
-#define C11N_S_PROXY_CSTRING_INIT(Name,CString) \
-    c11n_s_proxy_cstring Name = c11n_s_proxy_cstring_init; Name.string=CString
-#endif
 /**
    Serializes src to dest using the given marshaller for the
    conversion. If any parameters are null then false is returned.
    name. If serialization succeeeds, it is added to the parent and
    true is returned, otherwise the child is destroyed, parent
    is not modified, and false is returned.
 */
 bool c11n_serialize_subnode( c11n_node * parent, c11n_marshaller const * marshaller, c11n_key_type childName, void const * src );
@@ > / 1316 @@
 /**
-   NYI
+   The converse of c11n_serialize_subnode(), this routine searches
@@ | / 1319 / parent for a child node with the given name. If found, that child @@
@@ | / 1320 / is used as the deserialization source for the given marshaller and @@
@@ | / 1321 / serializable. On error (child not found or deserialization failed) @@
@@ | / 1322 / false is returned and the serializable may be in an undefined state @@
@@ | / 1323 / (that is up to the marshaller, actually). @@
@@ | / 1324 @@
@@ | / 1325 / Note that this only finds the first child with the given name. If @@
@@ | / 1326 / parent has multiple children with the same name, use the @@
@@ | / 1327 / c11n_node_iter_c API to iterate over them. @@
 */
-bool c11n_deserialize_subnode( c11n_node const * parent, c11n_marshaller const * marshaller, c11n_key_type childName, void * dest );
+bool c11n_deserialize_subnode( c11n_node const * parent, c11n_marshaller const * marshaller, c11n_key_type childName, void * serializable );
 /**
    Deserializes dest from src using the given marshaller for the
    conversion. If any parameters are null then false is returned.
 #  define C11N_CONFIG_LOG_ENABLE 0
 #endif
 /** @enum c11n_log_flags
-The c11n_log_flags enum contains a bitmask
+The c11n_log_flags enum contains a bitmask of logging/debugging flags,
-of debugging flags, for use with c11n_log() and
+for use with c11n_log() and friends.
@@ 1527 / friends. / | @@
 */
 enum c11n_log_flags {
 /**
    Never log any debug message.
 */
 /**
    Gets the current debug mask. See the c11n_log_flags enum for
    details.
 */
 unsigned int c11n_log_get_flags();
@@ > / 1598 @@
 /**
    Sets the current debug mask and returns the previous one. See the
    c11n_log_flags enum for details.
 */
 unsigned int c11n_log_set_flags(unsigned int newflags);
@@ > / 1604 @@
 /**
    Sets the debug output stream to f. Setting it to 0 completely
    disables debug output sent via c11n_log() and friends.
    Does not transfer ownership of f, and f must outlive all
 		va_list vargs );
 /**
    Identical to c11n_logv() but takes an ellipses list instead of
    a va_list.
 */
-void c11n_log(  unsigned int condition,
+void c11n_log( unsigned int condition,
-		C11N_SOURCE_INFO_PARAMS_DECL,
+	       C11N_SOURCE_INFO_PARAMS_DECL,
-		c11n_const_string_t fmt,
+	       c11n_const_string_t fmt,
 		... );
 //#define C11N_LOG_MARKER c11n_log(C,"c11n_log():%s:%d:%s(): ",__FILE__,__LINE__,__func__);
 //#define C11N_LOG c11n_log(C,"c11n_log():%s:%d:%s(): ",__FILE__,__LINE__,__func__); c11n_log
@@ 1754 / < @@
-#if 0
-bool c11n_register_marshaller( c11n_context * cx, c11n_key_type, c11n_marshaller const * marshaller );
-c11n_marshaller const * c11n_get_marshaller_for_type( c11n_context * cx, c11n_key_type classname );
-void * c11n_classload( c11n_context * cx, c11n_key_type key );
-/**
-   Registration of factories requires knowing:
@@ 1761 / < @@
-   - complete type
@@ 1763 / < @@
-   - class name
@@ 1765 / < @@
-   - factory function:  void* (*)();
@@ 1767 / < @@
-*/
-#endif
 /**
    Saves src as encoded binary data in dest. It does this by casting
    src to a (char const *), writing sizeOfSrc bytes to a string
    buffer, base64-encoding that buffer and then storing the
    @endcode
    @see c11n_deserialize_binary()
 */
 bool c11n_deserialize_binary( c11n_node const * src, c11n_binary_data * dest );
@@ > / 1749 @@
@@ > / 1750 @@
+/**
+   A marshaller instance for de/serializing objects of type int. Note,
+   however, that it is always much more efficient to store ints as
+   node properties, as opposed to as full-fledged (traited)
+   Cerializables.
@@ > / 1756 @@
+   Sample usage:
@@ > / 1758 @@
+   @code
+   // Serialize:
+   int const src = 42;
+   c11n_serialize( destNode, c11n_marshaller_pod_int, &src );
@@ > / 1763 @@
+   // Deserialize:
+   int dest = 0;
+   c11n_deserialize( srcNode, c11n_marshaller_pod_int, &dest );
+   @endcode
@@ > / 1768 @@
+   But the saner thing to do in most cases is to store simple
+   PODs as properties of some parent c11n_node:
@@ > / 1771 @@
+   @code
+   int const src = 42;
+   c11n_node_prop_set_fe( destNode, "myInt", "%d", src );
+   @endcode
@@ > / 1776 @@
+   as that requires far fewer resources internally and is
+   suitable for many POD types.
+*/
+extern const c11n_marshaller * c11n_marshaller_pod_int;
@@ > / 1781 @@
+/**
+   A marshaller instance for de/serializing objects of type unsigned int.
+   See c11n_marshaller_pod_int for more details and sample usage.
+*/
+extern const c11n_marshaller * c11n_marshaller_pod_uint;
@@ > / 1787 @@
+/**
+   A marshaller instance for de/serializing objects of type long.
+   See c11n_marshaller_pod_int for more details and sample usage.
+*/
+extern const c11n_marshaller * c11n_marshaller_pod_long;
@@ > / 1793 @@
+/**
+   A marshaller instance for de/serializing objects of type unsigned long.
+   See c11n_marshaller_pod_int for more details and sample usage.
+*/
+extern const c11n_marshaller * c11n_marshaller_pod_ulong;
@@ > / 1799 @@
+/**
+   A marshaller instance for de/serializing objects of type double.
+   See c11n_marshaller_pod_int for more details and sample usage.
+*/
+extern const c11n_marshaller * c11n_marshaller_pod_double;
@@ > / 1805 @@
+#if 0
+/*
+   DON'T USE! It can't work safely for some common cases.
@@ > / 1809 @@
+   A marshaller instance for de/serializing objects of type double.
+   The string value deserialized by api->deserialize()
+   will not be a copy, but will be a pointer to the data stored
+   within the c11n_node we are deserializing from. Thus if
+   you need to keep the string around longer than the corresponding
+   c11n_node, copy it.
@@ > / 1816 @@
+   Example usage:
+   @code
+   // Serialize:
+   c11n_const_string_t src = "This is a string.";
+   c11n_serialize( destNode, c11n_marshaller_pod_string, src );
@@ > / 1822 @@
+   // Deserialize:
+   c11n_const_string_t dest = 0;
+   if( c11n_deserialize( srcNode, c11n_marshaller_pod_string, &dest ) )
+   { // note the POINTER to dest here -->-->-->-->-->-->-->-^^^^^
+       // Now dest points to a copy of the deserialized string value
+       // of srcNode. Copy it here if you need it after srcNode goes
+       // out of your scope.
+   }
+   @endcode
@@ > / 1832 @@
+   BUG WARNING: this marshaller instance cannot work with
+   c11n_deserialize_new() because this object requires that
+   deserialization take a pointer to a pointer, which
+   c11n_deserialize_new() cannot generically handle. It also
+   cannot work with c11n_load_serializable() because it cannot
+   know how big of a string to allocate (and then cannot generically
+   handle the pointer-to-pointer part).
+*/
+//extern const c11n_marshaller * c11n_marshaller_pod_string;
+struct c11n_s_proxy_cstring
+{
+    c11n_marshaller_api api;
+    char * string;
+};
+typedef struct c11n_s_proxy_cstring c11n_s_proxy_cstring;
+extern const c11n_s_proxy_cstring c11n_s_proxy_cstring_init;
+#define C11N_S_PROXY_CSTRING_INIT(Name,CString) \
+    c11n_s_proxy_cstring Name = c11n_s_proxy_cstring_init; Name.string=CString
+#endif
 #ifdef __cplusplus
 } /* extern "C" */
 #endif
 #endif /* S11N_NET_C11N_H_INCLUDED */