ABCs of APIs 10

**The ABCs of APIs Lesson 10**
Using Winstring with Pointers to Text
[[toc]]

In [[ABCs of APIs 5|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 returned from an API function. It can be in the form of 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. 

[[code format="lb"]]
t$ = winstring(ptrText)
print "Text is ";t$
[[code]]

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

[[code format="lb"]]
t$ = winstring(hText)
print "Text is ";t$
[[code]]

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

[[code format="lb"]]
struct Test, var$ as ptr
Test.var$.struct="Hello, World!"
print winstring(Test.var$.struct)
[[code]]

==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.

[[code format="lb"]]
'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
[[code]]

==What's Next?==

[[ABCs of APIs 11|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:
[[http://www.lulu.com/content/611431|APIs for Liberty BASIC]]