Doc/lib/libxdrlib.tex

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