Serialization of Control Version Information

Serialization is the process by which persistent data is loaded or stored through an exchange object. One type of exchange object is used to initialize a control's persistent properties to default values; another type is used to load and store persistent data in persistent storage. A control's persistent data is serialized in the DoPropExchange function.

The Circle control's version, stock properties, and persistent custom properties, in that order, are serialized in the DoPropExchange function in CIRCCTL.CPP.

void CCircCtrl::DoPropExchange(CPropExchange* pPX)
{
    ExchangeVersion(pPX, MAKELONG(_wVerMinor, _wVerMajor));
    COleControl::DoPropExchange(pPX);

    PX_Bool(pPX, _T("CircleShape"), m_circleShape, TRUE);
    PX_Short(pPX, _T("CircleOffset"), m_circleOffset, 0);
    PX_Long(pPX, _T("FlashColor"), (long &)m_flashColor, RGB(0xFF, 0x00, 0x00));
    PX_String(pPX, _T("Note"), m_note, _T(""));
}

When the Circle control project was created, ControlWizard produced the code that calls the ExchangeVersion and COleControl::DoPropExchange functions. ControlWizard also defined the global constants _wVerMajor and _wVerMinor in CIRC.CPP as 1 and 0 respectively, which represents version 1.0.

The ExchangeVersion function serializes a control's version and sets the version used by the exchange object, pPX. This call should always be made before any version-sensitive persistent data is serialized. When persistent data is being initialized or written into persistent storage through the exchange object, the exchange object's version is set to the version parameter passed to the function. When persistent data is being read from persistent storage through the exchange object, the exchange object's version is read from persistent storage.

The COleControl::DoPropExchange function serializes all of a control's stock properties. The PX_ functions serialize each of the Circle control's persistent custom properties. These calls were added in previous lessons of the tutorial.