The ABCs of APIs Lesson 10
Using Winstring with Pointers to Text

In Lesson 5 we discussed the use of a string variable as a buffer sent to an API function. The function filled the buffer with text, which we were able to retrieve and use. Some API functions create the string in memory and return a pointer to the memory location. We retrieve the text from that location with Winstring()

Winstring()

Winstring() retrieves a string of text from a pointer to a memory location or from a handle to a data object.

In the following snippet, ptrText is a pointer to a memory location that contains a string of text.

t$ = winstring(ptrText)
print "Text is ";t$

In the following snippet, hText is a handle to a data object in memory that contains a string of text.

t$ = winstring(hText)
print "Text is ";t$

The following snippet demonstrates that winstring() can be used with struct members of type ptr. The type "PTR" is a pointer.

struct Test, var$ as ptr
Test.var$.struct="Hello, World!"
print winstring(Test.var$.struct)

Demo

The following small program opens the clipboard and checks for text data. If there is text data on the clipboard, it uses winstring() to retrieve the data from the handle to the text object that is returned by the function.

'A handle to the window to be associated with the open clipboard.
'If this parameter is NULL, the open clipboard is associated with the current task.
hTask = _NULL
 
calldll #user32, "OpenClipboard",_
    hTask as ulong,_    'handle to window or null for current task
    result as long      'nonzero=success
 
calldll #user32, "GetClipboardData",_
    _CF_TEXT as long,_    'clipboard format for text data
    hText as long         'handle to data object
 
if hText<>0 then
    print "Text on clipboard is:"
    'retrieve text at this address:
    t$ = winstring(hText)
    print t$
else
    print "No text data on clipboard."
end if
 
calldll #user32, "CloseClipboard", result as void

What's Next?

Lesson 11 will discuss the way to translate documentation for DLLs from other languages into Liberty BASIC syntax.

Written by Alyce Watson. For more on APIs, see:
APIs for Liberty BASIC