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