![]() |
(SST) ShlWAPI.pas Version 1.08 |
---|---|
Developer Reference |
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 |