all: updated FSF address in GPL text
[sip-router] / lib / cds / dstring.h
1 /* 
2  * Copyright (C) 2005 iptelorg GmbH
3  *
4  * This file is part of ser, a free SIP server.
5  *
6  * ser is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version
10  *
11  * For a license to use the ser software under conditions
12  * other than those described here, or to purchase support for this
13  * software, please contact iptel.org by e-mail at the following addresses:
14  *    info@iptel.org
15  *
16  * ser is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License
22  * along with this program; if not, write to the Free Software
23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
24  */
25
26 #ifndef __DSTRING_H
27 #define __DSTRING_H
28
29 #include <cds/sstr.h>
30
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34
35 /** \ingroup cds
36  * @{ 
37  *
38  * \defgroup cds_dstring Dynamic strings
39  *
40  * Dynamic strings were introduced to satisfy needs of presence
41  * modules when building presence documents.
42  *
43  * Dynamic string uses a list of buffers holding data. 
44  * Buffers are allocated when needed - when there is not enough
45  * space in the last buffer. The whole result can be copied into one
46  * destination buffer with \ref dstr_get_data, \ref dstr_get_str
47  * or \ref dstr_get_str_pkg function.
48  *
49  * \todo Function with sprintf syntax which will help with 
50  * readibility of code using dynamic strings.
51  * @{
52  * */
53
54 /** Buffer used by dynamic string. 
55  *
56  * \todo 'len' and 'used' can be replaced by 'unused' member 
57  * but it doesn't save too much */
58 typedef struct _dstr_buff_t {
59         int len; /**< the buffer length */
60         int used; /**< already used bytes from buffer */
61         struct _dstr_buff_t *next; /**< pointer to next buffer in the list*/
62         char data[1]; /** buffer data */
63 } dstr_buff_t;
64
65 /** Dynamic string structure. It is used
66  * for muliple appends of any strings. 
67  *
68  * \note There was an attempt to add flags for SHM/PKG memory using, ...
69  * but it shows that it slows down, thus they were removed and only the
70  * "most quick" version is used (rather two functions than one with param) */
71 typedef struct _dstring_t {
72         /** pointer to the first buffer in the list */
73         dstr_buff_t *first;
74         /** pointer to the last buffer in the list */
75         dstr_buff_t *last;
76         /** the length of whole string */
77         int len;
78         /** predefined buffer size */
79         int buff_size;
80
81         /** a operation on this string was unsuccesfull -> 
82          * all other operations will produce error */
83         int error;
84 } dstring_t;
85
86 /** Appends zero terminated string to dynamic string.
87  * \retval 0 if successful
88  * \retval negative on error */
89 int dstr_append_zt(dstring_t *dstr, const char *s);
90
91 /** Appends string with given length to dynamic string.
92  * \retval 0 if successful
93  * \retval negative on error */
94 int dstr_append(dstring_t *dstr, const char *s, int len);
95
96 /** Appends string to dynamic string.
97  * \retval 0 if successful
98  * \retval negative on error */
99 int dstr_append_str(dstring_t *dstr, const str_t *s);
100
101 /* int dstr_get_data_length(dstring_t *dstr); */
102
103 /** Returns data stored in dynamic string. It does NOT allocate
104  * space for them - it expects that the buffer is already allocated. 
105  * \retval 0 if successful
106  * \retval negative on error */
107 int dstr_get_data(dstring_t *dstr, char *dst);
108
109 /** Returns data stored in dynamic string. It allocates space for
110  * them with cds_malloc (SER's shared memory). 
111  * \retval 0 if successful
112  * \retval negative on error */
113 int dstr_get_str(dstring_t *dstr, str_t *dst);
114
115 /** Returns data stored in dynamic string. It allocates space for
116  * them with cds_malloc_pkg (SER's package memory).
117  * \retval 0 if successful
118  * \retval negative on error */
119 int dstr_get_str_pkg(dstring_t *dstr, str_t *dst);
120 /** Initializes dynamic string.
121  * \param dstr dynamic string to be initialized
122  * \param buff_size size of buffer used with this dynamic string 
123  * \retval 0 if successful
124  * \retval negative on error */
125 int dstr_init(dstring_t *dstr, int buff_size);
126
127 /** Destroys dynamic string. It frees all allocated buffers. */
128 int dstr_destroy(dstring_t *dstr);
129
130 /* returns nozero if error !!! */
131 /* int dstr_error(dstring_t *dstr);
132 void dstr_clear_error(dstring_t *dstr); */
133
134 /** Macro returning length of data stored in dynamic string. */
135 #define dstr_get_data_length(dstr) (dstr)->len
136
137 /** Macro pointing to error in dynamic string. If set
138  * there was an error during a previous operation with
139  * this dynamic string. */
140 #define dstr_error(dstr) (dstr)->error
141
142 /** Macro for cleaning error flag in dynamic string. */
143 #define dstr_clear_error(dstr) (dstr)->error = 0
144
145 /** @} 
146  @} */
147
148 #ifdef __cplusplus
149 }
150 #endif
151         
152 #endif