HyperIM SDK reference
This document is not yet fully complete
This document contains all you want (and need) to know in order to create HyperIM
plugins. HyperIM is a successful application used by tens of thousands of users
world-wide, so creating your very own plugins to extend HyperIM's features will
surely make you proud of your work, and also prove to the world your developer
abilities (or at least your great ideas).
About the HyperIM kernel
HyperIM was written in the C++ programming language, even though just a very
few of the C++ language features were used (like object-oriented code). At the
very lowest level, it uses native Windows API calls, without any MFC or other
layers. This means that HyperIM is very fast, and only relies itself on the
Windows core libraries.
The HyperIM core allows dynamic loading of other modules (which we will call
plug-ins), written by 3rd parties. This allows any kind of application extendability.
Plugins can be written in any other programming language that supports creating
DLLs (dynamic link libraries). As long as the plugins are created accordingly
to the HyperIM plugin SDK, they will be recognized by the main program, and
be usable.
Plugin loading
In order to make your plugin loadable by HyperIM, it must export a special
function. This function's name and its prototype are defined in the SDK header.
See HIM_EXP_FUNC for details on implementing this
function.
This function, if found, will be called by HyperIM immediately after the plugin
was loaded into the process memory. HyperIM will provide as a parameter the
address of an internal HIMKERNELPROC function that
is used for further communication between the plugin and HyperIM. You should
save this value for further use. The exported function must return the address
of a HIMPLUGINDATA structure which contains some
important plugin details like its name, features, and the address of a callback
function which receives messages from HyperIM.
Working with macros
You can extend the list of HyperIM macros by registering macro sets which contain
one or more macros. After you register a macro set, you can dynamically modify
any of the macros names or values at any time, without needing to notify the
kernel. HyperIM will notify you when (and what) macros should be updated, or
you can choose to internally refresh your macros as you wish.
When the kernel parses a string to replace the macro names with their values,
it will repeat the replacing operation up to 8 times, or until there are no
more macros to replace. Before each pass you will receive a HIMP_REFRESHMACROS
message. Before sending this message, the kernel checks to see what macros are
actually used for that level, and sets a bit-mask for each macro. The plugin
can use the bit-mask to determine if that macro is needed to be used or not.
Example
Initial string: "%mPreset%".
The kernel resets all the macros bActive member to 0. Also
an initial HIMK_DETECTMACROS message is sent
to all plugins.
First pass: the kernel determines that the only used macro is %mPreset%, so
it sets its first bit from the bActive member to 1.
The HIMK_REFRESHMACROS message is sent to all plugins, with the pvData argument
1. Ideally the only macro that will refresh itself will be
%mPreset%. After that, the kernel replaces the macro with the value, let's say
we end up with
"%mState% [%mVer%]/y:m".
Second pass: the kernel sets the second bit of the three found macros bActive
member to 1. After the HIMK_REFRESHMACROS
message is sent (with the pvData argument of 2), the
macros are replaced, and the result is (note that the last macro is actually
empty, but recognized to being used)
"Playing %mSong% %mSeek% [Winamp 5.25]"
Third pass: the two found macros get their third bit of the bActive
member set to 1. After the macros are refreshed (the plugins
know this is the third pass), the string becames
"Playing myArtist - mySong [--|-------] [Winamp 5.25]"
Fourth pass: no more macros are found. String parsing ends.
Testing the plugin
All plugins are resident in the Plugins directory inside the
HyperIM installation directory. Starting with HyperIM 2.0.7 a plugin can be
automatically installed using a compressed file with the special himzp
extension. To create a himzp file you just compress the DLL
plugin file using the bzip2 compression algorithm (for example
using 7-zip archiving utility). Then rename the file so that it will
have an himzp extension, to be recognized as a compressed HyperIM plugin that
should be installed. The new filename has to have the following form (replace
with the specific plugin name and its version):
him_pluginName_1.0.0.himzp
SDK Reference
1. Function prototypes
1.1 HIM_EXP_FUNC
HIM_EXPORTED HIM_EXP_FUNC (LPHIMKERNELPROC pHimKernel) ;
This function must be defined by the plugin, or else it will not be loaded
by the kernel.
Arguments
- pHimKernel
- pointer to an internal HIMKERNELPROC function
provided by the kernel.
Return value
The function should return the address of a HIMPLUGINDATA
structure that contains essential plugin details. This structure should exist
at least until the HIMP_UNLOAD message is received by the plugin.
1.2 HIMKERNELPROC prototype
LRESULT CALLBACK HIMKERNELPROC (WORD wMsg, void * pvData)
;
A function with this prototype is provided by HyperIM to be called by the plugin.
Arguments
- wMsg
- A kernel message value.
- pvData
- This value depends on the wMsg argument.
Return value
The return value depends on what message was sent to the kernel function.
1.3 HIMPLUGINPROC prototype
LRESULT CALLBACK HIMPLUGINPROC (WORD wMsg, void * pvData)
;
A function with this protoype can be defined by the plugin to treat incoming
messages sent by HyperIM.
Arguments
- wMsg
- A plugin message value.
- pvData
- This value depends on the wMsg argument.
Return value
The return value depends on what message was received by the plugin.
2. Structures
2.1 HIMPLUGINDATA
- pName
- Pointer to the plugin's name.
- hInstance
- Contains the module instance handle. It will be filled by HyperIM after
loading the plugin.
- dwCallFlags
- Set of boolean flags which specify the plugin capabilities. Combination
of any of the plugin flags.
- pTreatMessage
- Pointer to a HIMPLUGINPROC function that will
treat incoming messages sent to the plugin.
- wPluginID
- Numerical value that uniquely identifies the plugin. Only used if the plugin
is inter-operable with other plugins and the HIMP_FLAG_HASIPCID
flag is set in the dwCallFlags member.
2.2 HIMMACRO
- pFindValue
- pointer to the macro name
- pReplaceValue
- pointer to the macro value
- bActive
- bit-mask to be used when processing HIMP_REFRESHMACROS
messages. Do not change this, will be set by the kernel.
2.3 HIMREGISTERMACROS
- pGroupName
- pointer to the macro set name
- pMacrosArray
- pointer to an array of HIMMACRO structures
- nCount
- number of items pointed by the pMacrosArray member
2.4 HIMVERINFO
- dwVersion
- plugin version. Use the HIMMAKEVERSION macro to pack the version numbers
- pAuthor
- pointer to a text with extra comments
- pURL
- pointer to the plugins URL address
3. Constants
3.1 Plugin flags
- HIMP_FLAG_ONSETSTATUS
- The plugin wants to receive the HIMP_SETSTATUS and HIMP_ENABLESTATUS messages.
- HIMP_FLAG_HASMACROS
- The plugin wants to receive the HIMP_REFRESHMACROS, HIMP_ENABLEMACROS, and
HIMP_DETECTMACROS messages.
- HIMP_FLAG_HASCONFIG
- The plugin responds to the HIMP_ONCONFIG message.
- HIMP_FLAG_HASIPCID
- The plugin has a unique ID specified in its wPluginID member.
3.2 Plugin messages
- HIMP_INIT
- sent after the plugin has been fully loaded.
pvData: not used
Return value: not used
- HIMP_UNLOAD
- sent before the plugin will be unloaded.
pvData: NULL if the unloading is because of HyperIM exiting. Otherwise it's
the HWND of the Plugins Manager window.
Return value: return 0 to allow unloading of the plugin. If the return value
is not 0, the plugin will not be fully unloaded, but will not receive any
kind of other messages anymore until it's reloaded again and it's exported
function is called again.
- HIMP_SETSTATUS
- sent when the current status has changed. Received only if the plugin has
the HIMP_FLAG_ONSETSTATUS flag set and it is currently enabled by the user.
pvData: if pvData < 0x000000FF then it is the value of a predefined status
code. Otherwise it points to the new custom status text.
- HIMP_GETVERSIONINFO
- requests additional details about the plugin.
pvData: not used
Return value: a valid pointer to a HIMVERINFO structure.
- HIMP_ONCONFIG
- sent as a signal that configuration options are requested
pvData: handle to a window to be used as the parent window of any dialogs.
- HIMP_REFRESHMACROS
- sent once or more, while a string is being parsed for macros.
pvData: if NULL, then the macro menu will popup. Otherwise it's a value between
1 and 8 that represents the current pass number over the initial string; you
can use that to test the bit-mask of bActive members of each
macro.
- HIMP_ENABLEMACROS
- enables or disables the sending of further HIMP_REFRESHMACROS and HIMP_DETECTMACROS
messages
pvData: 0 if disabling, 1 if enabling
- HIMP_DETECTMACROS
- sent before a string starts being parsed for macros, or before the macro
popup menu will be shown.
pvData: if 1, then the macro menu will appear. If 0, then a string parsing
is on the way.
- HIMP_ENABLESTATUS
- enables or disables the sending of further HIMP_SETSTATUS messages to the
plugin
pvData: 0 if disabling, 1 if enabling
- HIMP_ENABLEOTHER
- sent as a signal that the plugin is to be enabled or disabled
- pvData: 0 if disabling, 1 if enabling
- HIMP_IPC
- message value reserved for any specific plugin-to-plugin communication
pvData: plugin-specific
- HIMP_UNINSTALL
- sent before the plugin will be uninstalled. You should delete any files
and settings the plugin may have created.
pvData: handle to a parent window to be used for any dialogs.
3.3 HyperIM kernel messages
- HIMK_WRITEDBG
- Prints a string on the Debug window.
- HIMK_GETSTATUS
- Retrieves the current status.
- HIMK_GETHWND
- Retrieves main HyperIM window handle.
- HIMK_REGISTERMACROS
- Adds a new set of macros.
- HIMK_UNREGMACROS
- Removes a previously added set of macros.
- HIMK_GETFLAGS
- Retrieves the current general use flags.
- HIMK_SETFLAGS
- Sets a general use flag.
- HIMK_REMOVEFLAGS
- Removes a general use flag
- HIMK_PARSESTRING
- Parses a string for macros.
- HIMK_SETSTATUS
- Sets the current status.
- HIMK_GETAPPINFO
- Gets additional kernel information.
- HIMK_GETPROFILENAME
- Retrieves the currently used profile name.
- HIMK_CHOOSEMACRO
- Shows popup macro menu.
- HIMK_TRAYBALLOON
- Shows a tray ballon message.
- HIMK_FINDPLUGIN
- Searches for a specific plugin based on its ID.
- HIMK_SETTOOLTIP
- Sets a tooltip for a window handle.
- HIMK_REMOVETOOLTIP
- Removes a toltip
- HIMK_OPENREG
-
- HIMK_CLOSEREG
-
- HIMK_READREGVAL
-
- HIMK_SETREGVAL
-
- HIMP_SETWINHEIGHTS
-
- HIMP_SETWINWIDTHS
3.4 Kernel general use flags
- HIMK_FLAG_MPLAYER
- This flag specifies whether a media-player is running.
- HIMP_FLAG_SKINNED
- This flag specifies whether HyperIM is currently in skinned mode.
3.5 Predefined status codes
- HIMK_STATUS_INVISIBLE
- Specifies Invisible mode.
