Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjlib-util / include / pjlib-util / scanner.h
1 /* $Id$ */
2 /* 
3  * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4  * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5  *
6  * This program 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  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19  */
20 #ifndef __PJ_SCANNER_H__
21 #define __PJ_SCANNER_H__
22
23 /**
24  * @file scanner.h
25  * @brief Text Scanning.
26  */
27
28 #include <pjlib-util/types.h>
29
30 PJ_BEGIN_DECL
31
32 /**
33  * @defgroup PJ_SCAN Fast Text Scanning
34  * @ingroup PJLIB_TEXT
35  * @brief Text scanning utility.
36  *
37  * This module describes a fast text scanning functions.
38  *
39  * @{
40  */
41 #if defined(PJ_SCANNER_USE_BITWISE) && PJ_SCANNER_USE_BITWISE != 0
42 #  include <pjlib-util/scanner_cis_bitwise.h>
43 #else
44 #  include <pjlib-util/scanner_cis_uint.h>
45 #endif
46
47 /**
48  * Initialize scanner input specification buffer.
49  *
50  * @param cs_buf    The scanner character specification.
51  */
52 PJ_DECL(void) pj_cis_buf_init(pj_cis_buf_t *cs_buf);
53
54 /**
55  * Create a new input specification.
56  *
57  * @param cs_buf    Specification buffer.
58  * @param cis       Character input specification to be initialized.
59  *
60  * @return          PJ_SUCCESS if new specification has been successfully
61  *                  created, or PJ_ETOOMANY if there are already too many
62  *                  specifications in the buffer.
63  */
64 PJ_DECL(pj_status_t) pj_cis_init(pj_cis_buf_t *cs_buf, pj_cis_t *cis);
65
66 /**
67  * Create a new input specification based on an existing specification.
68  *
69  * @param new_cis   The new specification to be initialized.
70  * @param existing  The existing specification, from which the input
71  *                  bitmask will be copied to the new specification.
72  *
73  * @return          PJ_SUCCESS if new specification has been successfully
74  *                  created, or PJ_ETOOMANY if there are already too many
75  *                  specifications in the buffer.
76  */
77 PJ_DECL(pj_status_t) pj_cis_dup(pj_cis_t *new_cis, pj_cis_t *existing);
78
79 /**
80  * Add the characters in the specified range '[cstart, cend)' to the 
81  * specification (the last character itself ('cend') is not added).
82  *
83  * @param cis       The scanner character specification.
84  * @param cstart    The first character in the range.
85  * @param cend      The next character after the last character in the range.
86  */
87 PJ_DECL(void) pj_cis_add_range( pj_cis_t *cis, int cstart, int cend);
88
89 /**
90  * Add alphabetic characters to the specification.
91  *
92  * @param cis       The scanner character specification.
93  */
94 PJ_DECL(void) pj_cis_add_alpha( pj_cis_t *cis);
95
96 /**
97  * Add numeric characters to the specification.
98  *
99  * @param cis       The scanner character specification.
100  */
101 PJ_DECL(void) pj_cis_add_num( pj_cis_t *cis);
102
103 /**
104  * Add the characters in the string to the specification.
105  *
106  * @param cis       The scanner character specification.
107  * @param str       The string.
108  */
109 PJ_DECL(void) pj_cis_add_str( pj_cis_t *cis, const char *str);
110
111 /**
112  * Add specification from another specification.
113  *
114  * @param cis       The specification is to be set.
115  * @param rhs       The specification to be copied.
116  */
117 PJ_DECL(void) pj_cis_add_cis( pj_cis_t *cis, const pj_cis_t *rhs);
118
119 /**
120  * Delete characters in the specified range from the specification.
121  *
122  * @param cis       The scanner character specification.
123  * @param cstart    The first character in the range.
124  * @param cend      The next character after the last character in the range.
125  */
126 PJ_DECL(void) pj_cis_del_range( pj_cis_t *cis, int cstart, int cend);
127
128 /**
129  * Delete characters in the specified string from the specification.
130  *
131  * @param cis       The scanner character specification.
132  * @param str       The string.
133  */
134 PJ_DECL(void) pj_cis_del_str( pj_cis_t *cis, const char *str);
135
136 /**
137  * Invert specification.
138  *
139  * @param cis       The scanner character specification.
140  */
141 PJ_DECL(void) pj_cis_invert( pj_cis_t *cis );
142
143 /**
144  * Check whether the specified character belongs to the specification.
145  *
146  * @param cis       The scanner character specification.
147  * @param c         The character to check for matching.
148  *
149  * @return          Non-zero if match (not necessarily one).
150  */
151 PJ_INLINE(int) pj_cis_match( const pj_cis_t *cis, pj_uint8_t c )
152 {
153     return PJ_CIS_ISSET(cis, c);
154 }
155
156
157 /**
158  * Flags for scanner.
159  */
160 enum
161 {
162     /** This flags specifies that the scanner should automatically skip
163         whitespaces 
164      */
165     PJ_SCAN_AUTOSKIP_WS = 1,
166
167     /** This flags specifies that the scanner should automatically skip
168         SIP header continuation. This flag implies PJ_SCAN_AUTOSKIP_WS.
169      */
170     PJ_SCAN_AUTOSKIP_WS_HEADER = 3,
171
172     /** Auto-skip new lines.
173      */
174     PJ_SCAN_AUTOSKIP_NEWLINE = 4
175 };
176
177
178 /* Forward decl. */
179 struct pj_scanner;
180
181
182 /**
183  * The callback function type to be called by the scanner when it encounters
184  * syntax error.
185  *
186  * @param scanner       The scanner instance that calls the callback .
187  */
188 typedef void (*pj_syn_err_func_ptr)(struct pj_scanner *scanner);
189
190
191 /**
192  * The text scanner structure.
193  */
194 typedef struct pj_scanner
195 {
196     char *begin;        /**< Start of input buffer.     */
197     char *end;          /**< End of input buffer.       */
198     char *curptr;       /**< Current pointer.           */
199     int   line;         /**< Current line.              */
200     char *start_line;   /**< Where current line starts. */
201     int   skip_ws;      /**< Skip whitespace flag.      */
202     pj_syn_err_func_ptr callback;   /**< Syntax error callback. */
203 } pj_scanner;
204
205
206 /**
207  * This structure can be used by application to store the state of the parser,
208  * so that the scanner state can be rollback to this state when necessary.
209  */
210 typedef struct pj_scan_state
211 {
212     char *curptr;       /**< Current scanner's pointer. */
213     int   line;         /**< Current line.              */
214     char *start_line;   /**< Start of current line.     */
215 } pj_scan_state;
216
217
218 /**
219  * Initialize the scanner. Note that the input string buffer must have
220  * length at least buflen+1 because the scanner will NULL terminate the
221  * string during initialization.
222  *
223  * @param scanner   The scanner to be initialized.
224  * @param bufstart  The input buffer to scan. Note that buffer[buflen] will be 
225  *                  filled with NULL char until scanner is destroyed, so
226  *                  the actual buffer length must be at least buflen+1.
227  * @param buflen    The length of the input buffer, which normally is
228  *                  strlen(bufstart).
229  * @param options   Zero, or combination of PJ_SCAN_AUTOSKIP_WS or
230  *                  PJ_SCAN_AUTOSKIP_WS_HEADER
231  * @param callback  Callback to be called when the scanner encounters syntax
232  *                  error condition.
233  */
234 PJ_DECL(void) pj_scan_init( pj_scanner *scanner, char *bufstart, int buflen, 
235                             unsigned options,
236                             pj_syn_err_func_ptr callback );
237
238
239 /** 
240  * Call this function when application has finished using the scanner.
241  *
242  * @param scanner   The scanner.
243  */
244 PJ_DECL(void) pj_scan_fini( pj_scanner *scanner );
245
246
247 /** 
248  * Determine whether the EOF condition for the scanner has been met.
249  *
250  * @param scanner   The scanner.
251  *
252  * @return Non-zero if scanner is EOF.
253  */
254 PJ_INLINE(int) pj_scan_is_eof( const pj_scanner *scanner)
255 {
256     return scanner->curptr >= scanner->end;
257 }
258
259
260 /** 
261  * Peek strings in current position according to parameter spec, and return
262  * the strings in parameter out. The current scanner position will not be
263  * moved. If the scanner is already in EOF state, syntax error callback will
264  * be called thrown.
265  *
266  * @param scanner   The scanner.
267  * @param spec      The spec to match input string.
268  * @param out       String to store the result.
269  *
270  * @return the character right after the peek-ed position or zero if there's
271  *         no more characters.
272  */
273 PJ_DECL(int) pj_scan_peek( pj_scanner *scanner,
274                            const pj_cis_t *spec, pj_str_t *out);
275
276
277 /** 
278  * Peek len characters in current position, and return them in out parameter.
279  * Note that whitespaces or newlines will be returned as it is, regardless
280  * of PJ_SCAN_AUTOSKIP_WS settings. If the character left is less than len, 
281  * syntax error callback will be called.
282  *
283  * @param scanner   The scanner.
284  * @param len       Length to peek.
285  * @param out       String to store the result.
286  *
287  * @return the character right after the peek-ed position or zero if there's
288  *         no more characters.
289  */
290 PJ_DECL(int) pj_scan_peek_n( pj_scanner *scanner,
291                              pj_size_t len, pj_str_t *out);
292
293
294 /** 
295  * Peek strings in current position until spec is matched, and return
296  * the strings in parameter out. The current scanner position will not be
297  * moved. If the scanner is already in EOF state, syntax error callback will
298  * be called.
299  *
300  * @param scanner   The scanner.
301  * @param spec      The peeking will stop when the input match this spec.
302  * @param out       String to store the result.
303  *
304  * @return the character right after the peek-ed position.
305  */
306 PJ_DECL(int) pj_scan_peek_until( pj_scanner *scanner,
307                                  const pj_cis_t *spec, 
308                                  pj_str_t *out);
309
310
311 /** 
312  * Get characters from the buffer according to the spec, and return them
313  * in out parameter. The scanner will attempt to get as many characters as
314  * possible as long as the spec matches. If the first character doesn't
315  * match the spec, or scanner is already in EOF when this function is called,
316  * an exception will be thrown.
317  *
318  * @param scanner   The scanner.
319  * @param spec      The spec to match input string.
320  * @param out       String to store the result.
321  */
322 PJ_DECL(void) pj_scan_get( pj_scanner *scanner,
323                            const pj_cis_t *spec, pj_str_t *out);
324
325
326 /** 
327  * Just like #pj_scan_get(), but additionally performs unescaping when
328  * escaped ('%') character is found. The input spec MUST NOT contain the
329  * specification for '%' characted.
330  *
331  * @param scanner   The scanner.
332  * @param spec      The spec to match input string.
333  * @param out       String to store the result.
334  */
335 PJ_DECL(void) pj_scan_get_unescape( pj_scanner *scanner,
336                                     const pj_cis_t *spec, pj_str_t *out);
337
338
339 /** 
340  * Get characters between quotes. If current input doesn't match begin_quote,
341  * syntax error will be thrown. Note that the resulting string will contain
342  * the enclosing quote.
343  *
344  * @param scanner       The scanner.
345  * @param begin_quote   The character to begin the quote.
346  * @param end_quote     The character to end the quote.
347  * @param out           String to store the result.
348  */
349 PJ_DECL(void) pj_scan_get_quote( pj_scanner *scanner,
350                                  int begin_quote, int end_quote, 
351                                  pj_str_t *out);
352
353 /** 
354  * Get characters between quotes. If current input doesn't match begin_quote,
355  * syntax error will be thrown. Note that the resulting string will contain
356  * the enclosing quote.
357  *
358  * @param scanner       The scanner.
359  * @param begin_quotes  The character array to begin the quotes. For example,
360  *                      the two characters " and '.
361  * @param end_quotes    The character array to end the quotes. The position
362  *                      found in the begin_quotes array will be used to match
363  *                      the end quotes. So if the begin_quotes was the array
364  *                      of "'< the end_quotes should be "'>. If begin_array
365  *                      matched the ' then the end_quotes will look for ' to
366  *                      match at the end.
367  * @param qsize         The size of the begin_quotes and end_quotes arrays.
368  * @param out           String to store the result.
369  */
370 PJ_DECL(void) pj_scan_get_quotes(pj_scanner *scanner,
371                                  const char *begin_quotes,
372                                  const char *end_quotes, int qsize,
373                                  pj_str_t *out);
374
375
376 /**
377  * Get N characters from the scanner.
378  *
379  * @param scanner   The scanner.
380  * @param N         Number of characters to get.
381  * @param out       String to store the result.
382  */
383 PJ_DECL(void) pj_scan_get_n( pj_scanner *scanner,
384                              unsigned N, pj_str_t *out);
385
386
387 /** 
388  * Get one character from the scanner.
389  *
390  * @param scanner   The scanner.
391  *
392  * @return The character.
393  */
394 PJ_DECL(int) pj_scan_get_char( pj_scanner *scanner );
395
396
397 /** 
398  * Get characters from the scanner and move the scanner position until the
399  * current character matches the spec.
400  *
401  * @param scanner   The scanner.
402  * @param spec      Get until the input match this spec.
403  * @param out       String to store the result.
404  */
405 PJ_DECL(void) pj_scan_get_until( pj_scanner *scanner,
406                                  const pj_cis_t *spec, pj_str_t *out);
407
408
409 /** 
410  * Get characters from the scanner and move the scanner position until the
411  * current character matches until_char.
412  *
413  * @param scanner       The scanner.
414  * @param until_char    Get until the input match this character.
415  * @param out           String to store the result.
416  */
417 PJ_DECL(void) pj_scan_get_until_ch( pj_scanner *scanner, 
418                                     int until_char, pj_str_t *out);
419
420
421 /** 
422  * Get characters from the scanner and move the scanner position until the
423  * current character matches until_char.
424  *
425  * @param scanner       The scanner.
426  * @param until_spec    Get until the input match any of these characters.
427  * @param out           String to store the result.
428  */
429 PJ_DECL(void) pj_scan_get_until_chr( pj_scanner *scanner,
430                                      const char *until_spec, pj_str_t *out);
431
432 /** 
433  * Advance the scanner N characters, and skip whitespace
434  * if necessary.
435  *
436  * @param scanner   The scanner.
437  * @param N         Number of characters to skip.
438  * @param skip      Flag to specify whether whitespace should be skipped
439  *                  after skipping the characters.
440  */
441 PJ_DECL(void) pj_scan_advance_n( pj_scanner *scanner,
442                                  unsigned N, pj_bool_t skip);
443
444
445 /** 
446  * Compare string in current position with the specified string.
447  * 
448  * @param scanner   The scanner.
449  * @param s         The string to compare with.
450  * @param len       Length of the string to compare.
451  *
452  * @return zero, <0, or >0 (just like strcmp()).
453  */
454 PJ_DECL(int) pj_scan_strcmp( pj_scanner *scanner, const char *s, int len);
455
456
457 /** 
458  * Case-less string comparison of current position with the specified
459  * string.
460  *
461  * @param scanner   The scanner.
462  * @param s         The string to compare with.
463  * @param len       Length of the string to compare with.
464  *
465  * @return zero, <0, or >0 (just like strcmp()).
466  */
467 PJ_DECL(int) pj_scan_stricmp( pj_scanner *scanner, const char *s, int len);
468
469 /**
470  * Perform case insensitive string comparison of string in current position,
471  * knowing that the string to compare only consists of alphanumeric
472  * characters.
473  *
474  * Note that unlike #pj_scan_stricmp, this function can only return zero or
475  * -1.
476  *
477  * @param scanner   The scanner.
478  * @param s         The string to compare with.
479  * @param len       Length of the string to compare with.
480  *
481  * @return          zero if equal or -1.
482  *
483  * @see strnicmp_alnum, pj_stricmp_alnum
484  */
485 PJ_DECL(int) pj_scan_stricmp_alnum( pj_scanner *scanner, const char *s, 
486                                     int len);
487
488
489 /** 
490  * Get a newline from the scanner. A newline is defined as '\\n', or '\\r', or
491  * "\\r\\n". If current input is not newline, syntax error will be thrown.
492  *
493  * @param scanner   The scanner.
494  */
495 PJ_DECL(void) pj_scan_get_newline( pj_scanner *scanner );
496
497
498 /** 
499  * Manually skip whitespaces according to flag that was specified when
500  * the scanner was initialized.
501  *
502  * @param scanner   The scanner.
503  */
504 PJ_DECL(void) pj_scan_skip_whitespace( pj_scanner *scanner );
505
506
507 /**
508  * Skip current line.
509  *
510  * @param scanner   The scanner.
511  */
512 PJ_DECL(void) pj_scan_skip_line( pj_scanner *scanner );
513
514 /** 
515  * Save the full scanner state.
516  *
517  * @param scanner   The scanner.
518  * @param state     Variable to store scanner's state.
519  */
520 PJ_DECL(void) pj_scan_save_state( const pj_scanner *scanner, 
521                                   pj_scan_state *state);
522
523
524 /** 
525  * Restore the full scanner state.
526  * Note that this would not restore the string if application has modified
527  * it. This will only restore the scanner scanning position.
528  *
529  * @param scanner   The scanner.
530  * @param state     State of the scanner.
531  */
532 PJ_DECL(void) pj_scan_restore_state( pj_scanner *scanner, 
533                                      pj_scan_state *state);
534
535 /**
536  * Get current column position.
537  *
538  * @param scanner   The scanner.
539  *
540  * @return          The column position.
541  */
542 PJ_INLINE(int) pj_scan_get_col( const pj_scanner *scanner )
543 {
544     return (int)(scanner->curptr - scanner->start_line);
545 }
546
547 /**
548  * @}
549  */
550
551
552 PJ_END_DECL
553
554 #endif
555