This class can be used for packing a series of numeric and string data into a binary stream, according to the DC specification. More...

Public Member Functions

 __init__ ()
 
 beginPack (const DCPackerInterface root)
 Begins a packing session. The parameter is the DC object that describes the packing format; it may be a DCParameter or DCField. More...
 
 beginRepack (const DCPackerInterface root)
 Begins a repacking session. You must have previously called set_unpack_data() to specify a buffer to unpack. More...
 
 beginUnpack (const DCPackerInterface root)
 Begins an unpacking session. You must have previously called set_unpack_data() to specify a buffer to unpack. More...
 
 clearData ()
 Empties the data in the pack buffer and unpack buffer. This should be called between calls to begin_pack(), unless you want to concatenate all of the pack results together. More...
 
bool endPack ()
 Finishes a packing session. More...
 
bool endRepack ()
 Finishes the repacking session. More...
 
bool endUnpack ()
 Finishes the unpacking session. More...
 
const DCPackerInterface getCurrentField ()
 Returns the field that will be referenced by the next call to pack_*() or unpack_*(). This will be NULL if we have unpacked (or packed) all fields, or if it is time to call pop(). More...
 
str getCurrentFieldName ()
 Returns the name of the current field, if it has a name, or the empty string if the field does not have a name or there is no current field. More...
 
const DCPackerInterface getCurrentParent ()
 Returns the field that we left in our last call to push(): the owner of the current level of fields. This may be NULL at the beginning of the pack operation. More...
 
const DCSwitchParameter getLastSwitch ()
 Returns a pointer to the last DCSwitch instance that we have passed by and selected one case of during the pack/unpack process. Each time we encounter a new DCSwitch and select a case, this will change state. More...
 
size_t getLength ()
 Returns the current length of the buffer. This is the number of useful bytes stored in the buffer, not the amount of memory it takes up. More...
 
int getNumNestedFields ()
 Returns the number of nested fields associated with the current field, if has_nested_fields() returned true. More...
 
size_t getNumUnpackedBytes ()
 Returns the number of bytes that have been unpacked so far, or after unpack_end(), the total number of bytes that were unpacked at all. This can be used to validate that all of the bytes in the buffer were actually unpacked (which is not otherwise considered an error). More...
 
DCPackType getPackType ()
 Returns the type of value expected by the current field. See the enumerated type definition at the top of DCPackerInterface.h. If this returns one of PT_double, PT_int, PT_int64, or PT_string, then you should call the corresponding pack_double(), pack_int() function (or unpack_double(), unpack_int(), etc.) to transfer data. Otherwise, you should call push() and begin packing or unpacking the nested fields. More...
 
str getString ()
 Returns the packed data buffer as a string. Also see get_data(). More...
 
size_t getUnpackLength ()
 Returns the total number of bytes in the unpack data buffer. This is the buffer used when unpacking; it is separate from the pack data returned by get_length(), which is filled during packing. More...
 
str getUnpackString ()
 Returns the unpack data buffer, as a string. This is the buffer used when unpacking; it is separate from the pack data returned by get_string(), which is filled during packing. Also see get_unpack_data(). More...
 
bool hadError ()
 Returns true if there has been any error (either a pack error or a range error) since the most recent call to begin(). If this returns true, then the matching call to end() will indicate an error (false). More...
 
bool hadPackError ()
 Returns true if there has been an packing error since the most recent call to begin(); in particular, this may be called after end() has returned false to determine the nature of the failure. More...
 
bool hadParseError ()
 Returns true if there has been an parse error since the most recent call to begin(); this can only happen if you call parse_and_pack(). More...
 
bool hadRangeError ()
 Returns true if there has been an range validation error since the most recent call to begin(); in particular, this may be called after end() has returned false to determine the nature of the failure. More...
 
bool hasNestedFields ()
 Returns true if the current field has any nested fields (and thus expects a push() .. pop() interface), or false otherwise. If this returns true, get_num_nested_fields() may be called to determine how many nested fields are expected. More...
 
bool moreNestedFields ()
 Returns true if there are more nested fields to pack or unpack in the current push sequence, false if it is time to call pop(). More...
 
 packDefaultValue ()
 Adds the default value for the current element into the stream. If no default has been set for the current element, creates a sensible default. More...
 
 packDouble (double value)
 Packs the indicated numeric or string value into the stream. More...
 
 packInt (int value)
 Packs the indicated numeric or string value into the stream. More...
 
 packInt64 (PNInt64 value)
 Packs the indicated numeric or string value into the stream. More...
 
 packLiteralValue (str value)
 Adds the indicated string value into the stream, representing a single pre-packed field element, or a whole group of field elements at once. More...
 
 packObject (object object)
 Packs the Python object of whatever type into the packer. Each numeric object and string object maps to the corresponding pack_value() call; a tuple or sequence maps to a push() followed by all of the tuple's contents followed by a pop(). More...
 
 packString (str value)
 Packs the indicated numeric or string value into the stream. More...
 
 packUint (unsigned int value)
 Packs the indicated numeric or string value into the stream. More...
 
 packUint64 (PNUint64 value)
 Packs the indicated numeric or string value into the stream. More...
 
bool parseAndPack (Istream in)
 Parses an object's value according to the DC file syntax (e.g. as a default value string) and packs it. Returns true on success, false on a parse error. More...
 
bool parseAndPack (str formatted_object)
 Parses an object's value according to the DC file syntax (e.g. as a default value string) and packs it. Returns true on success, false on a parse error. More...
 
 pop ()
 Marks the end of a nested series of fields. More...
 
 push ()
 Marks the beginning of a nested series of fields. More...
 
 rawPackFloat64 (double value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackInt16 (int value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackInt32 (int value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackInt64 (PNInt64 value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackInt8 (int value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackString (str value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackUint16 (unsigned int value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackUint32 (unsigned int value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackUint64 (PNUint64 value)
 Packs the data into the buffer between packing sessions. More...
 
 rawPackUint8 (unsigned int value)
 Packs the data into the buffer between packing sessions. More...
 
double rawUnpackFloat64 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
int rawUnpackInt16 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
int rawUnpackInt32 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
PNInt64 rawUnpackInt64 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
int rawUnpackInt8 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
str rawUnpackString ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
unsigned int rawUnpackUint16 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
unsigned int rawUnpackUint32 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
PNUint64 rawUnpackUint64 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
unsigned int rawUnpackUint8 ()
 Unpacks the data from the buffer between unpacking sessions. More...
 
bool seek (int seek_index)
 Seeks to the field indentified by seek_index, which was returned by an earlier call to DCField::find_seek_index() to get the index of some nested field. Also see the version of seek() that accepts a field name. More...
 
bool seek (str field_name)
 Sets the current unpack (or repack) position to the named field. In unpack mode, the next call to unpack_*() or push() will begin to read the named field. In repack mode, the next call to pack_*() or push() will modify the named field. More...
 
 setUnpackData (str data)
 Sets up the unpack_data pointer. You may call this before calling the version of begin_unpack() that takes only one parameter. More...
 
str unpackAndFormat (bool show_field_names)
 Unpacks an object and formats its value into a syntax suitable for parsing in the dc file (e.g. as a default value), or as an input to parse_object. More...
 
 unpackAndFormat (Ostream out, bool show_field_names)
 Unpacks an object and formats its value into a syntax suitable for parsing in the dc file (e.g. as a default value), or as an input to parse_object. More...
 
double unpackDouble ()
 Unpacks the current numeric or string value from the stream. More...
 
int unpackInt ()
 Unpacks the current numeric or string value from the stream. More...
 
PNInt64 unpackInt64 ()
 Unpacks the current numeric or string value from the stream. More...
 
str unpackLiteralValue ()
 Returns the literal string that represents the packed value of the current field, and advances the field pointer. More...
 
object unpackObject ()
 Unpacks a Python object of the appropriate type from the stream for the current field. This may be an integer or a string for a simple field object; if the current field represents a list of fields it will be a tuple. More...
 
 unpackSkip ()
 Skips the current field without unpacking it and advances to the next field. If the current field contains nested fields, skips all of them. More...
 
str unpackString ()
 Unpacks the current numeric or string value from the stream. More...
 
unsigned int unpackUint ()
 Unpacks the current numeric or string value from the stream. More...
 
PNUint64 unpackUint64 ()
 Unpacks the current numeric or string value from the stream. More...
 
 unpackValidate ()
 Internally unpacks the current numeric or string value and validates it against the type range limits, but does not return the value. If the current field contains nested fields, validates all of them. More...
 

Static Public Member Functions

static int getNumStackElementsEverAllocated ()
 Returns the number of DCPacker::StackElement pointers ever simultaneously allocated; these are now either in active use or have been recycled into the deleted DCPacker::StackElement pool to be used again. More...
 

Detailed Description

This class can be used for packing a series of numeric and string data into a binary stream, according to the DC specification.

See also direct/src/doc/dcPacker.txt for a more complete description and examples of using this class.

Member Function Documentation

__init__ ( )
beginPack ( const DCPackerInterface  root)

Begins a packing session. The parameter is the DC object that describes the packing format; it may be a DCParameter or DCField.

Unless you call clear_data() between sessions, multiple packing sessions will be concatenated together into the same buffer. If you wish to add bytes to the buffer between packing sessions, use append_data() or get_write_pointer().

beginRepack ( const DCPackerInterface  root)

Begins a repacking session. You must have previously called set_unpack_data() to specify a buffer to unpack.

Unlike begin_pack() or begin_unpack() you may not concatenate the results of multiple begin_repack() sessions in one buffer.

Also, unlike in packing or unpacking modes, you may not walk through the fields from beginning to end, or even pack two consecutive fields at once. Instead, you must call seek() for each field you wish to modify and pack only that one field; then call seek() again to modify another field.

beginUnpack ( const DCPackerInterface  root)

Begins an unpacking session. You must have previously called set_unpack_data() to specify a buffer to unpack.

If there was data left in the buffer after a previous begin_unpack() .. end_unpack() session, the new session will resume from the current point. This method may be used, therefore, to unpack a sequence of objects from the same buffer.

clearData ( )

Empties the data in the pack buffer and unpack buffer. This should be called between calls to begin_pack(), unless you want to concatenate all of the pack results together.

bool endPack ( )

Finishes a packing session.

The return value is true on success, or false if there has been some error during packing.

bool endRepack ( )

Finishes the repacking session.

The return value is true on success, or false if there has been some error during repacking (or if all fields have not been repacked).

bool endUnpack ( )

Finishes the unpacking session.

The return value is true on success, or false if there has been some error during unpacking (or if all fields have not been unpacked).

const DCPackerInterface getCurrentField ( )

Returns the field that will be referenced by the next call to pack_*() or unpack_*(). This will be NULL if we have unpacked (or packed) all fields, or if it is time to call pop().

str getCurrentFieldName ( )

Returns the name of the current field, if it has a name, or the empty string if the field does not have a name or there is no current field.

const DCPackerInterface getCurrentParent ( )

Returns the field that we left in our last call to push(): the owner of the current level of fields. This may be NULL at the beginning of the pack operation.

const DCSwitchParameter getLastSwitch ( )

Returns a pointer to the last DCSwitch instance that we have passed by and selected one case of during the pack/unpack process. Each time we encounter a new DCSwitch and select a case, this will change state.

This may be used to detect when a DCSwitch has been selected. At the moment this changes state, get_current_parent() will contain the particular SwitchCase that was selected by the switch.

size_t getLength ( )

Returns the current length of the buffer. This is the number of useful bytes stored in the buffer, not the amount of memory it takes up.

int getNumNestedFields ( )

Returns the number of nested fields associated with the current field, if has_nested_fields() returned true.

The return value may be -1 to indicate that a variable number of nested fields are accepted by this field type (e.g. a variable-length array).

Note that this method is unreliable to determine how many fields you must traverse before you can call pop(), since particularly in the presence of a DCSwitch, it may change during traversal. Use more_nested_fields() instead.

static int getNumStackElementsEverAllocated ( )
static

Returns the number of DCPacker::StackElement pointers ever simultaneously allocated; these are now either in active use or have been recycled into the deleted DCPacker::StackElement pool to be used again.

size_t getNumUnpackedBytes ( )

Returns the number of bytes that have been unpacked so far, or after unpack_end(), the total number of bytes that were unpacked at all. This can be used to validate that all of the bytes in the buffer were actually unpacked (which is not otherwise considered an error).

DCPackType getPackType ( )

Returns the type of value expected by the current field. See the enumerated type definition at the top of DCPackerInterface.h. If this returns one of PT_double, PT_int, PT_int64, or PT_string, then you should call the corresponding pack_double(), pack_int() function (or unpack_double(), unpack_int(), etc.) to transfer data. Otherwise, you should call push() and begin packing or unpacking the nested fields.

str getString ( )

Returns the packed data buffer as a string. Also see get_data().

size_t getUnpackLength ( )

Returns the total number of bytes in the unpack data buffer. This is the buffer used when unpacking; it is separate from the pack data returned by get_length(), which is filled during packing.

str getUnpackString ( )

Returns the unpack data buffer, as a string. This is the buffer used when unpacking; it is separate from the pack data returned by get_string(), which is filled during packing. Also see get_unpack_data().

bool hadError ( )

Returns true if there has been any error (either a pack error or a range error) since the most recent call to begin(). If this returns true, then the matching call to end() will indicate an error (false).

bool hadPackError ( )

Returns true if there has been an packing error since the most recent call to begin(); in particular, this may be called after end() has returned false to determine the nature of the failure.

A return value of true indicates there was a push/pop mismatch, or the push/pop structure did not match the data structure, or there were the wrong number of elements in a nested push/pop structure, or on unpack that the data stream was truncated.

bool hadParseError ( )

Returns true if there has been an parse error since the most recent call to begin(); this can only happen if you call parse_and_pack().

bool hadRangeError ( )

Returns true if there has been an range validation error since the most recent call to begin(); in particular, this may be called after end() has returned false to determine the nature of the failure.

A return value of true indicates a value that was packed or unpacked did not fit within the specified legal range for a parameter, or within the limits of the field size.

bool hasNestedFields ( )

Returns true if the current field has any nested fields (and thus expects a push() .. pop() interface), or false otherwise. If this returns true, get_num_nested_fields() may be called to determine how many nested fields are expected.

bool moreNestedFields ( )

Returns true if there are more nested fields to pack or unpack in the current push sequence, false if it is time to call pop().

packDefaultValue ( )

Adds the default value for the current element into the stream. If no default has been set for the current element, creates a sensible default.

packDouble ( double  value)

Packs the indicated numeric or string value into the stream.

packInt ( int  value)

Packs the indicated numeric or string value into the stream.

packInt64 ( PNInt64  value)

Packs the indicated numeric or string value into the stream.

packLiteralValue ( str  value)

Adds the indicated string value into the stream, representing a single pre-packed field element, or a whole group of field elements at once.

packObject ( object  object)

Packs the Python object of whatever type into the packer. Each numeric object and string object maps to the corresponding pack_value() call; a tuple or sequence maps to a push() followed by all of the tuple's contents followed by a pop().

packString ( str  value)

Packs the indicated numeric or string value into the stream.

packUint ( unsigned int  value)

Packs the indicated numeric or string value into the stream.

packUint64 ( PNUint64  value)

Packs the indicated numeric or string value into the stream.

bool parseAndPack ( Istream  in)

Parses an object's value according to the DC file syntax (e.g. as a default value string) and packs it. Returns true on success, false on a parse error.

bool parseAndPack ( str  formatted_object)

Parses an object's value according to the DC file syntax (e.g. as a default value string) and packs it. Returns true on success, false on a parse error.

pop ( )

Marks the end of a nested series of fields.

This must be called to match a previous push() only after all the expected number of nested fields have been packed. It is an error to call it too early, or too late.

push ( )

Marks the beginning of a nested series of fields.

This must be called before filling the elements of an array or the individual fields in a structure field. It must also be balanced by a matching pop().

It is necessary to use push() / pop() only if has_nested_fields() returns true.

rawPackFloat64 ( double  value)

Packs the data into the buffer between packing sessions.

rawPackInt16 ( int  value)

Packs the data into the buffer between packing sessions.

rawPackInt32 ( int  value)

Packs the data into the buffer between packing sessions.

rawPackInt64 ( PNInt64  value)

Packs the data into the buffer between packing sessions.

rawPackInt8 ( int  value)

Packs the data into the buffer between packing sessions.

rawPackString ( str  value)

Packs the data into the buffer between packing sessions.

rawPackUint16 ( unsigned int  value)

Packs the data into the buffer between packing sessions.

rawPackUint32 ( unsigned int  value)

Packs the data into the buffer between packing sessions.

rawPackUint64 ( PNUint64  value)

Packs the data into the buffer between packing sessions.

rawPackUint8 ( unsigned int  value)

Packs the data into the buffer between packing sessions.

double rawUnpackFloat64 ( )

Unpacks the data from the buffer between unpacking sessions.

int rawUnpackInt16 ( )

Unpacks the data from the buffer between unpacking sessions.

int rawUnpackInt32 ( )

Unpacks the data from the buffer between unpacking sessions.

PNInt64 rawUnpackInt64 ( )

Unpacks the data from the buffer between unpacking sessions.

int rawUnpackInt8 ( )

Unpacks the data from the buffer between unpacking sessions.

str rawUnpackString ( )

Unpacks the data from the buffer between unpacking sessions.

unsigned int rawUnpackUint16 ( )

Unpacks the data from the buffer between unpacking sessions.

unsigned int rawUnpackUint32 ( )

Unpacks the data from the buffer between unpacking sessions.

PNUint64 rawUnpackUint64 ( )

Unpacks the data from the buffer between unpacking sessions.

unsigned int rawUnpackUint8 ( )

Unpacks the data from the buffer between unpacking sessions.

bool seek ( int  seek_index)

Seeks to the field indentified by seek_index, which was returned by an earlier call to DCField::find_seek_index() to get the index of some nested field. Also see the version of seek() that accepts a field name.

Returns true if successful, false if the field is not known (or if the packer is in an invalid mode).

bool seek ( str  field_name)

Sets the current unpack (or repack) position to the named field. In unpack mode, the next call to unpack_*() or push() will begin to read the named field. In repack mode, the next call to pack_*() or push() will modify the named field.

Returns true if successful, false if the field is not known (or if the packer is in an invalid mode).

setUnpackData ( str  data)

Sets up the unpack_data pointer. You may call this before calling the version of begin_unpack() that takes only one parameter.

str unpackAndFormat ( bool  show_field_names)

Unpacks an object and formats its value into a syntax suitable for parsing in the dc file (e.g. as a default value), or as an input to parse_object.

unpackAndFormat ( Ostream  out,
bool  show_field_names 
)

Unpacks an object and formats its value into a syntax suitable for parsing in the dc file (e.g. as a default value), or as an input to parse_object.

double unpackDouble ( )

Unpacks the current numeric or string value from the stream.

int unpackInt ( )

Unpacks the current numeric or string value from the stream.

PNInt64 unpackInt64 ( )

Unpacks the current numeric or string value from the stream.

str unpackLiteralValue ( )

Returns the literal string that represents the packed value of the current field, and advances the field pointer.

object unpackObject ( )

Unpacks a Python object of the appropriate type from the stream for the current field. This may be an integer or a string for a simple field object; if the current field represents a list of fields it will be a tuple.

unpackSkip ( )

Skips the current field without unpacking it and advances to the next field. If the current field contains nested fields, skips all of them.

str unpackString ( )

Unpacks the current numeric or string value from the stream.

unsigned int unpackUint ( )

Unpacks the current numeric or string value from the stream.

PNUint64 unpackUint64 ( )

Unpacks the current numeric or string value from the stream.

unpackValidate ( )

Internally unpacks the current numeric or string value and validates it against the type range limits, but does not return the value. If the current field contains nested fields, validates all of them.