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
#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);