Added '%@' formatting to silc_snprintf and friends.

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

diff --git a/lib/silcutil/silcsnprintf.h b/lib/silcutil/silcsnprintf.h
index 00ae8c2c502c155ee70641beb7dded9ed26257cc..abc1e751ab369e0d0a966c7b5c30e48183eb6131 100644 (file)
--- a/lib/silcutil/silcsnprintf.h
+++ b/lib/silcutil/silcsnprintf.h
@@ -29,6 +29,34 @@
 #ifndef SILCSNPRINTF_H
 #define SILCSNPRINTF_H
 
+/****f* silcutil/SilcSnprintf/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/SilcSnprintf/silc_snprintf
  *
  * SYNOPSIS
@@ -42,6 +70,9 @@
  *    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, ...);