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 .BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
27 .BI " const char *" name ", const char *" value );
29 .BI "void url_initdec(url_dctx *" ctx ", const char *" p );
30 .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
35 read and write `form-urlencoded' data, as specified in RFC1866. The
36 encoding represents a sequence of name/value pairs where both the name
37 and value are arbitrary binary strings (although the format is optimized
38 for textual data). An encoded string contains no nonprintable
39 characters or whitespace. This interface is capable of decoding any
40 urlencoded string; however, it can currently only
42 names and values which do not contain null bytes, because the encoding
43 interface uses standard C strings.
45 Encoding a sequence of name/value pairs is achieved using the
47 function. It requires as input an
48 .IR "encoding context" ,
49 represented as an object of type
51 This must be initialized before use by passing it to the function
55 encodes one name/value pair, appending the encoded output to a dynamic
60 You can set flags in the encoding context's
65 Be strict about escaping non-alphanumeric characters. Without this,
66 potentially unsafe characters such as
70 will be left unescaped, which makes encoded filenames (for example) more
74 Be very lax about non-alphanumeric characters. Everything except
75 obviously-unsafe characters like
81 Decoding a sequence of name/value pairs is performed using the
83 function. It requires as input a
84 .IR "decoding context" ,
85 represented as an object of type
87 This must be initialized before use by passing it to the function
89 along with the address of the urlencoded string to decode. The string
90 is not modified during decoding. Each call to
92 extracts a name/value pair. The name and value are written to the
97 so you probably want to reset them before each call. If there are no
98 more name/value pairs to read,
100 returns zero; otherwise it returns a nonzero value.
102 The example code below demonstrates converting between a symbol table
103 and a urlencoded representation. The code is untested.
106 #include <mLib/alloc.h>
107 #include <mLib/dstr.h>
108 #include <mLib/sym.h>
109 #include <mLib/url.h>
116 void decode(sym_table *t, const char *p)
119 dstr n = DSTR_INIT, v = DSTR_INIT;
121 for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
123 val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
126 vv->v = xstrdup(v.buf);
134 void encode(sym_table *t, dstr *d)
141 for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
142 url_enc(&c, d, SYM_NAME(v), v->v);
148 Mark Wooding, <mdw@distorted.org.uk>.