]> git.meshlink.io Git - catta/blob - avahi-common/strlst.h
add an utf8 check when unescaping domains - essentially this means that all domain...
[catta] / avahi-common / strlst.h
1 #ifndef footxtlisthfoo
2 #define footxtlisthfoo
3
4 /* $Id$ */
5
6 /***
7   This file is part of avahi.
8  
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.
13  
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.
18  
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
22   USA.
23 ***/
24
25 /** \file strlst.h Implementation of a data type to store lists of strings */
26
27 #include <sys/types.h>
28 #include <inttypes.h>
29 #include <stdarg.h>
30
31 #include <avahi-common/cdecl.h>
32 #include <avahi-common/gccmacro.h>
33
34 AVAHI_C_DECL_BEGIN
35
36 /** Linked list of strings that can contain any number of binary
37  * characters, including NUL bytes. An empty list is created by
38  * assigning a NULL to a pointer to AvahiStringList. The string list
39  * is stored in reverse order, so that appending to the string list is
40  * effectively a prepending to the linked list.  This object is used
41  * primarily for storing DNS TXT record data. */
42 typedef struct AvahiStringList {
43     struct AvahiStringList *next; /**< Pointer to the next linked list element */
44     size_t size;  /**< Size of text[] */
45     uint8_t text[1]; /**< Character data */
46 } AvahiStringList;
47
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 AvahiStringList *avahi_string_list_new(const char *txt, ...) AVAHI_GCC_SENTINEL;
52
53 /** Same as avahi_string_list_new() but pass a va_list structure */
54 AvahiStringList *avahi_string_list_new_va(va_list va);
55
56 /** Create a new string list from a string array. The strings are
57  * copied using g_strdup(). length should contain the length of the
58  * array, or -1 if the array is NULL terminated*/
59 AvahiStringList *avahi_string_list_new_from_array(const char **array, int length);
60
61 /** Free a string list */
62 void avahi_string_list_free(AvahiStringList *l);
63
64 /** Append a NUL terminated string to the specified string list. The
65  * passed string is copied using g_strdup(). Returns the new list
66  * start. */
67 AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text);
68
69 /** Append a new NUL terminated formatted string to the specified string list */
70 AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23;
71
72 /** Append a new NUL terminated formatted string to the specified string list */
73 AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va);
74
75 /** Append an arbitrary length byte string to the list. Returns the
76  * new list start. */
77 AvahiStringList *avahi_string_list_add_arbitrary(AvahiStringList *l, const uint8_t *text, size_t size);
78
79 /** Append a new entry to the string list. The string is not filled
80 with data. The caller should fill in string data afterwards by writing
81 it to l->text, where l is the pointer returned by this function. This
82 function exists solely to optimize a few operations where otherwise
83 superfluous string copying would be necessary. */
84 AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size);
85
86 /** Same as avahi_string_list_add(), but takes a variable number of
87  * NUL terminated strings. The argument list must be terminated by a
88  * NULL pointer. Returns the new list start. */
89 AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL;
90
91 /** Same as avahi_string_list_add_many(), but use a va_list
92  * structure. Returns the new list start. */
93 AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va);
94
95 /** Convert the string list object to a single character string,
96  * seperated by spaces and enclosed in "". avahi_free() the result! This
97  * function doesn't work well with string that contain NUL bytes. */
98 char* avahi_string_list_to_string(AvahiStringList *l);
99
100 /** Serialize the string list object in a way that is compatible with
101  * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */
102 size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size);
103
104 /** Inverse of avahi_string_list_serialize() */
105 int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret);
106
107 /** Compare to string lists */
108 int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b);
109
110 /** Copy a string list */
111 AvahiStringList *avahi_string_list_copy(const AvahiStringList *l);
112
113 /** Reverse the string list. */
114 AvahiStringList* avahi_string_list_reverse(AvahiStringList *l);
115
116 /** Return the number of elements in the string list */
117 unsigned avahi_string_list_length(const AvahiStringList *l);
118
119 /** Find the string list entry for the given DNS-SD TXT key */
120 AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key);
121
122 /** Return the DNS-SD TXT key and value for the specified string list
123  * item. If size is not NULL it will be filled with the length of
124  * value. (for strings containing NUL bytes). If the entry doesn't
125  * contain a value *value will be set to NULL. You need to
126  * avahi_free() the strings returned in *key and *value. */
127 int avahi_string_list_get_pair(AvahiStringList *l, char **key, char **value, size_t *size);
128
129 /** Add a new DNS-SD TXT key value pair to the string list. value may
130  * be NULL in case you want to specify a key without a value */
131 AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key, const char *value);
132
133 /** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */
134 AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size);
135
136 /** Returns the next item in the string list */
137 AvahiStringList *avahi_string_list_get_next(AvahiStringList *l);
138
139 /** Returns the text for the current item */
140 uint8_t *avahi_string_list_get_text(AvahiStringList *l);
141
142 /** Returns the size of the current text */
143 size_t avahi_string_list_get_size(AvahiStringList *l);
144
145 /** Try to find a magic service cookie in the specified DNS-SD string
146  * list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */
147 uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l);
148
149 AVAHI_C_DECL_END
150
151 #endif
152