(SST) ShlWAPI.pas Version 1.08
Developer Reference
(SST)ShlWAPI wvnsprintf Function
Creates) a string from string and numerical parameters, according to a string that specifies how the individual parameters are to be interpreted and formatted.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function wvnsprintf(lpOutBuf : LPSTR; cchLimitIn : Integer; lpFmt : LPCSTR; arglist : Pointer) : Integer;
Parameters
lpOutBuf [out] Pointer to a buffer into which the function should write the resulting, formatted string. The buffer must be large enough to include a terminating NULL character.
cchLimitIn [in] The size, in number of characters, of the buffer specified in lpOutBuf.
lpFmt [in] Pointer to a NULL terminated string that specifies how to interpret and format the arguments in the arglist parameters list.
arglist [in] Array of pointers to the arguments to format.
Return Values
If the function was able to successfully format the arguments, it returns the number of characters copied to the output buffer. The returned value does not include any terminating NULL characters. If the function fails, for any reason, it returns a negative value, typically, -1.
Remarks
Some versions of the Microsoft documentation on this function state that, unlike the Delphi Format, FormatBuf, FmtStr, StrFmt, and StrLFmt functions (and the similar, C printf functions), the function cannot be used to format pointer and floating point parameters and therefore does not support the "p", "e", and "f", etc. format specifiers. However, based on the documentation of the "wsprintf" that accompanied MS SDK version 6.1, and subsequent tests, at least the "p" specifier is supported under Windows Vista, and presumably as early as Windows 2000.
In contrast to the Delphi functions mentioned in the previous remark, this function interprets some format specifiers in a case sensitive manner and formats the output accordingly.
Example
PROCEDURE TForm4.TestShlWAPIwvnsprintf(Sender : TObject);

VAR formattedstr : ARRAY[0 .. 64] OF CHAR;
VAR formattedstrp : PChar;
VAR fmt : STRING;
VAR arg1 : STRING;
VAR arg2 : INTEGER;
VAR arg3 : STRING;
VAR arg4 : WORD;
VAR arg5 : STRING;
VAR arg6 : WORD;
VAR arglist : ARRAY[1..4] OF POINTER;
VAR arglistp : POINTER;
VAR apiretval : INTEGER;
VAR newinfoline : STRING;

BEGIN
FillChar(formattedstr, Length(formattedstr), #0);
formattedstrp := NIL;
fmt := '';
arg1 := '';
arg2 := 0;
arg3 := '';
arg4 := 0;

arglistp := NIL;
apiretval := 0;
newinfoline := '';

//What's forty two ? The answer is : 6 x 7
//fmt := '%6s %d %10s %d %3s %d';
fmt := '%6s %d %1s';
arg1 := 'What''s';
arg2 := 42;
arg3 := '?';

arglist[1] := PChar(arg1);
arglist[2] := POINTER(arg2);
arglist[3] := PChar(arg3);
newinfoline := 'wvnsprintf called with ' + arg1 + ' and ' + IntToStr(arg2) + ' and ' + arg3;
Memo1.Lines.Add(newinfoline);
apiretval := wvnsprintf(formattedstr, Length(formattedstr) - 1, PChar(fmt), @arglist);
IF apiretval > 0 THEN
newinfoline := formattedstr
ELSE
newinfoline := IntToStr(apiretval);
Memo1.Lines.Add(newinfoline);

formattedstrp := StrAlloc(64);
//rmattedstrp := StrAlloc(5);
arg3 := 'The answer is : ';
arg4 := 6;
arg5 := ' x ';
arg6 := 7;
fmt := '%16s %d %3s %d';
arglist[1] := PChar(arg3);
arglist[2] := POINTER(arg4);
arglist[3] := PChar(arg5);
arglist[4] := POINTER(arg6);
newinfoline := 'wvnsprintf called with "' + arg3 + '" and "' + IntToStr(arg4) +
'" and "' + arg5 + '" and "' + IntToStr(arg6) + '"';
Memo1.Lines.Add(newinfoline);
arglistp := @arglist;
apiretval := wvnsprintf(formattedstrp, StrBufSize(formattedstrp) - 1, PChar(fmt), arglistp);
IF apiretval > 0 THEN
newinfoline := formattedstrp
ELSE
newinfoline := IntToStr(apiretval);
Memo1.Lines.Add(newinfoline);
StrDispose(formattedstrp);

//Contrary to some versions of the Microsoft documentation on this function
//the pointer specifier "p" is presumably supported as of Windows 2000.
//It is definitely supported under Vista with SP1 & IE 8.
fmt := '%43s%10p';
formattedstrp := StrAlloc(129);
arg1 := 'The address of the variable arglist is : 0x';
arg2 := INTEGER(@arglist);
newinfoline := 'wvnsprintf called with "' + arg1 + '" and "' + IntToStr(arg2) + '" (= @arglist)';
Memo1.Lines.Add(newinfoline);
arglist[1] := PChar(arg1);
arglist[2] := POINTER(arg2);
arglist[3] := NIL;
arglist[4] := NIL;
arglistp := @arglist;
apiretval := wvnsprintf(formattedstrp, StrBufSize(formattedstrp) - 1, PChar(fmt), arglistp);
IF apiretval > 0 THEN
newinfoline := formattedstrp
ELSE
newinfoline := IntToStr(apiretval);
Memo1.Lines.Add(newinfoline);
StrDispose(formattedstrp);

fmt := '%77s%8x';
formattedstrp := StrAlloc(129);
arg1 := 'The value of the variable arglist expressed in lower case, hex. notation : 0x';
arg2 := INTEGER(@arglist);
newinfoline := 'wvnsprintf called with "' + arg1 + '" and "' + IntToStr(arg2) + '" (= @arglist)';
Memo1.Lines.Add(newinfoline);
arglist[1] := PChar(arg1);
arglist[2] := POINTER(arg2);
arglist[3] := NIL;
arglist[4] := NIL;
arglistp := @arglist;
apiretval := wvnsprintf(formattedstrp, StrBufSize(formattedstrp) - 1, PChar(fmt), arglistp);
IF apiretval > 0 THEN
newinfoline := formattedstrp
ELSE
newinfoline := IntToStr(apiretval);
Memo1.Lines.Add(newinfoline);
StrDispose(formattedstrp);

fmt := '%77s%8X';
formattedstrp := StrAlloc(129);
arg1 := 'The value of the variable arglist expressed in upper case, hex. notation : 0x';
arg2 := INTEGER(@arglist);
newinfoline := 'wvnsprintf called with "' + arg1 + '" and "' + IntToStr(arg2) + '" (= @arglist)';
Memo1.Lines.Add(newinfoline);
arglist[1] := PChar(arg1);
arglist[2] := POINTER(arg2);
arglist[3] := NIL;
arglist[4] := NIL;
arglistp := @arglist;
apiretval := wvnsprintf(formattedstrp, StrBufSize(formattedstrp) - 1, PChar(fmt), arglistp);
IF apiretval > 0 THEN
newinfoline := formattedstrp
ELSE
newinfoline := IntToStr(apiretval);
Memo1.Lines.Add(newinfoline);
StrDispose(formattedstrp);

Memo1.Lines.Add('');
END;
Under Windows Vista (with SP1 & IE8) the above example produced the following output:
wvnsprintf called with What's and 42 and ?
What's 42 ?
wvnsprintf called with "The answer is : " and "6" and " x " and "7"
The answer is : 6 x 7
wvnsprintf called with "The address of the variable arglist is : 0x" and "1242420" (= @arglist)
The address of the variable arglist is : 0x 0012F534
wvnsprintf called with "The value of the variable arglist expressed in lower case, hex. notation : 0x" and "1242420" (= @arglist)
The value of the variable arglist expressed in lower case, hex. notation : 0x 12f534
wvnsprintf called with "The value of the variable arglist expressed in upper case, hex. notation : 0x" and "1242420" (= @arglist)
The value of the variable arglist expressed in upper case, hex. notation : 0x 12F534
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (wvnsprintf and wvnsprintfA) and Unicode (wvnsprintfW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.: 5.0
Min. ShlWAPI.dll version based on SST research: 5.0
Min. OS version(s) according to Microsoft SDK doc.: Windows 2000, Windows NT 4.0 with Internet Explorer 5, Windows 98, Windows 95 with Internet Explorer 5
Min. OS version(s) according to SST research.: Windows NT 4.0 with IE 5, Windows 98, Windows 95 with IE 5, Windows 2000 and later
See Also
wnsprintf
 
Windows APIs: wnsprintf, wvnsprintf, StringCbVPrintf


Document/Contents version 1.00
Page/URI last updated on 07.12.2023 		 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017 		Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com