Doc/lib/libxdrlib.tex

   1 \section{\module{xdrlib} ---
   2          Encode and decode XDR data.}
   3 \declaremodule{standard}{xdrlib}
   4
   5 \modulesynopsis{Encoders and decoders for the External Data
   6 Representation (XDR).}
   7
   8 \index{XDR}
   9 \index{External Data Representation}
  10
  11
  12 The \module{xdrlib} module supports the External Data Representation
  13 Standard as described in \rfc{1014}, written by Sun Microsystems,
  14 Inc. June 1987.  It supports most of the data types described in the
  15 RFC.
  16
  17 The \module{xdrlib} module defines two classes, one for packing
  18 variables into XDR representation, and another for unpacking from XDR
  19 representation.  There are also two exception classes.
  20
  21 \begin{classdesc}{Packer}{}
  22 \class{Packer} is the class for packing data into XDR representation.
  23 The \class{Packer} class is instantiated with no arguments.
  24 \end{classdesc}
  25
  26 \begin{classdesc}{Unpacker}{data}
  27 \code{Unpacker} is the complementary class which unpacks XDR data
  28 values from a string buffer.  The input buffer is given as
  29 \var{data}.
  30 \end{classdesc}
  31
  32
  33 \subsection{Packer Objects \label{xdr-packer-objects}}
  34
  35 \class{Packer} instances have the following methods:
  36
  37 \begin{methoddesc}[Packer]{get_buffer}{}
  38 Returns the current pack buffer as a string.
  39 \end{methoddesc}
  40
  41 \begin{methoddesc}[Packer]{reset}{}
  42 Resets the pack buffer to the empty string.
  43 \end{methoddesc}
  44
  45 In general, you can pack any of the most common XDR data types by
  46 calling the appropriate \code{pack_\var{type}()} method.  Each method
  47 takes a single argument, the value to pack.  The following simple data
  48 type packing methods are supported: \method{pack_uint()},
  49 \method{pack_int()}, \method{pack_enum()}, \method{pack_bool()},
  50 \method{pack_uhyper()}, and \method{pack_hyper()}.
  51
  52 \begin{methoddesc}[Packer]{pack_float}{value}
  53 Packs the single-precision floating point number \var{value}.
  54 \end{methoddesc}
  55
  56 \begin{methoddesc}[Packer]{pack_double}{value}
  57 Packs the double-precision floating point number \var{value}.
  58 \end{methoddesc}
  59
  60 The following methods support packing strings, bytes, and opaque data:
  61
  62 \begin{methoddesc}[Packer]{pack_fstring}{n, s}
  63 Packs a fixed length string, \var{s}.  \var{n} is the length of the
  64 string but it is \emph{not} packed into the data buffer.  The string
  65 is padded with null bytes if necessary to guaranteed 4 byte alignment.
  66 \end{methoddesc}
  67
  68 \begin{methoddesc}[Packer]{pack_fopaque}{n, data}
  69 Packs a fixed length opaque data stream, similarly to
  70 \method{pack_fstring()}.
  71 \end{methoddesc}
  72
  73 \begin{methoddesc}[Packer]{pack_string}{s}
  74 Packs a variable length string, \var{s}.  The length of the string is
  75 first packed as an unsigned integer, then the string data is packed
  76 with \method{pack_fstring()}.
  77 \end{methoddesc}
  78
  79 \begin{methoddesc}[Packer]{pack_opaque}{data}
  80 Packs a variable length opaque data string, similarly to
  81 \method{pack_string()}.
  82 \end{methoddesc}
  83
  84 \begin{methoddesc}[Packer]{pack_bytes}{bytes}
  85 Packs a variable length byte stream, similarly to \method{pack_string()}.
  86 \end{methoddesc}
  87
  88 The following methods support packing arrays and lists:
  89
  90 \begin{methoddesc}[Packer]{pack_list}{list, pack_item}
  91 Packs a \var{list} of homogeneous items.  This method is useful for
  92 lists with an indeterminate size; i.e. the size is not available until
  93 the entire list has been walked.  For each item in the list, an
  94 unsigned integer \code{1} is packed first, followed by the data value
  95 from the list.  \var{pack_item} is the function that is called to pack
  96 the individual item.  At the end of the list, an unsigned integer
  97 \code{0} is packed.
  98
  99 For example, to pack a list of integers, the code might appear like
 100 this:
 101
 102 \begin{verbatim}
 103 import xdrlib
 104 p = xdrlib.Packer()
 105 p.pack_list([1, 2, 3], p.pack_int)
 106 \end{verbatim}
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item}
 110 Packs a fixed length list (\var{array}) of homogeneous items.  \var{n}
 111 is the length of the list; it is \emph{not} packed into the buffer,
 112 but a \exception{ValueError} exception is raised if
 113 \code{len(\var{array})} is not equal to \var{n}.  As above,
 114 \var{pack_item} is the function used to pack each element.
 115 \end{methoddesc}
 116
 117 \begin{methoddesc}[Packer]{pack_array}{list, pack_item}
 118 Packs a variable length \var{list} of homogeneous items.  First, the
 119 length of the list is packed as an unsigned integer, then each element
 120 is packed as in \method{pack_farray()} above.
 121 \end{methoddesc}
 122
 123
 124 \subsection{Unpacker Objects \label{xdr-unpacker-objects}}
 125
 126 The \class{Unpacker} class offers the following methods:
 127
 128 \begin{methoddesc}[Unpacker]{reset}{data}
 129 Resets the string buffer with the given \var{data}.
 130 \end{methoddesc}
 131
 132 \begin{methoddesc}[Unpacker]{get_position}{}
 133 Returns the current unpack position in the data buffer.
 134 \end{methoddesc}
 135
 136 \begin{methoddesc}[Unpacker]{set_position}{position}
 137 Sets the data buffer unpack position to \var{position}.  You should be
 138 careful about using \method{get_position()} and \method{set_position()}.
 139 \end{methoddesc}
 140
 141 \begin{methoddesc}[Unpacker]{get_buffer}{}
 142 Returns the current unpack data buffer as a string.
 143 \end{methoddesc}
 144
 145 \begin{methoddesc}[Unpacker]{done}{}
 146 Indicates unpack completion.  Raises an \exception{Error} exception
 147 if all of the data has not been unpacked.
 148 \end{methoddesc}
 149
 150 In addition, every data type that can be packed with a \class{Packer},
 151 can be unpacked with an \class{Unpacker}.  Unpacking methods are of the
 152 form \code{unpack_\var{type}()}, and take no arguments.  They return the
 153 unpacked object.
 154
 155 \begin{methoddesc}[Unpacker]{unpack_float}{}
 156 Unpacks a single-precision floating point number.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[Unpacker]{unpack_double}{}
 160 Unpacks a double-precision floating point number, similarly to
 161 \method{unpack_float()}.
 162 \end{methoddesc}
 163
 164 In addition, the following methods unpack strings, bytes, and opaque
 165 data:
 166
 167 \begin{methoddesc}[Unpacker]{unpack_fstring}{n}
 168 Unpacks and returns a fixed length string.  \var{n} is the number of
 169 characters expected.  Padding with null bytes to guaranteed 4 byte
 170 alignment is assumed.
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}[Unpacker]{unpack_fopaque}{n}
 174 Unpacks and returns a fixed length opaque data stream, similarly to
 175 \method{unpack_fstring()}.
 176 \end{methoddesc}
 177
 178 \begin{methoddesc}[Unpacker]{unpack_string}{}
 179 Unpacks and returns a variable length string.  The length of the
 180 string is first unpacked as an unsigned integer, then the string data
 181 is unpacked with \method{unpack_fstring()}.
 182 \end{methoddesc}
 183
 184 \begin{methoddesc}[Unpacker]{unpack_opaque}{}
 185 Unpacks and returns a variable length opaque data string, similarly to
 186 \method{unpack_string()}.
 187 \end{methoddesc}
 188
 189 \begin{methoddesc}[Unpacker]{unpack_bytes}{}
 190 Unpacks and returns a variable length byte stream, similarly to
 191 \method{unpack_string()}.
 192 \end{methoddesc}
 193
 194 The following methods support unpacking arrays and lists:
 195
 196 \begin{methoddesc}[Unpacker]{unpack_list}{unpack_item}
 197 Unpacks and returns a list of homogeneous items.  The list is unpacked
 198 one element at a time
 199 by first unpacking an unsigned integer flag.  If the flag is \code{1},
 200 then the item is unpacked and appended to the list.  A flag of
 201 \code{0} indicates the end of the list.  \var{unpack_item} is the
 202 function that is called to unpack the items.
 203 \end{methoddesc}
 204
 205 \begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item}
 206 Unpacks and returns (as a list) a fixed length array of homogeneous
 207 items.  \var{n} is number of list elements to expect in the buffer.
 208 As above, \var{unpack_item} is the function used to unpack each element.
 209 \end{methoddesc}
 210
 211 \begin{methoddesc}[Unpacker]{unpack_array}{unpack_item}
 212 Unpacks and returns a variable length \var{list} of homogeneous items.
 213 First, the length of the list is unpacked as an unsigned integer, then
 214 each element is unpacked as in \method{unpack_farray()} above.
 215 \end{methoddesc}
 216
 217
 218 \subsection{Exceptions \label{xdr-exceptions}}
 219
 220 Exceptions in this module are coded as class instances:
 221
 222 \begin{excdesc}{Error}
 223 The base exception class.  \exception{Error} has a single public data
 224 member \member{msg} containing the description of the error.
 225 \end{excdesc}
 226
 227 \begin{excdesc}{ConversionError}
 228 Class derived from \exception{Error}.  Contains no additional instance
 229 variables.
 230 \end{excdesc}
 231
 232 Here is an example of how you would catch one of these exceptions:
 233
 234 \begin{verbatim}
 235 import xdrlib
 236 p = xdrlib.Packer()
 237 try:
 238     p.pack_double(8.01)
 239 except xdrlib.ConversionError, instance:
 240     print 'packing the double failed:', instance.msg
 241 \end{verbatim}