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 | .. |
08da152e |
14 | .TH url 3 "20 June 1999" mLib |
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 |
60 | Decoding a sequence of name/value pairs is performed using the |
61 | .B url_dec |
62 | function. It requires as input a |
63 | .IR "decoding context" , |
64 | represented as an object of type |
65 | .BR url_dctx . |
66 | This must be initialized before use by passing it to the function |
67 | .BR url_initdec , |
68 | along with the address of the urlencoded string to decode. The string |
69 | is not modified during decoding. Each call to |
70 | .B url_dec |
71 | extracts a name/value pair. The name and value are written to the |
72 | dynamic strings |
73 | .I n |
74 | and |
75 | .IR v , |
76 | so you probably want to reset them before each call. If there are no |
77 | more name/value pairs to read, |
78 | .B url_dec |
79 | returns zero; otherwise it returns a nonzero value. |
80 | .SH EXAMPLE |
81 | The example code below demonstrates converting between a symbol table |
82 | and a urlencoded representation. The code is untested. |
83 | .VS |
84 | #include <stdlib.h> |
85 | #include <mLib/alloc.h> |
86 | #include <mLib/dstr.h> |
87 | #include <mLib/sym.h> |
88 | #include <mLib/url.h> |
89 | |
90 | typedef struct { |
91 | sym_base _b; |
92 | char *v; |
93 | } val; |
94 | |
95 | void decode(sym_table *t, const char *p) |
96 | { |
97 | url_dctx c; |
98 | dstr n = DSTR_INIT, v = DSTR_INIT; |
99 | |
100 | for (url_initdec(&c, p); url_dec(&c, &n, &v); ) { |
101 | unsigned f; |
102 | val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f); |
103 | if (f) |
104 | free(vv->v); |
105 | vv->v = xstrdup(v.buf); |
106 | DRESET(&n); |
107 | DRESET(&v); |
108 | } |
109 | dstr_destroy(&n); |
110 | dstr_destroy(&v); |
111 | } |
112 | |
113 | void encode(sym_table *t, dstr *d) |
114 | { |
115 | sym_iter i; |
116 | url_ectx c; |
117 | val *v; |
118 | |
119 | url_initenc(&c); |
120 | for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; ) |
121 | url_enc(&c, d, SYM_NAME(v), v->v); |
122 | } |
123 | .VE |
08da152e |
124 | .SH "SEE ALSO" |
125 | .BR mLib (3). |
b6b9d458 |
126 | .SH AUTHOR |
127 | Mark Wooding, <mdw@nsict.org>. |