wpRestoreData
This instance method is called to allow the object to **restore its binary instance data**.
Syntax
_wpRestoreData(somSelf, pszClass, ulKey, pValue, pcbValue)
Parameters
- somSelf (WPObject *) - input
- Pointer to the object on which the method is being invoked.
- Points to an object of class WPObject.
- pszClass (PSZ) - input
- Pointer to the class name. It is a pointer to a zero-terminated string that contains any unique string, with the class name recommended but not enforced.
- ulKey (ULONG) - input
- A class-defined identifier that correlates to a particular instance data variable.
- pValue (PBYTE) - in/out
- Address of the data to be restored.
- pcbValue (PULONG) - in/out
- Size of the data block to be restored. If `pValue` is NULL, the actual size is returned in `pcbValue`.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE: Successful completion**.
- FALSE: Error occurred**.
Remarks
This method restores data that was saved by a call to the `wpSaveData` method.
Usage
This method can be called **only during the processing of the `wpRestoreState` method**.
How to Override
This method is **generally not overridden**.
Example Code
Declaration:
#define INCL_WINWORKPLACE #include <os2.h> WPObject *somSelf; /* Pointer to the object on which the method is being invoked. */ PSZ pszClass; /* Pointer to the class name. */ ULONG ulKey; /* Class-defined identifier. */ PBYTE pValue; /* Address of the data to be restored. */ PULONG pcbValue; /* Size of the data block to be restored. */ BOOL rc; /* Success indicator. */ rc = _wpRestoreData(somSelf, pszClass, ulKey, pValue, pcbValue);
The following example demonstrates an override of `wpRestoreState` to restore data from the `OS2.INI` file, which includes a call to `_wpRestoreData`. If restoration fails, it initializes a string to NULL and saves it using `_wpSaveData`:
SOM_Scope void SOMLINK UserSetTitle(nbk *somSelf,
PSZ pszNewTitle)
{
nbkData *somThis = nbkGetData(somSelf);
nbkMethodDebug("nbk","UserSetTitle");
strcpy ( _title, pszNewTitle );
}
/*
* Override of wpRestoreState method to restore our data
* from the OS2.INI file.
*/
SOM_Scope BOOL SOMLINK wpRestoreState(nbk *somSelf,
ULONG ulReserved)
{
BOOL fSuccess;
ULONG ulCount;
CHAR buf;
nbkData *somThis = nbkGetData(somSelf);
nbkMethodDebug("nbk","wpRestoreState");
ulCount = 40; /* Length of data buffer */
fSuccess = _wpRestoreData ( somSelf /* Our pointer */
, (PSZ) "nbk" /* Name of class */
, WPNBK_KEY /* Key of data requested */
, (PBYTE) &buf /* Where to put data */
, &ulCount ); /* Length of data returned */
if ( !fSuccess )
{
/* first time the object is being restored */
/* initialize string to NULL */
strcpy ( buf, "" );
/* Save initial string to OS2.INI file */
_wpSaveData ( somSelf /* Pointer to ourself */
, (PSZ) "nbk" /* Class name */
, WPNBK_KEY /* Key of data */
, (PBYTE) buf /* Pointer to data */
, 40 ); /* Length of data to write */
} /* endif */
_UserSetTitle ( somSelf, buf );
return (parent_wpRestoreState(somSelf,ulReserved));
}