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