When MSDN says "pointer to structure", what is proper PB translation?

[John Montenigro]

When the SDK Help for an API call says that a parameter should be a "pointer to a structure", is it asking for an address or a handle?

Sorry to be dense on this topic, but the MSDN definition of "pointer to structure" is not clear to me, and when I read the PB Help for STRPTR, VARPTR, and ASCIIZ PTR, I get pretty lost.

I'm trying to use this:

BOOL TrackMouseEvent(

LPTRACKMOUSEEVENT lpEventTrack // pointer to a TRACKMOUSEEVENT structure
);

So in PB code, I need:

      Local tme As trackmouseeventapi

and, (here's what I'm not sure of):

      Local tme_ptr As String Ptr

Then, to make the call (besides setting the other members), I need what?

      TrackMouseEvent(@tme_ptr)

Can anyone provide a clear explanation of what I need here and why?

Thanks!

[Edwin Knoppert]

If you pass a variable BYREF it will pass the pointer to the memory.
So:
Local p as RECT
TheFunction( p )
would do if you have declared TheFunction() like:
Delcare TheFunction lib "...." Alias .... ( BYREF R AS RECT )

[José Roca]

TrackMouseEvent is already defined in win32api.inc:

DECLARE FUNCTION TrackMouseEvent LIB "USER32.DLL" ALIAS "TrackMouseEvent" (lpEventTrack AS TRACKMOUSEEVENTAPI) AS LONG

So in PB code, you need:

Local tme As trackmouseeventapi

Then, to make the call (besides setting the other members), you need:

TrackMouseEvent(tme)

Why?

Because if a parameter is declared BYREF, PB passes a pointer to the variable.

[John Montenigro]

I was incorrectly expecting that the pointer had to be defined explicitly, and now I have a process for how to analyze what's needed - after reading the MSDN, I should have checked the PB DECLARE...

Thanks Edwin for the example, and Jose for the clarification!

[José Roca]

It is fundamental to understand calling conventions and parameters passing.

You could also declare the function as:

DECLARE FUNCTION TrackMouseEvent LIB "USER32.DLL" ALIAS "TrackMouseEvent" (BYVAL lpEventTrack AS TRACKMOUSEEVENTAPI PTR) AS LONG

and use it as:

LOCAL tme AS TRACKMOUSEEVENTAPI
tme.cbSize = SIZEOF(TRACKMOUSEEVENTAPI)
tme.dwFlags = %TME_LEAVE
tme.hwndTrack = hwnd
tme.dwHoverTime = 1
TrackMouseEvent(VARPTR(tme))

or, using the equivalent to C code:

LOCAL ptme AS TRACKMOUSEEVENTAPI PTR
@ptme.cbSize = SIZEOF(TRACKMOUSEEVENTAPI)
@ptme.dwFlags = %TME_LEAVE
@ptme.hwndTrack = hwnd
@ptme.dwHoverTime = 1
TrackMouseEvent(ptme)

In the three cases, the result is the same: A pointer to a TRACKMOUSEEVENTAPI structure is pushed into the stack.

[colin glenn]

José, in your second example, to a newbie, it's not pointing out that you need to have the pointer variable pointing to a valid structure to succeed.

LOCAL tme AS TRACKMOUSEEVENTAPI
LOCAL ptme AS TRACKMOUSEEVENTAPI PTR

ptme = VARPTR(tme)
...

Also, would not calling the function and enforcing BYREF generate the pointer for you?
code TrackMouseEvent(BYREF tme)/code

[José Roca]

Yes. This is what happens when you post code without testing it first

[Fred Harris]

I tried pretty hard to explain that sort of thing throughout my Beginning Api Programming Example series over in Jose's Forum...

http://www.jose.it-berater.org/smfforum/index.php?board=285.0

Like Jose said, its not even barely possible to comprehend the Api documentation without understanding this, it is so fundamental. The thing is, if you have been programming in a BASIC dialect for ten years, you have been using pointers for ten years perhaps without even knowing it.

[John Montenigro]

Wow! What a goldmine! Thanks Fred (and Jose for hosting)!!!

there goes the rest of my weekend!