wpScanSetupString
This instance method is called by wpSetup to parse the KEYWORDS and KEYWORD values from the setup string that is passed when the object is created.
Syntax
_wpScanSetupString(somSelf, pszSetupString,
pszKey, pszValue, pcbValue)
Parameters
- somSelf (WPObject *) - input
- Pointer to the object on which the method is being invoked.
- Points to an object of class WPObject.
- pszSetupString (PSZ) - input
- Class-specific setup parameters for an object.
- pszKey (PSZ) - input
- Key to scan for.
- pszValue (PSZ) - input
- Buffer for the value. If **NULL**, the size of the buffer required is returned in *pcbValue*.
- pcbValue (PULONG) - in/out
- Buffer length.
- input The length of the buffer pointed to by *pszValue*. If *pszValue* is not **NULL**, this parameter must be initialized with the size of the buffer string (*pszValue*).
- output The actual length of the returned string, plus one for the **NULL** terminator, or the size of the buffer required if *pszValue* is **NULL** or the input value of *pcbValue* is too small.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE Successful completion; key found.
- FALSE Error occurred; key not found or buffer too small.
How to Override
This method is generally not overridden.
Usage
This method is generally called from within an override of the wpSetup method.
Remarks
If a semicolon is needed in the setup string, the escape character **^** can be used.
Example Code
#define INCL_WINWORKPLACE
#include <os2.h>
WPObject *somSelf; /* Pointer to the object on which the method is being invoked. */
PSZ pszSetupString; /* Class-specific setup parameters for an object. */
PSZ pszKey; /* Key to scan for. */
PSZ pszValue; /* Buffer for the value. */
PULONG pcbValue; /* Buffer length. */
BOOL rc; /* Success indicator. */
rc = _wpScanSetupString(somSelf, pszSetupString,
pszKey, pszValue, pcbValue);
/* Example code provided in the source (override of wpSetup): */
SOM_Scope BOOL SOMLINK myf_wpSetup(MYFILE *somSelf,
PSZ pszSetupString)
{
MYFILEData *somThis = MYFILEGetData(somSelf);
ULONG cbBytesWritten; /* Number of bytes written */
APIRET rc; /* Return code */
BOOL fSuccess; /* Success flag */
HFILE hf; /* File handle */
ULONG ulAction; /* Action taken by DosOpen */
CHAR szObjectFilename[CCHMAXPATH]; /* Buffer for wpQueryRealName() */
ULONG cb = sizeof(szObjectFilename); /* Size of object */
PSZ pszDefaultText; /* Default text */
BOOL rcParentCall; /* Result of parent's method */
CHAR szValue[CCHMAXPATH+1];
ULONG cbBuffer;
MYFILEMethodDebug("MYFILE","myf_wpSetup");
/* When the object is created from scratch, put some default
text into the file on the hard disk */
fSuccess =
_wpQueryRealName( /* query full-pathname of object's file */
somSelf, /* pointer to this object */
szObjectFilename, /* return buffer */
&cb, /* sizeof buffer */
TRUE); /* request fully qualified pathname? */
if (fSuccess)
{
rc = DosOpen(szObjectFilename, &hf, &ulAction, 20L, FILE_NORMAL,
FILE_OPEN | FILE_CREATE,
OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE,
NULL);
if (rc == NO_ERROR) {
pszDefaultText = _clsQueryDefaultFileText(_MYFILE);
DosWrite(hf, pszDefaultText, strlen(pszDefaultText), &cbBytesWritten);
DosClose(hf);
} /* endif */
/* New Setup Strings parsed and processed by this override:
*
* SOUND=(YES/NO) YES will invoke _soundAlarm method
* NO will do nothing */
} else {
_wpclsSetError( somSelf, MYFILE_QRN_FAILED );
} /* endif (fSuccess) */
rcParentCall = parent_wpSetup(somSelf,pszSetupString);
/* Process setup strings we understand */
cbBuffer = CCHMAXPATH;
if ( _wpScanSetupString(somSelf, pszSetupString, "SOUND",
szValue,&cbBuffer) )
{
if ((szValue[0] == 'Y') && (szValue[1] == 'E') && (szValue[2] == 'S')) {
_soundAlarm(somSelf);
} /* endif */
} /* endif */
return( rcParentCall );
}