If you are a Win32asm or Windows C programmer, you can stop reading this now. This is meant to be an introduction to the wsprintf API call, for newbies.
Whether we're coding in Win32asm or C etc, it is always nice to use predefined API functions. This is because it makes our code smaller and more concise. However, calling APIs may not be the most efficient method, since there are obviously overheads involved in making any function call. This is irrelevant within the scope of this article, which aims to introduce to you a very interesting and useful API, wsprintf from user32.lib.
The most common use of wsprintf is to convert a hexedecimal number stored in a register, or memory location into its equivalent string value.
For example, lets say that: ESI = 000000AAh.
This can be converted into the null-terminated string, "AA", "aa" or "170" depending upon the format given to wsprintf.
Please refer to my source code API1.ASM now. It is neatly commented, so you should not have any problem following it.
In my demonstration application, API1.EXE, you will see a MessageBox showing the value 170. Now, the neat part about this API is that you can force the application to give you another string representation for your value, without re-compiling the source!!!
Try it
Extra Information
For more information, this is what the Win32 Programmers Reference says about this API call:
The wsprintf function formats and stores a series of characters and values in a buffer. Any arguments are converted and copied to the output buffer according to the corresponding format specification in the format string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.
int wsprintf (
);
Parameters
lpOut Points to a buffer to receive the formatted output.
lpFmt Points to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the Remarks section.
...
Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding
format-control specifications in the lpFmt parameter.
Return Values
If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the terminating null character.
If the function fails, the return value is less than the length of the format-control string. To get extended error information, call GetLastError.
Remarks
The format-control string contains format specifications that determine the output format for the arguments following the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, %% produces a single percent-sign character).
The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the output buffer according to the format specification. The second format specification causes the second argument to be converted and copied, and so on. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.
A format specification has the following form:
Field Meaning
- Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted,
the output is padded to the left, justifying it to the right.
# Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0 Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width
specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified
width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument
is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when
the number of digits exceeds the specified precision. If the specified precision is 0 or omitted entirely, or if the period (.)
appears without a number following it, the precision is set to 1.
For strings, copy the specified maximum number of characters to the output buffer.
type Output the corresponding argument as a character, a string, or a number.
This field can be any of the following character sequences:
Sequence Insert
c A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence
is interpreted as type WCHAR when the calling application uses the #define UNICODE compile flag and as
type CHAR otherwise.
C A single character. This sequence is interpreted as type CHAR when the calling application uses the
#define UNICODE compile flag and as type WCHAR otherwise.
d A signed decimal integer argument. This sequence is equivalent to the i sequence.
hc, hC A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence
is always interpreted as type CHAR, even when the calling application uses the #define UNICODE compile flag.
hs, hS A string. This sequence is always interpreted as type LPSTR, even when the calling application uses the
#define UNICODE compile flag.
i A signed decimal integer. This sequence is equivalent to the d sequence.
lc, lC A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence
is always interpreted as type WCHAR, even when the calling application does not use the
#define UNICODE compile flag.
ld A long signed decimal integer. This sequence is equivalent to the li sequence.
li A long signed decimal integer. This sequence is equivalent to the ld sequence.
ls, lS A string. This sequence is always interpreted as type LPWSTR, even when the calling application does not use
the #define UNICODE compile flag. This sequence is equivalent to the ws sequence.
lu A long unsigned integer.
lx, lX A long unsigned hexadecimal integer in lowercase or uppercase.
s A string. This sequence is interpreted as type LPWSTR when the calling application uses the #define UNICODE
compile flag and as type LPSTR otherwise.
S A string. This sequence is interpreted as type LPSTR when the calling application uses the
#define UNICODE compile flag and as type LPWSTR otherwise.
u An unsigned integer argument.
x, X An unsigned hexadecimal integer in lowercase or uppercase.
Note that, unlike other Windows functions, wsprintf uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, it is the responsibility of the calling process to pop arguments off the stack, and arguments are pushed on the stack from right to left. In C-language modules, the C compiler performs this task