+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-url \- manipulation of form-urlencoded strings
-.\" @url_initenc
-.\" @url_enc
-.\" @url_initdec
-.\" @url_dec
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/url.h>"
-
-.BI "void url_initenc(url_ectx *" ctx );
-.BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
-.BI " const char *" name ", const char *" value );
-
-.BI "void url_initdec(url_dctx *" ctx ", const char *" p );
-.BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
-.fi
-.SH DESCRIPTION
-The functions in
-.B <mLib/url.h>
-read and write `form-urlencoded' data, as specified in RFC1866. The
-encoding represents a sequence of name/value pairs where both the name
-and value are arbitrary binary strings (although the format is optimized
-for textual data). An encoded string contains no nonprintable
-characters or whitespace. This interface is capable of decoding any
-urlencoded string; however, it can currently only
-.I encode
-names and values which do not contain null bytes, because the encoding
-interface uses standard C strings.
-.PP
-Encoding a sequence of name/value pairs is achieved using the
-.B url_enc
-function. It requires as input an
-.IR "encoding context" ,
-represented as an object of type
-.BR url_ectx .
-This must be initialized before use by passing it to the function
-.BR url_initenc .
-Each call to
-.B url_enc
-encodes one name/value pair, appending the encoded output to a dynamic
-string (see
-.BR dstr (3)
-for details).
-.PP
-You can set flags in the encoding context's
-.B f
-member:
-.TP
-.B URLF_STRICT
-Be strict about escaping non-alphanumeric characters. Without this,
-potentially unsafe characters such as
-.RB ` / '
-and
-.RB ` ~ '
-will be left unescaped, which makes encoded filenames (for example) more
-readable.
-.TP
-.B URLF_LAX
-Be very lax about non-alphanumeric characters. Everything except
-obviously-unsafe characters like
-.RB ` & '
-and
-.RB ` = '
-are left unescaped.
-.PP
-Decoding a sequence of name/value pairs is performed using the
-.B url_dec
-function. It requires as input a
-.IR "decoding context" ,
-represented as an object of type
-.BR url_dctx .
-This must be initialized before use by passing it to the function
-.BR url_initdec ,
-along with the address of the urlencoded string to decode. The string
-is not modified during decoding. Each call to
-.B url_dec
-extracts a name/value pair. The name and value are written to the
-dynamic strings
-.I n
-and
-.IR v ,
-so you probably want to reset them before each call. If there are no
-more name/value pairs to read,
-.B url_dec
-returns zero; otherwise it returns a nonzero value.
-.SH EXAMPLE
-The example code below demonstrates converting between a symbol table
-and a urlencoded representation. The code is untested.
-.VS
-#include <stdlib.h>
-#include <mLib/alloc.h>
-#include <mLib/dstr.h>
-#include <mLib/sym.h>
-#include <mLib/url.h>
-
-typedef struct {
- sym_base _b;
- char *v;
-} val;
-
-void decode(sym_table *t, const char *p)
-{
- url_dctx c;
- dstr n = DSTR_INIT, v = DSTR_INIT;
-
- for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
- unsigned f;
- val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
- if (f)
- free(vv->v);
- vv->v = xstrdup(v.buf);
- DRESET(&n);
- DRESET(&v);
- }
- dstr_destroy(&n);
- dstr_destroy(&v);
-}
-
-void encode(sym_table *t, dstr *d)
-{
- sym_iter i;
- url_ectx c;
- val *v;
-
- url_initenc(&c);
- for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
- url_enc(&c, d, SYM_NAME(v), v->v);
-}
-.VE
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>.
~mdw / mLib / blobdiff