WConsole SDK

Overview

Welcome to WConsole SDK !

WConsole is designed so, that you can extend its functions easily, by creating new modules.

This document is intended to help you understand the structure of a WConsole module and how to write them yourself. It is assumed that you have some knowledge of C, Delphi or other programming language and also have used Microsoft Visual C++, Borland C++ Builder, Borland Delphi or any other product for developing programs for Microsoft Windows.

You can visit the project's home page: http://sourceforge.net/projects/wconsole for more information.

What is a module

A WConsole module is a Windows Dynamic-Link Library (DLL) that offers some functions to the program. If you know how to write DLLs, you can skip this part and go to the section "Module Structure".

DLLs can be written in various languages: C/C++, Delphi (Object Pascal), Assembler, etc. as long as they follow some rules:

1. Every function that can be used outside the DLL, must be "exported". There is something called "DLL export table" - a special structure in the DLL that contains information about which DLL functions are exported. There are tools, like Dependency Walker (in Visual C++), that can display this information.
   
   To export a function, it must be marked in a special way in the source (there are examples below), it depends on the compiler.
   
   
2. For initialization and clean up, you can (if you need to) use the DllMain function (see here);
   
   
3. Each exported function needs a special calling convention - stdcall. This tells the compiler in what order to pass the arguments to the function (like in C, right to left on the stack), and that the called function will clean up before returning. There are several ways to declare a stdcall function, so see below for examples for different compilers.
   
   
4. You can export only functions from a DLL - not variables, classes, etc. There is no standard way to do this - every compiler has some proprietary methods to export such things but if you use them, this will make very difficult to port your DLL to another compiler.

Examples

Declaration of a exported function in Microsoft Visual C++ 5 (and later):

/* myDLL.h */

/* Define this to save some writing */
#define WCONSOLEAPI __declspec(dllexport)

EXPORT int MyFunc(int x);

/* myDLL.c */
#include "MyDLL.h"

WCONSOLEAPI int MyFunc(int x) {          
    return (x*x);
}

Declaration of a exported function in Borland Delphi 3 (and later):

{ MyDLL.pas }
library MyDLL;

function MyFunc(X : Integer) : Integer; stdcall;
begin
    Result := X*X;
end;

// Tells Delphi that we want to export this routine
exports
    MyFunc;

end.

For more information about writing DLLs, see you compiler's manual.

Module Structure

The WConsole module structure is extremely simple: each has at least two exported functions: InitModule and EnumFunctions. All other add-on functions provided by the DLL must be also exported. Follows a description of the functions (in declarations is used the WCONSOLEAPI word, as described in the previous section):

function InitModule()

This routine is called by WConsole after the module was loaded. It has one argument that is of type MODULE_INFO.

WCONSOLEAPI int InitModule(MODULE_INFO *pmi);

function InitModule(pmi : PModuleInfo) : Integer; stdcall;

You can use this function to initialize an internal (global or other) MODULE_INFO structure and to store the information contained in there for later use. MODULE_INFO has the following format:

typedef struct tagMODULE_INFO {
    DWORD cbSize;       /* Count of bytes allocated for the struct */
    UINT  nVersion;     /* WConsole current version (like 0x020B for v2.11) */ 
    HWND  hStatusWnd;   /* Window handle of the status window */
    HWND  hConsoleWnd;  /* Window handle of the console window */
    HINSTANCE hinst;    /* WConsole instance handle */
} MODULE_INFO;

type
  PModuleInfo = ^TModuleInfo;
  TModuleInfo = record
      cbSize : Integer;    { Count of bytes allocated for the struct }
      nVersion : Integer;  { WConsole current version (like $020B for v2.11) } 
      hStatusWnd : HWND;   { Window handle of the status window }
      hConsoleWnd : HWND;  { Window handle of the console window }
      hinst : Integer;     { WConsole instance handle }
  end;

Note: The format of the structure, provided above is for the current version of WConsole (0.1) but it may change in the future. Nevertheless, it will be kept backward-compatible, so the older modules will be able to run on newer version of WConsole.

function EnumFunctions()

EnumFunctions is called after InitModule by WConsole to find out what module functions are exported. Its first argument is a pointer to a callback function (of type ENUM_FUNC), provided by WConsole; the second argument is an arbitrary pointer, that is also used by WConsole (you must pass it to the callback without changes). The simplest implementation of EnumFunctions could be a mere loop over an array of FUNCTION_INFO stuctures that contain the necessary information (see below for an example). EnumFunctions must stop the enumeration either when there are no more functions to enum, or when the callback routine returns FALSE. On exit, the functions returns the number of enumerated routines (i.e. how many times was the callback invoked).

/* Declaration of the callback-type ENUM_FUNC */
typedef BOOL (*ENUM_FUNC)(FUNCTION_INFO *,LPVOID);

/* Declaration of EnumFunctions */
WCONSOLEAPI int EnumFunctions(ENUM_FUNC pEnumFunc, LPVOID lpParameter);

{ Declaration of the callback-type TEnumFunc }
type
  TEnumFunc = function(pInfo : PFunctionInfo; lpParameter : Pointer) : Boolean;

{ Declaration of EnumFunctions }
function EnumFunctions(pEnumFunc : TEnumFunc; lpParameter : Pointer) : Integer; stdcall;

The declaration of FUNCTION_INFO is as follows:

/* Pointer-type to an exported function */
typedef int (*CONSOLE_FUNC)(int,char**); 

typedef struct tagFUNCTION_INFO {
    char *sName;          /* Function name */
    char *sDesc;          /* Description, help string */
    CONSOLE_FUNC pFunc;   /* Pointer to the function */
} FUNCTION_INFO;

type
  { Pointer-type to an exported function }
  TConsoleFunc = function(nArgc : Integer; sArgs : array of PChar) : Integer; stdcall;

  PFunctionInfo = ^TFunctionInfo;
  TFunctionInfo = record
	  sName : PChar;        { Function name }
	  sDesc : PChar;        { Description, help string }
	  pFunc : TConsoleFunc; { Pointer to the function }
  end;

Your functions

The last part of a module is, of course, the functions you have written. They must follow the format of CONSOLE_FUNC pointer type, i.e. two arguments - first of type integer (contains the number of arguments passed to function) and the second of type "array of strings" (where the actual parameters are passed), and it must return an integer value. The declaration is as follows:

WCONSOLEAPI int MyFunc(int argc, char *argv[]);

function MyFunc(nArgc : Integer; sArgs : array of PChar) : Integer; stdcall;

That declaration is very similar to the standard C function main(), so you can easily adopt existing console programs as plug-ins to the WConsole.

An Example DLL

In this section are provided links to the projects's home page, where you can find an example module for the WConsole. It is called TemplateDLL and you can use it as a base for writting your own modules. The source code is pretty well documented, but if you need more information ore help, please visit: http://sourceforge.net/projects/wconsole, or write us at: wconsole-devel@lists.sourceforge.net.

The source is available as a Microsoft Visual C++ project and as a Borland Delphi project.

Have fun ! :)
WConsole Development Team

About

This is version 0.2 of WConsole SDK. Latest version can be found at the web site.

Written by: Dimiter Naydenov

Microsoft®, Windows™, Visual C++™, are either registered trademarks or trademarks of Microsoft Corporation. Borland®, Delphi™, Borland C++™, Borland C++ Builder™ are either registered trademarks or trademarks of Inprise Corporation. Other trademarks are property of their respective owners.