UNPACK(3)

NAME
packet.unpack - Unpack module

DESCRIPTION

Provides the object for managing and unpacking raw data from a working buffer.

CLASSES

  class Unpack(builtins.object)
Unpack object

Usage:
    from packet.unpack import Unpack

    x = Unpack(buffer)

    # Get 32 bytes from the working buffer and move the offset pointer
    data = x.read(32)

    # Get all the unprocessed bytes from the working buffer
    # (all bytes starting from the offset pointer)
    # Do not move the offset pointer
    data = x.getbytes()

    # Get all bytes from the working buffer from the given offset
    # Do not move the offset pointer
    data = x.getbytes(offset)

    # Return the number of unprocessed bytes left in the working buffer
    size = x.size()
    size = len(x)

    # Get the offset pointer
    offset = x.tell()

    # Set the offset pointer
    x.seek(offset)

    # Append the given data to the working buffer
    x.append(data)

    # Insert the given data to the working buffer right before the
    # offset pointer. This resets the working buffer completely
    # and the offset pointer is initialized to zero. It is like
    # re-instantiating the object like:
    #   x = Unpack(data + x.getbytes())
    x.insert(data)

    # Save state
    sid = x.save_state()

    # Restore state
    x.restore_state(sid)

    # Unpack an 'unsigned short' (2 bytes in network order)
    short_int = x.unpack(2, '!H')[0]

    # Unpack different basic types
    char      = x.unpack_char()
    uchar     = x.unpack_uchar()
    short     = x.unpack_short()
    ushort    = x.unpack_ushort()
    int       = x.unpack_int()
    uint      = x.unpack_uint()
    int64     = x.unpack_int64()
    uint64    = x.unpack_uint64()
    data1     = x.unpack_opaque()
    data2     = x.unpack_opaque(64)  # Length of opaque must be <= 64
    data3     = x.unpack_fopaque(32)

    # Get string where length is given as an unsigned integer
    buffer = x.unpack_string()
    # Get string of fixed length
    buffer = x.unpack_string(32)
    # Get string where length is given as a short integer
    buffer = x.unpack_string(Unpack.unpack_short)
    buffer = x.unpack_string(ltype=Unpack.unpack_short)
    # Get string padded to a 4 byte boundary, discard padding bytes
    buffer = x.unpack_string(pad=4)

    # Get an array of unsigned integers
    alist = x.unpack_array()
    # Get a fixed length array of unsigned integers
    alist = x.unpack_array(ltype=10)
    # Get an array of short integers
    alist = x.unpack_array(Unpack.unpack_short)
    # Get an array of strings, the length of the array is given
    # by a short integer
    alist = x.unpack_array(Unpack.unpack_string, Unpack.unpack_short)
    # Get an array of strings, the length of each string is given by
    # a short integer and each string is padded to a 4 byte boundary
    alist = x.unpack_array(Unpack.unpack_string, uargs={'ltype':Unpack.unpack_short, 'pad':4})
    # Get an array of objects decoded by item_obj where the first
    # argument to item_obj is the unpack object, e.g., item = item_obj(x)
    alist = x.unpack_array(item_obj)

    # Get a list of unsigned integers
    alist = x.unpack_list()
    # Get a list of short integers
    alist = x.unpack_list(Unpack.unpack_short)
    # Get a list of strings, the next item flag is given
    # by a short integer
    alist = x.unpack_list(Unpack.unpack_string, Unpack.unpack_short)
    # Get a list of strings, the length of each string is given by
    # a short integer and each string is padded to a 4 byte boundary
    alist = x.unpack_list(Unpack.unpack_string, uargs={'ltype':Unpack.unpack_short, 'pad':4})

    # Unpack a conditional, it unpacks a conditional flag first and
    # if it is true it unpacks the item given and returns it. If the
    # conditional flag decoded is false, the method returns None
    buffer = x.unpack_conditional(Unpack.unpack_opaque)

    # Unpack an array of unsigned integers and convert array into
    # a single long integer
    bitmask = unpack_bitmap()

Methods defined here:
---------------------

__init__(self, data)
Constructor

Initialize object's private data.

    data:
        Raw packet data

__len__ = size(self)

append(self, data)
Append data to the working buffer.

getbytes(self, offset=None)
Get the number of bytes given from the working buffer.
Do not move the offset pointer.

    offset:
        Starting offset of data to return [default: current offset]

insert(self, data)
Insert data to the beginning of the current working buffer.

read(self, size, pad=0)
Get the number of bytes given from the working buffer.
Move the offset pointer.

    size:
        Length of data to get

    pad:
        Get and discard padding bytes [default: 0]
        If given, data is padded to this byte boundary

restore_state(self, sid)
Restore state given by the state id

save_state(self)
Save state and return the state id

seek(self, offset)
Set the offset pointer.

size(self)
Return the number of unprocessed bytes left in the working buffer

tell(self)
Get the offset pointer.

unpack(self, size, fmt)
Get the number of bytes given from the working buffer and process
it according to the given format.
Return a tuple of unpack items, see struct.unpack.

    size:
        Length of data to process

    fmt:
        Format string on how to process data

unpack_array(self, unpack_item=<function Unpack.unpack_uint at 0x7fdc09097d08>, ltype=<function Unpack.unpack_uint at 0x7fdc09097d08>, uargs={}, maxcount=0, islist=False)
Get a variable length array, the type of objects in the array
is given by the unpacking function unpack_item and the type
to decode the length of the array is given by ltype

    unpack_item:
        Unpack function for each item in the array [default: unpack_uint]

    ltype:
        Function to decode length of array [default: unpack_uint]
        Could also be given as an integer to have a fixed length array

    uargs:
        Named arguments to pass to unpack_item function [default: {}]

    maxcount:
        Maximum length of array [default: any length]

unpack_bitmap(self)
Unpack an array of unsigned integers and convert array into
a single long integer

unpack_char(self)
Get a signed char

unpack_conditional(self, unpack_item=<function Unpack.unpack_uint at 0x7fdc09097d08>, ltype=<function Unpack.unpack_uint at 0x7fdc09097d08>, uargs={})
Get an item if condition flag given by ltype is true, if condition
flag is false then return None

    unpack_item:
        Unpack function for item if condition is true [default: unpack_uint]

    ltype:
        Function to decode the condition flag [default: unpack_uint]

    uargs:
        Named arguments to pass to unpack_item function [default: {}]

unpack_fopaque(self, size)
Get a fixed length opaque

unpack_futf8(self, size)
Get a fixed length utf8 string

unpack_int(self)
Get a signed integer

unpack_int64(self)
Get a signed 64 bit integer

unpack_list(self, *kwts, **kwds)
Get an indeterminate size list, the type of objects in the list
is given by the unpacking function unpack_item and the type
to decode the next item flag is given by ltype

    unpack_item:
        Unpack function for each item in the list [default: unpack_uint]

    ltype:
        Function to decode the next item flag [default: unpack_uint]

    uargs:
        Named arguments to pass to unpack_item function [default: {}]

unpack_opaque(self, maxcount=0)
Get a variable length opaque up to a maximum length of maxcount

unpack_short(self)
Get a signed short integer

unpack_string(self, ltype=<function Unpack.unpack_uint at 0x7fdc09097d08>, pad=0, maxcount=0)
Get a variable length string

    ltype:
        Function to decode length of string [default: unpack_uint]
        Could also be given as an integer to have a fixed length string

    pad:
        Get and discard padding bytes [default: 0]
        If given, string is padded to this byte boundary

    maxcount:
        Maximum length of string [default: any length]

unpack_uchar(self)
Get an unsigned char

unpack_uint(self)
Get an unsigned integer

unpack_uint64(self)
Get an unsigned 64 bit integer

unpack_ushort(self)
Get an unsigned short integer

unpack_utf8(self, maxcount=0)
Get a variable length utf8 string up to a maximum length of maxcount

BUGS
No known bugs.

AUTHOR
Jorge Mora (mora@netapp.com)