[asterisk-commits] rizzo: branch rizzo/video_v2 r87810 - /team/rizzo/video_v2/include/asterisk/

[SVN commits to the Asterisk project]

Author: rizzo
Date: Wed Oct 31 09:42:39 2007
New Revision: 87810

URL: http://svn.digium.com/view/asterisk?view=rev&rev=87810
Log:
complete documentation of stringfields cleanup


Modified:
    team/rizzo/video_v2/include/asterisk/stringfields.h

Modified: team/rizzo/video_v2/include/asterisk/stringfields.h
URL: http://svn.digium.com/view/asterisk/team/rizzo/video_v2/include/asterisk/stringfields.h?view=diff&rev=87810&r1=87809&r2=87810
==============================================================================
--- team/rizzo/video_v2/include/asterisk/stringfields.h (original)
+++ team/rizzo/video_v2/include/asterisk/stringfields.h Wed Oct 31 09:42:39 2007
@@ -23,7 +23,7 @@
   fields in structures without requiring them to be allocated
   as fixed-size buffers or requiring individual allocations for
   for each field.
-  
+
   Using this functionality is quite simple. An example structure
   with three fields is defined like this:
   
@@ -39,56 +39,64 @@
   };
   \endcode
   
-  When an instance of this structure is allocated, the fields
-  (and the pool of storage for them) must be initialized:
+  When an instance of this structure is allocated (either statically or
+  dynamically), the fields and the pool of storage for them must be
+  initialized:
   
   \code
-  struct sample_fields *sample;
-  
-  sample = ast_calloc(1, sizeof(*sample));
-  if (sample) {
-	  if (ast_string_field_init(sample, 256)) {
-		  ast_free(sample);
-		  sample = NULL;
-	  }
-  }
-  
-  if (!sample) {
-  ... handle error
+  struct sample_fields *x;
+  
+  x = ast_calloc(1, sizeof(*x));
+  if (x == NULL || ast_string_field_init(x, 252)) {
+	if (x)
+		ast_free(x);
+	x = NULL;
+  	... handle error
   }
   \endcode
 
-  Fields will default to pointing to an empty string, and will
-  revert to that when ast_string_field_set() is called with a NULL
-  argument: a string field will \b never contain NULL (this is not
-  needed in this code, but comes from external requirements).
-  ast_string_field_init(x, 0) can be used to reset fields to the
+  Fields will default to pointing to an empty string, and will revert to
+  that when ast_string_field_set() is called with a NULL argument.
+  A string field will \b never contain NULL (this feature is not used
+  in this code, but comes from external requirements).
+
+  ast_string_field_init(x, 0) will reset fields to the
   initial value while keeping the pool allocated.
   
-  Using the fields is much like using regular 'const char *' fields
-  in the structure, except that writing into them must be done
-  using wrapper macros defined in this file, and assignments are
-  always by value (i.e. strings are copied).
-  Storing simple values into fields can be done using ast_string_field_set();
-  more complex values (using printf-style format strings) can be stored
-  using ast_string_field_build(). Variant of these function allow passing
-  a pointer to the field as an argument:
+  Reading the fields is much like using 'const char * const' fields in the
+  structure: you cannot write to the field or to the memory it points to
+  (XXX perhaps the latter is too much of a restriction since values
+  are not shared).
+
+  Writing to the fields must be done using the wrapper macros listed below;
+  and assignments are always by value (i.e. strings are copied):
+  * ast_string_field_set() stores a simple value;
+  * ast_string_field_build() builds the string using a printf-style;
+  * ast_string_field_build_va() is the varargs version of the above (for
+    portability reasons it uses two vararg);
+  * variants of these function allow passing a pointer to the field
+    as an argument.
   \code
-  ast_string_field_set(sample, foo, "infinite loop");
-  ast_string_field_set(sample, foo, NULL); // set to an empty string
-  ast_string_field_ptr_set(sample, &sample->bar, "right way");
-  ast_string_field_build(sample, blah, "%d %s", zipcode, city);
-  ast_string_field_ptr_build(sample, &sample->blah, "%d %s", zipcode, city);
+  ast_string_field_set(x, foo, "infinite loop");
+  ast_string_field_set(x, foo, NULL); // set to an empty string
+  ast_string_field_ptr_set(x, &x->bar, "right way");
+
+  ast_string_field_build(x, blah, "%d %s", zipcode, city);
+  ast_string_field_ptr_build(x, &x->blah, "%d %s", zipcode, city);
+
+  ast_string_field_build_va(x, bar, fmt, args1, args2)
+  ast_string_field_ptr_build_va(x, &x->bar, fmt, args1, args2)
   \endcode
-  There are two more varargs versions of the 'build' functions.
 
   When the structure instance is no longer needed, the fields
   and their storage pool must be freed:
   
   \code
-  ast_string_field_free_memory(sample);
-  ast_free(sample);
+  ast_string_field_free_memory(x);
+  ast_free(x);
   \endcode
+
+  This completes the API description.
 */
 
 #ifndef _ASTERISK_STRINGFIELDS_H