diff options
Diffstat (limited to 'Doc/libxdrlib.tex')
-rw-r--r-- | Doc/libxdrlib.tex | 232 |
1 files changed, 0 insertions, 232 deletions
diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex deleted file mode 100644 index 56459f8..0000000 --- a/Doc/libxdrlib.tex +++ /dev/null @@ -1,232 +0,0 @@ -\section{Standard Module \module{xdrlib}} -\label{module-xdrlib} -\stmodindex{xdrlib} -\index{XDR} -\index{External Data Representation} - - - -The \module{xdrlib} module supports the External Data Representation -Standard as described in \rfc{1014}, written by Sun Microsystems, -Inc. June 1987. It supports most of the data types described in the -RFC. - -The \module{xdrlib} module defines two classes, one for packing -variables into XDR representation, and another for unpacking from XDR -representation. There are also two exception classes. - -\begin{classdesc}{Packer}{} -\class{Packer} is the class for packing data into XDR representation. -The \class{Packer} class is instantiated with no arguments. -\end{classdesc} - -\begin{classdesc}{Unpacker}{data} -\code{Unpacker} is the complementary class which unpacks XDR data -values from a string buffer. The input buffer is given as -\var{data}. -\end{classdesc} - - -\subsection{Packer Objects} -\label{xdr-packer-objects} - -\class{Packer} instances have the following methods: - -\begin{methoddesc}[Packer]{get_buffer}{} -Returns the current pack buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Packer]{reset}{} -Resets the pack buffer to the empty string. -\end{methoddesc} - -In general, you can pack any of the most common XDR data types by -calling the appropriate \code{pack_\var{type}()} method. Each method -takes a single argument, the value to pack. The following simple data -type packing methods are supported: \method{pack_uint()}, -\method{pack_int()}, \method{pack_enum()}, \method{pack_bool()}, -\method{pack_uhyper()}, and \method{pack_hyper()}. - -\begin{methoddesc}[Packer]{pack_float}{value} -Packs the single-precision floating point number \var{value}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_double}{value} -Packs the double-precision floating point number \var{value}. -\end{methoddesc} - -The following methods support packing strings, bytes, and opaque data: - -\begin{methoddesc}[Packer]{pack_fstring}{n, s} -Packs a fixed length string, \var{s}. \var{n} is the length of the -string but it is \emph{not} packed into the data buffer. The string -is padded with null bytes if necessary to guaranteed 4 byte alignment. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_fopaque}{n, data} -Packs a fixed length opaque data stream, similarly to -\method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_string}{s} -Packs a variable length string, \var{s}. The length of the string is -first packed as an unsigned integer, then the string data is packed -with \method{pack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_opaque}{data} -Packs a variable length opaque data string, similarly to -\method{pack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_bytes}{bytes} -Packs a variable length byte stream, similarly to \method{pack_string()}. -\end{methoddesc} - -The following methods support packing arrays and lists: - -\begin{methoddesc}[Packer]{pack_list}{list, pack_item} -Packs a \var{list} of homogeneous items. This method is useful for -lists with an indeterminate size; i.e. the size is not available until -the entire list has been walked. For each item in the list, an -unsigned integer \code{1} is packed first, followed by the data value -from the list. \var{pack_item} is the function that is called to pack -the individual item. At the end of the list, an unsigned integer -\code{0} is packed. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item} -Packs a fixed length list (\var{array}) of homogeneous items. \var{n} -is the length of the list; it is \emph{not} packed into the buffer, -but a \exception{ValueError} exception is raised if -\code{len(\var{array})} is not equal to \var{n}. As above, -\var{pack_item} is the function used to pack each element. -\end{methoddesc} - -\begin{methoddesc}[Packer]{pack_array}{list, pack_item} -Packs a variable length \var{list} of homogeneous items. First, the -length of the list is packed as an unsigned integer, then each element -is packed as in \method{pack_farray()} above. -\end{methoddesc} - - -\subsection{Unpacker Objects} -\label{xdr-unpacker-objects} - -The \class{Unpacker} class offers the following methods: - -\begin{methoddesc}[Unpacker]{reset}{data} -Resets the string buffer with the given \var{data}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_position}{} -Returns the current unpack position in the data buffer. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{set_position}{position} -Sets the data buffer unpack position to \var{position}. You should be -careful about using \method{get_position()} and \method{set_position()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{get_buffer}{} -Returns the current unpack data buffer as a string. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{done}{} -Indicates unpack completion. Raises an \exception{Error} exception -if all of the data has not been unpacked. -\end{methoddesc} - -In addition, every data type that can be packed with a \class{Packer}, -can be unpacked with an \class{Unpacker}. Unpacking methods are of the -form \code{unpack_\var{type}()}, and take no arguments. They return the -unpacked object. - -\begin{methoddesc}[Unpacker]{unpack_float}{} -Unpacks a single-precision floating point number. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_double}{} -Unpacks a double-precision floating point number, similarly to -\method{unpack_float()}. -\end{methoddesc} - -In addition, the following methods unpack strings, bytes, and opaque -data: - -\begin{methoddesc}[Unpacker]{unpack_fstring}{n} -Unpacks and returns a fixed length string. \var{n} is the number of -characters expected. Padding with null bytes to guaranteed 4 byte -alignment is assumed. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_fopaque}{n} -Unpacks and returns a fixed length opaque data stream, similarly to -\method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_string}{} -Unpacks and returns a variable length string. The length of the -string is first unpacked as an unsigned integer, then the string data -is unpacked with \method{unpack_fstring()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_opaque}{} -Unpacks and returns a variable length opaque data string, similarly to -\method{unpack_string()}. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_bytes}{} -Unpacks and returns a variable length byte stream, similarly to -\method{unpack_string()}. -\end{methoddesc} - -The following methods support unpacking arrays and lists: - -\begin{methoddesc}[Unpacker]{unpack_list}{unpack_item} -Unpacks and returns a list of homogeneous items. The list is unpacked -one element at a time -by first unpacking an unsigned integer flag. If the flag is \code{1}, -then the item is unpacked and appended to the list. A flag of -\code{0} indicates the end of the list. \var{unpack_item} is the -function that is called to unpack the items. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item} -Unpacks and returns (as a list) a fixed length array of homogeneous -items. \var{n} is number of list elements to expect in the buffer. -As above, \var{unpack_item} is the function used to unpack each element. -\end{methoddesc} - -\begin{methoddesc}[Unpacker]{unpack_array}{unpack_item} -Unpacks and returns a variable length \var{list} of homogeneous items. -First, the length of the list is unpacked as an unsigned integer, then -each element is unpacked as in \method{unpack_farray()} above. -\end{methoddesc} - - -\subsection{Exceptions} -\nodename{xdr-exceptions} - -Exceptions in this module are coded as class instances: - -\begin{excdesc}{Error} -The base exception class. \exception{Error} has a single public data -member \member{msg} containing the description of the error. -\end{excdesc} - -\begin{excdesc}{ConversionError} -Class derived from \exception{Error}. Contains no additional instance -variables. -\end{excdesc} - -Here is an example of how you would catch one of these exceptions: - -\begin{verbatim} -import xdrlib -p = xdrlib.Packer() -try: - p.pack_double(8.01) -except xdrlib.ConversionError, instance: - print 'packing the double failed:', instance.msg -\end{verbatim} |