diff options
Diffstat (limited to 'Doc/libxdrlib.tex')
-rw-r--r-- | Doc/libxdrlib.tex | 110 |
1 files changed, 56 insertions, 54 deletions
diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex index cea50e0..6157c9d 100644 --- a/Doc/libxdrlib.tex +++ b/Doc/libxdrlib.tex @@ -32,13 +32,13 @@ values from a string buffer. The input buffer is given as \class{Packer} instances have the following methods: -\begin{funcdesc}{get_buffer}{} +\begin{methoddesc}[Packer]{get_buffer}{} Returns the current pack buffer as a string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{reset}{} +\begin{methoddesc}[Packer]{reset}{} Resets the pack buffer to the empty string. -\end{funcdesc} +\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 @@ -47,45 +47,45 @@ 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{funcdesc}{pack_float}{value} +\begin{methoddesc}[Packer]{pack_float}{value} Packs the single-precision floating point number \var{value}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_double}{value} +\begin{methoddesc}[Packer]{pack_double}{value} Packs the double-precision floating point number \var{value}. -\end{funcdesc} +\end{methoddesc} The following methods support packing strings, bytes, and opaque data: -\begin{funcdesc}{pack_fstring}{n, s} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_fopaque}{n, data} +\begin{methoddesc}[Packer]{pack_fopaque}{n, data} Packs a fixed length opaque data stream, similarly to \method{pack_fstring()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_string}{s} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_opaque}{data} +\begin{methoddesc}[Packer]{pack_opaque}{data} Packs a variable length opaque data string, similarly to \method{pack_string()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_bytes}{bytes} +\begin{methoddesc}[Packer]{pack_bytes}{bytes} Packs a variable length byte stream, similarly to \method{pack_string()}. -\end{funcdesc} +\end{methoddesc} The following methods support packing arrays and lists: -\begin{funcdesc}{pack_list}{list, pack_item} +\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 @@ -93,115 +93,117 @@ 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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_farray}{n, array, pack_item} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{pack_array}{list, pack_item} +\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{funcdesc} +\end{methoddesc} + \subsection{Unpacker Objects} \label{xdr-unpacker-objects} The \class{Unpacker} class offers the following methods: -\begin{funcdesc}{reset}{data} +\begin{methoddesc}[Unpacker]{reset}{data} Resets the string buffer with the given \var{data}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{get_position}{} +\begin{methoddesc}[Unpacker]{get_position}{} Returns the current unpack position in the data buffer. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{set_position}{position} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{get_buffer}{} +\begin{methoddesc}[Unpacker]{get_buffer}{} Returns the current unpack data buffer as a string. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{done}{} +\begin{methoddesc}[Unpacker]{done}{} Indicates unpack completion. Raises an \exception{Error} exception if all of the data has not been unpacked. -\end{funcdesc} +\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{funcdesc}{unpack_float}{} +\begin{methoddesc}[Unpacker]{unpack_float}{} Unpacks a single-precision floating point number. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_double}{} +\begin{methoddesc}[Unpacker]{unpack_double}{} Unpacks a double-precision floating point number, similarly to \method{unpack_float()}. -\end{funcdesc} +\end{methoddesc} In addition, the following methods unpack strings, bytes, and opaque data: -\begin{funcdesc}{unpack_fstring}{n} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_fopaque}{n} +\begin{methoddesc}[Unpacker]{unpack_fopaque}{n} Unpacks and returns a fixed length opaque data stream, similarly to \method{unpack_fstring()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_string}{} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_opaque}{} +\begin{methoddesc}[Unpacker]{unpack_opaque}{} Unpacks and returns a variable length opaque data string, similarly to \method{unpack_string()}. -\end{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_bytes}{} +\begin{methoddesc}[Unpacker]{unpack_bytes}{} Unpacks and returns a variable length byte stream, similarly to \method{unpack_string()}. -\end{funcdesc} +\end{methoddesc} The following methods support unpacking arrays and lists: -\begin{funcdesc}{unpack_list}{unpack_item} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_farray}{n, unpack_item} +\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{funcdesc} +\end{methoddesc} -\begin{funcdesc}{unpack_array}{unpack_item} +\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{funcdesc} +\end{methoddesc} + \subsection{Exceptions} \nodename{Exceptions in xdrlib module} |