BBC BASIC for Windows
Programming >> BBC BASIC language >> Windows API Parameters
http://bb4w.conforums.com/index.cgi?board=language&action=display&num=1450220719
Windows API Parameters
Post by Kirkkaf13 on Dec 15th, 2015, 10:05pm

Hello,

I am playing around with some of the examples that use the Windows API and looking at the Microsoft Dev Centre to get a description of what functions do and how they work.

The GetWindowsText function like many others take parameters, in this case it takes 3.

1 - HWND
2 - LPTST
3 - INT

Is LPTST a string? After a quick google search I came across this article http://www.codeproject.com/Articles/2995/The-Complete-Guide-to-C-Strings-Part-I-Win-Chara which suggest it is zero-terminated string of TCHAR, but when calling this function from BBC Basic why do I have to use a integer?

Code:
SYS "GetWindowText", @hwnd%, title%, 1000


I am trying to get a better understand of how the types work so I can just use the Microsoft reference to call the API functions I need passing the correct parameters.

Thank you.
Re: Windows API Parameters
Post by hellomike on Dec 16th, 2015, 09:01am

Hi,

As far as I understand LPTST stands for Long Pointer To String. In practice it means it is the memory address of where the null terminated string is located.

And so it is just a number hence an integer.
Furthermore, note that the API call Gets a text. So, as far as I understand, the call will place the text (string) into the memory, starting at the provided address. I'm pretty sure this call (or any) will test if the address provided is a valid one or if its OK to overwrite what is in it already!
In other words you must make sure to provide a memory location where it is OK for the call to dump the text string. You need to DIM it. For example:

Code:
DIM text% 255


will make BB4W set aside a block of 256 bytes which can be used to store data in.

Indeed, 'translating' Windows API descriptions into how to use it in BB4W is a pain.

Regards,

Mike
Re: Windows API Parameters
Post by Kirkkaf13 on Dec 16th, 2015, 2:56pm

Hello,

Thank you for your response Mike.

I would like to ask a few further questions just to make sure I am understanding the concept correctly.

Here is the full function I am using:
Code:
      DEF FN_get_window_title
      LOCAL title%
      DIM title% LOCAL 3
      SYS "GetWindowText", @hwnd%, title%, 300
      = $$title%


So the 3rd parameter of the GetWindowText function determines the amount of characters to return. If I want to store up to 300 characters, and as the BB4W documentation suggests Integers are stored in 32 bits / 4 bytes. When calling DIM for the title%, will LOCAL 3 will be enough space?

As you suggested the API call is returning a string of text, so the variable title% is an Integer not a String, is this because it refers to the memory address rather than the data stored at that address?

I know in essence, any character is just a number, I am trying to understand what is happening behind the scenes here. If my text was just the character A would 65 be at the memory location title%? If so, does the memory address have a heading as such so it knows this is not the number 65 but in fact the letter A?

Sorry for all the questions, I am new to these concepts.

Kind regards,

Kirk



Re: Windows API Parameters
Post by DDRM on Dec 16th, 2015, 6:27pm

Hi Kirk,

No, 3 won't be enough. As Mike says, what you are doing is to create a buffer (by reserving some memory), into which the API call can put the name. Your variable title% is an integer holding the address of that memory.

Characters are (normally - if they are ASCII not unicode) stored in a single byte, so your DIM statement would need to allow enough space for your string. So if you want 300 characters (plus a terminating null character), you'd need (at least)

DIM title% LOCAL 300

...which actually gives you 301 bytes (the first is number 0!). In general, I'd recommend DIMming a bit spare (especially since this is a LOCAL variable, so you get it back when the routine finishes).

Having said that, I think the last number in the call is the MAXIMUM length it will return, and I can't remember offhand whether that includes the final termination character or not - you could check on MSDN.

The final

=$$title%

is a rather cryptic way of telling BB4W that it should return a string, which is stored as a nul-terminated string, at address title%

Hope that helps.

D
Re: Windows API Parameters
Post by Kirkkaf13 on Dec 16th, 2015, 9:20pm

Hello D,

This is just the response I was looking for, it makes a lot more sense now.

I will continue to play around with various Windows API commands and see what I can come up with.

Regards,

Kirk