Packable::BeginConfigurationUnpack

Defined in: C4Packing.h

Notifies an object that its settings are about to be unpacked as part of a restoration operation.

Prototype

virtual void *BeginConfigurationUnpack(void);

Description

The BeginConfigurationUnpack function is called right before an object is about to have its settings unpacked as part of a restoration operation such as an undo command. This function is not called before an object is unpacked as it is being loaded from a resource file. An implementation of the BeginConfigurationUnpack function should restore an object to the state it would be in before any extra memory allocations or resource acquisitions are made inside the Packable::Unpack function. That is, it should release any previously allocated memory or resources that will be allocated again when the Packable::Unpack function is called. Furthermore, if any settings have a default state that would cause them not to be stored inside the Packable::Pack function, then they should be restored to this default state because it's possible that those settings will not be restored inside the Unpack function.

After the object is unpacked, its Packable::EndConfigurationUnpack function will be called. It is not a requirement that the EndConfigurationUnpack function be implemented whenever the BeginConfigurationUnpack function is implemented. If the object needs to retain information between calls to the BeginConfigurationUnpack and EndConfigurationUnpack functions, then is can allocate some structure in memory and return a pointer to it from the BeginConfigurationUnpack function. This pointer will then be passed to the cookie parameter of the EndConfigurationUnpack function.