LoadString function

11 out of 25 rated this helpful Rate this topic

LoadString function

Loads a string resource from the executable file associated with a specified module, copies the string into a buffer, and appends a terminating null character.

Syntax

int WINAPI LoadString(
  __in_opt  HINSTANCE hInstance,
  __in      UINT uID,
  __out     LPTSTR lpBuffer,
  __in      int nBufferMax
);

Parameters

hInstance [in, optional]

Type: HINSTANCE

A handle to an instance of the module whose executable file contains the string resource. To get the handle to the application itself, call the GetModuleHandle function with NULL.

uID [in]

Type: UINT

The identifier of the string to be loaded.

lpBuffer [out]

Type: LPTSTR

The buffer is to receive the string.

nBufferMax [in]

Type: int

The size of the buffer, in characters. The string is truncated and null-terminated if it is longer than the number of characters specified. If this parameter is 0, then lpBuffer receives a read-only pointer to the resource itself.

Return value

Type: int

If the function succeeds, the return value is the number of characters copied into the buffer, not including the terminating null character, or zero if the string resource does not exist. To get extended error information, call GetLastError.

Remarks

Security Remarks

Using this function incorrectly can compromise the security of your application. Incorrect use includes specifying the wrong size in the nBufferMax parameter. For example, if lpBuffer points to a buffer szBuffer which is declared as TCHAR szBuffer[100], then sizeof(szBuffer) gives the size of the buffer in bytes, which could lead to a buffer overflow for the Unicode version of the function. Buffer overflow situations are the cause of many security problems in applications. In this case, using sizeof(szBuffer)/sizeof(TCHAR) or sizeof(szBuffer)/sizeof(szBuffer[0]) would give the proper size of the buffer.

Examples

For an example, see Creating a Child Window

Requirements

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	Winuser.h (include Windows.h)
Library	User32.lib
DLL	User32.dll
Unicode and ANSI names	LoadStringW (Unicode) and LoadStringA (ANSI)

At some point I've tried to load a dll and decided to use its strings. I noticed some strange thing. I was getting different result when nBufferMax is 0 than when it is not. When loading from a STRINGTABLE in a resource to a buffer and giving nBufferMax the size of that buffer, the string would be loaded, null terminated and everything is fine. When, however, i used nBufferMax = 0 in the following call: const wchar_t *str int i=LoadStringW(ResContainer, 103, (LPWSTR)&str,0) the str variable was suddenly pointing to a string which was null terminated, but at the point where STRINGTABLE ends, not where resource identified by 103 ends! At the end of string identified by resource 103 there was 0x06 or 0x07 for some reason. Let's say my resource looks like this: STRINGTABLE BEGIN A "A" B "B" END Then, after LoadLibraryEx and using LoadStringW as shown above, memory str points to looks like this: 41 00 07 00 42 00 00 00 Strange, eh?

Kitet

1/14/2012

Return value 0 or -1

The return value 0 not necessarily means an error. If: 1) the string resource exists, 2) it is an empty string and 3) the buffer (lpBuffer) has at least one TCHAR the function returns 0. This happens because it copies to the buffer (lpBuffer) only the terminating NULL character (since the string is empty) and returns number of TCHARs copied into the buffer, not including the terminating NULL character which is 0.

But since the function does not clear last error code so to reliably know whether there was an error we must call SetLastError(0) before calling LoadString and then if 0 is returned and GetLastError() returns something else then ERROR_SUCCESS (value 0) there was an error.

The return value -1 is possible in the ANSI version (LoadStringA) which does not handle mentioned special case of nBufferMax == 0. This happens because it cannot copy anything to the buffer (as it has 0 size) not even the terminating NULL character but still returns one less then number of copied characters which is -1.

Adam Badura

9/13/2010

nBufferMax == 0

The special behaviour when nBufferMax == 0 applies only to LoadStringW, and not to LoadStringA.

For LoadStringA specifying nBufferMax == 0 will result (if the string exists) in return value of -1 which just blindly follows the rule of returning number of TCHARs copied into the buffer, not including the terminating NULL character.

Adam Badura

2/26/2010

Loading std::wstring from resources

A C++ function to load std::wstring from resources can be found here (it uses the convenient behaviour of nBufferMax == 0).

http://msmvps.com/blogs/gdicanio/archive/2010/01/05/stl-strings-loading-from-resources.aspx

Giovanni Dicanio

1/5/2010

LoadString can load strings with embedded nulls, but your wrapper function might not

Interesting note:

http://blogs.msdn.com/oldnewthing/archive/2009/10/09/9904648.aspx

Giovanni Dicanio

10/9/2009

sizeof(szBuffer)/sizeof(szBuffer[0])

The security warning suggests using sizeof(szBuffer)/sizeof(szBuffer[0]) but _countof is safer and should be used when available.

Motti Lanzkron

11/4/2008

LoadString function

CharLower

CharLowerBuff

CharNext

CharNextExA

CharPrev

CharPrevExA

CharToOem

CharToOemBuff

CharUpper

CharUpperBuff

IsCharAlpha

IsCharAlphaNumeric

IsCharLower

IsCharUpper

LoadString

lstrcat

lstrcmp

lstrcmpi

lstrcpy

lstrcpyn

lstrlen

OemToChar

OemToCharBuff

wsprintf

wvsprintf

LoadString function

Syntax

Parameters

Return value

Remarks

Security Remarks

Examples

Requirements

See also