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 34AVAHI_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. */ 42typedef 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/** @{ \name Construction and destruction */ 49 50/** Create a new string list by taking a variable list of NUL 51 * terminated strings. The strings are copied using g_strdup(). The 52 * argument list must be terminated by a NULL pointer. */ 53AvahiStringList *avahi_string_list_new(const char *txt, ...) AVAHI_GCC_SENTINEL; 54 55/** \cond fulldocs */ 56/** Same as avahi_string_list_new() but pass a va_list structure */ 57AvahiStringList *avahi_string_list_new_va(va_list va); 58/** \endcond */ 59 60/** Create a new string list from a string array. The strings are 61 * copied using g_strdup(). length should contain the length of the 62 * array, or -1 if the array is NULL terminated*/ 63AvahiStringList *avahi_string_list_new_from_array(const char **array, int length); 64 65/** Free a string list */ 66void avahi_string_list_free(AvahiStringList *l); 67 68/** @} */ 69 70/** @{ \name Adding strings */ 71 72/** Append a NUL terminated string to the specified string list. The 73 * passed string is copied using g_strdup(). Returns the new list 74 * start. */ 75AvahiStringList *avahi_string_list_add(AvahiStringList *l, const char *text); 76 77/** Append a new NUL terminated formatted string to the specified string list */ 78AvahiStringList *avahi_string_list_add_printf(AvahiStringList *l, const char *format, ...) AVAHI_GCC_PRINTF_ATTR23; 79 80/** \cond fulldocs */ 81/** Append a new NUL terminated formatted string to the specified string list */ 82AvahiStringList *avahi_string_list_add_vprintf(AvahiStringList *l, const char *format, va_list va); 83/** \endcond */ 84 85/** Append an arbitrary length byte string to the list. Returns the 86 * new list start. */ 87AvahiStringList *avahi_string_list_add_arbitrary(AvahiStringList *l, const uint8_t *text, size_t size); 88 89/** Append a new entry to the string list. The string is not filled 90with data. The caller should fill in string data afterwards by writing 91it to l->text, where l is the pointer returned by this function. This 92function exists solely to optimize a few operations where otherwise 93superfluous string copying would be necessary. */ 94AvahiStringList*avahi_string_list_add_anonymous(AvahiStringList *l, size_t size); 95 96/** Same as avahi_string_list_add(), but takes a variable number of 97 * NUL terminated strings. The argument list must be terminated by a 98 * NULL pointer. Returns the new list start. */ 99AvahiStringList *avahi_string_list_add_many(AvahiStringList *r, ...) AVAHI_GCC_SENTINEL; 100 101/** \cond fulldocs */ 102/** Same as avahi_string_list_add_many(), but use a va_list 103 * structure. Returns the new list start. */ 104AvahiStringList *avahi_string_list_add_many_va(AvahiStringList *r, va_list va); 105/** \endcond */ 106 107/** @} */ 108 109/** @{ \name String list operations */ 110 111/** Convert the string list object to a single character string, 112 * seperated by spaces and enclosed in "". avahi_free() the result! This 113 * function doesn't work well with strings that contain NUL bytes. */ 114char* avahi_string_list_to_string(AvahiStringList *l); 115 116/** \cond fulldocs */ 117/** Serialize the string list object in a way that is compatible with 118 * the storing of DNS TXT records. Strings longer than 255 bytes are truncated. */ 119size_t avahi_string_list_serialize(AvahiStringList *l, void * data, size_t size); 120 121/** Inverse of avahi_string_list_serialize() */ 122int avahi_string_list_parse(const void *data, size_t size, AvahiStringList **ret); 123/** \endcond */ 124 125/** Compare to string lists */ 126int avahi_string_list_equal(const AvahiStringList *a, const AvahiStringList *b); 127 128/** Copy a string list */ 129AvahiStringList *avahi_string_list_copy(const AvahiStringList *l); 130 131/** Reverse the string list. */ 132AvahiStringList* avahi_string_list_reverse(AvahiStringList *l); 133 134/** Return the number of elements in the string list */ 135unsigned avahi_string_list_length(const AvahiStringList *l); 136 137/** @} */ 138 139/** @{ \name Accessing items */ 140 141/** Returns the next item in the string list */ 142AvahiStringList *avahi_string_list_get_next(AvahiStringList *l); 143 144/** Returns the text for the current item */ 145uint8_t *avahi_string_list_get_text(AvahiStringList *l); 146 147/** Returns the size of the current text */ 148size_t avahi_string_list_get_size(AvahiStringList *l); 149 150/** @} */ 151 152/** @{ \name DNS-SD TXT pair handling */ 153 154/** Find the string list entry for the given DNS-SD TXT key */ 155AvahiStringList *avahi_string_list_find(AvahiStringList *l, const char *key); 156 157/** Return the DNS-SD TXT key and value for the specified string list 158 * item. If size is not NULL it will be filled with the length of 159 * value. (for strings containing NUL bytes). If the entry doesn't 160 * contain a value *value will be set to NULL. You need to 161 * avahi_free() the strings returned in *key and *value. */ 162int avahi_string_list_get_pair(AvahiStringList *l, char **key, char **value, size_t *size); 163 164/** Add a new DNS-SD TXT key value pair to the string list. value may 165 * be NULL in case you want to specify a key without a value */ 166AvahiStringList *avahi_string_list_add_pair(AvahiStringList *l, const char *key, const char *value); 167 168/** Same as avahi_string_list_add_pair() but allow strings containing NUL bytes in *value. */ 169AvahiStringList *avahi_string_list_add_pair_arbitrary(AvahiStringList *l, const char *key, const uint8_t *value, size_t size); 170 171/** @} */ 172 173/** \cond fulldocs */ 174/** Try to find a magic service cookie in the specified DNS-SD string 175 * list. Or return AVAHI_SERVICE_COOKIE_INVALID if none is found. */ 176uint32_t avahi_string_list_get_service_cookie(AvahiStringList *l); 177/** \endcond */ 178 179AVAHI_C_DECL_END 180 181#endif 182 183