Function Mem2Str() Foundation

Create a character string from a memory address.

Syntax
Mem2Str( <nAddress> [, <nLen>] [, @<cMem>] ) --> cMem | NIL
Parameters
<nAddress>
A numeric value with the memory address of the data to create the string from.
<nLen>
The length of the character string to be returned. If the memory pointed to by <nAddress> contains a NULL-terminated string, the <nLen> parameter is optional and can be omitted. In this case, the returned string contains all characters up to but not including the NULL-terminator.
If <nLen> is omitted and a buffer is passed in <cMem>, the entire buffer is filled starting from address <nAddress>.
<cMem>
The optional parameter <cMem> can be used for specifying the buffer the character string is created in. In this case, <cMem> must be a string large enough for storing at least <nLen> characters. The string must be passed by reference. If no buffer is passed, a new string is created and returned by the function Mem2Str().
Return

A character string with the data at the specified memory location. If a buffer is passed in parameter <cMem>, however, the string is returned in this buffer and Mem2Str() returns the value NIL.

Description

The function Mem2Str() returns the contents of a certain memory location as a character string. The function is most often used in conjunction with API functions returning pointers to strings residing in memory owned by the callee.

The optional parameter <cMem> can be used for specifying an existing buffer for the resulting character string. This allows the same memory to be used in repeated calls to Mem2Str(), for example, in inner loops. The buffer must be large enough for performing the operation. Otherwise the Mem2Str() function generates a runtime error.

Examples
Getting the name of the client machine in a Remote Desktop session
// This example shows using Mem2Str() for getting the name of the client machine 
// in a Remote Desktop session. 
#include "dll.ch" 

#define WTS_CURRENT_SERVER_HANDLE 0 
#define WTS_CURRENT_SESSION       0xffffffff 
#define WTS_ClientName            10 
#define SM_REMOTESESSION          0x1000 

EXTERN BOOL WTSQuerySessionInformation( hServer AS UINTEGER, ; 
                                        SessionId AS UINTEGER, ; 
                                        WTSInfoClass AS UINTEGER, ; 
                                        @ppBuffer AS UINTEGER, ; 
                                        @pBytesReturned AS UINTEGER ) IN wtsapi32.dll 
EXTERN WTSFreeMemory( pMemory AS UINTEGER ) IN wtsapi32.dll 
EXTERN INTEGER GetSystemMetrics( nIndex AS INTEGER ) IN WIN32API 

PROCEDURE Main() 
   LOCAL nBuff := 0 
   LOCAL nBytes:= 0 
   LOCAL lRet 
   LOCAL cName 
   LOCAL nBuffer 

   IF .NOT. IsWTSClientSession() 
      ? "Client is not running in a Remote Desktop session" 
      QUIT 
   ENDIF 

   lRet := WTSQuerySessionInformation( WTS_CURRENT_SERVER_HANDLE, ; 
                                       WTS_CURRENT_SESSION,       ; 
                                       WTS_ClientName,            ; 
                                       @nBuff, @nBytes ) 
   IF ! lRet .OR. nBytes == 0 
      ? "Error getting the name of the client machine" 
      QUIT 
   ENDIF 

   cName := Mem2Str( nBuff, nBytes ) 
   WTSFreeMemory( nBuff ) 

   ? "The name of the client machine is ", cName   
RETURN 

// Check whether the current process runs in a Remote Desktop session. 
FUNCTION IsWTSClientSession() 
RETURN (GetSystemMetrics(SM_REMOTESESSION) != 0) 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.