Function Reference


Returns the data of an element of the struct.

DllStructGetData ( Struct, Element [, index = Default] )


Struct The struct returned by DllStructCreate().
Element Which element of the struct you want to access, starting at 1 or the element name as defined in DllStructCreate().
index [optional] For elements that are an array this specifies the 1-based index to retrieve. If omitted or the Default keyword then the entire array is retrieved (Useful for quickly retrieving strings). Not used for non-array elements.

Return Value

Success: Data in the element of the struct.
Failure: 0.
@error: 1 = Struct not a valid struct returned by DllStructCreate().
2 = Element out of range or unknown.
3 = Index out of range.
4 = Element data type is unknown
5 = Index <= 0.


When the element is char or char[n], wchar or wchar[n] the data returned is always a String(),
when the element is byte[n] and index is omitted the data returned is a binary type,
otherwise it always returns the best fit AutoIt datatype corresponding to the type of the individual element (e.g. byte returns Int32, float returns Double).


DllStructCreate, DllStructSetData


#include <MsgBoxConstants.au3>


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

    \ int    \ byte   \ uint   \ char   \
     \   var1 \   var2 \   var3 \   var4 \

    ; 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

    ; 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