SDK for Dreamkeys v1.02 (spec-ver 1)

Here's the Software Development Kit for DreamKeys. It specifies how the DLL should be made,
and how a plug-in is made for DreamKeys.
The Project File is for Microsoft Visual C++ 6 SP2 and probably won't work on older versions.
However, there are just a few things you need to do when you make a new project in Visual C++ 5.
All functions available are explained. In the sample-code, extra information is provided as
comments. You can build and test this sample code without trouble, so you can use it as a
framework for your own plug-ins.

Making a new project:
-Create a new "Win32 Dynamic-Link Library" project.
-In the project settings, you'll need to set the calling convetion to __stdcall: Project|Settings,
then the C++ tab, select "code generation" in the drop-list and in the "Calling convention" select
"__stdcall". I've done this, so people programming in other languages also can make plug-ins.
__stdcall is just the standard way of passing arguments and handling the stack.
-Now add the source and header files you want. Don't forget you'll need to tell which functions
are exported. Most easy way is using the .def file provided in this SDK. You can leave out unused
functions. Exported functions have the same name as the functions in this source, so no name
decoration is allowed. Using the standard .def file, you don't need to bother with this.
-DreamKeys plug-ins always have the name DK_*.dll, so when you make your own plug-in, make sure
it starts with "DK_" and has the .dll extension. If your DLL has another name, you'll need to
rename it, or the control panel won't find it.

The source:
There are required functions and functions you may omit. Required functions MUST be made,
otherwise, things WILL crash and that's not what we want. The other functions can be used freely,
so if you want to provide more infomation about the plug-in using the Control Panel, you can
implement the MoreInfo function.

REQUIRED are:
-DLLName
-NumberOfHotkeys
-DefaultHotkey
-HotkeyName
-HotkeyPressed
-DLLSpecVersion

NOT required are:
-MoreInfo
-SaveSettings
-LoadSettings
-AcceptAuto
-Config

The functions:

char* DLLName(void)
The name of the plug-in. This is printed in the "Plug-in name" field of the control panel.
IN: none.
OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
     fits in the control panel.


int NumberOfHotkeys(void)
The number of hotkeys that are used by this plug-in (a plug-in can have more than one hotkeys)
This number is used extensivly and is printed in the "Number of Hotkeys used in this Plug-in"
field in the control panel.
IN: none.
OUT: return an integer >=0. 0 doesn't make much sense, but is supported.


void DefaultHotkey(int iHotkeyNr, int &iVkCode, int &iMod)
Although the user can change the default hotkey combination, the plug-in provides a default
combination for every hotkey. iMod specifies which of the modifiers (Control, Shift, Alt) must
be pressed, iVkCode is the virtual key code of the key to activate. Usually this is simply the
same character as the key.
IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
OUT: put the values you want in iVkCode and iMod, see the source for more details. iVkCode and
     iMod can both 0, when both are 0, no hotkey is used.


char* HotkeyName(int iHotkeyNr)
Provides a name for every Hotkey Action. This name is used in the "Hotkeys used by Plug-in" field
in the control panel. Make sure that when you place the words "In order to" in front of it, you
get a nice sentence.
IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
     fits in the control panel.


void HotkeyPressed(int iHotkeyNr)
This function is called when a key combination associated with the plug-in is pressed. Which
hotkey is pressed is provided in iHotkeyNr. Do whatever needs to be done to do the action.
IN: 0>=iHotkeyNr>=NumberOfHotkeys-1 (start counting at 0!)
OUT: none.


int DLLSpecVersion(int DKVersion)
Verifies the plug-in and control panel can work with each other. The plug-in can decide if it
can work with the version of the Control Panel, and the Control Panel can decide if it can work
with the version of the plug-in.
IN: DKVersion, integer, provides the specification-version (spec-ver) with which the Control Panel
    communicates with the plug-ins. In DreamKeys v1.01 this is 1, but when the specifications
    change, this will be a higher number. If your plug-in is written for spec-ver 3, and the
    Control Panel reports in communicates with spec-ver 2, your plug-in is most likely to fail
    and/or crash.
OUT: To avoid these crashes, return 0 if your plug-in is made with a higher spec-ver than the
     Control Panel, otherwise, return the spec-ver number for with which this plug-in was made.

Note: you CAN provide backwards compatibility in the plug-in. If the Control Panel reports it is
using spec-ver 1, and your plug-in is written for spec-ver 2 it still might be possible to use
the plug-in, as long as you stick to the rules of spec-ver 1. When you know your plug-in will
work with an older version of the Control Panel, simply return the spec-ver of the plug-in.

As for now in spec-ver 1, you can simply return 1 without any checking.


char* MoreInfo(void)
This text is printed in the MessageBox when the user pressed the "More Information" button.
Usually, this is a short description and a copyright notice.
IN: none.
OUT: return a pointer to a zero-terminated string. Size doesn't really matter, as long as it
     fits in the message box. Use '\n' to get a newline.


BOOL AcceptAuto(void);
Some plug-ins won't work correctly if they operate in "Auto" mode, since the plug-in is loaded
and unloaded immediatly after the action is completed. Quick!hide, for example, need to store
information. This information is lost when the plug-in is unloaded.
With this function, you can tell the Control Panel if it is possible to use the plug-in in
Auto-mode.
IN: none.
OUT: return 0 (false) if the plug-in won't work correctly in Auto-mode. Otherwise return
     whatever you want (true).

Note: The control panel only issues a warning when a user tries to switch the plug-in to "auto"
mode, when AcceptAuto is false. Look at Quick!Hide for an example.


void Config(void);
When the user presses the "Other plug-in settings" button, this function is called. You can open
a dialog so the user can make additional settings for the plug-in. Both ICQ Shortcut and
Quick!Start use this feature.
IN: none.
OUT: none.


BOOL LoadSettings(int iNumber, char *&pszKey, char *&pszValue, int &iValueSize)
Provides an interface to load settings from the DreamKeys.ini file.
This function is implemented because I think it's a good thing when all settings are together in
one .ini file. This way, settings can be copied and backuped easily.
LoadSettings is the first thing executed after the version check.
IN: iNumber: integer, starts at 0, increased by one every call to LoadSettings.
    pszKey: a pointer to a zero-terminated string with the key- or item-name of which data you
    want to read. Make this static or global!
    pszValue: a pointer to a zero-terminated string which will receive the data.
    ALLOCATE the memory before passing this pointer, and/or make it a global variable!
    iValueSize: put the size of pszValue in this variable.
OUT: return TRUE when you need more things to load, otherwise return FALSE (0)


BOOL SaveSettings(int iNumber, char *&pszKey, char *&pszValue)
Provides an interface to save settings in the DreamKeys.ini file. Use this in conjuction with the
LoadSettings function. You can only save strings, so you'll have to convert numbers to a string.
Also, avoid using key names starting with "Mod" or "VkCode" as this is likely to interfere with
other things.
SaveSettings is executed just before the plug-in is unloaded.
IN: iNumber: integer, starts at 0, increased by one every call to SaveSettings.
    pszKey: a pointer to a zero-terminated string with the key- or item-name of which data you
    want to save. Make this static or global!
    pszValue: a pointer to a zero-terminated string which contains the data to be saved. Make sure
    this data is available outside the function, so make it global or static!
OUT: return TRUE when you need more things to save, otherwise return FALSE (0)


Need more help making plug-ins?
I'll be glad to help you out with problems. Keep in mind that I've only used Visual C++, and I've
no experience with Inprise products. Also, my knownledge is limited to the Win32 API.
e-mail: Randy@dgdr.com
ICQ UIN: 1384866. When you ask for my authorization when you want to add me to your ICQ list,
please make clear it's about DreamKeys; I get a lot of requests from people asking me if I can
"hack" something and other things I'm not interested in...