SILC Runtime Toolkit 1.2 Beta 1

[runtime.git] / lib / silcutil / silcsnprintf.h

diff --git a/lib/silcutil/silcsnprintf.h b/lib/silcutil/silcsnprintf.h
index 00ae8c2c502c155ee70641beb7dded9ed26257cc..fd89b72157cfe273b2370c633128aeaa687a2e6e 100644 (file)
--- a/lib/silcutil/silcsnprintf.h
+++ b/lib/silcutil/silcsnprintf.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2007 Pekka Riikonen
+  Copyright (C) 2007 - 2008 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -17,7 +17,7 @@
 
 */
 
-/****h* silcutil/Snprintf
+/****h* silcutil/Snprintf Interface
  *
  * DESCRIPTION
  *
@@ -29,7 +29,35 @@
 #ifndef SILCSNPRINTF_H
 #define SILCSNPRINTF_H
 
-/****f* silcutil/SilcSnprintf/silc_snprintf
+/****f* silcutil/SilcSnprintfRender
+ *
+ * SYNOPSIS
+ *
+ *    typedef char *(*SilcSnprintfRender)(void *data);
+ *
+ * DESCRIPTION
+ *
+ *    Snprintf rendering function.  This function can be used with '%@'
+ *    formatting character.  The `data' is rendered into a string and
+ *    allocated string is returned.  If NULL is returned the rendering
+ *    is skipped and ignored.  If the returned string does not fit to
+ *    the destination buffer it may be truncated.
+ *
+ * EXAMPLE
+ *
+ *    char *id_render(void *data)
+ *    {
+ *      ...render...
+ *      return id_string;
+ *    }
+ *
+ *    // Call id_render function to render the 'client_id'.
+ *    silc_snprintf(buf, sizeof(buf), "Client ID %@", id_render, client_id);
+ *
+ ***/
+typedef char *(*SilcSnprintfRender)(void *data);
+
+/****f* silcutil/silc_snprintf
  *
  * SYNOPSIS
  *
@@ -42,10 +70,13 @@
  *    snprintf(3) and printf(3) formatting.  Returns the number of character
  *    in `str' or negative value on error.
  *
+ *    This also supports '%@' formatting to render data and structures
+ *    using SilcSnprintfRender.
+ *
  ***/
 int silc_snprintf(char *str, size_t count, const char *fmt, ...);
 
-/****f* silcutil/SilcSnprintf/silc_vsnprintf
+/****f* silcutil/silc_vsnprintf
  *
  * SYNOPSIS
  *
@@ -60,7 +91,7 @@ int silc_snprintf(char *str, size_t count, const char *fmt, ...);
  ***/
 int silc_vsnprintf(char *str, size_t count, const char *fmt, va_list args);
 
-/****f* silcutil/SilcSnprintf/silc_asprintf
+/****f* silcutil/silc_asprintf
  *
  * SYNOPSIS
  *
@@ -74,7 +105,7 @@ int silc_vsnprintf(char *str, size_t count, const char *fmt, va_list args);
  ***/
 int silc_asprintf(char **ptr, const char *format, ...);
 
-/****f* silcutil/SilcSnprintf/silc_vasprintf
+/****f* silcutil/silc_vasprintf
  *
  * SYNOPSIS
  *