chiark - git - mdw - mLib/blob - codec/url.3

   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 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
  15 .SH NAME
  16 url \- manipulation of form-urlencoded strings
  17 .\" @url_initenc
  18 .\" @url_enc
  19 .\" @url_initdec
  20 .\" @url_dec
  21 .SH SYNOPSIS
  22 .nf
  23 .B "#include <mLib/url.h>"
  24
  25 .ta 2n
  26 .B "typedef struct {"
  27 .B "    unsigned f;"
  28 .B "    ..."
  29 .B "} url_ectx;"
  30
  31 .B "typedef struct {"
  32 .B "    unsigned f;"
  33 .B "    ..."
  34 .B "} url_dctx;"
  35
  36 .B "#define URLF_STRICT ..."
  37 .B "#define URLF_LAX ..."
  38 .B "#define URLF_SEMI ..."
  39
  40 .BI "void url_initenc(url_ectx *" ctx );
  41 .ta \w'\fBvoid url_enc('u
  42 .BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
  43 .BI "   const char *" name ", const char *" value );
  44
  45 .BI "void url_initdec(url_dctx *" ctx ", const char *" p );
  46 .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
  47 .fi
  48 .SH DESCRIPTION
  49 The functions in
  50 .B <mLib/url.h>
  51 read and write `form-urlencoded' data, as specified in RFC1866.  The
  52 encoding represents a sequence of name/value pairs where both the name
  53 and value are arbitrary binary strings (although the format is optimized
  54 for textual data).  An encoded string contains no nonprintable
  55 characters or whitespace.  This interface is capable of decoding any
  56 urlencoded string; however, it can currently only
  57 .I encode
  58 names and values which do not contain null bytes, because the encoding
  59 interface uses standard C strings.
  60 .PP
  61 Encoding a sequence of name/value pairs is achieved using the
  62 .B url_enc
  63 function.  It requires as input an
  64 .IR "encoding context" ,
  65 represented as an object of type
  66 .BR url_ectx .
  67 This must be initialized before use by passing it to the function
  68 .BR url_initenc .
  69 Each call to
  70 .B url_enc
  71 encodes one name/value pair, appending the encoded output to a dynamic
  72 string (see
  73 .BR dstr (3)
  74 for details).
  75 .PP
  76 You can set flags in the encoding context's
  77 .B f
  78 member:
  79 .TP
  80 .B URLF_STRICT
  81 Be strict about escaping non-alphanumeric characters.  Without this,
  82 potentially unsafe characters such as
  83 .RB ` / '
  84 and
  85 .RB ` ~ '
  86 will be left unescaped, which makes encoded filenames (for example) more
  87 readable.
  88 .TP
  89 .B URLF_LAX
  90 Be very lax about non-alphanumeric characters.  Everything except
  91 obviously-unsafe characters like
  92 .RB ` & '
  93 and
  94 .RB ` = '
  95 are left unescaped.
  96 .TP
  97 .B URLF_SEMI
  98 Use a semicolon
  99 .RB ` ; '
 100 to separate name/value pairs, rather than the ampersand
 101 .RB ` & '.
 102 .PP
 103 Decoding a sequence of name/value pairs is performed using the
 104 .B url_dec
 105 function.  It requires as input a
 106 .IR "decoding context" ,
 107 represented as an object of type
 108 .BR url_dctx .
 109 This must be initialized before use by passing it to the function
 110 .BR url_initdec ,
 111 along with the address of the urlencoded string to decode.  The string
 112 is not modified during decoding.  Each call to
 113 .B url_dec
 114 extracts a name/value pair.  The name and value are written to the
 115 dynamic strings
 116 .I n
 117 and
 118 .IR v ,
 119 so you probably want to reset them before each call.  If there are no
 120 more name/value pairs to read,
 121 .B url_dec
 122 returns zero; otherwise it returns a nonzero value.
 123 .PP
 124 You can set flags in the encoding context's
 125 .B f
 126 member:
 127 .TP
 128 .B URLF_SEMI
 129 Allow a semicolon
 130 .RB ` ; '
 131 to separate name/value pairs,
 132 .I in addition to
 133 the ampersand
 134 .RB ` & '.
 135 Without this flag, the semicolon is considered an `ordinary' character
 136 which can appear unescaped as part of names and values.  (Note the
 137 difference from the same flag's meaning when encoding.  When encoding,
 138 it
 139 .I forces
 140 the use of the semicolon, and when decoding, it
 141 .I permits
 142 its use.)
 143 .SH EXAMPLE
 144 The example code below demonstrates converting between a symbol table
 145 and a urlencoded representation.  The code is untested.
 146 .VS
 147 .ta 2n +2n
 148 #include <stdlib.h>
 149 #include <mLib/alloc.h>
 150 #include <mLib/dstr.h>
 151 #include <mLib/sym.h>
 152 #include <mLib/url.h>
 153
 154 typedef struct {
 155         sym_base _b;
 156         char *v;
 157 } val;
 158
 159 void decode(sym_table *t, const char *p)
 160 {
 161         url_dctx c;
 162         dstr n = DSTR_INIT, v = DSTR_INIT;
 163         val *vv;
 164         unsigned f;
 165
 166         for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
 167                 vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
 168                 if (f) free(vv->v);
 169                 vv->v = xstrdup(v.buf);
 170                 DRESET(&n);
 171                 DRESET(&v);
 172         }
 173         dstr_destroy(&n); dstr_destroy(&v);
 174 }
 175
 176 void encode(sym_table *t, dstr *d)
 177 {
 178         sym_iter i;
 179         url_ectx c;
 180         val *v;
 181
 182         url_initenc(&c);
 183         for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
 184                 url_enc(&c, d, SYM_NAME(v), v->v);
 185 }
 186 .VE
 187 .SH "SEE ALSO"
 188 .BR mLib (3).
 189 .SH AUTHOR
 190 Mark Wooding, <mdw@distorted.org.uk>.