Doc/libxdrlib.tex

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