Function Reference

_WinAPI_CreateString

Copies a specified string to the newly allocated memory block and returns its pointer

#include <WinAPIMem.au3>
_WinAPI_CreateString ( $sString [, $pString = 0 [, $iLength = -1 [, $bUnicode = True [, $bAbort = True]]]] )

Parameters

$sString The source string to be copied.
$pString [optional] A pointer to the existing string that to be replaced by a new string.
If this parameter is a valid string pointer, the memory will be reallocated for a new string.
However, the new memory is allocated at a different location. Therefore, you should always use the pointer that returns this function.
If this parameter is 0 (Default) or invalid string pointer, the function just allocates a new memory.
$iLength [optional] The required buffer length, in TCHARs, without null-terminating character.
If this parameter is (-1), the buffer length will be equal to the length of the source string.
If $iLength is less than a source string, the string will be truncated to the specified length. Default is 1.
$bUnicode [optional] Specifies whether a string is Unicode or ASCII code of a character, valid values:
    True - Unicode (Default).
    False - ASCII.
$bAbort [optional] Specifies whether to exit the script if not enough memory, valid values:
    True - Displaying an error message and exit the script with error code 1 (Default).
    False - Continue the script and return an error.

Return Value

Success: A pointer to the new null-terminated string, @extended returns the length of the string buffer, in TCHARs (not including the null-terminating character).
Failure: 0.

Remarks

When a string is no longer needed, you must destroy it by calling the _WinAPI_FreeMemory() function.

Related

_WinAPI_FreeMemory

Example

#include <GUIConstantsEx.au3>
#include <SendMessage.au3>
#include <WinAPIMem.au3>
#include <WinAPIMisc.au3>
#include <WinAPISysWin.au3>

Global Const $WM_MYMESSAGE = _WinAPI_RegisterWindowMessage('MyMessage')

_Example()

Func _Example()
        Local $hForm = GUICreate('Test ' & StringReplace(@ScriptName, '.au3', '()'), 400, 93)
        Local $idInput = GUICtrlCreateInput('', 20, 20, 360, 20)
        Local $idButton = GUICtrlCreateButton('Send', 165, 59, 70, 23)
        GUIRegisterMsg($WM_MYMESSAGE, 'WM_MYMESSAGE')
        GUISetState(@SW_SHOW)

        Local $pString
        While 1
                Switch GUIGetMsg()
                        Case $GUI_EVENT_CLOSE
                                ExitLoop
                        Case $idButton
                                $pString = _WinAPI_CreateString(GUICtrlRead($idInput))
                                _WinAPI_SetMessageExtraInfo($pString)
                                _SendMessage($hForm, $WM_MYMESSAGE, 1, 255)
                                _WinAPI_FreeMemory($pString)
                EndSwitch
        WEnd
EndFunc   ;==>_Example

Func WM_MYMESSAGE($hWnd, $iMsg, $wParam, $lParam)
        #forceref $hWnd, $iMsg

        Local $pString = _WinAPI_GetMessageExtraInfo()

        If _WinAPI_IsMemory($pString) Then
                ConsoleWrite('WM_MYMESSAGE | WP = ' & Number($wParam) & ' | LP = ' & Number($lParam) & ' | EXTRA = "' & _WinAPI_GetString($pString) & '"' & @CRLF)
        EndIf
EndFunc   ;==>WM_MYMESSAGE