Fields

General

Every declared variable in 010 templates creates a pfp.fields.Field instance in memory.

Naming Convention

Some may find it annoying having the prefix _pfp__ affixed to field methods and variables, but I found it more annoying having to access all child fields of a struct via square brackets. The prefix is simply to prevent name collisions so that __getattr__ can be used to access child fields with dot-notation.

Parsed Offset

Parsed offsets of fields are set during object parsing and are re-set each time the main pfp.fields.Dom instance is built. This means that operations that should modify the offsets of fields will cause invalid offsets to exist until the main dom is built again.

Printing

Use the pfp.fields.Field._pfp__show method to return a pretty-printed representation of the field.

Full Field Paths

Use the pfp.fields.Field._pfp__path method to fetch the full path of the field. E.g. in the template below, the inner field would have a full path of root.nested1.nested2.inner, and the second element of the array field would have a full path of root.nested1.nested2.array[1]:

struct {
    struct {
        struct {
            char inner;
            char array[4];
        } nested2;
        int some_int;
    } nested1;
    int some_int2;
} root;

Structs

Structs are the main containers used to add fields to. A pfp.fields.Dom instance is the struct that all fields are added to.

Field Reference Documentation

class pfp.fields.Field(stream=None, metadata_processor=None)

Core class for all fields used in the Pfp DOM.

All methods use the _pfp__XXX naming convention to avoid conflicting names used in templates, since struct fields will implement __getattr__ and __setattr__ to directly access child fields

_pfp__build(output_stream=None, save_offset=False)

Pack this field into a string. If output_stream is specified, write the output into the output stream

Output_stream:Optional output stream to write the results to Save_offset:If true, the current offset into the stream will be saved in the field Returns:Resulting string if output_stream is not specified. Else the number of bytes writtern.

_pfp__name = None

The name of the Field

_pfp__parent = None

The parent of the field

_pfp__parse(stream, save_offset=False)

Parse this field from the stream

Stream:An IO stream that can be read from Save_offset:Save the offset into the stream Returns:None

_pfp__path()

Return the full pathname of this field. E.g. given the template below, the a field would have a full path of root.nested.a

struct {
    struct {
        char a;
    } nested;
} root;

_pfp__set_value(new_val)

Set the new value if type checking is passes, potentially (TODO? reevaluate this) casting the value to something else

New_val:The new value Returns:TODO

_pfp__show(level=0, include_offset=False)

Return a representation of this field

Parameters:

• level (int) – The indent level of the output
• include_offset (bool) – Include the parsed offsets of this field

_pfp__watch_fields = []

All fields that this field is watching

_pfp__watchers = []

All fields that are watching this field

_pfp__width()

Return the width of the field (sizeof)

class pfp.fields.Array(width, field_cls, stream=None, metadata_processor=None)

The array field

field_cls = None

The class for items in the array

raw_data = None

The raw data of the array. Note that this will only be set if the array’s items are a core type (E.g. Int, Char, etc)

width = -1

The number of items of the array. len(array_field) also works

class pfp.fields.Struct(stream=None, metadata_processor=None)

The struct field

_pfp__add_child(name, child, stream=None, overwrite=False)

Add a child to the Struct field. If multiple consecutive fields are added with the same name, an implicit array will be created to store all fields of that name.

Parameters:

• name (str) – The name of the child
• child (pfp.fields.Field) – The field to add
• overwrite (bool) – Overwrite existing fields (False)
• stream (pfp.bitwrap.BitwrappedStream) – unused, but her for compatability with Union._pfp__add_child

Returns:

The resulting field added

_pfp__children = []

All children of the struct, in order added

class pfp.fields.Array(width, field_cls, stream=None, metadata_processor=None)

The array field

field_cls = None

The class for items in the array

implicit = False

If the array is an implicit array or not

raw_data = None

The raw data of the array. Note that this will only be set if the array’s items are a core type (E.g. Int, Char, etc)

width = -1

The number of items of the array. len(array_field) also works

class pfp.fields.BitfieldRW(interp, cls)

Handles reading and writing the total bits for the bitfield data type from the input stream, and correctly applying endian and bit direction settings.

read_bits(stream, num_bits, padded, left_right, endian)

Return num_bits bits, taking into account endianness and left-right bit directions

reserve_bits(num_bits, stream)

Used to “reserve” num_bits amount of bits in order to keep track of consecutive bitfields (or are the called bitfield groups?).

E.g.

struct {
    char a:8, b:8;
    char c:4, d:4, e:8;
}

Parameters:

• num_bits (int) – The number of bits to claim
• stream (pfp.bitwrap.BitwrappedStream) – The stream to reserve bits on

Returns:

If room existed for the reservation

write_bits(stream, raw_bits, padded, left_right, endian)

Write the bits. Once the size of the written bits is equal to the number of the reserved bits, flush it to the stream

class pfp.fields.Char(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a signed char

class pfp.fields.Dom(*args, **kwargs)

The main container struct for a template

class pfp.fields.Double(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a double

class pfp.fields.Enum(stream=None, enum_cls=None, enum_vals=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

The enum field class

class pfp.fields.Field(stream=None, metadata_processor=None)

Core class for all fields used in the Pfp DOM.

All methods use the _pfp__XXX naming convention to avoid conflicting names used in templates, since struct fields will implement __getattr__ and __setattr__ to directly access child fields

class pfp.fields.Float(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a float

class pfp.fields.ImplicitArrayWrapper(last_field, implicit_array)

class pfp.fields.Int(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a signed int

class pfp.fields.Int64(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a signed int64

class pfp.fields.IntBase(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

The base class for all integers

class pfp.fields.NumberBase(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

The base field for all numeric fields

class pfp.fields.Short(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a signed short

class pfp.fields.String(stream=None, metadata_processor=None)

A null-terminated string. String fields should be interchangeable with char arrays

class pfp.fields.Struct(stream=None, metadata_processor=None)

The struct field

class pfp.fields.UChar(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing an unsigned char

class pfp.fields.UInt(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing an unsigned int

class pfp.fields.UInt64(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing an unsigned int64

class pfp.fields.UShort(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing an unsigned short

class pfp.fields.Union(stream=None, metadata_processor=None)

A union field, where each member is an alternate view of the data

class pfp.fields.Void(stream=None, metadata_processor=None)

The void field - used for return value of a function

class pfp.fields.WChar(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing a signed wchar (aka short)

class pfp.fields.WString(stream=None, metadata_processor=None)

class pfp.fields.WUChar(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)

A field representing an unsigned wuchar (aka ushort)