程式扎記: [Python Std Library] File Formats : xdrlib — Encode and decode XDR data

標籤

2012年6月17日 星期日

[Python Std Library] File Formats : xdrlib — Encode and decode XDR data

來源自 這裡 
Preface : 
The 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. Below is Wiki for XDR : 
外部數據表示法(External Data Representation,縮寫為XDR) 是一個在1995年制定的IETF標準協定。在OSI模型的表示層presentation layer中實現。XDR允許把數據包裝在獨立於介質的結構中使得數據可以在異構的計算機系統中傳輸。從局部表示轉換到XDR稱為編碼,從XDR轉換到局部表示稱為解碼。XDR使用軟體來完成變換,所以在不同的作業系統中可以靈活的運用。另外,XDR 還是獨立於傳輸層的 transport layer。Sun的遠端程序呼叫 RPC 就是使用 XDR。

This module defines two classes, one for packing variables into XDR representation, and another for unpacking from XDR representation. There are also two exception classes. 
- class xdrlib.Packer 
Packer is the class for packing data into XDR representation. The Packer class is instantiated with no arguments.

- class xdrlib.Unpacker(data) 
Unpacker is the complementary class which unpacks XDR data values from a string buffer. The input buffer is given as data.

Packer Objects : 
Packer instances have the following methods : 
Packer.get_buffer() 
Returns the current pack buffer as a string.

Packer.reset() 
Resets the pack buffer to the empty string.

In general, you can pack any of the most common XDR data types by calling the appropriate pack_type() method. Each method takes a single argument, the value to pack. The following simple data type packing methods are supported: pack_uint(), pack_int(), pack_enum(), pack_bool(), pack_uhyper(), and pack_hyper()
Packer.pack_float(value) 
Packs the single-precision floating point number value.

Packer.pack_double(value) 
Packs the double-precision floating point number value.

The following methods support packing strings, bytes, and opaque data : 
Packer.pack_fstring(n, s) 
Packs a fixed length string, sn is the length of the string but it is not packed into the data buffer. The string is padded with null bytes if necessary to guaranteed 4 byte alignment.

Packer.pack_fopaque(n, data) 
Packs a fixed length opaque data stream, similarly to pack_fstring().

Packer.pack_string(s) 
Packs a variable length string, s. The length of the string is first packed as an unsigned integer, then the string data is packed with pack_fstring().
>>> pkr = Packer()
>>> pkr.pack_string('John')
>>> upkr = Unpacker(pkr.get_buffer())
>>> upkr.unpack_string() # 首先 string 的 length 會先被 unpacked
b'\x00\x00\x00\x04' # packed string 長度為 4.
>>> upkr.unpack_fstring(4)
b'John'

Packer.pack_opaque(data) 
Packs a variable length opaque data string, similarly to pack_string().

Packer.pack_bytes(bytes) 
Packs a variable length byte stream, similarly to pack_string().

The following methods support packing arrays and lists : 
Packer.pack_list(list, pack_item) 
Packs a 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 1 is packed first, followed by the data value from the list. pack_item is the function that is called to pack the individual item. At the end of the list, an unsigned integer 0 is packed.

For example, to pack a list of integers, the code might appear like this :
  1. import xdrlib  
  2. p = xdrlib.Packer()  
  3. p.pack_list([123], p.pack_int)  

Packer.pack_farray(n, array, pack_item) 
Packs a fixed length list (array) of homogeneous items. n is the length of the list; it is not packed into the buffer, but a ValueError exception is raised if len(array) is not equal to n. As above, pack_item is the function used to pack each element.

Packer.pack_array(list, pack_item) 
Packs a variable length list of homogeneous items. First, the length of the list is packed as an unsigned integer, then each element is packed as in pack_farray()above.

Unpacker Objects : 
The Unpacker class offers the following methods : 
Unpacker.reset(data) 
Resets the string buffer with the given data.

Unpacker.get_position() 
Returns the current unpack position in the data buffer.

Unpacker.set_position(position) 
Sets the data buffer unpack position to position. You should be careful about using get_position() and set_position().

Unpacker.get_buffer() 
Returns the current unpack data buffer as a string.

Unpacker.done() 
Indicates unpack completion. Raises an Error exception if all of the data has not been unpacked.

In addition, every data type that can be packed with a Packer, can be unpacked with an Unpacker. Unpacking methods are of the form unpack_type(), and take no arguments. They return the unpacked object. 
Unpacker.unpack_float() 
Unpacks a single-precision floating point number.

Unpacker.unpack_double() 
Unpacks a double-precision floating point number, similarly to unpack_float().

Unpacker.unpack_fstring(n) 
Unpacks and returns a fixed length string. n is the number of characters expected. Padding with null bytes to guaranteed 4 byte alignment is assumed.

Unpacker.unpack_fopaque(n) 
Unpacks and returns a fixed length opaque data stream, similarly to unpack_fstring().

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 withunpack_fstring().

Unpacker.unpack_opaque() 
Unpacks and returns a variable length opaque data string, similarly to unpack_string().

Unpacker.unpack_bytes() 
Unpacks and returns a variable length byte stream, similarly to unpack_string().

The following methods support unpacking arrays and lists : 
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 1, then the item is unpacked and appended to the list. A flag of 0 indicates the end of the list. unpack_item is the function that is called to unpack the items.

Unpacker.unpack_farray(n, unpack_item) 
Unpacks and returns (as a list) a fixed length array of homogeneous items. n is number of list elements to expect in the buffer. As above, unpack_item is the function used to unpack each element.

Unpacker.unpack_array(unpack_item) 
Unpacks and returns a variable length list of homogeneous items. First, the length of the list is unpacked as an unsigned integer, then each element is unpacked as in unpack_farray() above.


Supplement : 
Data structure alignment

沒有留言:

張貼留言

網誌存檔

關於我自己

我的相片
Where there is a will, there is a way!