7 This file is part of avahi.
9 avahi is free software; you can redistribute it and/or modify it
10 under the terms of the GNU Lesser General Public License as
11 published by the Free Software Foundation; either version 2.1 of the
12 License, or (at your option) any later version.
14 avahi is distributed in the hope that it will be useful, but WITHOUT
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
17 Public License for more details.
19 You should have received a copy of the GNU Lesser General Public
20 License along with avahi; if not, write to the Free Software
21 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
25 /** \file strlst.h Implementation of a data type to store lists of strings */
27 #include <sys/types.h>
31 #include <avahi-common/cdecl.h>
35 /** Linked list of strings that can contain any number of binary
36 * characters, including NUL bytes. An empty list is created by
37 * assigning a NULL to a pointer to AvahiStringList. The string list
38 * is stored in reverse order, so that appending to the string list is
39 * effectively a prepending to the linked list. This object is used
40 * primarily for storing DNS TXT record data. */
41 typedef struct AvahiStringList {
42 struct AvahiStringList *next; /**< Pointe to the next linked list element */
43 size_t size; /**< Size of text[] */
44 uint8_t text[1]; /**< Character data */
47 /** Create a new string list by taking a variable list of NUL
48 * terminated strings. The strings are copied using g_strdup(). The
49 * argument list must be terminated by a NULL pointer. */
50 AvahiStringList *avahi_string_list_new(const char *txt, ...);
52 /** Same as avahi_string_list_new() but pass a va_list structure */
53 AvahiStringList *avahi_string_list_new_va(va_list va);
55 /** Create a new string list from a string array. The strings are
56 * copied using g_strdup(). length should contain the length of the
57 * array, or -1 if the array is NULL terminated*/
58 AvahiStringList *avahi_string_list_new_from_array(const char **array, int length);
60 /** Free a string list */
61 void avahi_string_list_free(AvahiStringList *l);
63 /** Append a NUL terminated string to the specified string list. The
64 * passed string is copied using g_strdup(). Returns the new list
66 AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text);
68 /** Append an arbitrary length byte string to the list. Returns the
70 AvahiStringList *avahi_string_list_add_arbitrary(AvahiStringList *l, const uint8_t *text, size_t size);
72 /** Append a new entry to the string list. The string is not filled
73 with data. The caller should fill in string data afterwards by writing
74 it to l->text, where l is the pointer returned by this function. This
75 function exists solely to optimize a few operations where otherwise
76 superfluous string copying would be necessary. */
77 AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size);
79 /** Same as avahi_string_list_add(), but takes a variable number of
80 * NUL terminated strings. The argument list must be terminated by a
81 * NULL pointer. Returns the new list start. */
82 AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...);
84 /** Same as avahi_string_list_add_many(), but use a va_list
85 * structure. Returns the new list start. */
86 AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va);
88 /** Convert the string list object to a single character string,
89 * seperated by spaces and enclosed in "". g_free() the result! This
90 * function doesn't work well with string that contain NUL bytes. */
91 char* avahi_string_list_to_string(AvahiStringList *l);
93 /** Serialize the string list object in a way that is compatible with
94 * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */
95 size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size);
97 /** Inverse of avahi_string_list_serialize() */
98 AvahiStringList *avahi_string_list_parse(const void *data, size_t size);
100 /** Compare to string lists */
101 int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b);
103 /** Copy a string list */
104 AvahiStringList *avahi_string_list_copy(const AvahiStringList *l);
106 /** Reverse the string list. */
107 AvahiStringList* avahi_string_list_reverse(AvahiStringList *l);
109 /** Return the number of elements in the string list */
110 unsigned avahi_string_list_length(const AvahiStringList *l);