Status of ubyte in structures

[jchd]

AFAICT ubyte is accepted and treated the same as byte in structures, yet DllStructGetData documentation mentions it but DllStructCreate doesn't.

So which documentation needs fixing and are there plans to handle ubyte differently?

[Jon]

ubyte doesn't make sense, it's always an unsigned char. Both byte and ubyte are set to be unsigned chars in the source. Not sure why it's still there - maybe compat.  It has this comment next to it in the source:

// to be removed when no more referenced

[Jon]

Probably should remove all mentions of ubyte from the docs.

[guinness]

It's also used in several UDF functions.

[jpm]

does ubyte a type in MSDN ?

[trancexx]

So, it's an alias. C isn't the only language that can "produce" dlls, nor is DllCall() limited to system dlls.

[jchd]

Revision of my _VarDump function made me find this as well:

DllStructCreate datatypes documentation vs. real-life

1. ubyte not described (despite its widespread use in UDFs). Shouldn't it still be mentionned as an alias of byte?
2. HWND and HANDLE described as "32bit(4bytes) integer". HWND AutoIt type is a Pointer and it is unclear (at least to me today) whether said types should themselves read back as Ptr or described as "32 or 64bit unsigned integer (depending on if the x86 or x64 version of AutoIt is used)"
3. ptr described as "32 or 64bit unsigned integer (depending on if the x86 or x64 version of AutoIt is used)" but read back as Pointer type. Should be described as "32 or 64bit pointer (depending on if the x86 or x64 version of AutoIt is used)".
    

I wanted this function to be as reliable and explicit as possible:

expandcollapse popup

#AutoIt3Wrapper_UseUpx=n
#AutoIt3Wrapper_Compile_Both=n
#AutoIt3Wrapper_UseX64=y
#AutoIt3Wrapper_Run_AU3Check=y


Global Const $_TAB = '      '

Func _VarDump(ByRef $vVar, $iLimit = 10, $sIndent = '')
    Local $ret, $len, $ptr
    If $iLimit < 3 Then $iLimit = 0

    Select

        Case IsString($vVar)
            $len = StringLen($vVar)
            Return 'String       (' & $len & ") " & __DumpStr($vVar)

        Case VarGetType($vVar) = "Double"
            Return 'Double       ' & $vVar & (IsInt($vVar) ? '.0' : '')

        Case IsInt($vVar)
            Return VarGetType($vVar) & '        ' & $vVar

        Case IsArray($vVar)
            Local $iSubscripts = UBound($vVar, 0)
            Local $iCells = 1
            $ret = 'Array'
            $iSubscripts -= 1
            For $i = 0 To $iSubscripts
                $ret &= '[' & UBound($vVar, $i + 1) & ']'
                $iCells *= UBound($vVar, $i + 1)
            Next
            If $iCells = 0 Then
                Return $ret & $_TAB & '  (array is empty)'
            Else
                Return $ret & @CRLF & __VarDumpArray($vVar, $iLimit, $sIndent)
            EndIf

        Case IsBinary($vVar)
            $len = BinaryLen($vVar)
            $ret = 'Binary       (' & BinaryLen($vVar) & ') '
            Return($ret & ($len <= 32) ? $vVar : BinaryMid($vVar, 1, 16) & ' ... ' & StringTrimLeft(BinaryMid($vVar, $len - 15, 16), 2))

        Case IsBool($vVar)
            Return 'Boolean      ' & $vVar

        Case IsKeyword($vVar)
            Return('Keyword      ' & (($vVar = Null) ? 'Null' : 'Default'))

        Case IsPtr($vVar)
            Return 'Pointer      ' & $vVar

        Case IsObj($vVar)
            Return 'Object       ' & ObjName($vVar)

        Case IsHWnd($vVar)
            Return 'HWnd         ' & $vVar

        Case IsFunc($vVar)
            Return StringFormat('%-13s', VarGetType($vVar)) & FuncName($vVar)

        Case IsDllStruct($vVar)
            $len = DllStructGetSize($vVar)
            $ptr = DllStructGetPtr($vVar)
            $ret = 'Struct       (' & $len & ') @:' & Hex($ptr) & ' (structure alignment is unknown)' & @CRLF
            Local $nbElem = 1, $idx, $incr, $data, $type, $indent = $sIndent & $_TAB, $oldvalue, $readvalue, $field, $elem
            While 1
                $data = DllStructGetData($vVar, $nbElem)
                If @error = 2 Then ExitLoop
                $type = VarGetType($data)
                $idx = 1
                $incr = 0
                ; determine max index of element
                While 1
                    DllStructGetData($vVar, $nbElem, 2 * $idx)
                    If @error = 3 Then ExitLoop
                    $incr = $idx
                    $idx *= 2
                WEnd
                ; index is in [$idx, (2 * $idx) - 1]
                $idx += $incr
                Do
                    DllStructGetData($vVar, $nbElem, $idx)
                    If @error = 3 Then
                        ; approach is asymetric (upper bound is too big)
                        $idx -= ($incr = 1) ? 1 : $incr / 2
                    Else
                        $idx += Int($incr / 2)
                    EndIf
                    $incr = Int($incr / 2)
                Until $incr = 0
                Switch $type
                    Case "Int32", "Int64"
                        $ret &= $indent
                        $data = DllStructGetData($vVar, $nbElem, 1)
                        DllStructSetData($vVar, $nbElem, 0x7777666655554433, 1)
                        $readvalue = DllStructGetData($vVar, $nbElem, 1)
                        Switch $readvalue
                            Case 0x7777666655554433
                                $elem = "int64"
                                ; alias: uint64
                                ; alias: int_ptr(x64), long_ptr(x64), lresult(x64), lparam(x64)
                                ; alias: uint_ptr(x64), ulong_ptr(x64), dword_ptr(x64), wparam(x64)
                            Case 0x55554433
                                DllStructSetData($vVar, $nbElem, 0x88887777, 1)
                                $readvalue = DllStructGetData($vVar, $nbElem, 1)
                                $elem = ($readvalue > 0 ? "uint" : "int")
                                ; int aliases: long, bool, int_ptr(x86), long_ptr(x86), lresult(x86), lparam(x86);
                                ; uint aliases: ulong, dword, uint_ptr(x86), ulong_ptr(x86), dword_ptr(x86), wparam(x86)
                            Case 0x4433
                                DllStructSetData($vVar, $nbElem, 0x8888, 1)
                                $readvalue = DllStructGetData($vVar, $nbElem, 1)
                                $elem = ($readvalue > 0 ? "ushort" : "short")
                                ; ushort alias: word
                            Case 0x33
                                $elem = "byte"
                                ; alias: ubyte
                        EndSwitch
                        DllStructSetData($vVar, $nbElem, $data, 1)
                        If $idx = 1 Then
                            $ret &= StringFormat('%-' & 9 + StringLen($len) & 's ', $elem) & $data & @CRLF
                        Else
                            $ret &= $elem & "[" & $idx & "]" & @CRLF
                            For $i = 1 To $idx
                                If $iLimit And $idx > $iLimit And $i = $iLimit Then
                                    $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's ', '') & '... (' & $idx - $iLimit + 1 & ' more elements)' & @CRLF
                                    ExitLoop
                                Else
                                    $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's ', '') & DllStructGetData($vVar, $nbElem, $i) & @CRLF
                                EndIf
                            Next
                        EndIf
                    Case "String"
                        $oldvalue = DllStructGetData($vVar, $nbElem, 1)
                        DllStructSetData($vVar, $nbElem, ChrW(0x2573), 1)
                        $readvalue = DllStructGetData($vVar, $nbElem, 1)
                        DllStructSetData($vVar, $nbElem, $oldvalue, 1)
                        $elem = ($readvalue = ChrW(0x2573) ? "wchar" : "char")
                        If $idx > 1 Then $elem &= "[" & $idx & "]"
                        $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's ', $elem) & __DumpStr($data) & @CRLF
                    Case "Binary"
                        Local $blen = BinaryLen($data)
                        $elem = "byte"
                        If $idx > 1 Then $elem &= "[" & $idx & "]"
                        $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's ', $elem) & (($blen <= 32) ? $data : BinaryMid($data, 1, 16) & ' ... ' & StringTrimLeft(BinaryMid($data, $blen - 15, 16), 2)) & @CRLF
                    Case "Ptr"
                        $ret &= $indent
                        $elem = "ptr"
                        ; alias: hwnd, handle
                        If $idx = 1 Then
                            $ret &= StringFormat('%-' & 9 + StringLen($len) & 's ', $elem) & $data & @CRLF
                        Else
                            $ret &= $elem & "[" & $idx & "]" & @CRLF
                            For $i = 1 To $idx
                                $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's ', '') & DllStructGetData($vVar, $nbElem, $i) & @CRLF
                            Next
                        EndIf
                    Case "Double"
                        $ret &= $indent
                        $oldvalue = DllStructGetData($vVar, $nbElem, 1)
                        DllStructSetData($vVar, $nbElem, 10^-15, 1)
                        $readvalue = DllStructGetData($vVar, $nbElem, 1)
                        DllStructSetData($vVar, $nbElem, $oldvalue, 1)
                        $elem = ($readvalue = 10^-15 ? "double" : "float")
                        If $idx = 1 Then
                            $ret &= StringFormat('%-' & 9 + StringLen($len) & 's ', $elem) & $data & (IsInt($data) ? '.0' : '') & @CRLF
                        Else
                            $ret &= $elem & "[" & $idx & "]" & @CRLF
                            For $i = 1 To $idx
                                $ret &= $indent & StringFormat('%-' & 9 + StringLen($len) & 's %s', '', DllStructGetData($vVar, $nbElem, $i)) & (IsInt(DllStructGetData($vVar, $nbElem, $i)) ? '.0' : '') & @CRLF
                            Next
                        EndIf
                EndSwitch
                $nbElem += 1
            WEnd
            Return StringTrimRight($ret, 2)

;~      Case VarGetType($vVar) = "Table"
;~          Return 'Table '     ; TODO: enumerate contents

        Case Else
            Return StringFormat('%-13s', VarGetType($vVar)) & $vVar

    EndSelect
EndFunc   ;==>_VarDump

Func __VarDumpArray(ByRef $aArray, $iLimit, $sIndent = $_TAB)
    Local $sDump
    Local $sArrayFetch, $sArrayRead, $bDone
    Local $iSubscripts = UBound($aArray, 0)
    Local $aUBounds[$iSubscripts]
    Local $aCounts[$iSubscripts]
    $iSubscripts -= 1
    For $i = 0 To $iSubscripts
        $aUBounds[$i] = UBound($aArray, $i + 1) - 1
        $aCounts[$i] = 0
    Next
    $sIndent &= $_TAB
    While 1
        $bDone = True
        $sArrayFetch = ''
        For $i = 0 To $iSubscripts
            $sArrayFetch &= '[' & $aCounts[$i] & ']'
            If $aCounts[$i] < $aUBounds[$i] Then $bDone = False
        Next
        $sArrayRead = Execute('$aArray' & $sArrayFetch)
        If @error Then
            ExitLoop
        Else
            $sDump &= $sIndent & $sArrayFetch & ' => ' & _VarDump($sArrayRead, $iLimit, $sIndent)
            If Not $bDone Then
                $sDump &= @CRLF
            Else
                Return $sDump
            EndIf
        EndIf

        For $i = $iSubscripts To 0 Step -1
            $aCounts[$i] += 1
            If $aCounts[$i] > $aUBounds[$i] Then
                $aCounts[$i] = 0
            Else
                ExitLoop
            EndIf
        Next
    WEnd
EndFunc   ;==>_VarDumpArray

Func __DumpStr(ByRef $vVar)
    Local $len = StringLen($vVar)
    $vVar = Execute("'" & StringRegExpReplace($vVar, "([\p{Cc}])", "<0x' & Hex(AscW('$1'), 2) & '>") & "'")
    Return "'" & (($len <= 64) ? $vVar : StringMid($vVar, 1, 32) & ' ... ' & StringTrimLeft(StringMid($vVar, $len - 31, 32), 2)) & "'"
EndFunc   ;==>__DumpStr

Local $tTest = DllStructCreate("byte;byte[3];ubyte;ubyte[3];char;char[3];wchar;wchar[3];short;short[3];ushort;ushort[3];int;int[3];uint;uint[3];int64;int64[3];uint64;uint64[3];float;float[3];double;double[3];handle;handle[3];boolean;bool;hwnd;handle;int_ptr;long_ptr;lresult;lparam;uint_ptr;ulong_ptr;dword_ptr;wparam")
ConsoleWrite('Test structure types' & @LF & _VarDump($tTest) & @LF & @LF)

Local $struct = DllStructCreate("char[3];handle[3];uint[35];byte[128];wchar[190000]; double[3];int64[3];char[3];float;double;byte;ubyte;short;ushort;int;uint;char")
DllStructSetData($struct, 1, 'sos')
DllStructSetData($struct, 2, Ptr(123456789))
DllStructSetData($struct, 3, 8, 1)
DllStructSetData($struct, 3, 0x87654321, 2)
DllStructSetData($struct, 3, 256, 5)
DllStructSetData($struct, 4, Binary('sos'))
DllStructSetData($struct, 5, 'gno' & @CRLF & 'ji' & @TAB & 'o')
DllStructSetData($struct, 6, 3.1415926, 2)
DllStructSetData($struct, 7, 17, 1)
DllStructSetData($struct, 7, -1, 2)
DllStructSetData($struct, 8, 'end')
DllStructSetData($struct, 9, 2.7182818284590452353602874713527)
DllStructSetData($struct, 10, 2.7182818284590452353602874713527)
DllStructSetData($struct, 11, 107)
DllStructSetData($struct, 12, -108)
DllStructSetData($struct, 13, 109)
DllStructSetData($struct, 14, 110)
DllStructSetData($struct, 15, 111)
DllStructSetData($struct, 16, 112)

Local $f = _VarDump

Local $c[2][0]
Local $e[2][2] = [[Null, Default], [__DumpStr, MsgBox]]
Local Enum $p = 33333333333333
Opt("WinTitleMatchMode", 2)
Local $a[3][4] = [ _
    [$c, $e, ObjCreate("shell.application"), WinGetHandle("Dump.au3")], _
    ['zzz', 1/3, True, 0x123456], _
    [$struct, 93, Null, $p] _
]

ConsoleWrite('Test example of moderate complexity' & @LF & $f($a) & @LF)

[Jon]

Any time the word "pointer" is used then it's 32bit or 64bit depending.

HWND = 32bit = wrong

The DllCall docs look OK, probably only one of the tables got updated properly.

[jchd]

I follow up in the Help File/Documentation Issues thread, as there are more related to this.

[Richard Robertson]

So everything is already a ubyte, Is there a counter sbyte to represent char?

[trancexx]

^^ No there isn't and hence the confusion.

DllStruct misses it more than DllCall because in struct "char" is allways treated as string. There are some structs (particularly if coming from lower level languages) that have signed char elements and then you can't read values correctly because you allways get unsigned value.

But really, it's not big deal if you are familiar with the limitations and when you know what to do when you, for some reason, read values above 127.

[jchd]

+1

Edit: I meant: yes it misses somehow, but that isn't the most important thing in life.

Edited January 19, 2014 by jchd

[Ascend4nt]

More like -256.

[Richard Robertson]

More like -256.

That would never fit in a byte.

[Ascend4nt]

+1

Edit: I meant: yes it misses somehow, but that isn't the most important thing in life.

Wow, really. Editing after I responded. Lame.

That would never fit in a byte.

It's how you convert a unsigned byte (a value over 127) into a signed char.

[Ascend4nt]

Not to bump the topic, but I was told privately that I wasn't being clear enough (not by anyone in this thread).

Basically, when I say to subtract 256, this is mathematically the same as adding negative 256.   And -256 is represented as this in hexadecimal:

FFFF FFFF FFFF FF00

You can see clearly the last 8 bits are zeroes.  Effectively, adding the above to any 8-bit value will leave the lower 8 bits changed; however, the interpretation of the number now becomes different.  If the sign bit in the lower 8 bits was set, then what we just performed is sign-extension.

Since AutoIt works with integers (32 or 64-bit), when we extract a non-floating point value from a structure, regardless of size, it is always either 32-bit or 64-bit integer.  This is why you need to sign-extend.

To show what happens, and that the lower 8 bits are left unchanged when -256 is added, run the following code:

$stByte = DllStructCreate("byte;")
DllStructSetData($stByte, 1, -50)
$nVal = DllStructGetData($stByte, 1)
ConsoleWrite("Value as read from DLLStruct =  " & $nVal & @CRLF)
ConsoleWrite(" Value -256  = " & $nVal - 256 & @CRLF)
ConsoleWrite(" Value BitOR'd with -256 = " & BitOR(0xFFFFFF00, $nVal) & @CRLF)
DllStructSetData($stByte, 1, $nVal)
$nVal = DllStructGetData($stByte, 1)
ConsoleWrite("Value read from DLLStruct again = " & $nVal & @CRLF)