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