5 This file is part of catta.
7 catta is free software; you can redistribute it and/or modify it
8 under the terms of the GNU Lesser General Public License as
9 published by the Free Software Foundation; either version 2.1 of the
10 License, or (at your option) any later version.
12 catta is distributed in the hope that it will be useful, but WITHOUT
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
15 Public License for more details.
17 You should have received a copy of the GNU Lesser General Public
18 License along with catta; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
23 /** \file strlst.h Implementation of a data type to store lists of strings */
25 #include <sys/types.h>
29 #include <catta/cdecl.h>
30 #include <catta/gccmacro.h>
34 /** Linked list of strings that can contain any number of binary
35 * characters, including NUL bytes. An empty list is created by
36 * assigning a NULL to a pointer to CattaStringList. The string list
37 * is stored in reverse order, so that appending to the string list is
38 * effectively a prepending to the linked list. This object is used
39 * primarily for storing DNS TXT record data. */
40 typedef struct CattaStringList {
41 struct CattaStringList *next; /**< Pointer to the next linked list element */
42 size_t size; /**< Size of text[] */
43 uint8_t text[1]; /**< Character data */
46 /** @{ \name Construction and destruction */
48 /** Create a new string list by taking a variable list of NUL
49 * terminated strings. The strings are copied using g_strdup(). The
50 * argument list must be terminated by a NULL pointer. */
51 CattaStringList *catta_string_list_new(const char *txt, ...) CATTA_GCC_SENTINEL;
54 /** Same as catta_string_list_new() but pass a va_list structure */
55 CattaStringList *catta_string_list_new_va(va_list va);
58 /** Create a new string list from a string array. The strings are
59 * copied using g_strdup(). length should contain the length of the
60 * array, or -1 if the array is NULL terminated*/
61 CattaStringList *catta_string_list_new_from_array(const char **array, int length);
63 /** Free a string list */
64 void catta_string_list_free(CattaStringList *l);
68 /** @{ \name Adding strings */
70 /** Append a NUL terminated string to the specified string list. The
71 * passed string is copied using g_strdup(). Returns the new list
73 CattaStringList *catta_string_list_add(CattaStringList *l, const char *text);
75 /** Append a new NUL terminated formatted string to the specified string list */
76 CattaStringList *catta_string_list_add_printf(CattaStringList *l, const char *format, ...) CATTA_GCC_PRINTF_ATTR23;
79 /** Append a new NUL terminated formatted string to the specified string list */
80 CattaStringList *catta_string_list_add_vprintf(CattaStringList *l, const char *format, va_list va);
83 /** Append an arbitrary length byte string to the list. Returns the
85 CattaStringList *catta_string_list_add_arbitrary(CattaStringList *l, const uint8_t *text, size_t size);
87 /** Append a new entry to the string list. The string is not filled
88 with data. The caller should fill in string data afterwards by writing
89 it to l->text, where l is the pointer returned by this function. This
90 function exists solely to optimize a few operations where otherwise
91 superfluous string copying would be necessary. */
92 CattaStringList*catta_string_list_add_anonymous(CattaStringList *l, size_t size);
94 /** Same as catta_string_list_add(), but takes a variable number of
95 * NUL terminated strings. The argument list must be terminated by a
96 * NULL pointer. Returns the new list start. */
97 CattaStringList *catta_string_list_add_many(CattaStringList *r, ...) CATTA_GCC_SENTINEL;
100 /** Same as catta_string_list_add_many(), but use a va_list
101 * structure. Returns the new list start. */
102 CattaStringList *catta_string_list_add_many_va(CattaStringList *r, va_list va);
107 /** @{ \name String list operations */
109 /** Convert the string list object to a single character string,
110 * seperated by spaces and enclosed in "". catta_free() the result! This
111 * function doesn't work well with strings that contain NUL bytes. */
112 char* catta_string_list_to_string(CattaStringList *l);
114 /** \cond fulldocs */
115 /** Serialize the string list object in a way that is compatible with
116 * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */
117 size_t catta_string_list_serialize(CattaStringList *l, void * data, size_t size);
119 /** Inverse of catta_string_list_serialize() */
120 int catta_string_list_parse(const void *data, size_t size, CattaStringList **ret);
123 /** Compare to string lists */
124 int catta_string_list_equal(const CattaStringList *a, const CattaStringList *b);
126 /** Copy a string list */
127 CattaStringList *catta_string_list_copy(const CattaStringList *l);
129 /** Reverse the string list. */
130 CattaStringList* catta_string_list_reverse(CattaStringList *l);
132 /** Return the number of elements in the string list */
133 unsigned catta_string_list_length(const CattaStringList *l);
137 /** @{ \name Accessing items */
139 /** Returns the next item in the string list */
140 CattaStringList *catta_string_list_get_next(CattaStringList *l);
142 /** Returns the text for the current item */
143 uint8_t *catta_string_list_get_text(CattaStringList *l);
145 /** Returns the size of the current text */
146 size_t catta_string_list_get_size(CattaStringList *l);
150 /** @{ \name DNS-SD TXT pair handling */
152 /** Find the string list entry for the given DNS-SD TXT key */
153 CattaStringList *catta_string_list_find(CattaStringList *l, const char *key);
155 /** Return the DNS-SD TXT key and value for the specified string list
156 * item. If size is not NULL it will be filled with the length of
157 * value. (for strings containing NUL bytes). If the entry doesn't
158 * contain a value *value will be set to NULL. You need to
159 * catta_free() the strings returned in *key and *value. */
160 int catta_string_list_get_pair(CattaStringList *l, char **key, char **value, size_t *size);
162 /** Add a new DNS-SD TXT key value pair to the string list. value may
163 * be NULL in case you want to specify a key without a value */
164 CattaStringList *catta_string_list_add_pair(CattaStringList *l, const char *key, const char *value);
166 /** Same as catta_string_list_add_pair() but allow strings containing NUL bytes in *value. */
167 CattaStringList *catta_string_list_add_pair_arbitrary(CattaStringList *l, const char *key, const uint8_t *value, size_t size);
171 /** \cond fulldocs */
172 /** Try to find a magic service cookie in the specified DNS-SD string
173 * list. Or return CATTA_SERVICE_COOKIE_INVALID if none is found. */
174 uint32_t catta_string_list_get_service_cookie(CattaStringList *l);