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 | .. |
14 | .TH url 3mLib "20 June 1999" mLib |
15 | .SH NAME |
16 | url \- manipulation of form-urlencoded strings |
17 | .SH SYNOPSIS |
18 | .nf |
19 | .B "#include <mLib/url.h> |
20 | |
21 | .BI "void url_initenc(url_ectx *" ctx ); |
22 | .BI "void url_enc(url_ectx *" ctx ", dstr *" d , |
23 | .BI " const char *" name ", const char *" value ); |
24 | |
25 | .BI "void url_initdec(url_dctx *" ctx ", const char *" p ); |
26 | .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v ); |
27 | .fi |
28 | .SH DESCRIPTION |
29 | The functions in |
30 | .B <mLib/url.h> |
31 | read and write `form-urlencoded' data, as specified in RFC1866. The |
32 | encoding represents a sequence of name/value pairs where both the name |
33 | and value are arbitrary binary strings (although the format is optimized |
34 | for textual data). An encoded string contains no nonprintable |
35 | characters or whitespace. This interface is capable of decoding any |
36 | urlencoded string; however, it can currently only |
37 | .I encode |
38 | names and values which do not contain null bytes, because the encoding |
39 | interface uses standard C strings. |
40 | .PP |
41 | Encoding a sequence of name/value pairs is achieved using the |
42 | .B url_enc |
43 | function. It requires as input an |
44 | .IR "encoding context" , |
45 | represented as an object of type |
46 | .BR url_ectx . |
47 | This must be initialized before use by passing it to the function |
48 | .BR url_initenc . |
49 | Each call to |
50 | .B url_enc |
51 | encodes one name/value pair, appending the encoded output to a dynamic |
52 | string (see |
53 | .BR dstr (3mLib) |
54 | for details). |
55 | .PP |
56 | Decoding a sequence of name/value pairs is performed using the |
57 | .B url_dec |
58 | function. It requires as input a |
59 | .IR "decoding context" , |
60 | represented as an object of type |
61 | .BR url_dctx . |
62 | This must be initialized before use by passing it to the function |
63 | .BR url_initdec , |
64 | along with the address of the urlencoded string to decode. The string |
65 | is not modified during decoding. Each call to |
66 | .B url_dec |
67 | extracts a name/value pair. The name and value are written to the |
68 | dynamic strings |
69 | .I n |
70 | and |
71 | .IR v , |
72 | so you probably want to reset them before each call. If there are no |
73 | more name/value pairs to read, |
74 | .B url_dec |
75 | returns zero; otherwise it returns a nonzero value. |
76 | .SH EXAMPLE |
77 | The example code below demonstrates converting between a symbol table |
78 | and a urlencoded representation. The code is untested. |
79 | .VS |
80 | #include <stdlib.h> |
81 | #include <mLib/alloc.h> |
82 | #include <mLib/dstr.h> |
83 | #include <mLib/sym.h> |
84 | #include <mLib/url.h> |
85 | |
86 | typedef struct { |
87 | sym_base _b; |
88 | char *v; |
89 | } val; |
90 | |
91 | void decode(sym_table *t, const char *p) |
92 | { |
93 | url_dctx c; |
94 | dstr n = DSTR_INIT, v = DSTR_INIT; |
95 | |
96 | for (url_initdec(&c, p); url_dec(&c, &n, &v); ) { |
97 | unsigned f; |
98 | val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f); |
99 | if (f) |
100 | free(vv->v); |
101 | vv->v = xstrdup(v.buf); |
102 | DRESET(&n); |
103 | DRESET(&v); |
104 | } |
105 | dstr_destroy(&n); |
106 | dstr_destroy(&v); |
107 | } |
108 | |
109 | void encode(sym_table *t, dstr *d) |
110 | { |
111 | sym_iter i; |
112 | url_ectx c; |
113 | val *v; |
114 | |
115 | url_initenc(&c); |
116 | for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; ) |
117 | url_enc(&c, d, SYM_NAME(v), v->v); |
118 | } |
119 | .VE |
120 | .SH AUTHOR |
121 | Mark Wooding, <mdw@nsict.org>. |