Required software: Visual C++ Express Edition (free).
Required knowledge: None
Open Visual C++, and on the start page click “Create project”. Select ‘Win32’ under projects, and then ‘Win32 project’ under Templates:
Next, you’ll have to type a name for your project. I’ll call mine “TutorialPlugin”, but you can call yours anything you like. Click OK, and then the Win32 application wizard will open. Just click Next, and then you should see this:
Select dll as the application type and then click “Finish” – Visual Studio will then create the files you need to get started. They’ll be listed in the Solution Explorer, on the left of the screen:
Most of the files here can be ignored, as they’re standard to all dlls – just make sure you don’t modify or delete them! The only important file is the one carrying the name of your project (here it’s ‘TutorialPlugin.cpp’), as this is where you’ll type all your commands.
To get started, open this file by double-clicking on it in the Solution explorer. At first you’ll see this standard code that Visual Studio has entered for you:
// TutorialPlugin.cpp : Defines the exported functions for the DLL application.
//
#include "stdafx.h"
Let’s start with something simple, like having the dll return a value. Type the following code after the #include command:
#define MYCOMMAND __declspec ( dllexport )
MYCOMMAND int GetValue( void )
{
int A = 4;
int B = 5;
A = A+B;
return A;
}
The #define command creates a macro so that when you compile your code, the text ‘MYCOMMAND’ will be automatically replaced with the line ‘__declspec (dllexport)’. This line of code is vital as it tells the DLL that the function will be exported, which means that other programs (like DBPro) can call this function from outside the DLL. Without this line, DBPro won’t know that your function even exists!
Now let’s look at the rest of the code you just typed. The function starts with:
MYCOMMAND int GetValue( void )
int tells the compiler that the function returns an integer value, GetValue is the name of the function, and ( void ) tells the compiler that no parameters will be passed in to the function. In DBPro you’d write this line as:
The {} curly brackets are used to define blocks of code in C++. The { marks the start of your list of commands for the function, while the } marks the end of the function. The next line, ‘int A = 4;’ tells the compiler to create an integer variable, called ‘A’, and assign it a value of 4. The semi-colon ( ; ) marks the end of the statement – without it, the compiler would run multiple lines together and probably crash.
After creating a variable B in the same way, the statement ‘A = A + B;’ simply adds the two values together (just like DBPro). Lastly, the line ‘return A;’ simply returns the answer of the sum. You could write the whole function in DBPro as:
Function GetValue()
A = 4
B = 5
A = A+B
EndFunction A
Press F7 to compile and you have your first DLL… Unfortunately, it’s not quite ready for DBPro to use!
You have to add a string table to the DLL, so that DBPro knows which functions are there, what parameters they take and what values they return. This is stored in a resource file, but you can’t edit these easily in Visual Studio 2008 Express, so you have to add it manually.
Right click the “Header Files” folder in the Solution Explorer and selected Add->New Item…
A dialogue box will appear, where you can choose what to add. Select ‘Header file(.h)’ and name it ‘resource.h’. Click Add, and then open the file to edit it.
You need to type the following:
#define IDS_STRING1 1
#define IDS_STRING2 2
#define IDS_STRING3 3
…
We only need the first line in this tutorial as the plugin only has one function, but you can have up to 999 functions in a single DLL. Note the pattern in the lines – IDS_STRING
n n, where
n is a number. The number increases so as to define a unique entry in the string table (which we can now create).
Right click on the “Resource Files” folder in the Solution Explorer, and select Add->NewItem again. Select the header file option again, but type the filename as ‘TutorialPlugin.rc’ – note the .rc file extension, as this will make it a resource file rather than a header file. When you click ‘Add’, the file will be created but a window will pop up saying that you cannot edit resource files.
Close this window, then right click on the .rc file name in the Solution Explorer and select ‘Open With…’. A choice of options will appear, select Source Code (Text) Editor and click OK.
The resource file can now be edited like a C++ source file. Type the following code:
#include "resource.h"
STRINGTABLE
{
IDS_STRING1 "GET VALUE[%L%?GetValue@@YAHXZ%ReturnAValue"
}
Everything within the {} curly brackets following the line STRINGTABLE makes up the string table. The single entry in the table is quite complex:
IDS_STRING1 "GET VALUE[%L%?GetValue@@YAHXZ%ReturnAValue"
Let’s break it down into its various parts:
GET VALUE The function name that DBPro will recognise
[ The function returns a value
% End Of Function Name
L The function returns an integer value
% End of Return/Parameter List
?GetValue@@YAHXZ Function’s Decorated Name
% End of Decorated Name
ReturnAValue Optional description of parameters
Just two things to note:
1) Although L is used to signify the return type, you can use other data types as well. The full list of codes are:
L = Integer
F = Float
S = String
O = Double Float (capital o)
R = Double Integer (capital r)
D = Boolean, BYTE, WORD and DWORD
0 = Zero Character (no param)
2) The function’s decorated name looks a little garbled, but it is very important. Hit F7 to compile and then open your DLL in notepad (or any other simple text editor). Do a search for your function name (in this case, GetValue) as you typed it in the C++ Editor. You can then copy the decorated name into the string table – don’t forget to include the question mark at the start!
Once the string table is complete, you’re ready to build and test your DLL. In Visual Studio, click Build->Configuration Manager.
Change the project configuration from Debug to Release, and click Close. When you compile again, your DLL will be placed in a folder called “Release”. It will also be much smaller, as Visual Studio removes a lot of stuff designed to aid the debugging of your DLL.
Copy this file to the folder “Dark Basic Professional\Compiler\plugins-user”, and DBPro will then be able to use it. Type this code in DBPro:
Print Get Value()
Wait key
End
When you run this code, you should see the number 9 printed on screen. You’ve also just written your first plugin!
We spend our lives chasing dreams. Dark Basic lets us catch some of them.