[NSIS-devel] Plugin API transparently compatible with both ANSI & Unicode installers

[Wizou <sou...@wi...>]

#ifndef ___NSIS_PLUGIN__H___
#define ___NSIS_PLUGIN__H___

#ifdef __cplusplus
extern "C" {
#endif

#include "api.h"
#include "nsis_tchar.h"
#pragma comment(lib, "pluginapi.lib")

#ifdef _countof
#define COUNTOF _countof
#else
#define COUNTOF(a) (sizeof(a)/sizeof(a[0]))
#endif

#ifndef NSISCALL
#  define NSISCALL __stdcall
#endif

typedef struct _stack_t stack_t;
extern unsigned int g_stringsize; // length of strings used in the current NSIS installer (in ANSI or Unicode characters)

enum
{
	INST_0,         // $0
	INST_1,         // $1
	INST_2,         // $2
	INST_3,         // $3
	INST_4,         // $4
	INST_5,         // $5
	INST_6,         // $6
	INST_7,         // $7
	INST_8,         // $8
	INST_9,         // $9
	INST_R0,        // $R0
	INST_R1,        // $R1
	INST_R2,        // $R2
	INST_R3,        // $R3
	INST_R4,        // $R4
	INST_R5,        // $R5
	INST_R6,        // $R6
	INST_R7,        // $R7
	INST_R8,        // $R8
	INST_R9,        // $R9
	INST_CMDLINE,   // $CMDLINE
	INST_INSTDIR,   // $INSTDIR
	INST_OUTDIR,    // $OUTDIR
	INST_EXEDIR,    // $EXEDIR
	INST_LANG,      // $LANGUAGE
	__INST_LAST
};


// The following macro or function must be called at the beginning of every NSIS entrypoint provided by your plugin!
#define EXDLL_INIT()  ExDLL_Init(hwndParent, string_size, stacktop, (char*)variables)
void NSISCALL ExDLL_Init(HWND hwndParent, unsigned int string_size, stack_t **stacktop, char *variables); // pass the arguments from your entrypoint


/*
TCHAR is a generic type defined as 'wchar_t' or 'char' depending if you are compiling with UNICODE defined or not.
For portability, use TCHAR as your character type. You can then choose the type of compilation that suits you best or provide both variant of your plugin.
Ex: if you want your plugin to work under Windows 9x, you might want to compile as ANSI because Unicode API won't be available on the target computer.
On the contrary, if you need to support Unicode for multi-language compatibility, you might want to compile your plugin as UNICODE.

In any case, if you use this plugin API, both variants of your plugin will be compatible with both the ANSI *and* Unicode version of NSIS.
This plugin API will do the work of converting ANSI/Unicode strings as required, as well as truncation if the length of strings differ (ending \0 included)

===== NSIS GENERIC API =====

popstring(str) : pop a string off NSIS stack. str must be defined as: TCHAR str[maxlen]
popstringn(str,maxlen) : same, but str can be a pointer to a buffer of maxlen TCHARs
	return 0 on success, 1 on empty stack.

pushstring(str) : push a string onto NSIS stack.

peekstring(stkpos,str) : copy a string from NSIS stack. str must be defined as: TCHAR str[maxlen]
peekstringn(stkpos,str,maxlen) : same, but str can be a pointer to a buffer of maxlen TCHARs
	stkpos is the position of the string to copy from the stack (0 for stack top)
	return 0 on success, 1 if stack does not contain enough entries

getuservariable(varnum,str) : retrieve the value of a standard NSIS variable. str must be defined as: TCHAR str[maxlen]
getuservariablen(varnum,str,maxlen) : same, but str can be a pointer to a buffer of maxlen TCHARs
	use the INST_* enum to choose which variable

setuservariable(varnum,str) : change the value of a standard NSIS variable
	use the INST_* enum to choose which variable

myatoi(str) : convert a string to a signed integer (supports "-" and "0x" prefixes)
myatou(str) : convert a string to an unsigned integer (supports only decimal digits)
myatoi_or(str) : same as myatoi, but you can 'OR' several binary values using the '|' character (ex: "1|4|8" returns 13)
*/

int  NSISCALL popint();           // pop an integer off NSIS stack
int  NSISCALL popint_or();        // pop an integer with support for or'ing (ex: "1|4|8")
void NSISCALL pushint(int value); // push an integer onto NSIS stack

//==========================


// generic redirection based on your ANSI/UNICODE compilation variant
#ifdef _UNICODE
#define popstring(str)              PopStringW(str,COUNTOF(str))
#define popstringn                  PopStringW
#define pushstring                  PushStringW
#define peekstring(stkpos,str)      PeekStringW(str,COUNTOF(str))
#define peekstringn                 PeekStringW
#define getuservariable(varnum,str) GetUserVariableW(varnum,str,COUNTOF(str))
#define getuservariablen            GetUserVariableW
#define setuservariable             SetUserVariableW
#define myatoi                      myatoiW
#define myatou                      myatouW
#define myatoi_or                   myatoi_orW
#else // ANSI defs:
#define popstring(str)              PopStringA(str,COUNTOF(str))
#define popstringn                  PopStringA
#define pushstring                  PushStringA
#define peekstring(stkpos,str)      PeekStringA(str,COUNTOF(str))
#define peekstringn                 PeekStringA
#define getuservariable(varnum,str) GetUserVariableA(varnum,str,COUNTOF(str))
#define getuservariablen            GetUserVariableA
#define setuservariable             SetUserVariableA
#define myatoi                      myatoiA
#define myatou                      myatouA
#define myatoi_or                   myatoi_orA
#endif

// use preferably the above generic TCHAR-compatible macros rather than the following prototypes
int      NSISCALL PopStringA(char *str, int maxlen); // 0 on success, 1 on empty stack
void     NSISCALL PushStringA(const char *str);
int      NSISCALL PeekStringA(int stkpos, char *str, int maxlen); // 0 on success, 1 on error
void     NSISCALL GetUserVariableA(const int varnum, char* str, int maxlen);
void     NSISCALL SetUserVariableA(const int varnum, const char *str);
int      NSISCALL myatoiA(const char *str); // converts a string to an integer
unsigned NSISCALL myatouA(const char *str); // converts a string to an unsigned integer, decimal only
int      NSISCALL myatoi_orA(const char *str); // with support for or'ing (2|4|8)

int      NSISCALL PopStringW(wchar_t *str, int maxlen); // 0 on success, 1 on empty stack
void     NSISCALL PushStringW(const wchar_t *str);
int      NSISCALL PeekStringW(int stkpos, wchar_t *str, int maxlen); // 0 on success, 1 on error
void     NSISCALL GetUserVariableW(const int varnum, wchar_t* str, int maxlen);
void     NSISCALL SetUserVariableW(const int varnum, const wchar_t *str);
int      NSISCALL myatoiW(const wchar_t *str); // converts a string to an integer
unsigned NSISCALL myatouW(const wchar_t *str); // converts a string to an unsigned integer, decimal only
int      NSISCALL myatoi_orW(const wchar_t *str); // with support for or'ing (2|4|8)

#ifdef __cplusplus
}
#endif

#endif//!___NSIS_PLUGIN__H___