Understanding DllCall and data types

[jguinch]

Hi !
I have difficulties to learn how to use WinAPI functions with DllCall.
 
I red the (very good) >Tutorial on DllCall() & DllStructs. I understand the tutorial, but it's hard for me to apply it myself.
For example, the function GetUserName (just an example, I know @username of course) :

BOOL WINAPI GetUserName(
  _Out_    LPTSTR lpBuffer,
  _Inout_  LPDWORD lpnSize
);

Parameters

lpBuffer [out]

    A pointer to the buffer to receive the user's logon name. If this buffer is not large enough to contain the entire user name, the function fails. A buffer size of (UNLEN + 1) characters will hold the maximum length user name including the terminating null character. UNLEN is defined in Lmcons.h.
lpnSize [in, out]

    On input, this variable specifies the size of the lpBuffer buffer, in TCHARs. On output, the variable receives the number of TCHARs copied to the buffer, including the terminating null character.

    If lpBuffer is too small, the function fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. This parameter receives the required buffer size, including the terminating null character.

For me, the first parameter (lpBuffer) sould be a STR type (from AutoIt helpfile in DllCall)

The second, a DWORD (I think), but the MSDN says it is the size of the lpBuffer, in TCHARs : what is it ?

In >this topic, I found a solution for GetUserName :

MsgBox(0, "", _GetUserName() )

Func _GetUserName()
    Local $tlpnSize = DllStructCreate("dword[255]")
    Local $aDLL = DllCall("Advapi32.dll", "int", "GetUserName", "str", "", "dword*", DllStructGetPtr($tlpnSize))
    If @error Then Return SetError(@error, 0, 0)
    Return $aDLL[1]
EndFunc

I don't understand :

 - why using "int" instead of "bool" for the first parameter (as said in the MSDN page)?

 - why the second parameter value is empty ?

 - does TCHAR is equals to dword[255], how to find this by myself ?

 - why the last parameter is not DllStructGetPtr (I thought the size of the lpBuffer buffer should have been defined by DllStructGetSize)

As you can see, I am a newbie for this, and I would like to understand more, but I don't know how ....

Can someone give me some explanations or links ??

Thanks in advance, and sorry for the blurred question...

[funkey]

I would write the same function this way, the more right way:

Func _GetUserNameFunkey()
    Local $aDLL = DllCall("Advapi32.dll", "BOOL", "GetUserName", "str", "", "dword*", 255)
    If @error Then Return SetError(@error, 0, 0)
    Return $aDLL[1]
EndFunc

BOOL and int are both 32 bit integer, so it can be interchanged, but for understanding of the function use BOOL so that you know there are only two values returned, zero and non zero.

If you pass an empty string to the dll function then this happens lieke documentation says: a minimum of 65536 chars is allocated.

So the last parameter can be up to 65536 without any difference. But usernames are not that long

[jguinch]

Thanks for this explanation Funkey. I appreciate you help.

Now, can you explain me how to represent the EXTENDED_NAME_FORMAT parameter in GetUserNameEx function ?

I tried this, but it does not work at all... :

MsgBox(0, "", _GetUserNameEx() )

Func _GetUserNameEx()
    Local $aDLL = DllCall("Secur32.dll", "bool", "GetUserNameEx", "int", 2, "str", "", "ulong*", 255)
    If @error Then Return SetError(@error, 0, 0)
    Return $aDLL[1]
EndFunc

do not laugh, please ...

[JFX]

Looks good, but you want to return the second parameter, won't you?

Return $aDLL[2]

[jguinch]

Allright JFX !

I begin to understand : $aDLL[1] contains the value of the first parameter (value=2), $aDLL[2] contains the value of the 2nd parameter and so on...

It is written in the helpfile, but I did not understand that.

Thanks, it's clearing up !

 

I will continue with other functions and come here to ask for help (I will need, sure)

Global Const $NameUnknown = 0, _
             $NameFullyQualifiedDN  = 1, _
             $NameSamCompatible     = 2, _
             $NameDisplay           = 3, _
             $NameUniqueId          = 6, _
             $NameCanonical         = 7, _
             $NameUserPrincipal     = 8, _
             $NameCanonicalEx       = 9, _
             $NameServicePrincipal  = 10, _
             $NameDnsDomain         = 12
             
MsgBox(0, "", _GetUserNameEx($NameDisplay) )



Func _GetUserNameEx ($NameFormat)
    $ret = DllCall("Secur32.dll", "bool", "GetUserNameEx", "int", $NameFormat , "str", "", "ulong*", 255)
    If @error Then Return SetError(1, 0, 0)
    
    Return $ret[2]
EndFunc

[jguinch]

Well, now, I tried to use CreateProfile, and... it's a success !

MsgBox(0, "", _WinAPI_CreateProfile("S-1-5-21-3114055946-370887941-3244374214-500", "administrator") )

Func _WinAPI_CreateProfile($sUserSid, $sUserName)
    Local $ret = DllCall("Userenv.dll", "long", "CreateProfile", "wstr", $sUserSid, "wstr", $sUserName, "wstr", "", "dword", 255)
    If @error Then Return SetError(1, 0, -1)
    
    Return $ret[3]
EndFunc

i still have difficulties to understand when I must use (or not) a wildcard after the datatype...

[Danyfirex]

when is a out data.

Saludos

[jguinch]

Thanks Danyfirex.

So, with CreateProfile, the pszProfilePath parameter should be wstr*, no ?

it's still dark, sorry ...

[trancexx]

wstr is AutoIt's way to say wchar_t*, if you are familiar with C++.

[jguinch]

Thanks trancexx.
Not familiar at all... I have never use C or C++...
It seems to be a reason to my difficulties.

I think there are a lot of members in this case.
What could you recommend to us ? Is it possible to learn how to use complex WinApi funtions with these limited knowledges?

Thanks for your patience

Edited October 4, 2014 by jguinch

[Danyfirex]

You just need to see Conversions from Windows API types to AutoIt types.

it says 

LPCWSTR/LPWSTR=wstr

or get the pointer (ptr*) to that unicodestring and supply that pointer to a structure (dllstructcreate("wchar",yourptr)).

 

PD: I know basic about C++/C

Saludos

Edited October 4, 2014 by Danyfirex

[jguinch]

Hi again !

I tried some other functions, and now I have a little question.

Here is my code for QueryFullProcessImageName (just for learning, I know _WinAPI_GetProcessFileName):

$h = _OpenProcess( @AutoitPid)
MsgBox(0, "", _QueryFullProcessImageName($h) )


Func _QueryFullProcessImageName($hProcess)
    $ret = DllCall("Kernel32.dll", "bool", "QueryFullProcessImageName", "handle", $hProcess, "dword", 0, "str", "", "dword*", 256)
    If @error Then Return SetError(1, 0, -1)
    
    Return $ret[3]
EndFunc


Func _OpenProcess($iProcessId)
    $ret = DllCall("Kernel32.dll", "HANDLE", "OpenProcess", "dword", 0x0400, "bool", True, "dword", $iProcessId)
    Return $ret[0]
EndFunc

As you can see in my QueryFullProcessImageName call, I set the last parameter to 256. But if the returned full path length is bigger than this value, the function fails.

So my question is : which value should I use for this parameter ? Something like 4096 or more ?

Thanks again. It''s a pleasure to learn with you !

 

Edit : Danyfirex, I do not really understand what you said...

Edited October 4, 2014 by jguinch

[Danyfirex]

If you use (ANSI) API  Use 256.

if you use (Unicode) API use  32767

what exactly you don't understand?

Saludos

Edited October 4, 2014 by Danyfirex

[jguinch]

OK, thanks  Danyfirex!

[Danyfirex]

what exactly you don't understand >here?

Saludos

[jguinch]

LPCWSTR/LPWSTR=wstr : OK, understand

(dllstructcreate("wchar",yourptr)) : node to the brain!

[Danyfirex]

In this case you have to do the structure before because is not a pointer to constant(LPCSTR/LPCWSTR). and pass the pointer. look:

MsgBox(0, "", _WinAPI_CreateProfile("S-1-5-21-3114055946-370887941-3244374214-500", "Danyfirex") )


Func _WinAPI_CreateProfile($sUserSid, $sUserName)
Local $tPath=DllStructCreate("wchar[255]")
    Local $ret = DllCall("Userenv.dll", "long", "CreateProfile", "wstr", $sUserSid, "wstr", $sUserName, "ptr", DllStructGetPtr($tPath), "dword", 255)
    If @error Then Return SetError(1, 0, -1)
    Return DllStructGetData($tPath,1)
EndFunc

If it was a pointer to a constant you could use ptr* something like this:

;this code will not work (it's a way if the api returns a pointer, CreateProfile does not).

msdn say:

pszProfilePath [out]

When this function returns, contains a pointer to the full path of the profile.

But it's wrong it will need a wide string pointer to fill it.

MsgBox(0, "", _WinAPI_CreateProfile("S-1-5-21-3114055946-370887941-3244374214-521", "Danyfirex") )

Func _WinAPI_CreateProfile($sUserSid, $sUserName)
    Local $tPath=0
    Local $ret = DllCall("Userenv.dll", "long", "CreateProfile", "wstr", $sUserSid, "wstr", $sUserName, "ptr*", 0, "dword", 255)
    If @error Then Return SetError(1, 0, -1)
    $tPath=DllStructCreate("wchar[255]",$ret[3])
    Return DllStructGetData($tPath,1)
EndFunc

or simply use Conversions from Windows API types to AutoIt types

Saludos

Edited October 4, 2014 by Danyfirex

[jguinch]

You exactly point out a difficulty for me : wchar[255] in a structure is equivalent to wstr ?

Sorry for these ridiculous questions....

Moderators, if you consider this topic is not in the good section, you can move it. The problem is that I have not just one question, but a lot of interrogations..

Thanks again Danyfirex.

[Danyfirex]

Basically yes.

wstr is a pointer to a sequence of Unicode characters with null termination( in this case for being a wide(unicode) string need to be double null termination)

wchar is a sequence of Unicode characters.

if you do a structure with wchar[n size] and pass its pointer is  same as you pass wstr.

Saludos

[jchd]

wchar is the type of one UTF16 (-LE or BE) Unicode encoding unit. A Unicode character needs one or two encoding unit(s) to represent. Those Unicode characters requiring two units are seldom used and AFAIK no widespread font can display them.

So most practical applications restrict wchar to mean "one Unicode character", which implies that only those in BMP (or plane 0 or base Multilingual plane) can be represented. This restricted character set is (roughly) called UCS-2 and it's what AutoIt uses.

wchar is to wstr what char is to str. [w]str is a pointer to the base address of a C [w]char array (C doesn't have a built-in string type).