# Function Reference

# DllStructCreate

Creates a C/C++ style structure to be used in DllCall.

DllStructCreate ( Struct [, Pointer] )

## Parameters

Struct | A string representing the structure to create (See Remarks).
Pointer | [optional] If supplied the struct will not allocate memory but use the pointer supplied.

## Return Value

Success: | a variable for use with DllStruct calls.
Failure: | sets the @error flag to non-zero.
@error: | 1 = Variable passed to DllStructCreate was not a string. 2 = There is an unknown Data Type in the string passed. 3 = Failed to allocate the memory needed for the struct, or Pointer = 0. 4 = Error allocating memory for the passed string.

Type | Details
BYTE | 8bit(1byte) unsigned integer
BOOLEAN | 8bit(1byte) unsigned integer
CHAR | 8bit(1byte) ASCII char
WCHAR | 16bit(2byte) UNICODE wide char
SHORT | 16bit(2bytes) signed integer
USHORT | 16bit(2bytes) unsigned integer
WORD | 16bit(2bytes) unsigned integer
INT | 32bit(4bytes) signed integer
LONG | 32bit(4bytes) signed integer
BOOL | 32bit(4bytes) signed integer
UINT | 32bit(4bytes) unsigned integer
ULONG | 32bit(4bytes) unsigned integer
DWORD | 32bit(4bytes) unsigned integer
INT64 | 64bit(8bytes) signed integer
UINT64 | 64bit(8bytes) unsigned integer
PTR | 32 or 64bit pointer (depending on if the x86 or x64 version of AutoIt is used)
HWND | 32 or 64bit pointer (depending on if the x86 or x64 version of AutoIt is used)
HANDLE | 32 or 64bit pointer (depending on if the x86 or x64 version of AutoIt is used)
FLOAT | 32bit(4bytes) floating point
DOUBLE | 64bit(8bytes) floating point
INT_PTR, LONG_PTR, LRESULT, LPARAM | 32 or 64bit signed integer (depending on if the x86 or x64 version of AutoIt is used)
UINT_PTR, ULONG_PTR, DWORD_PTR, WPARAM | 32 or 64bit unsigned integer (depending on if the x86 or x64 version of AutoIt is used)
STRUCT | The following datatypes will be align according to C declaration rules. See below.
ENDSTRUCT | End of the collection datatypes. Padding can occurs see below.
ALIGN | n bytes boundary where datatype must be aligned.

## Remarks

Each data type must be separated by a semi-colon ';'.
Create arrays by adding '[size]' after the data type: DllStructCreate("int;char[128]")
An elementname can be added similar to a C-style declaration: DllStructCreate("int n;char buffer[128]").
This dataname can be used in place of the element in other DllStruct... functions. The dataname must be alphanumeric or an underscore.
If a collection of datatypes is defined as in a "struct{}" in C declaration, the "STRUCT; ...; ENDSTRUCT;" must be used.
This needs to be done to respect alignment inside the entire structure creation. No need if all datatypes are in the defined structure as an implicit structure alignment is done.
DllStructCreate("int;STRUCT;ptr;int;ENDSTRUCT;int") ; structure is 32 bytes under a Windows 64-bit and 16 under Windows 32-bit
DllStructCreate("int;ptr;int;int") ; structure is 24 bytes under a Windows 64-bit and 16 under Windows 32-bit
To use a different alignment prefix the structure with the align keyword. The default value for n is 8. Valid values are 1, 2, 4, 8, and 16. The alignment of a member will be on a boundary that is either a multiple of n or a multiple of the size of the member, whichever is smaller. This is equivalent to the #pragma pack option with the Microsoft Visual C++ compiler.
DllStructCreate("short;int") ; structure is 8 bytes, the "int" is at offset 4
DllStructCreate("align 2;short;int") ; structure is 6 bytes, the "int" is at offset 2
DllStructCreate("byte;double") ; structure is 16 bytes, the "double" is at offset 8
DllStructCreate("align 4;byte;double") ; structure is 12 bytes, the "double" is at offset 4
If a change of alignment is needed "align" can be use before the first element which need to be changed.
"align" or "align 8" leads to default alignment.
To release allocated memory just set the returned variable to 0.
The following aggregate alignment rules apply:
The alignment of an array is the same as the alignment of one of the elements of the array.
The alignment of the beginning of a structure is the maximum alignment of any individual member.
Each member within the structure is be placed at its proper alignment as defined in the previous table, which require implicit internal padding, depending on the previous member.
Structure size is an integral multiple of its alignment, which requires padding after the last member.

## Related

DllCall, DllStructGetData, DllStructGetPtr, DllStructGetSize, DllStructSetData, IsDllStruct

## Example

    #include <MsgBoxConstants.au3>

    Example()

    Func Example()
        #cs Comments:
            Create the following structure (C language):
            struct {
                int var1;
                unsigned char var2;
                unsigned int var3;
                char var4[128];
            };

            Schema:
            ------------------------------------
            \ int    \ byte   \ uint   \ char   \
             \   var1 \   var2 \   var3 \   var4 \
              ------------------------------------
        #ce Comments:

        ; Assign a Local constant variable the definition of a structure (read carefully the DllStructCreate remarks).
        Local Const $tagSTRUCT1 = "struct;int var1;byte var2;uint var3;char var4[128];endstruct"

        ; Note: The tag variable is declared as Constant because its value will never change for any script execution.

        ; Assign a Local variable the structure.
        Local $tSTRUCT1 = DllStructCreate($tagSTRUCT1)

        ; If an error occurred display the error code and return False.
        If @error Then
            MsgBox($MB_SYSTEMMODAL, "", "Error in DllStructCreate, Code: " & @error)
            Return False
        EndIf

        ; Set the data of the element var1 (int) in the $tSTRUCT1.
        DllStructSetData($tSTRUCT1, "var1", -1) ; Or 1 instead of "var1".

        ; Set the data of the element var2 (byte) in the $tSTRUCT1.
        DllStructSetData($tSTRUCT1, 2, 255) ; Or "var2" instead of 2.

        ; Set the data of the element var3 (uint) in the $tSTRUCT1.
        DllStructSetData($tSTRUCT1, "var3", -1) ; The -1 (signed int) will be typecasted to unsigned int.
        ; Or 3 instead of "var3".

        ; Set the data of the element var4 (char) in the $tSTRUCT1.
        DllStructSetData($tSTRUCT1, "var4", "Hello") ; Or 4 instead of "var4".

        ; Note: This element can contain up to 128 characters.

        ; Change the data of the element var4 (char) in the $tSTRUCT1, at the index 1 of the char array (1 based index).
        DllStructSetData($tSTRUCT1, "var4", Asc("h"), 1)

        ; Display the results.
        MsgBox($MB_SYSTEMMODAL, "", "Struct Size: " & DllStructGetSize($tSTRUCT1) & @CRLF & _
                "Struct pointer: " & DllStructGetPtr($tSTRUCT1) & @CRLF & _
                "Data:" & @CRLF & _
                DllStructGetData($tSTRUCT1, 1) & @CRLF & _ ; Or "var1" instead of 1.
                DllStructGetData($tSTRUCT1, "var2") & @CRLF & _ ; Or 2 instead of "var2".
                DllStructGetData($tSTRUCT1, 3) & @CRLF & _ ; Or "var3" instead of 3.
                DllStructGetData($tSTRUCT1, 4)) ; Or "var4" instead of 4.

        ; Release the resources used by the structure.
        $tSTRUCT1 = 0
    EndFunc   ;==>Example