LiteStep SDK Documentation

Welcome to the LiteStep SDK

The LiteStep SDK Documentation Project is an attempt to provide a reference guide for LiteStep module coders. If this is your first time using this document, please read the disclaimer. The What's New section provides an overview of the changes made to this document.


What's New

Everything! Booyah!


Disclaimer

This document is an unofficial guide to the LiteStep API. It should be used in conjunction with newer LS builds (2001-11-13 or newer). It is also rather incomplete, as I am not a LS developer (that is, I've never coded the LiteStep core itself). I have only covered what I know and understand 100% (okay, maybe 70 to 90%). This was written more to help myself than anyone else, so that I could learn more about the LSAPI and not have to bug anyone for help. Having said that, I hope you find this document useful.


Bang commands

LSAPI: Bang commands

A LiteStep module can use the following functions to handle bang commands.

Summary

Function | Description
AddBangCommand | Registers a bang command.
AddBangCommandEx | Registers a bang command.
ParseBangCommand | Executes a bang command.
RemoveBangCommand | Removes a bang command.


LSAPI :: Bang commands :: AddBangCommand

LSAPI: Bang commands
AddBangCommand
The AddBangCommand function registers a bang command.

BOOL AddBangCommand(
   LPCSTR command,     // Name of the bang command.
   BangCommand f       // Address of bang handler.
);

Parameters
command
Name of the bang command you want to register.
f
Pointer to the application-defined function that will handle the bang command. For more information on the bang function, see BangProc.
Return Values
This function returns TRUE if the bang was successfully registered, FALSE if it failed.

Remarks
When the module unloads it should remove the bang commands registered using RemoveBangCommand.

See Also
AddBangCommandEx, RemoveBangCommand, BangProc


LSAPI :: Bang commands :: AddBangCommandEx

LSAPI: Bang commands
AddBangCommandEx
The AddBangCommandEx function registers a bang command.

BOOL AddBangCommandEx(
   LPCSTR command,     // Name of the bang command.
   BangCommandEx f     // Address of bang handler.
);

Parameters
command
Name of the bang command you want to register.
f
Pointer to the application-defined function that will handle the bang command. For more information on the bang function, see BangProcEx.
Return Values
This function returns TRUE if the bang was successfully registered, FALSE if it failed.

Remarks
When the module unloads it should remove the bang commands registered using RemoveBangCommand.

See Also
AddBangCommand, RemoveBangCommand, BangProcEx


LSAPI :: Bang commands :: ParseBangCommand

LSAPI: Bang commands
ParseBangCommand
The ParseBangCommand function executes a bang command.

BOOL ParseBangCommand(
  HWND hwndCaller,           // Handle of a window
  LPCSTR pszBangCommandName, // Name of the bang command to execute
  LPCSTR pszArguments        // Arguments to be passed to the bang command
);

Parameters
hwndCaller
Handle of a window that will act as owner for any dialogs or message boxes. This parameter can be NULL.
pszBangCommandName
Name of the bang command to execute. The first character must be an exclamation point (!).
pszArguments
Arguments to be passed to the bang command. This parameter can be NULL.
Return Values
The return value is nonzero if it succeeds and zero if it fails.

Remarks
The preferred way to execute bang commands is to call LSExecute or LSExecuteEx as these functions can execute both bang commands and applications.

See Also
AddBangCommand, AddBangCommandEx, LSExecute, LSExecuteEx, RemoveBangCommand


LSAPI :: Bang commands :: RemoveBangCommand

LSAPI: Bang commands
RemoveBangCommand
The RemoveBangCommand function removes a previously registerd bang command.

BOOL RemoveBangCommand(
   LPCSTR command,     // Name of the bang command.
);

Parameters
command
Name of the bang command you want to remove.
Return Values
This function returns TRUE if the bang was successfully removed, FALSE if it failed.

See Also
AddBangCommand, AddBangCommandEx


Configuration

LSAPI: Configuration

A LiteStep module can use the following functions to read its configuration from the step.rc file.

Summary

Function | Description
GetRCBool | Gets a boolean value.
GetRCBoolDef | Gets a boolean value.
GetRCColor | Gets a color value.
GetRCCoordinate | Gets a coordiante value.
GetRCInt | Gets an integer.
GetRCLine | Gets a line.
GetRCString | Gets a string.
LCClose | Closes a text file.
LCOpen | Opens a text file.
LCReadNextCommand | Reads a line from a file.
LCReadNextLine | Reads a line from a text file.
LCReadNextConfig | Searches for and reads a line from a text file.


LSAPI :: Configuration :: GetRCBool

LSAPI: Configuration
GetRCBool
The GetRCBool function reads a boolean value from the step.rc file.

BOOL GetRCBool(
   LPCTSTR lpKeyName,  // key name
   BOOL ifFound,       // value returned if found
);

Parameters
lpKeyName
The key to read.
ifFound
Value to return if the key is found..
Return Values
Returns a BOOL value based on whether or not lpKeyName was found.

Remarks
GetRCBool works a little differently than the other GetRCxxxx functions. If GetRCBool finds lpKeyName, it returns the value of ifFound. If lpKeyName is not found then the opposite value is returned (!ifFound). This can make it a little easier to bridge the gap between programmer logic and end-user logic.

See Also
GetRCBoolDef


LSAPI :: Configuration :: GetRCBoolDef

LSAPI: Configuration
GetRCBoolDef
The GetRCBoolDef function reads a boolean value from the step.rc.

BOOL GetRCBoolDef(
   LPCTSTR lpKeyName,  // key name
   BOOL bDefault,      // default value
);

Parameters
lpKeyName
The key to read.
bDefault
Value to return if the key is not found.
Return Values
Returns a BOOL value.

See Also
GetRCBool


LSAPI :: Configuration :: GetRCColor

LSAPI: Configuration
GetRCColor
The GetRCColor reads a color value in either hexadecimal or R G B notation.

COLORREF GetRCColor(
   LPCTSTR lpKeyName,  // key to read
   COLORREF colDef,    // default value
);

Parameters
lpKeyName
The key to read.
colDef
Value to return if lpKeyName is not found.
Return Values
Returns a COLORREF.


LSAPI :: Configuration :: GetRCCoordinate

LSAPI: Configuration
GetRCCoordinate
The GetRCCoordinate reads a coordinate value in either and parses it into a integer.

COLORREF GetRCCoordinate(
   LPCTSTR lpKeyName,  // key to read
   int nDef,    // default value
   int nMax     // maximum value
);

Parameters
lpKeyName
The key to read.
nDef
Value to return if lpKeyName is not found.
nMax
Maximum return value.
Return Values
Returns a int.

Remarks
This function was added in the 2002-04-15 build.


LSAPI :: Configuration :: GetRCInt

LSAPI: Configuration
GetRCInt
The GetRCInt function reads an integer value from the step.rc file.

int GetRCInt(
   LPCTSTR lpKeyName,  // key name
   int nDefault        // default value
);

Parameters
lpKeyName
The key to read.
pParam
Value to return if the key is not found..
Return Values
Returns the value of lpKeyName if found, otherwise it returns nDefault.


LSAPI :: Configuration :: GetRCLine

LSAPI: Configuration
GetRCLine
The GetRCLine reads a line from the step.rc.

BOOL GetRCLine(
   LPCTSTR szKeyName,  // key name
   LPTSTR szBuffer,    // buffer that recieves the line
   UINT nBufLen,       // maximum length of line
   LPCTSTR szDefault,  // default value
);

Parameters
szKeyName
The key to read.
szBuffer
Pointer to the buffer that will recieve the line.
nBufLen
Maximum length of szBuffer.
szDefault
Default value used if szBuffer is not found.
Return Values
Returns TRUE if the function succeeds. If an error occurs FALSE is returned.

Remarks
This function reads a string from the step.rc even if the string has spaces in it. If the step.rc looks like this:
ModuleParamString This is my string
and your code looks like this:
TCHAR sBuffer[100];
GetRCLine("ModuleParamString", sBuffer, 100, ".none");
Then sBuffer will be "This is my string".

Comments are never read as part of the line.

See Also
GetRCString


LSAPI :: Configuration :: GetRCString

LSAPI: Configuration
GetRCString
The GetRCString reads a string value from the step.rc.

BOOL GetRCString(
   LPCTSTR lpKeyName,  // key name
   LPTSTR value,       // buffer that recieves string
   LPCTSTR defStr,     // default string
   int maxLen,         // maximum length of string
);

Parameters
lpKeyName
The key to read.
value
Pointer to the buffer that will recieve the string.
defStr
Default value if lpKeyName is not found.
maxLen
Maximum length of the string.
Return Values
Returns TRUE if the function succeeds. If an error occurs FALSE is returned.

Remarks
GetRCString reads a string until a new line or space is encountered. In order for a string with spaces to be completely read it must be enclosed in double quotes. If the step.rc looks like this:
ModuleParamString This is my string
and your code looks like this:
TCHAR sBuffer[100];
GetRCString("ModuleParamString", sBuffer, ".none", 100);
then sBuffer will be "This", not "This is my string". In order to read a line with spaces without requiring double-quotes use the GetRCLine function.

Comments are never read as part of a string.

See Also
GetRCLine


LSAPI :: Configuration :: LCClose

LSAPI: Configuration
LCClose
The LCClose function closes a file.

BOOL LCClose(
   FILE* f,     // Handle to the file.
);

Parameters
f
File handle you want to close.
Return Values
This function returns TRUE.

See Also
LCOpen, LCReadNextConfig, LCReadNextLine


LSAPI :: Configuration :: LCOpen

LSAPI: Configuration
LCOpen
The LCOpen function opens a file for reading.

FILE* LCOpen(
   LPCTSTR szPath,     // path of file
);

Parameters
szPath
Path to the file. Set this parameter to NULL to open step.rc.
Return Values
If the function succeeds it returns a handle to the file.

If the function fails it returns a handle to the file. However, subsequent calls to LCReadNextLine, LCReadNextCommand, and LCReadNextConfig will fail.

Remarks
Every call to LCOpen should have a corresponding call to LCClose.

See Also
LCClose, LCReadNextConfig, LCReadNextLine


LSAPI :: Configuration :: LCReadNextCommand

LSAPI: Configuration
LCReadNextCommand
The LCReadNextCommand is functionally the same as LCReadNextLine.


LSAPI :: Configuration :: LCReadNextConfig

LSAPI: Configuration
LCReadNextConfig
The LCReadNextConfig function searches for and reads a line from the step.rc

BOOL LCReadNextConfig(
   FILE* f,           // file to search
   LPCTSTR szPrefix,  // prefix to search for
   LPTSTR szBuffer,   // buffer to recieve the line
   DWORD dwLength,    // maximum length of the buffer
);

Parameters
f
File to search. The file must be opened with LCOpen.
szPrefix
The prefix to search for. Usually a line like
*YourConfig parameter1 parameter2
(a la popup.dll).
szBuffer
The buffer recieving the line (if found).
dwLength
The buffer's maximum length.
Return Values
Returns TRUE if szPrefix was found.

Returns FALSE if szPrefix was not found.

Remarks
This is an example of how to use the LCReadNextConfig function.
FILE * fStep = LCOpen(NULL);
char buffer[1024];

while ( LCReadNextConfig( fStep, "*MyConfig", buffer, sizeof(buffer) ) )
{
   MessageBox( 0, buffer, "Found line!", MB_OK );
}

LCClose(fStep);

See Also
LCOpen, LCClose, LCReadNextLine


LSAPI :: Configuration :: LCReadNextLine

LSAPI: Configuration
LCReadNextLine
The LCReadNextLine functions reads a line from a file opened with LCOpen.

BOOL LCReadNextLine(
   FILE* f,          // file to read
   LPTSTR szBuffer,  // buffer that will contain the line
   DWORD dwLength,   // buffer's maximum length
);

Parameters
f
File to read.
pParam
Buffer that will contain the line.
pParam
The buffer's maximum length.
Return Values
Returns TRUE if a line has been read.

Returns FALSE when the end of the file is reached.

See Also
LCOpen, LCClose, LCReadNextConfig


Debugging

LSAPI: Debugging

A debugger is used for most debugging (go figure, eh?) but the following functions can also help catch errors that arise.

Summary

Function | Description
LSLog | Logs a string.
LSLogPrintf | printf() style logging.


LSAPI :: Debugging :: LSLog

LSAPI: Debugging
LSLog
The LSLog function writes a string to the log.

BOOL LSLog(
   int nLevel,        // logging level (urgency)
   LPCSTR pszModule,  // module name
   LPCSTR pszFormat   // message to log
);

Parameters
nLevel
The logging level (urgency) of the message. Can be one of the following:

Level | Urgency | LSLogLevel
LOG_ERROR | Critical error. | 1+
LOG_WARNING | Non-critical error or warning. | 2+
LOG_NOTICE | General notices. | 3+
LOG_DEBUG | Debug message. | 4

pszModule
Name of module. This will be added to the log file before the actual message
pszFormat
The format of the message. Refer to the printf(..) function for more information.
Return Values
If the function succeeds LSLogPrintf returns TRUE.

If the function fails LSLogPrintf returns FALSE.

Remarks
LSLog will fail if the user has not specified a log file or has set LSLogLevel lower than nLevel

See Also
LSLogPrintf


LSAPI :: Debugging :: LSLogPrintf

LSAPI: Debugging
LSLogPrintf
The LSLogPrintf function writes user-formatted string to the log.

BOOL LSLogPrintf(
   int nLevel,        // logging level (urgency)
   LPCSTR pszModule,  // module name
   LPCSTR pszFormat   // message to log
   [,argument]...     // optional arguments
);

Parameters
nLevel
The logging level (urgency) of the message. See the documentation for LSLog for a list of log levels.

pszModule
Name of module. This will be added to the log file before the actual message
pszFormat
The format of the message. Refer to the printf(..) function for more information.
argument
Optional arguments needed by the pszFormat parameter. Refer to the printf(..) function for more information.
Return Values
If the function succeeds LSLogPrintf returns TRUE.

If the function fails LSLogPrintf returns FALSE.

Remarks
LSLogPrintf will fail if the user has not specified a log file or has set LSLogLevel lower than nLevel.

See Also
LSLog


Graphics

LSAPI: Graphics

LiteStep provides several functions that make working with graphics a little easier.

Summary

Function | Description
BitmapFromIcon | Converts an HICON to an HBITMAP.
BitmapToRegion | Converts an HBITMAP to an HRGN.
GetLSBitmapSize | Gets the width and height of an HBITMAP
LoadLSIcon | Loads an icon.
LoadLSImage | Loads an image file.
TransparentBltLS | Merges two device contexts with transparency.


LSAPI :: Graphics :: BitmapFromIcon

LSAPI: Graphics
BitmapFromIcon
The BitmapFromIcon function converts an icon into a bitmap. The transparent areas of the icon become magic pink in the bitmap.

HBITMAP BitmapFromIcon(
   HICON hIcon,  // handle to icon
);

Parameters
hIcon
The icon to convert.
Return Values
If the function succeeds the return value is the handle to the new bitmap. You will have to delete this bitmap after you are done using it.

If the function fails it returns NULL.


LSAPI :: Graphics :: BitmapToRegion

LSAPI: Graphics
BitmapToRegion
The BitmapToRegion function creates a window region using the supplied bitmap.

HRGN BitmapToRegion(
   HBITMAP hBmp,          // bitmap to use
   COLORREF clrTransp     // transparent color
   COLORREF clrTolerance  // tolerance for transparent color
   int xoffset            // horizontal offset of bitmap
   int yoffset            // vertical offset of bitmap
);

Parameters
hBmp
Handle to the bitmap that will be used to create the region.
clrTransp
Color that will become transparent. Usually magic pink.
clrTolerance
Amount of variance allowed for the transparent color.
xoffset
Starting horizontal (x) offset of the bitmap.
yoffset
Starting vertical (y) offset of the btimap.
Return Values
Returns a handle to the new region.

Remarks
If you use the handle in a subsequent call to SetWindowRgn(...) the system takes control of the handle, so you should not make any further calls with this handle.


LSAPI :: Graphics :: GetLSBitmapSize

LSAPI: Graphics
GetLSBitmapSize
The GetLSBitmapSize function gets the height and width of an HBITMAP.

void GetLSBitmapSize(
   HBITMAP hBitmap,  // handle to the bitmap
   LPINT x,          // recieves width
   LPINT y,          // recieves height
);

Parameters
hBitmap
Handle to the bitmap you want to find the size of.
x
Pointer to an int that will recieve the width.
y
Pointer to an int that will recieve the height.
Return Values
This function is void and so does not return anything. However, if the function fails the x and y parameters will be zero.


LSAPI :: Graphics :: LoadLSIcon

LSAPI: Graphics
LoadLSIcon
The LoadLSIcon function loads an icon from an icon file.

HICON LoadLSIcon(
   LPCTSTR szIconPath,  // icon to load
   LPCTSTR szFile,      // unused, should be NULL.
);

Parameters
szIconPath
Path to the icon.
Return Values
If the function succeeds it returns a handle to the new icon. The icon should be deleted when you are done using it.

If the function fails it returns NULL.

Remarks
LoadLSIcon supports the following syntax for the szIconPath parameter:
  • iconfile.ico
    Path to an icon file.
  • c:\windows\explorer,1
    Extracts an icon from a library (.ICL, .DLL) or a progam (.EXE)


LSAPI :: Graphics :: LoadLSImage

LSAPI: Graphics
LoadLSImage
The LoadLSImage function loads an image from a file. It currently supports
  • Windows Bitmaps (BMP).
  • Portable Network Graphics (PNG).
  • Windows Icon files (ICO).

HBITMAP LoadLSImage(
   LPCTSTR szFile,  // image to load
   LPCTSTR szImage  // unused, should be NULL
);

Parameters
szFile
The image to load.
szImage
This parameter is unused and should be NULL.
Return Values
If the function succeeds the return value is the handle to the new bitmap. You will need to delete this bitmap when you are done with it.

If an error occurrs or if szFile is ".none" it returns NULL.

Remarks
Currently LoadLSImage supports the following syntax for the szFile parameter:
  • image.bmp
    Uses the LSImageFolder as the path to the image.
  • C:\image.bmp
    Full path to image.
  • image1.bmp|image2.bmp
    Merges two or more images. The first image will be on the top, the last image on the bottom. Use the pipe character in between each file you want to merge.
  • .extract=C:\Windows\explorer.exe,1
    Loads an icon from a library (.ICL, .DLL) or program (.EXE).


LSAPI :: Graphics ::TransparentBltLS

LSAPI: Graphics
TransparentBltLS
The TransparentBltLS function overlays a source device context onto a destination device context, making all pixels of a certain color in the source device context transparent.

void TransparentBltLS(
   HDC dc,                     // destination DC
   int nXDest,                 // x-coord of destination's upper-left corner
   int nYDest,                 // y-coord of destination's upper-left corner
   int nWidth,                 // width of destination rectangle
   int nHeight,                // height of destination rectangle
   HDC tempDC,                 // source DC
   int nXSrc,                  // x-coord of source's upper-left corner
   int nYSrc,                  // y-coord of source's upper-left corner
   COLORREF colorTransparent,  // transparent color
);

Parameters
dc
Handle to the destination (background) device context.
nXDest
X coordinate of the destination's upper-left corner.
nYDest
Y coordinate of the destination's upper-left corner..
nWidth
Width of the destination device context.
nHeight
Height of the destination device context.
tempDC
Handle to the source (foreground) device context.
nXSrc
X coordinate of the destination's upper-left corner.
nYSrc
X coordinate of the destination's upper-left corner.
colorTransparent
The color that will be transparent (i.e. any pixel this color will not be painted onto the destination device context).
Return Values
None.

Remarks
This function is a replacement for the Win32 GDI function TransparentBlt. Microsoft's TransparentBlt caused memory leaks on Windows 95/98, so you should use this if you want your module to run smoothly on Windows 95/98.

See Also
Microsoft Knowledge Base article "HOWTO: Drawing Transparent Bitmaps (Q79212)"


Helpers

LSAPI: Helpers

This category contains various functions that doesn't fit into any other category.

Summary

Function | Description
GetLitestepWnd | Returns a handle to the main Litestep window.
LCTokenize | Breaks up a string into tokens.
LSExecute | Executes a bang command or application.
LSExecuteEx | Executes a bang command or application.
LSGetImagePath | Retrieves the path to the image directory.
LSGetLitestepPath | Retrieves the path to the Litestep directory.
VarExpansion | Replaces $vars$ with their values.


LSAPI :: Helpers :: GetLitestepWnd

LSAPI: Helpers
GetLitestepWnd
GetLitestepWnd returns a handle to the main Litestep window.

void GetLitestepWnd(VOID);

Parameters
This function has no parameters.

Return Values
This function returns a handle to the main Litestep window.


LSAPI :: Helpers :: LCTokenize

LSAPI: Helpers
LCTokenize
LCTokenize breaks up a string into tokens.

int LCTokenize(
   LPCSTR szString,         // String to tokenize
   LPSTR *ppszTokenBuffers, // Array of addresses of buffers to receive the tokens
   DWORD nBuffers,          // Number of buffers in the ppszTokenBuffers array
   LPSTR pszExtra           // String that will receive any remaining characters
);

Parameters
szString
This is the input string that will be tokenized.
ppszTokenBuffers
This is an array of string-pointers. The strings in the array will receive the tokens.
nBuffers
Number of buffers in the ppszTokenBuffers array.
pszExtra
This string will receive the remainder of the input string after the first nBuffer tokens are removed.

Return Values
LCTokenize returns the number of tokens actually scanned.


LSAPI :: Helpers :: LSExecute

LSAPI: Helpers
LSExecute
LSExecute executes a bang command or application.

HINSTANCE LSExecute(
   HWND hwndCaller,       // Handle to calling window
   LPCSTR pszCommandLine, // Command to execute
   int nShowCmd           // Specifies how an application will be displayed
);

Parameters
hwndCaller
Handle of a window that will act as owner for any dialogs or message boxes. This parameter can be NULL.
pszCommandLine
Command line to execute. This consists of the name of a bang command or the path to an application followed by any arguments.
nShowCmd
Flag that specifies how an application will be displayed. This can be any of the SW_* constants used with the ShowWindow function. If executing a bang command this parameter is ignored.

Return Values
The return value of this function is not well defined and should not be relied upon.

See Also
LSExecuteEx, ParseBangCommand


LSAPI :: Helpers :: LSExecuteEx

LSAPI: Helpers
LSExecuteEx
LSExecuteEx executes a bang command or application.

HINSTANCE LSExecuteEx(
   HWND hwndCaller,     // Handle to calling window
   LPCSTR pszOperation, // Operation to perform
   LPCSTR pszCommand,   // Command to execute
   LPCSTR pszArguments, // Arguments to pass to the bang command or application
   LPCSTR pszDirectory, // Path to the default directory
   int nShowCmd         // Specifies how an application will be displayed
);

Parameters
hwndCaller
Handle of a window that will act as owner for any dialogs or message boxes. This parameter can be NULL.
pszOperation
Operation to perform. If executing an application this parameter is passed on to ShellExecuteEx, otherwise it is ignored. This parameter can be NULL.
pszCommand
Command to execute. This can be the name of a bang command or the path to an application.
pszArguments
Arguments to pass to the bang command or application. This parameter can be NULL.
pszDirectory
Path to the default directory. This parameter can be NULL and is ignored if executing a bang command.
nShowCmd
Flag that specifies how an application will be displayed. This can be any of the SW_* constants used with the ShowWindow function. If executing a bang command this parameter is ignored.

Return Values
The return value of this function is not well defined and should not be relied upon.

See Also
LSExecute, ParseBangCommand


LSAPI :: Helpers :: LSGetImagePath

LSAPI: Helpers
LSGetImagePath
The LSGetImagePath function gives you the path to the image directory.

BOOL LSGetImagePath(
    LPSTR pszBuffer,   // Buffer to receive the path
    UINT nSize         // Size of the buffer
);

Parameters
pszBuffer
Pointer to a buffer that receives the path.
nSize
Size of the buffer pointed to by pszBuffer.

Return Values
The return value is nonzero if it succeeds and zero if it fails.

Remarks
The image directory is set in the step.rc by the "LSImageFolder" key and is the default location for images. LoadLSImage and LoadLSIcon search for files in this directory.

See Also
LoadLSIcon, LoadLSImage, LSGetLitestepPath, VarExpansion


LSAPI :: Helpers :: LSGetLitestepPath

LSAPI: Helpers
LSGetLitestepPath
LSGetLitestepPath retrieves the path to the Litestep directory.

BOOL LSGetLitestepPath(
    LPSTR pszBuffer,   // Buffer to receive the path
    UINT nSize         // Size of the buffer
);

Parameters
pszBuffer
Pointer to a buffer that receives the path.
nSize
Size of the buffer pointed to by pszBuffer.

Return Values
The return value is nonzero if it succeeds and zero if it fails.

Remarks
The Litestep directory is where the main Litestep executable (LITESTEP.EXE) resides. The predefined variable "LitestepDir" also contains the path to this directory.

See Also
LSGetImagePath, VarExpansion


LSAPI :: Helpers :: VarExpansion

LSAPI: Helpers
VarExpansion
VarExpansion replaces $vars$ in a string with their values.

void VarExpansion(
   LPSTR szBuffer,     // Output string
   LPCSTR szValue      // Input string
);

Parameters
szBuffer
String that will be filled with the expanded equivalence of the input.
szValue
String containing the $variables$

Return Values
No return value.


Messages

LSAPI: Messages

The following window messages can be used by a LiteStep module.

Summary

Message | Description
LM_GETREVID | Description
LM_RECYCLE | Description
LM_REFRESH | Description
LM_REGISTERMESSAGE | Description
LM_UNREGISTERMESSAGE | Description


LSAPI :: Messages :: LM_GETREVID

LSAPI: Messages
LM_GETREVID
LM_GETREVID is sent by Litestep when it populates the "Revision IDs" part of the about box and the module returns the string that will be displayed. To receive this message the module must register for it by sending a LM_REGISTERMESSAGE to Litestep.

LRESULT CALLBACK WindowProc(
   HWND hwnd,          // Handle to module window.
   UINT uMsg,          // LM_GETREVID
   WPARAM wParam,      // Value determining what string to return.
   LPARAM lParam       // Pointer to string.
);

Parameters
wParam
If wParam is set to 0, the revision ID should be returned. If set to 1 the full RCS ID should be returned (never used, can be ignored).
lParam
Pointer to a string to be filled with the return value.
Return Values
The modules should return the length of the returned string.

Remarks
This in an example of how the code can look:
LPSTR szBuffer = (LPSTR)lParam;
switch(wParam)
{
    case 0:
        strcpy(szBuffer, "mymodule 1.0 (Me)");
        break;
    default:
        strcpy(szBuffer, "");
}
return strlen(szBuffer);

See Also
LM_REGISTERMESSAGE, LM_UNREGISTERMESSAGE


LSAPI :: Messages :: LM_RECYCLE

LSAPI: Messages
LM_RECYCLE
When Litestep receives a LM_RECYCLE messages it recycles.

LRESULT CALLBACK WindowProc(
   HWND hwnd,          // Handle to module window.
   UINT uMsg,          // LM_RECYCLE
   WPARAM wParam,      // Determines the action taken.
   LPARAM lParam       // Not used.
);

Parameters
wParam
A numeric value determining what action to be taken.
0 - Recycle Litestep
1 - Logoff Windows
2 - Quit Litestep
Other values will shut down your computer.
lParam
Not used.
Return Values
No return value.


LSAPI :: Messages :: LM_REIGSTERMESSAGE

LSAPI: Messages
LM_REGISTERMESSAGE
To receive any of the LiteStep specific window messages the module must register for them. This is done by sending a LM_REGISTERMESSAGE to LiteStep (see GetLitestepWnd).

LRESULT CALLBACK WindowProc(
   HWND hwnd,          // Handle to LiteStep window.
   UINT uMsg,          // LM_REGISTERMESSAGE
   WPARAM wParam,      // Handle to recipient/module window.
   LPARAM lParam       // Array of messages to register.
);

Parameters
wParam
Handle to the window that will receive the registered messages.
lParam
A zero-terminated array of integers filled with the messages to register for.
Return Values
No return value.

Remarks
When the module is unloaded, it must unregister the messages it has registered for by sending the same array of messages with the LM_UNREGISTERMESSAGE message to LiteStep.

See Also
LM_UNREGISTERMESSAGE, GetLitestepWnd


LSAPI :: Messages :: LM_UNREIGSTERMESSAGE

LSAPI: Messages
LM_UNREGISTERMESSAGE
When the module unloads, any messages registered with LM_REGISTERMESSAGE should be unregisterd again. This is done by sending a LM_UNREGISTERMESSAGE to LiteStep (see GetLitestepWnd).

LRESULT CALLBACK WindowProc(
   HWND hwnd,          // Handle to LiteStep window.
   UINT uMsg,          // LM_UNREGISTERMESSAGE
   WPARAM wParam,      // Handle to recipient/module window.
   LPARAM lParam       // Array of messages to unregister.
);

Parameters
wParam
Handle to the window that has been receiving the registered messages.
lParam
A zero-terminated array of integers filled with the messages to unregister.
Return Values
No return value.

Remarks
To unregister the messages they must first be registered using LM_REIGSTERMESSAGE.

See Also
LM_REGISTERMESSAGE, GetLitestepWnd


LSAPI :: Bang commands :: BangProc

LSAPI: Bang commands
BangProc
The BangProc function is an application-defined function that handles a bang command. Specify this address when calling the AddBangCommand function. BangProc is a placeholder for the application-defined function name.

void BangProc(
   HWND sender         // Handle of the window calling the bang command.
   LPCSTR args         // Arguments/parameters to the bang command.
);

Parameters
sender
Window handle of the window calling the bang command.
args
Arguments/parameters supplied to the bang command.
Return Values
No return value.

See Also
AddBangCommand, RemoveBangCommand


LSAPI :: Bang commands :: BangProcEx

LSAPI: Bang commands
BangProcEx
The BangProcEx function is an application-defined function that handles a bang command. Specify this address when calling the AddBangCommandEx function. BangProcEx is a placeholder for the application-defined function name. The BangProcEx function can, in contrast to BangProc, handle an infinite number of bang commands.

void BangProcEx(
   HWND hSender         // Handle of the window calling the bang command.
   LPCSTR szCommand      // Name of the bang command.
   LPCSTR szArgs         // Arguments/parameters to the bang command.
);

Parameters
hSender
Window handle of the window calling the bang command.
szCommand
Name of the bang command called.
szArgs
Arguments/parameters supplied to the bang command.
Return Values
No return value.

See Also
AddBangCommandEx, RemoveBangCommand