Passing Buffers and Strings

A number of calls take the address and size of a buffer, into which the function will place a variable-sized structure. In each case, the mechanism used is the same. The caller allocates a buffer and passes its address to the function in lpBuffer, and the address of a word containing the buffer size in bytes via lpBufferSize. The function then copies as much of the requested structure as it can into the buffer. If it fits, the function returns success, but if it does not, the data may be left incomplete, and the function sets the WN_MORE_DATA error. When WN_MORE_DATA is returned, lpBufferSize is filled with the number of bytes actually required by the structure. This way, if the buffer passed in was too small and the function failed, the caller may allocate a new buffer of the required size and call the function again. The system takes a copy of the size so that an NP need only fill the size in correctly if it returns WN_MORE_DATA.

When the structure returned includes variable-length strings, the individual structures will usually contain a pointer to the string. The strings themselves should also be placed within the buffer (at the end) so that they will not throw off the ability to index to the Nth structure (all structures are located contiguously at the start of the buffer). Pointers to strings or variable-length data must be actual pointers, not offsets into the buffer.

Windows 95 uses DBCS ANSI/OEM character sets, so that when a buffer is used to pass in and return strings, lpBufferSize specifies the number of bytes that will fit, not the number of characters. This is different from Windows NT, which uses Unicode and specifies the number of characters.