14 .TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
16 url \- manipulation of form-urlencoded strings
23 .B "#include <mLib/url.h>"
25 .BI "void url_initenc(url_ectx *" ctx );
26 .ds mT \fBvoid url_enc(
27 .BI "\*(mTurl_ectx *" ctx ", dstr *" d ,
28 .BI "\h'\w'\*(mT'u'const char *" name ", const char *" value );
30 .BI "void url_initdec(url_dctx *" ctx ", const char *" p );
31 .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
36 read and write `form-urlencoded' data, as specified in RFC1866. The
37 encoding represents a sequence of name/value pairs where both the name
38 and value are arbitrary binary strings (although the format is optimized
39 for textual data). An encoded string contains no nonprintable
40 characters or whitespace. This interface is capable of decoding any
41 urlencoded string; however, it can currently only
43 names and values which do not contain null bytes, because the encoding
44 interface uses standard C strings.
46 Encoding a sequence of name/value pairs is achieved using the
48 function. It requires as input an
49 .IR "encoding context" ,
50 represented as an object of type
52 This must be initialized before use by passing it to the function
56 encodes one name/value pair, appending the encoded output to a dynamic
61 You can set flags in the encoding context's
66 Be strict about escaping non-alphanumeric characters. Without this,
67 potentially unsafe characters such as
71 will be left unescaped, which makes encoded filenames (for example) more
75 Be very lax about non-alphanumeric characters. Everything except
76 obviously-unsafe characters like
85 to separate name/value pairs, rather than the ampersand
88 Decoding a sequence of name/value pairs is performed using the
90 function. It requires as input a
91 .IR "decoding context" ,
92 represented as an object of type
94 This must be initialized before use by passing it to the function
96 along with the address of the urlencoded string to decode. The string
97 is not modified during decoding. Each call to
99 extracts a name/value pair. The name and value are written to the
104 so you probably want to reset them before each call. If there are no
105 more name/value pairs to read,
107 returns zero; otherwise it returns a nonzero value.
109 You can set flags in the encoding context's
116 to separate name/value pairs,
120 Without this flag, the semicolon is considered an `ordinary' character
121 which can appear unescaped as part of names and values. (Note the
122 difference from the same flag's meaning when encoding. When encoding,
125 the use of the semicolon, and when decoding, it
129 The example code below demonstrates converting between a symbol table
130 and a urlencoded representation. The code is untested.
133 #include <mLib/alloc.h>
134 #include <mLib/dstr.h>
135 #include <mLib/sym.h>
136 #include <mLib/url.h>
143 void decode(sym_table *t, const char *p)
146 dstr n = DSTR_INIT, v = DSTR_INIT;
148 for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
150 val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
153 vv->v = xstrdup(v.buf);
161 void encode(sym_table *t, dstr *d)
168 for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
169 url_enc(&c, d, SYM_NAME(v), v->v);
175 Mark Wooding, <mdw@distorted.org.uk>.