| 1 |
#ifndef footxtlisthfoo |
| 2 |
#define footxtlisthfoo |
| 3 |
|
| 4 |
/*** |
| 5 |
This file is part of avahi. |
| 6 |
|
| 7 |
avahi 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. |
| 11 |
|
| 12 |
avahi 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. |
| 16 |
|
| 17 |
You should have received a copy of the GNU Lesser General Public |
| 18 |
License along with avahi; if not, write to the Free Software |
| 19 |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 |
| 20 |
USA. |
| 21 |
***/ |
| 22 |
|
| 23 |
/** \file strlst.h Implementation of a data type to store lists of strings */ |
| 24 |
|
| 25 |
#include <sys/types.h> |
| 26 |
#include <inttypes.h> |
| 27 |
#include <stdarg.h> |
| 28 |
|
| 29 |
#include "cdecl.h" |
| 30 |
#include "gccmacro.h" |
| 31 |
|
| 32 |
AVAHI_C_DECL_BEGIN |
| 33 |
|
| 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 AvahiStringList. 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 AvahiStringList { |
| 41 |
struct AvahiStringList *next; /**< Pointer to the next linked list element */ |
| 42 |
size_t size; /**< Size of text[] */ |
| 43 |
uint8_t text[1]; /**< Character data */ |
| 44 |
} AvahiStringList; |
| 45 |
|
| 46 |
/** @{ \name Construction and destruction */ |
| 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 |
/** \cond fulldocs */ |
| 54 |
/** Same as avahi_string_list_new() but pass a va_list structure */ |
| 55 |
AvahiStringList *avahi_string_list_new_va(va_list va); |
| 56 |
/** \endcond */ |
| 57 |
|
| 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 |
AvahiStringList *avahi_string_list_new_from_array(const char **array, int length); |
| 62 |
|
| 63 |
/** Free a string list */ |
| 64 |
void avahi_string_list_free(AvahiStringList *l); |
| 65 |
|
| 66 |
/** @} */ |
| 67 |
|
| 68 |
/** @{ \name Adding strings */ |
| 69 |
|
| 70 |
/** Append a NUL terminated string to the specified string list. The |
| 71 |
* passed string is copied using g_strdup(). Returns the new list |
| 72 |
* start. */ |
| 73 |
AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text); |
| 74 |
|
| 75 |
/** Append a new NUL terminated formatted string to the specified string list */ |
| 76 |
AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23; |
| 77 |
|
| 78 |
/** \cond fulldocs */ |
| 79 |
/** Append a new NUL terminated formatted string to the specified string list */ |
| 80 |
AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va); |
| 81 |
/** \endcond */ |
| 82 |
|
| 83 |
/** Append an arbitrary length byte string to the list. Returns the |
| 84 |
* new list start. */ |
| 85 |
AvahiStringList *avahi_string_list_add_arbitrary(AvahiStringList *l, const uint8_t *text, size_t size); |
| 86 |
|
| 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 |
AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size); |
| 93 |
|
| 94 |
/** Same as avahi_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 |
AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL; |
| 98 |
|
| 99 |
/** \cond fulldocs */ |
| 100 |
/** Same as avahi_string_list_add_many(), but use a va_list |
| 101 |
* structure. Returns the new list start. */ |
| 102 |
AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va); |
| 103 |
/** \endcond */ |
| 104 |
|
| 105 |
/** @} */ |
| 106 |
|
| 107 |
/** @{ \name String list operations */ |
| 108 |
|
| 109 |
/** Convert the string list object to a single character string, |
| 110 |
* seperated by spaces and enclosed in "". avahi_free() the result! This |
| 111 |
* function doesn't work well with strings that contain NUL bytes. */ |
| 112 |
char* avahi_string_list_to_string(AvahiStringList *l); |
| 113 |
|
| 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 avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size); |
| 118 |
|
| 119 |
/** Inverse of avahi_string_list_serialize() */ |
| 120 |
int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret); |
| 121 |
/** \endcond */ |
| 122 |
|
| 123 |
/** Compare to string lists */ |
| 124 |
int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b); |
| 125 |
|
| 126 |
/** Copy a string list */ |
| 127 |
AvahiStringList *avahi_string_list_copy(const AvahiStringList *l); |
| 128 |
|
| 129 |
/** Reverse the string list. */ |
| 130 |
AvahiStringList* avahi_string_list_reverse(AvahiStringList *l); |
| 131 |
|
| 132 |
/** Return the number of elements in the string list */ |
| 133 |
unsigned avahi_string_list_length(const AvahiStringList *l); |
| 134 |
|
| 135 |
/** @} */ |
| 136 |
|
| 137 |
/** @{ \name Accessing items */ |
| 138 |
|
| 139 |
/** Returns the next item in the string list */ |
| 140 |
AvahiStringList *avahi_string_list_get_next(AvahiStringList *l); |
| 141 |
|
| 142 |
/** Returns the text for the current item */ |
| 143 |
uint8_t *avahi_string_list_get_text(AvahiStringList *l); |
| 144 |
|
| 145 |
/** Returns the size of the current text */ |
| 146 |
size_t avahi_string_list_get_size(AvahiStringList *l); |
| 147 |
|
| 148 |
/** @} */ |
| 149 |
|
| 150 |
/** @{ \name DNS-SD TXT pair handling */ |
| 151 |
|
| 152 |
/** Find the string list entry for the given DNS-SD TXT key */ |
| 153 |
AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key); |
| 154 |
|
| 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 |
* avahi_free() the strings returned in *key and *value. */ |
| 160 |
int avahi_string_list_get_pair(AvahiStringList *l, char **key, char **value, size_t *size); |
| 161 |
|
| 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 |
AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key, const char *value); |
| 165 |
|
| 166 |
/** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */ |
| 167 |
AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size); |
| 168 |
|
| 169 |
/** @} */ |
| 170 |
|
| 171 |
/** \cond fulldocs */ |
| 172 |
/** Try to find a magic service cookie in the specified DNS-SD string |
| 173 |
* list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */ |
| 174 |
uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l); |
| 175 |
/** \endcond */ |
| 176 |
|
| 177 |
AVAHI_C_DECL_END |
| 178 |
|
| 179 |
#endif |
| 180 |
|