Kannel: Open Source WAP and SMS gateway  svn-r5335
parse.h
Go to the documentation of this file.
1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2018 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Kannel Group (http://www.kannel.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  * endorse or promote products derived from this software without
29  * prior written permission. For written permission, please
30  * contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  * nor may "Kannel" appear in their name, without prior written
34  * permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group. For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * parse.h - functions for octet-by-octet parsing of an octstr
59  *
60  * Interface to keep track of position in an octstr, and remember
61  * error conditions so that they can be checked after a bunch of
62  * calls. Also allows temporary clipping of the string, so that
63  * parsing doesn't go past a boundary until it's explicitly allowed
64  * to. This helps parse strings containing length-defined chunks.
65  *
66  * The main use of this interface is to simplify code that does
67  * this kind of parsing, so that it can pass around a single
68  * ParseContext value instead of an octstr and one or more offset
69  * and length parameters.
70  *
71  * Note: The octstr involved MUST NOT change during parsing.
72  *
73  * Richard Braakman
74  */
75 
76 #ifndef PARSE_H
77 #define PARSE_H
78 
79 typedef struct context ParseContext;
80 
81 /*
82  * Return a ParseContext object for this octstr, with parsing starting
83  * at position 0 and the limit at the end of the string.
84  */
86 
87 /*
88  * Destroy a ParseContext object. Note that this does not free the string
89  * that was parsed.
90  */
92 
93 /*
94  * Return -1 if any error has occurred during parsing, otherwise 0.
95  */
97 
98 /*
99  * Clear the error flag for the next call to parse_error.
100  */
102 
103 /*
104  * Set the error flag.
105  */
107 
108 /*
109  * Set a new "end" of the string, for parsing purposes, at length
110  * octets from the current position. Return 0 if it's okay.
111  * If it doesn't fit in the current limit, don't do anything and
112  * return -1.
113  */
114 int parse_limit(ParseContext *context, long length);
115 
116 /*
117  * Restore the previous "end" of the string. Limits can be stacked
118  * as deeply as needed. The original limit (end-of-string) can
119  * not be popped. Return -1 and set the error flag if there was
120  * nothing to pop, otherwise return 0.
121  */
123 
124 /*
125  * Return the number of octets between the current position and
126  * the current limit.
127  */
129 
130 /*
131  * Skip count octets. If that would go past the limit, return -1,
132  * skip to the limit, and set the error flag. Otherwise return 0.
133  */
134 int parse_skip(ParseContext *context, long count);
135 
136 /*
137  * Skip to the current limit. Cannot fail.
138  */
140 
141 /*
142  * Set offset to new position. If that would go past the limit, return
143  * -1, skip to the limit, and set the error flag. Otherwise return 0.
144  */
146 
147 /*
148  * Return the next octet, but do not skip over it.
149  * If already at the limit, return -1 and set the error flag.
150  */
152 
153 /*
154  * Return the next octet and skip one position forward.
155  * If already at the limit, return -1 and set the error flag.
156  */
158 
159 /*
160  * Return "length" octets starting at current position, and skip
161  * that many octets forward. If that would go over the limit,
162  * return NULL, do not skip, and set the error flag.
163  */
165 
166 /*
167  * Return the value of an uintvar-encoded integer at current
168  * position, then skip over it. If there's an error in the
169  * encoding, or if it would go past the limit, then return 0,
170  * do not skip, and set the error flag. Since 0 is a valid
171  * uintvar value, the error flag is only way to detect this error.
172  */
173 unsigned long parse_get_uintvar(ParseContext *context);
174 
175 /*
176  * Look for a NUL-terminated string starting at the current offset,
177  * and return it (without the NUL) as an Octstr. Skip forward past
178  * the NUL. If there is no NUL, return NULL and set the error flag.
179  */
181 
182 /*
183  * Look for a EOL-terminated line starting at the current offset,
184  * and return it (without the EOL) as an Octstr. Skip forward past
185  * the EOL. If there is no EOL, return NULL and set the error flag.
186  */
188 
189 /*
190  * Look for an Octstr block that is between two seperators defined by
191  * the seperator Octstr. Return the Octstr between the seperators and
192  * move the parsing context up before the last of the two seperators.
193  * So the last seperator is next in the parsing scope. If there are
194  * no two seperators in the parsing scope return NULL.
195  */
197 
198 /*
199  * Return unparsed content. This should be used only after all
200  * headers are parsed (and the headers and content are stored in
201  * same octstr).
202  */
204 
205 #endif
long parse_octets_left(ParseContext *context)
Definition: parse.c:159
Octstr * parse_get_octets(ParseContext *context, long length)
Definition: parse.c:230
Definition: parse.c:65
void parse_skip_to_limit(ParseContext *context)
Definition: parse.c:180
int parse_pop_limit(ParseContext *context)
Definition: parse.c:142
long pos
Definition: parse.c:68
Octstr * parse_get_nul_string(ParseContext *context)
Definition: parse.c:263
int parse_peek_char(ParseContext *context)
Definition: parse.c:206
unsigned long parse_get_uintvar(ParseContext *context)
Definition: parse.c:246
void parse_clear_error(ParseContext *context)
Definition: parse.c:107
int parse_skip_to(ParseContext *context, long pos)
Definition: parse.c:187
int parse_limit(ParseContext *context, long length)
Definition: parse.c:121
void parse_set_error(ParseContext *context)
Definition: parse.c:114
void parse_context_destroy(ParseContext *context)
Definition: parse.c:88
Octstr * parse_get_rest(ParseContext *context)
Definition: parse.c:329
int parse_get_char(ParseContext *context)
Definition: parse.c:218
Definition: octstr.c:118
int parse_error(ParseContext *context)
Definition: parse.c:100
Octstr * parse_get_line(ParseContext *context)
Definition: parse.c:282
ParseContext * parse_context_create(Octstr *str)
Definition: parse.c:74
Octstr * parse_get_seperated_block(ParseContext *context, Octstr *seperator)
Definition: parse.c:303
int parse_skip(ParseContext *context, long count)
Definition: parse.c:166
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.