14 .TH url 3 "20 June 1999" mLib
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 Decoding a sequence of name/value pairs is performed using the
62 function. It requires as input a
63 .IR "decoding context" ,
64 represented as an object of type
66 This must be initialized before use by passing it to the function
68 along with the address of the urlencoded string to decode. The string
69 is not modified during decoding. Each call to
71 extracts a name/value pair. The name and value are written to the
76 so you probably want to reset them before each call. If there are no
77 more name/value pairs to read,
79 returns zero; otherwise it returns a nonzero value.
81 The example code below demonstrates converting between a symbol table
82 and a urlencoded representation. The code is untested.
85 #include <mLib/alloc.h>
86 #include <mLib/dstr.h>
95 void decode(sym_table *t, const char *p)
98 dstr n = DSTR_INIT, v = DSTR_INIT;
100 for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
102 val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
105 vv->v = xstrdup(v.buf);
113 void encode(sym_table *t, dstr *d)
120 for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
121 url_enc(&c, d, SYM_NAME(v), v->v);
127 Mark Wooding, <mdw@nsict.org>.