checkAPIs.pl: support for new-style dissectors in check_hf_entries
[metze/wireshark/wip.git] / epan / strutil.h
1 /* strutil.h
2  * String utility definitions
3  *
4  * Wireshark - Network traffic analyzer
5  * By Gerald Combs <gerald@wireshark.org>
6  * Copyright 1998 Gerald Combs
7  *
8  * SPDX-License-Identifier: GPL-2.0-or-later
9  */
10
11 #ifndef __STRUTIL_H__
12 #define __STRUTIL_H__
13
14 #include "ws_symbol_export.h"
15
16 #include <epan/wmem/wmem.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif /* __cplusplus */
21
22 /** @file
23  * String handling and conversion utilities.
24  */
25
26 /** Given a pointer into a data buffer, and to the end of the buffer,
27  *  find the end of the (putative) line at that position in the data
28  *  buffer.
29  *
30  * @param data A pointer to the beginning of the data
31  * @param dataend A pointer to the end of the data
32  * @param eol A pointer that will receive the EOL location
33  * @return A pointer to the EOL character(s) in "*eol".
34  */
35 const guchar *find_line_end(const guchar *data, const guchar *dataend,
36     const guchar **eol);
37
38 /** Get the length of the next token in a line, and the beginning of the
39  *  next token after that (if any).
40  * @param linep A pointer to the beginning of the line
41  * @param lineend A pointer to the end of the line
42  * @param next_token Receives the location of the next token
43  * @return 0 if there is no next token.
44  */
45 WS_DLL_PUBLIC
46 int        get_token_len(const guchar *linep, const guchar *lineend,
47     const guchar **next_token);
48
49 /** Given a string, generate a string from it that shows non-printable
50  *  characters as C-style escapes, and return a pointer to it.
51  *
52  * @param allocator The wmem scope
53  * @param line A pointer to the input string
54  * @param len The length of the input string
55  * @return A pointer to the formatted string
56  *
57  * @see tvb_format_text()
58  */
59 WS_DLL_PUBLIC
60 gchar*     format_text(wmem_allocator_t* allocator, const guchar *line, size_t len);
61
62 /**
63  * Given a string, generate a string from it that shows non-printable
64  * characters as C-style escapes except a whitespace character
65  * (space, tab, carriage return, new line, vertical tab, or formfeed)
66  * which will be replaced by a space, and return a pointer to it.
67  *
68  * @param allocator The wmem scope
69  * @param line A pointer to the input string
70  * @param len The length of the input string
71  * @return A pointer to the formatted string
72  *
73  */
74 WS_DLL_PUBLIC
75 gchar*     format_text_wsp(wmem_allocator_t* allocator, const guchar *line, size_t len);
76
77 /**
78  * Given a string, generate a string from it that shows non-printable
79  * characters as the chr parameter passed, except a whitespace character
80  * (space, tab, carriage return, new line, vertical tab, or formfeed)
81  * which will be replaced by a space, and return a pointer to it.
82  *
83  * @param allocator The wmem scope
84  * @param string A pointer to the input string
85  * @param len The length of the input string
86  * @param chr The character to use to replace non-printable characters
87  * @return A pointer to the formatted string
88  *
89  */
90 WS_DLL_PUBLIC
91 gchar*     format_text_chr(wmem_allocator_t* allocator, const guchar *string, const size_t len, const guchar chr);
92
93
94 /** Turn a string of hex digits with optional separators (defined by
95  *  is_byte_sep() into a byte array.
96  *
97  * @param hex_str The string of hex digits.
98  * @param bytes The GByteArray that will receive the bytes.  This
99  *        must be initialized by the caller.
100  * @param force_separators If set to TRUE, separators MUST exist between
101  *        bytes.
102  * @return True if the string was converted successfully
103  */
104 WS_DLL_PUBLIC
105 gboolean   hex_str_to_bytes(const char *hex_str, GByteArray *bytes,
106     gboolean force_separators);
107
108 /* Turn a string of hex digits with optional separators (defined by encoding)
109  * into a byte array. Unlike hex_str_to_bytes(), this will read as many hex-char
110  * pairs as possible and not error if it hits a non-hex-char; instead it just ends
111  * there. (i.e., like strtol()/atoi()/etc.) But it must see two hex chars at the
112  * beginning or it will return FALSE.
113  *
114  * @param hex_str The string of hex digits.
115  * @param bytes The GByteArray that will receive the bytes.  This
116  *        must be initialized by the caller.
117  * @param endptr if not NULL, is set to the char after the last hex character consumed.
118  * @param encoding set to one or more bitwise-or'ed ENC_SEP_* (see proto.h)
119  * @param fail_if_partial If set to TRUE, then the conversion fails if the whole
120  *    hex_str is not consumed.
121  * @return FALSE only if no bytes were generated; or if fail_if_partial is TRUE
122  *    and the entire hex_str was not consumed.
123  *
124  * If no ENC_SEP_* is set, then no separators are allowed. If multiple ENC_SEP_* are
125  * bit-or'ed, any of them can be a separator, but once the separator is seen then
126  * only its same type is accepted for the rest of the string. (i.e., it won't convert
127  * a "01:23-4567" even if ENC_SEP_COLON|ENC_SEP_DASH|ENC_SEP_NONE is passed in)
128  *
129  * This is done this way because it's likely a malformed scenario if they're mixed,
130  * and this routine is used by dissectors via tvb_get_string_XXX routines.
131  */
132 WS_DLL_PUBLIC
133 gboolean hex_str_to_bytes_encoding(const char *hex_str, GByteArray *bytes, const char **endptr,
134                                    const guint encoding, const gboolean fail_if_partial);
135
136 /** Turn an RFC 3986 percent-encoded string into a byte array.
137  *
138  * @param uri_str The string of hex digits.
139  * @param bytes The GByteArray that will receive the bytes.  This
140  *        must be initialized by the caller.
141  * @return True if the string was converted successfully
142  * @see format_uri()
143  */
144 WS_DLL_PUBLIC
145 gboolean   uri_str_to_bytes(const char *uri_str, GByteArray *bytes);
146
147 /** Turn a byte array into an RFC 3986 percent-encoded string.
148  *
149  * @param allocator The wmem scope
150  * @param bytes The GByteArray that will receive the bytes.  This
151  *        must be initialized by the caller.
152  * @param reserved_chars Normally the "gen-delims" and "sub-delims"
153  *        from RFC 3986 (":/?#[]@" and "!$&'()*+,;=" respectively)
154  *        plus space (hex value 20) are treated as reserved characters.
155  *        If this variable is non-NULL, its contents will be used
156  *        instead.
157  * @note Any non-printing character determined by isprint(), along
158  *       with the % character itself are always reserved.
159  * @see uri_str_to_bytes(),  format_text(), isprint()
160  */
161 WS_DLL_PUBLIC
162 gchar* format_uri(wmem_allocator_t* allocator, const GByteArray *bytes, const gchar *reserved_chars);
163
164 /** Turn a OID string representation (dot notation) into a byte array.
165  *
166  * @param oid_str The OID string (dot notaion).
167  * @param bytes The GByteArray that will receive the bytes.  This
168  *        must be initialized by the caller.
169  * @param is_absolute True if this is an absolute OID; false for relative OID.
170  * @return True if the string was converted successfully
171  */
172 WS_DLL_PUBLIC
173 gboolean   rel_oid_str_to_bytes(const char *oid_str, GByteArray *bytes, gboolean is_absolute);
174
175 /** Turn a OID string representation (dot notation) into a byte array.
176  *
177  * @param oid_str The OID string (dot notaion).
178  * @param bytes The GByteArray that will receive the bytes.  This
179  *        must be initialized by the caller.
180  * @return True if the string was converted successfully
181  */
182 WS_DLL_PUBLIC
183 gboolean   oid_str_to_bytes(const char *oid_str, GByteArray *bytes);
184
185 /**
186  * Create a copy of a GByteArray
187  *
188  * @param ba The byte array to be copied.
189  * @return If ba exists, a freshly allocated copy.  NULL otherwise.
190  *
191  * @todo - Should this be in strutil.c?
192  */
193 WS_DLL_PUBLIC
194 GByteArray *byte_array_dup(const GByteArray *ba);
195
196 /**
197  * Compare the contents of two GByteArrays
198  *
199  * @param ba1 A byte array
200  * @param ba2 A byte array
201  * @return If both arrays are non-NULL and their lengths are equal and
202  *         their contents are equal, returns TRUE.  Otherwise, returns
203  *         FALSE.
204  *
205  * @todo - Should this be in strutil.c?
206  */
207 WS_DLL_PUBLIC
208 gboolean byte_array_equal(GByteArray *ba1, GByteArray *ba2);
209
210
211 /** Return a XML escaped representation of the unescaped string.
212  *  The returned string must be freed when no longer in use.
213  *
214  * @param unescaped The unescaped string
215  * @return An XML-escaped representation of the input string
216  */
217 WS_DLL_PUBLIC
218 gchar*     xml_escape(const gchar *unescaped);
219
220 /**
221  * Return the first occurrence of needle in haystack.
222  * Algorithm copied from GNU's glibc 2.3.2 memcmp()
223  *
224  * @param haystack The data to search
225  * @param haystack_len The length of the search data
226  * @param needle The string to look for
227  * @param needle_len The length of the search string
228  * @return A pointer to the first occurrence of "needle" in
229  *         "haystack".  If "needle" isn't found or is NULL, or if
230  *         "needle_len" is 0, NULL is returned.
231  */
232 WS_DLL_PUBLIC
233 const guint8 * epan_memmem(const guint8 *haystack, guint haystack_len,
234                 const guint8 *needle, guint needle_len);
235
236 /** Scan a string to make sure it's valid hex.
237  *
238  * @param string The string to validate
239  * @param nbytes The length of the return buffer
240  * @return A pointer to a buffer containing the converted raw bytes.  This
241  *         buffer must be g_free()d by the caller.
242  */
243 WS_DLL_PUBLIC
244 guint8 * convert_string_to_hex(const char *string, size_t *nbytes);
245
246 /** Prep a string for case-sensitive vs case-insensitive searching.
247  *
248  * @param string The search string
249  * @param case_insensitive TRUE if case-insensitive, FALSE if not
250  * @return A direct copy of the string if it's a case-sensitive search and
251  * an uppercased version if not.  In either case the string must be g_free()d
252  * by the caller.
253  */
254 WS_DLL_PUBLIC
255 char * convert_string_case(const char *string, gboolean case_insensitive);
256
257 /** Finds the first occurrence of string 'needle' in string 'haystack'.
258  *  The matching is done in a case insensitive manner.
259  *
260  * @param haystack The string possibly containing the substring
261  * @param needle The substring to be searched
262  * @return A pointer into 'haystack' where 'needle' is first found.
263  *   Otherwise it returns NULL.
264  */
265 WS_DLL_PUBLIC
266 const char * epan_strcasestr(const char *haystack, const char *needle);
267
268 /** Guarantee a non-null string.
269  *
270  * @param string The string to check
271  * @return A pointer 'string' if it's non-null, otherwise "[NULL]".
272  */
273 WS_DLL_PUBLIC
274 const char * string_or_null(const char *string);
275
276 WS_DLL_PUBLIC
277 int escape_string_len(const char *string);
278 WS_DLL_PUBLIC
279 char * escape_string(char *dst, const char *string);
280
281
282 WS_DLL_PUBLIC
283 void IA5_7BIT_decode(unsigned char * dest, const unsigned char* src, int len);
284
285 /** Copy a string, escaping the 'chr' characters in it
286  *
287  * @param str The string to be copied
288  * @param chr The character to be escaped
289  * @return A copy of the string with every original 'chr' being
290  * transformed into double 'chr'.
291  */
292 WS_DLL_PUBLIC
293 gchar* ws_strdup_escape_char (const gchar *str, const gchar chr);
294
295 /** Copy a string, unescaping the 'chr' characters in it
296  *
297  * @param str The string to be copied
298  * @param chr The character to be escaped
299  * @return A copy of the string with every occurrence of double 'chr' in
300  * the original string being copied as a single 'chr'.
301  */
302 WS_DLL_PUBLIC
303 gchar* ws_strdup_unescape_char (const gchar *str, const gchar chr);
304
305 /** Replace values in a string
306  *
307  * @param str String containing 0 or more values to be replaced.
308  * @param old_val Old value.
309  * @param new_val New value. May be NULL, in which case occurences of
310  *                           old_value will be removed.
311  * @return A newly-allocated version of str with replacement values or
312  * NULL on failure.
313  */
314 WS_DLL_PUBLIC
315 gchar *string_replace(const gchar* str, const gchar *old_val, const gchar *new_val);
316
317 #ifdef __cplusplus
318 }
319 #endif /* __cplusplus */
320
321 #endif /* __STRUTIL_H__ */