TranslatingDLLsfromC

=ABCs of APIs 1111.1 - <span style="background-color: #ffffff;"> Translating documentation for DLLs in MS "C" into Liberty BASIC </span>= 
//Petermat//
[[toc|flat]]
----
=Introduction= 
I am afraid this note is not by your friendly expert <span style="background-color: #ffffff;">Alyce Watson, but by ignoramus Petermat. Why? Because Alyce did not write this, I needed it, and all I can do is to try to find my way. If I fail maybe someone will be encouraged to pick up and correct the note.</span>note. (This is a wiki, right?).</span>
<span style="background-color: #ffffff;">Why is the note necessary? Because Microsoft documents it's API's using C / C++ examples</span>

<span style="font-size: 1.4em;">**The example I am going to use.**</span>First Example.**</span>
The following LB code is due to <span style="background-color: #ffffff;">Alyce Watson at </span>http://libertybasicuniversity.com/lbnews/nl109/browse.htm.
I don't intend to go into the semantics or use of this - just its translation.
[[code]]
calldll #shell32, "SHGetPathFromIDList",_
            lpIDList as long,_
            sPath$ as ptr,_
            r as long
[[code]]
The MS definition at https://msdn.microsoft.com/en-us/library/windows/desktop/bb762194(v=vs.85).aspx
[[code]]
BOOL SHGetPathFromIDList(
  _In_  PCIDLIST_ABSOLUTE pidl,
  _Out_ LPTSTR            pszPath
);

[[code]]
This is C++ code. SHGetPathFromIDList is the name of a function - just like LB - and the comma delimited items inside the () are the two function parameters. A C++ function returns a value just like an LB function - which is covered as described in previous notes as the last parameter in the LB call - here it's "r as long". You do have to know that "BOOL" defines the type of the C++ return and that this needs a "long" type in LB. The "_In_" and "_Out_" mean just what you might think. "pidl" is defined as of type "PCIDLIST_ABSOLUTE" and the MS definition of this is "address of an item identifier list" which has to be type long in LB.

**<span style="font-size: 18.2px;">The Second Example.</span>**
Now let's start with the C++ definition and code from https://msdn.microsoft.com/en-us/library/windows/desktop/bb762115(v=vs.85).aspx
[[code]]
<span style="font-family: Consolas,Courier,monospace; font-size: 14px;">PIDLIST_ABSOLUTE SHBrowseForFolder(
  _In_ LPBROWSEINFO lpbi
);</span>
[[code]]
Looking at this code we see that the return is of type "PIDLIST" (whatever that is), there is one parameter which is used as an input by function 
SHBrowseForFolder. The definition is headed "<span style="font-family: 'Segoe UI','Lucida Grande',Verdana,Arial,Helvetica,sans-serif;"><span style="color: #000000; font-family: 'Segoe UI Semibold','Segoe UI','Lucida Grande',Verdana,Arial,Helvetica,sans-serif; font-size: 1em; text-decoration: none;">[[https://msdn.microsoft.com/en-us/library/windows/desktop/bb773177(v=vs.85).aspx|The Windows Shell]]</span> <span style="color: #000000; font-family: 'Segoe UI Semibold','Segoe UI','Lucida Grande',Verdana,Arial,Helvetica,sans-serif; font-size: 1em; text-decoration: none;">[[https://msdn.microsoft.com/en-us/library/windows/desktop/ff521731(v=vs.85).aspx|Shell Reference]]</span> </span><span class="breadcrumbDropSmall" style="font-family: 'Segoe UI','Lucida Grande',Verdana,Arial,Helvetica,sans-serif;"> <span style="color: #000000; font-family: 'Segoe UI Semibold','Segoe UI','Lucida Grande',Verdana,Arial,Helvetica,sans-serif; font-size: 1em; text-decoration: none;">[[https://msdn.microsoft.com/en-us/library/windows/desktop/bb762115(v=vs.85).aspx#|Shell Functions]]</span>" which is the clue we are still working with shell32.dll, so we can continue to use #shell32 inour LB code. The definition tells us that type </span><span style="background-color: #eeeeee; font-family: Consolas,Courier,monospace; font-size: 14px;">LPBROWSEINFO </span><span style="font-family: Arial,Helvetica,sans-serif;">is "A pointer to a BROWSEINFO structure" - which at least tells us it is of type struct from an LB perspective. And lastly, the definition states that the return "</span><span style="font-family: Arial,Helvetica,sans-serif;"> a PIDL that specifies the location of the selected folder"</span>

[[code]]
calldll #shell32, "SHBrowseForFolder",_
            lbpi struct,_
            result as
[[code]]






Much moreMore to come - Petermat
<span style="display: block; height: 1px; left: 0px; overflow: hidden; position: absolute; top: 583.5px; width: 1px;">SHBrowseForFolder</span>