chiark - git - mdw - mLib/blob - man/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 3mLib "20 June 1999" mLib
  15 .SH NAME
  16 url \- manipulation of form-urlencoded strings
  17 .SH SYNOPSIS
  18 .nf
  19 .B "#include <mLib/url.h>
  20
  21 .BI "void url_initenc(url_ectx *" ctx );
  22 .BI "void url_enc(url_ectx *" ctx ", dstr *" d ,
  23 .BI "             const char *" name ", const char *" value );
  24
  25 .BI "void url_initdec(url_dctx *" ctx ", const char *" p );
  26 .BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
  27 .fi
  28 .SH DESCRIPTION
  29 The functions in
  30 .B <mLib/url.h>
  31 read and write `form-urlencoded' data, as specified in RFC1866.  The
  32 encoding represents a sequence of name/value pairs where both the name
  33 and value are arbitrary binary strings (although the format is optimized
  34 for textual data).  An encoded string contains no nonprintable
  35 characters or whitespace.  This interface is capable of decoding any
  36 urlencoded string; however, it can currently only
  37 .I encode
  38 names and values which do not contain null bytes, because the encoding
  39 interface uses standard C strings.
  40 .PP
  41 Encoding a sequence of name/value pairs is achieved using the
  42 .B url_enc
  43 function.  It requires as input an
  44 .IR "encoding context" ,
  45 represented as an object of type
  46 .BR url_ectx .
  47 This must be initialized before use by passing it to the function
  48 .BR url_initenc .
  49 Each call to
  50 .B url_enc
  51 encodes one name/value pair, appending the encoded output to a dynamic
  52 string (see
  53 .BR dstr (3mLib)
  54 for details).
  55 .PP
  56 Decoding a sequence of name/value pairs is performed using the
  57 .B url_dec
  58 function.  It requires as input a
  59 .IR "decoding context" ,
  60 represented as an object of type
  61 .BR url_dctx .
  62 This must be initialized before use by passing it to the function
  63 .BR url_initdec ,
  64 along with the address of the urlencoded string to decode.  The string
  65 is not modified during decoding.  Each call to
  66 .B url_dec
  67 extracts a name/value pair.  The name and value are written to the
  68 dynamic strings
  69 .I n
  70 and
  71 .IR v ,
  72 so you probably want to reset them before each call.  If there are no
  73 more name/value pairs to read,
  74 .B url_dec
  75 returns zero; otherwise it returns a nonzero value.
  76 .SH EXAMPLE
  77 The example code below demonstrates converting between a symbol table
  78 and a urlencoded representation.  The code is untested.
  79 .VS
  80 #include <stdlib.h>
  81 #include <mLib/alloc.h>
  82 #include <mLib/dstr.h>
  83 #include <mLib/sym.h>
  84 #include <mLib/url.h>
  85
  86 typedef struct {
  87   sym_base _b;
  88   char *v;
  89 } val;
  90
  91 void decode(sym_table *t, const char *p)
  92 {
  93   url_dctx c;
  94   dstr n = DSTR_INIT, v = DSTR_INIT;
  95
  96   for (url_initdec(&c, p); url_dec(&c, &n, &v); ) {
  97     unsigned f;
  98     val *vv = sym_find(t, n.buf, -1, sizeof(*vv), &f);
  99     if (f)
 100       free(vv->v);
 101     vv->v = xstrdup(v.buf);
 102     DRESET(&n);
 103     DRESET(&v);
 104   }
 105   dstr_destroy(&n);
 106   dstr_destroy(&v);
 107 }
 108
 109 void encode(sym_table *t, dstr *d)
 110 {
 111   sym_iter i;
 112   url_ectx c;
 113   val *v;
 114
 115   url_initenc(&c);
 116   for (sym_mkiter(&i, t); (v = sym_next(&i)) != 0; )
 117     url_enc(&c, d, SYM_NAME(v), v->v);
 118 }
 119 .VE
 120 .SH AUTHOR
 121 Mark Wooding, <mdw@nsict.org>.