# 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>
    #include <WindowsNotifsConstants.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