LinkDll - Learn To Code - PlayBASIC Documentation

LinkDll

LinkDll "DllName"

Parameters:

"DllName" = Name of DLL

Returns: NONE

LinkDll opens a DLL binding block. DLL binding blocks allows us to declared external DLL functions as if they are PlayBASIC user defined functions within your PlayBASIC code. Once declared, those external functions can be called just like their native user functions and psubs. Prior to the addition of LinkDLL, the PlayBASIC programmer would have to manually wrap PlayBASIC functions around DLL function calls (via CallDll) to create similar functionality. Which is not only tedious for the programmer to set up, but it's generally slower to execute. Now we just declare them as functions at the top of your code and use them at will.

Function Declaration Format

      Functions are expected to be declared in the following format. At the time of writing PlayBASIC only supports Integer,Float and String data types as input and return parameters.

      Bellow is an example of how LinkDLL function delcaration is expected to be formated,

PBFunctionName(IntegerParam,FloatParam#,StringParam$) alias "DLLFunctionName" as ReturnType

      The declaration contains the name of the function that the user will call in their program, followed by the parameter list. DLL functions don't actually have a way to grab the parameter lists from them, so the user must know these up front. Failure to get them correct and you should expect the function to be faultly. After the parameter list we use the ALIAS keyword to define what this function name is going to be inside the DLL. DLL function names can be a little strange, since they'll often have some crazy characters in them. It's important you get the name exact, otherwise PlayBASIC won't be able to find it correctly.

      Valid Return Types

                 As Integer (32bit)
                 As Float (32bit)
                 As String

      If a function doesn't return a result then just leave it blank.

How Can I Find The Function Names Within a DLL?

That's a good question, generally system / windows DLL's are well documented. So head over to your search engine of choice and search for the dll name and you'll find thousands of results, Happy hunting. If you can't find any information on the dll in question, there are some tools that can pull out a list of function names from dlls, but unforunately they can't get the parameters. So those can take a bit more research on your part, unforunately we can't automate this process for you.

FACTS:

      * LinkDll expects the DLL name to be a constant/ string.

      * Linked dll function names are resolved prior to program start up. But, if a function name is unknown, an error is not generated until the function is called.

      * Linked DLL functions can be called using CallFunction.

      * LinkDll functionality was expanded to support DLL resource binding in PlayBASIC V1.64O (June 2013). This feature allows PlayBASIC to bind the DLL file not only into the final EXE, but execute it from memory.

Mini Tutorial:

Here's an example that uses LinkDll to declare customer function to hide/show the windows mouse pointer.

; Start a DLL Binding block
  LinkDll "user32.dll"

   ; Declare the function name HIDEMOUSE as an ALIAS to
   ; the ShowCursor function inside the user32.dll
     HideMouse(State) Alias "ShowCursor"

   ; End of the DLL binding block
  EndLinkDll


; Start of test program
  Do

   ; Clear the screen to black
     Cls RGB(0,0,0)

   ; Display control instructions
     Print "Press Mouse Buttons to hide/show mouse"


   ; Check if the Left mouse is pressed, if so, Hide mouse
     If MouseButton()=1 Then  HideMouse off

   ; Check if the Right mouse is pressed, if so, Show mouse
     If MouseButton()=2 Then  HideMouse on


   ; refresh the screen
     Sync
   ; Loop back to the Do statement
  Loop


Related Info:	Alias \| CallDll \| CallDll# \| CallDll$ \| CallFunction \| EndLinkDll \| LoadDLL :