Commit | Line | Data |
---|---|---|
b6b9d458 | 1 | .\" -*-nroff-*- |
2 | .de VS | |
3 | .sp 1 | |
4 | .in +5n | |
5 | .ft B | |
6 | .nf | |
7 | .. | |
8 | .de VE | |
9 | .ft R | |
10 | .in -5n | |
11 | .sp 1 | |
12 | .fi | |
13 | .. | |
fbf20b5b | 14 | .TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library" |
b6b9d458 | 15 | .SH NAME |
16 | url \- manipulation of form-urlencoded strings | |
08da152e | 17 | .\" @url_initenc |
18 | .\" @url_enc | |
19 | .\" @url_initdec | |
20 | .\" @url_dec | |
b6b9d458 | 21 | .SH SYNOPSIS |
22 | .nf | |
d2a91066 | 23 | .B "#include <mLib/url.h>" |
b6b9d458 | 24 | |
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 ); | |
28 | ||
29 | .BI "void url_initdec(url_dctx *" ctx ", const char *" p ); | |
30 | .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v ); | |
31 | .fi | |
32 | .SH DESCRIPTION | |
33 | The functions in | |
34 | .B <mLib/url.h> | |
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 | |
41 | .I encode | |
42 | names and values which do not contain null bytes, because the encoding | |
43 | interface uses standard C strings. | |
44 | .PP | |
45 | Encoding a sequence of name/value pairs is achieved using the | |
46 | .B url_enc | |
47 | function. It requires as input an | |
48 | .IR "encoding context" , | |
49 | represented as an object of type | |
50 | .BR url_ectx . | |
51 | This must be initialized before use by passing it to the function | |
52 | .BR url_initenc . | |
53 | Each call to | |
54 | .B url_enc | |
55 | encodes one name/value pair, appending the encoded output to a dynamic | |
56 | string (see | |
08da152e | 57 | .BR dstr (3) |
b6b9d458 | 58 | for details). |
59 | .PP | |
7e4708e4 MW |
60 | You can set flags in the encoding context's |
61 | .B f | |
62 | member: | |
63 | .TP | |
64 | .B URLF_STRICT | |
65 | Be strict about escaping non-alphanumeric characters. Without this, | |
d4efbcd9 | 66 | potentially unsafe characters such as |
7e4708e4 MW |
67 | .RB ` / ' |
68 | and | |
69 | .RB ` ~ ' | |
70 | will be left unescaped, which makes encoded filenames (for example) more | |
71 | readable. | |
72 | .TP | |
73 | .B URLF_LAX | |
74 | Be very lax about non-alphanumeric characters. Everything except | |
75 | obviously-unsafe characters like | |
76 | .RB ` & ' | |
d4efbcd9 | 77 | and |
7e4708e4 MW |
78 | .RB ` = ' |
79 | are left unescaped. | |
80 | .PP | |
b6b9d458 | 81 | Decoding a sequence of name/value pairs is performed using the |
82 | .B url_dec | |
83 | function. It requires as input a | |
84 | .IR "decoding context" , | |
85 | represented as an object of type | |
86 | .BR url_dctx . | |
87 | This must be initialized before use by passing it to the function | |
88 | .BR url_initdec , | |
89 | along with the address of the urlencoded string to decode. The string | |
90 | is not modified during decoding. Each call to | |
91 | .B url_dec | |
92 | extracts a name/value pair. The name and value are written to the | |
93 | dynamic strings | |
94 | .I n | |
95 | and | |
96 | .IR v , | |
97 | so you probably want to reset them before each call. If there are no | |
98 | more name/value pairs to read, | |
99 | .B url_dec | |
100 | returns zero; otherwise it returns a nonzero value. | |
101 | .SH EXAMPLE | |
102 | The example code below demonstrates converting between a symbol table | |
103 | and a urlencoded representation. The code is untested. | |
104 | .VS | |
105 | #include <stdlib.h> | |
106 | #include <mLib/alloc.h> | |
107 | #include <mLib/dstr.h> | |
108 | #include <mLib/sym.h> | |
109 | #include <mLib/url.h> | |
110 | ||
111 | typedef struct { | |
112 | sym_base _b; | |
113 | char *v; | |
114 | } val; | |
115 | ||
116 | void decode(sym_table *t, const char *p) | |
117 | { | |
118 | url_dctx c; | |
119 | dstr n = DSTR_INIT, v = DSTR_INIT; | |
120 | ||
121 | for (url_initdec(&c, p); url_dec(&c, &n, &v); ) { | |
122 | unsigned f; | |
123 | val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f); | |
124 | if (f) | |
125 | free(vv->v); | |
126 | vv->v = xstrdup(v.buf); | |
127 | DRESET(&n); | |
128 | DRESET(&v); | |
129 | } | |
130 | dstr_destroy(&n); | |
131 | dstr_destroy(&v); | |
132 | } | |
133 | ||
134 | void encode(sym_table *t, dstr *d) | |
135 | { | |
136 | sym_iter i; | |
137 | url_ectx c; | |
138 | val *v; | |
139 | ||
140 | url_initenc(&c); | |
141 | for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; ) | |
142 | url_enc(&c, d, SYM_NAME(v), v->v); | |
143 | } | |
144 | .VE | |
08da152e | 145 | .SH "SEE ALSO" |
146 | .BR mLib (3). | |
b6b9d458 | 147 | .SH AUTHOR |
9b5ac6ff | 148 | Mark Wooding, <mdw@distorted.org.uk>. |