text: #ifndef footxtlisthfoo
  #define footxtlisthfoo
  
  /* $Id: strlst.h 1477 2007-05-09 19:45:54Z lennart $ */
  
  /***
    This file is part of avahi.
   
    avahi is free software; you can redistribute it and/or modify it
    under the terms of the GNU Lesser General Public License as
    published by the Free Software Foundation; either version 2.1 of the
    License, or (at your option) any later version.
   
    avahi is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
    Public License for more details.
   
    You should have received a copy of the GNU Lesser General Public
    License along with avahi; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
    USA.
  ***/
  
  /** \file strlst.h Implementation of a data type to store lists of strings */
  
  #include <sys/types.h>
  #include <inttypes.h>
  #include <stdarg.h>
  
  #include <avahi-common/cdecl.h>
  #include <avahi-common/gccmacro.h>
  
  AVAHI_C_DECL_BEGIN
  
  /** Linked list of strings that can contain any number of binary
   * characters, including NUL bytes. An empty list is created by
   * assigning a NULL to a pointer to AvahiStringList. The string list
   * is stored in reverse order, so that appending to the string list is
   * effectively a prepending to the linked list.  This object is used
   * primarily for storing DNS TXT record data. */
  typedef struct AvahiStringList {
      struct AvahiStringList *next; /**< Pointer to the next linked list element */
      size_t size;  /**< Size of text[] */
      uint8_t text[1]; /**< Character data */
  } AvahiStringList;
  
  /** @{ \name Construction and destruction */
  
  /** Create a new string list by taking a variable list of NUL
   * terminated strings. The strings are copied using g_strdup(). The
   * argument list must be terminated by a NULL pointer. */
  AvahiStringList *avahi_string_list_new(const char *txt, ...) AVAHI_GCC_SENTINEL;
  
  /** \cond fulldocs */
  /** Same as avahi_string_list_new() but pass a va_list structure */
  AvahiStringList *avahi_string_list_new_va(va_list va);
  /** \endcond */
  
  /** Create a new string list from a string array. The strings are
   * copied using g_strdup(). length should contain the length of the
   * array, or -1 if the array is NULL terminated*/
  AvahiStringList *avahi_string_list_new_from_array(const char **array, int length);
  
  /** Free a string list */
  void avahi_string_list_free(AvahiStringList *l);
  
  /** @} */
  
  /** @{ \name Adding strings */
  
  /** Append a NUL terminated string to the specified string list. The
   * passed string is copied using g_strdup(). Returns the new list
   * start. */
  AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text);
  
  /** Append a new NUL terminated formatted string to the specified string list */
  AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23;
  
  /** \cond fulldocs */
  /** Append a new NUL terminated formatted string to the specified string list */
  AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va);
  /** \endcond */
  
  /** Append an arbitrary length byte string to the list. Returns the
   * new list start. */
  AvahiStringList *avahi_string_list_add_arbitrary(AvahiStringList *l, const uint8_t *text, size_t size);
  
  /** Append a new entry to the string list. The string is not filled
  with data. The caller should fill in string data afterwards by writing
  it to l->text, where l is the pointer returned by this function. This
  function exists solely to optimize a few operations where otherwise
  superfluous string copying would be necessary. */
  AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size);
  
  /** Same as avahi_string_list_add(), but takes a variable number of
   * NUL terminated strings. The argument list must be terminated by a
   * NULL pointer. Returns the new list start. */
  AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL;
  
  /** \cond fulldocs */
  /** Same as avahi_string_list_add_many(), but use a va_list
   * structure. Returns the new list start. */
  AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va);
  /** \endcond */
  
  /** @} */
  
  /** @{ \name String list operations */
  
  /** Convert the string list object to a single character string,
   * seperated by spaces and enclosed in "". avahi_free() the result! This
   * function doesn't work well with string that contain NUL bytes. */
  char* avahi_string_list_to_string(AvahiStringList *l);
  
  /** \cond fulldocs */
  /** Serialize the string list object in a way that is compatible with
   * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */
  size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size);
  
  /** Inverse of avahi_string_list_serialize() */
  int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret);
  /** \endcond */
  
  /** Compare to string lists */
  int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b);
  
  /** Copy a string list */
  AvahiStringList *avahi_string_list_copy(const AvahiStringList *l);
  
  /** Reverse the string list. */
  AvahiStringList* avahi_string_list_reverse(AvahiStringList *l);
  
  /** Return the number of elements in the string list */
  unsigned avahi_string_list_length(const AvahiStringList *l);
  
  /** @} */
  
  /** @{ \name Accessing items */
  
  /** Returns the next item in the string list */
  AvahiStringList *avahi_string_list_get_next(AvahiStringList *l);
  
  /** Returns the text for the current item */
  uint8_t *avahi_string_list_get_text(AvahiStringList *l);
  
  /** Returns the size of the current text */
  size_t avahi_string_list_get_size(AvahiStringList *l);
  
  /** @} */
  
  /** @{ \name DNS-SD TXT pair handling */
  
  /** Find the string list entry for the given DNS-SD TXT key */
  AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key);
  
  /** Return the DNS-SD TXT key and value for the specified string list
   * item. If size is not NULL it will be filled with the length of
   * value. (for strings containing NUL bytes). If the entry doesn't
   * contain a value *value will be set to NULL. You need to
   * avahi_free() the strings returned in *key and *value. */
  int avahi_string_list_get_pair(AvahiStringList *l, char **key, char **value, size_t *size);
  
  /** Add a new DNS-SD TXT key value pair to the string list. value may
   * be NULL in case you want to specify a key without a value */
  AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key, const char *value);
  
  /** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */
  AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size);
  
  /** @} */
  
  /** \cond fulldocs */
  /** Try to find a magic service cookie in the specified DNS-SD string
   * list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */
  uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l);
  /** \endcond */
  
  AVAHI_C_DECL_END
  
  #endif
  
  