summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libxdrlib.tex
blob: 595848b5d0838f2f7e1d2fa6950e4ffee409aa35 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
\section{\module{xdrlib} ---
         Encode and decode XDR data}

\declaremodule{standard}{xdrlib}
\modulesynopsis{Encoders and decoders for the External Data
                Representation (XDR).}

\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}


\begin{seealso}
  \seerfc{1014}{XDR: External Data Representation Standard}{This RFC
                defined the encoding of data which was XDR at the time
                this module was originally written.  It has
                appearantly been obsoleted by \rfc{1832}.}

  \seerfc{1832}{XDR: External Data Representation Standard}{Newer RFC
                that provides a revised definition of XDR.}
\end{seealso}


\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.

For example, to pack a list of integers, the code might appear like
this:

\begin{verbatim}
import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)
\end{verbatim}
\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 \label{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}