5.2.6 Passing Buffers

Functions, such as WNetGetConnection, WNetGetErrorText, and WNetGetUser, copy data to a buffer supplied by Windows. Since Windows can not know the size of the data before making the call, these functions return the WN_MORE_DATA value if the complete data does not fit in the buffer.

To make a call, Windows allocates a buffer and passes its address to the function. Windows also passes the address of a 16-bit variable containing the buffer size. The function then copies as much of the requested data structure as it can into the buffer. If it all fits, the function returns successfully. However, if it does not, the data may be left incomplete, and the function returns the WN_MORE_DATA value. In both cases, the function sets the 16-bit variable to the number of bytes actually required by the data 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.