View source for DrgQueryStrName

This function gets the contents of a string associated with a string handle.

==Syntax==
 DrgQueryStrName(hstr, cbBuffer, pBuffer)

==Parameters==
;hstr (HSTR) - input: The handle must have been created with [[DrgAddStrHandle]].
;cbBuffer ([[ULONG]]) - input: Maximum number of bytes to copy into pBuffer. Must be greater than 0. Otherwise, an error is returned.
;pBuffer (PSZ) - output: Buffer where the null-terminated string is returned.

==Returns==
;ulLength ([[ULONG]]) - returns: Number of bytes written to pBuffer.

==Remarks==
This function should be called whenever the contents of a string referenced by a drag string handle are required. If the input string handle is NULLHANDLE or not valid, a null string is returned.

==Errors==
Possible returns from WinGetLastError:
;PMERR_INVALID_PARAMETERS (0x1208): An application parameter value is invalid for its converted PM type. For example: a 4-byte value outside the range -32 768 to +32 767 cannot be converted to a SHORT, and a negative number cannot be converted to a ULONG or USHORT.

==Example Code==
<pre>
#define INCL_WINSTDDRAG /* Direct Manipulation (Drag) Functions */
#define INCL_DOSMEMMGR  /* Memory Management Functions for      */
                       /* DosAllocMem                          */
#include <OS2.H>

HSTR  hstr;      /* Handle to a string. The handle must */
                 /* have been created with             */
                 /* DrgAddStrHandle.                   */
PSZ   pBuffer;   /* Buffer where the null-terminated    */
                 /* string is returned                */
ULONG ulStrlen;  /* String length                       */
ULONG ulBytesRead;/* Number of bytes read                */
ULONG rc;        /* Return code                         */

ulStrlen = DrgQueryStrNameLen(hstr) + 1;
rc = DosAllocMem((PVOID *) pBuffer,
                 (LONG)ulStrlen,
                 fPERM |
                 PAG_COMMIT);
/*****************************************************************/
/* The ulBytesRead parameter contains the number of bytes      */
/* actually written to the memory pointed to by pBuffer         */
/*****************************************************************/
ulBytesRead = DrgQueryStrName(hstr,
                              ulStrlen, /* Number of bytes to copy */
                              pBuffer);
</pre>

==Related Functions==
* [[DrgQueryStrNameLen]]
* [[DrgAddStrHandle]]

[[Category:Drg]]