chiark / gitweb /
Import buf from Catacomb; split out the dstr bits, and throw away the mp and
[mLib] / man / url.3
CommitLineData
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
16url \- 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
33The functions in
34.B <mLib/url.h>
35read and write `form-urlencoded' data, as specified in RFC1866. The
36encoding represents a sequence of name/value pairs where both the name
37and value are arbitrary binary strings (although the format is optimized
38for textual data). An encoded string contains no nonprintable
39characters or whitespace. This interface is capable of decoding any
40urlencoded string; however, it can currently only
41.I encode
42names and values which do not contain null bytes, because the encoding
43interface uses standard C strings.
44.PP
45Encoding a sequence of name/value pairs is achieved using the
46.B url_enc
47function. It requires as input an
48.IR "encoding context" ,
49represented as an object of type
50.BR url_ectx .
51This must be initialized before use by passing it to the function
52.BR url_initenc .
53Each call to
54.B url_enc
55encodes one name/value pair, appending the encoded output to a dynamic
56string (see
08da152e 57.BR dstr (3)
b6b9d458 58for details).
59.PP
60Decoding a sequence of name/value pairs is performed using the
61.B url_dec
62function. It requires as input a
63.IR "decoding context" ,
64represented as an object of type
65.BR url_dctx .
66This must be initialized before use by passing it to the function
67.BR url_initdec ,
68along with the address of the urlencoded string to decode. The string
69is not modified during decoding. Each call to
70.B url_dec
71extracts a name/value pair. The name and value are written to the
72dynamic strings
73.I n
74and
75.IR v ,
76so you probably want to reset them before each call. If there are no
77more name/value pairs to read,
78.B url_dec
79returns zero; otherwise it returns a nonzero value.
80.SH EXAMPLE
81The example code below demonstrates converting between a symbol table
82and 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
90typedef struct {
91 sym_base _b;
92 char *v;
93} val;
94
95void 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
113void 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
9b5ac6ff 127Mark Wooding, <mdw@distorted.org.uk>.