The Bat! Common Plug-in Application Programming Interface (CP API) v1.12
Maxim Masiutin <[email protected]> Thu, 8 Jun 2017 22:49:08 +0300
| Newsgroups | gmane.mail.the-bat.plugins |
|---|---|
| Message-ID | <[email protected]> |
--===============8326932700465985844==
Content-Type: text/html; charset=windows-1250
Content-Transfer-Encoding: quoted-printable
<html><head><title>The Bat! Common Plug-in Application Programming Interfac=
e (CP API) v1.12</title>
</head>
<body>
<span style=3D" font-family:'courier new'; font-size: 9pt;">Hello All,<br>
<br>
Please find the updated The Bat! Common Plug-in Application Programming Int=
erface (CP API) v1.12 document below. The document is also available at </s=
pan><a style=3D" font-family:'courier new'; font-size: 9pt;" href=3D"https:=
//www.ritlabs.com/download/files3/the_bat/doc/thebat-common-plugin-api-v1-1=
2.rar">https://www.ritlabs.com/download/files3/the_bat/doc/thebat-common-pl=
ugin-api-v1-12.rar</a><br>
<br>
<br>
<div align=3Dcenter>
<span style=3D" font-family:'arial'; font-size: 16pt;"><b>The Bat! Common P=
lug-in Application Programming Interface (CP API) v1.12<br>
</b></span></div>
<div align=3Dleft>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Copyright =
2003-2017 Ritlabs, SRL. All rights reserved.<br>
<a name=3D"_Toc244601698"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>1. Abstract<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">St=
arting from version 2, The Bat! introduces possibility to expand its functi=
onality by adding plug-in modules. This document describes the principles o=
f how those modules are used and what functionality should/can be included =
in them.<br>
<a name=3D"_Toc244601699"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>2. Plug-in mod=
ules<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">A =
Plug-in module for The Bat! is a Win32 Dynamically Linked Library (DLL). Th=
e default file extension of general purpose Plug-in files is .TBP (TBP stan=
ds for The Bat! Plug-in).<br>
Below is a set of functions that can be implemented in the Plug-in module (=
function names are case-sensitive):<br>
<br>
TBP_Initialize<br>
TBP_Finalize<br>
TBP_GetName<br>
TBP_GetVersion<br>
TBP_GetStatus<br>
TBP_GetInfo<br>
TBP_NeedConfig<br>
TBP_Setup<br>
TBP_SetConfigData<br>
TBP_GetConfigData<br>
TBP_NeedCOM<br>
TBP_GetSpamScore<br>
TBP_FeedSpam<br>
TBP_GetMacroList<br>
TBP_ExecMacro<br>
TBP_SetLibEntryPoints<br>
TBP_NeedResave<br>
TBP_SetCoreBridge<br>
<br>
Minimum implementation level of a Plug-in includes the following functions:=
<br>
<br>
TBP_GetName<br>
TBP_GetStatus<br>
<br>
<br>
<a name=3D"_Toc244601700"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>3. Code conven=
tions<br>
<a name=3D"_Toc244601701"></a>
<span style=3D" font-size: 13pt;">3.1. Calling convention<br>
</span></i></b><span style=3D" font-family:'times new roman'; font-size: 12=
pt;">All Plug-in functions must be implemented using standard Win32 API cal=
ling convention, which is defined as <b>TBP_EXPORT</b> in <i>C</i> and <b>s=
tdcall</b> in <i>Object Pascal <br>
</i>A code excerpt below defines <b>TBP_Export</b> for most popular C/C++ c=
ompilers:<br>
<br>
<span style=3D" font-family:'courier new'; font-size: 11pt;">// if we're in=
MS Visual C++<br>
#ifdef _MSC_VER<br>
#define TBP_EXPORT __stdcall<br>
#endif<br>
<br>
// if we're in Borland C++ Builder<br>
#ifdef __BORLANDC__<br>
#define TBP_EXPORT __stdcall <br>
#endif<br>
<br>
// if we're in Metrowerks CodeWarrior<br>
#ifdef __MWERKS__<br>
#define TBP_EXPORT __declspec(dllexport)<br>
#endif<br>
<br>
<a name=3D"_Toc244601702"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>3.2. Thread sa=
fety<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">An=
y plug-in function can be called from different threads simultaneously, so =
all functions must be aware to multi-threaded model and provide appropriate=
level of protection of internal data. If a Plug-in author does not want to=
support full-blown multithreading, a simple workaround can be made by usin=
g critical sections (<i>EnterCriticalSection</i> at the start of a function=
and <i>LeaveCriticalSection</i> at the end, make sure the critical section=
is initialised at the DLL’s entry point or in the <b>TBP_Initialize<=
/b> function and the code between <i>EnterCriticalSection</i> and <i>LeaveC=
riticalSection</i> is protected from exceptions).<br>
The plug-in must not assume that the <b>DllMain</b> or <b>TBP_Initialize</b=
> or other functions will be called from the same thread or that these thre=
ads won’t be destroyed after calling these functions. The Bat! May ca=
ll them from different threads and free the treads subsequently.<br>
The Bat! version 5 and later supports <b>TBP_MainWindowLoaded </b>function =
to notify the plugin about the main thread. The only function that is calle=
d from the thread that The Bat! would not free while the program is running=
is <b>TBP_MainWindowLoaded</b>. This function is always called from the ma=
in thread (GUI thread) after the main window of The Bat! is loaded. The plu=
gin must not assume that any of The Bat! windows or window handles exist pr=
ior to the <b>TBP_MainWindowLoaded</b> call.<br>
<a name=3D"_Toc244601703"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>3.3. Null-term=
inated strings<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Un=
less it is explicitly specified, length of string buffers <b>MUST NOT</b> i=
nclude the terminating null character and the terminating null character <b=
>MUST NOT</b> be added upon retrieval of any string data from Plug-ins.<br>
<a name=3D"_Toc244601704"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>3.4. “Bu=
ffer overrun” control<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Fo=
r safety sake, it is highly recommended not to use local array variables as=
buffers for retrieving data from objects provided by The Bat! Buffer=
s passed to Plug-in functions are dynamically allocated, but it is still hi=
ghly recommended to pay special attention to the “buffer overrun̶=
1; problem, so the program’s data stays safe.<br>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>3.5. String en=
coding<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Si=
nce The Bat! version 7.4.16.17, encoding of all strings is UTF-8. Before th=
at version, strings were encoded using the system-default codepage, configu=
red via the “Language for non-Unicode programs” Windows Regiona=
l Settings option.<br>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>3.6. Data type=
sizes<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Th=
e Bat! 32-bit version uses 32-bit plugins only, so is the 64-bit version of=
The Bat! – it can only use 64-bit versions of the plugins.<br>
So, the size of the pointer types is 4 bytes under for The Bat! 32-bit and,=
respectively, 8 bytes for The Bat! 64-bit.<br>
The size of integer types is always 4 bytes, regardless of the bitness of t=
he plugin.<br>
The size of char is always one byte, or 8 bits.<br>
<a name=3D"_Toc244601705"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>4. Programming=
languages<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">An=
y programming language can be used for creation of Plug-in modules as long =
as they can be used for creation of a Win32 DLL module, support name, call =
and thread safety conventions provided in this document.<br>
This document provides function definitions in C/C++ and Object Pascal<br>
<a name=3D"_Toc244601706"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>5. Functions <=
br>
<a name=3D"_Toc244601707"></a>
<span style=3D" font-size: 13pt;">5.1. General purpose functions.<br>
</span></i></b><span style=3D" font-family:'times new roman'; font-size: 12=
pt;">Functions described in this section are common for all types of plug-i=
ns. They are used for retrieving general information about a plug-in and pr=
oviding a proper way to initialise, finalise and configure the plug-in. <br>
<span style=3D" font-family:'arial';"><b>5.1.1. TBP_Initialize<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C=
++: <=
span style=3D" font-family:'courier new'; font-size: 10pt;">void WINAPI TBP=
_Initialize(); <br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp; Object Pascal: <span style=3D" font-family:'couri=
er new'; font-size: 10pt;">procedure TBP_Initialize; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called upon initialization of the Plug-in. During The =
Bat! execution, it is called just once right after the Plug-in module is lo=
aded. Use <b>TBP_Initialize</b> to initialize all internal data for proper =
functioning of the Plug-in. <br>
<br>
<b>Return values:<br>
<br>
</b>None. If an error occurs during a call to <b>TBP_Initialize</b>, and th=
is error is critical to the Plug-in’s functionality, <b>TBP_GetStatus=
</b> must return an error code.<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.2. TBP_Finalize<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C=
++: <=
span style=3D" font-family:'courier new'; font-size: 10pt;">void WINAPI TBP=
_Finalize(); <br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp; Object Pascal: <span style=3D" font-family:'couri=
er new'; font-size: 10pt;">procedure TBP_Finalize; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called once before the Plug-in is unloaded from memory=
. Use <b>TBP_Finalize </b>for cleaning up memory, temporary files, etc. <br>
<br>
<br>
<b>Return values:<br>
<br>
</b>None.<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.3. TBP_GetName<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetName(char* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetName(ABuf: PChar; ABufSize:=
Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called in order to retrieve the name of the Plug-in. <=
br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABuf <br>
</i>[out] Pointer to a string buffer that receives string specifying the na=
me of the Plug-in. If <b><i>ABuf</i></b> is a null pointer, the function mu=
st return value is the required buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the string buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<b>Return values:<br>
<br>
</b>A positive value  =
; the number of bytes written in the <b><i>ABuf</i></b> or th=
e required buffer size<br>
Zero or a negative value function is not suppor=
ted<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.4. TBP_GetVersion<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetVersion(char* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetVersion(ABuf: PChar; ABufSi=
ze: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called in order to retrieve the version name of the Pl=
ug-in. It is encouraged to add any valuable information about the current s=
tate of the Plug-in to the version name.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABuf <br>
</i>[out] Pointer to a string buffer that receives the string specifying th=
e version name of the Plug-in. If <b><i>ABuf</i></b> is a null pointer, the=
function must return value is the required buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the string buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<b>Return values:<br>
<br>
</b>A positive value  =
; the number of bytes written in the <b><i>ABuf</i></b> or th=
e required buffer size<br>
Zero or a negative value function is not suppor=
ted<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.5. TBP_GetStatus<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetStatus();<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetStatus: Integer; stdcall;<b=
r>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called to determine whether the Plug-in is functioning=
properly.<br>
<br>
<b>Return values:<br>
<br>
</b>0 =
the Plug-in is functioning properly<br>
Non-zero error code (will be logged)<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.6. TBP_GetInfo<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetInfo(char* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetInfo(ABuf: PChar; ABufSize:=
Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called in order to retrieve additional information abo=
ut the Plug-in. This information will be displayed when a user clicks the &=
#8220;Information” button on the Plug-in configuration page.<br>
<br>
<b>Note:</b> If the information text starts with the <HTML> tag, it i=
s displayed as an HTML document.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABuf <br>
</i>[out] Pointer to a string buffer that receives the string with informat=
ion about the Plug-in. If <b><i>ABuf</i></b> is a null pointer, the functio=
n must return value is the required buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the string buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<b>Return values:<br>
<br>
</b>A positive value  =
; the number of bytes written in the <b><i>ABuf</i></b> or th=
e required buffer size<br>
Zero or a negative value function is not suppor=
ted<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.7. TBP_NeedConfig<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;int WINAPI TBP_NeedConfig();<br>
<br>
Object Pascal: function TBP_NeedCo=
nfig: Integer; stdcall;<br>
<br>
<b>Description:<br>
<br>
</b>This function is called to determine whether the Plug-in can be configu=
red within The Bat! A user can configure Plug-ins by clicking the Con=
figure button at the Plug-in configuration page.<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>0 =
the Plug-in cannot be configured within The Bat!<br>
Non-zero the Plug-in can be configured within T=
he Bat!<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.8. TBP_Setup<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_Setup();<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_Setup: Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called for configuring the Plug-in from The Bat! Plug-=
in configuration page by clicking the Configure button or right after insta=
lling the Plug-in. The <b>TBP_Setup</b> can be called by The Bat! only if t=
he <b>TBP_NeedConfig</b> returned a non-zero value. The handle of the calli=
ng window can be retrieved by the <b>GetActiveWindow</b> Win32 API function=
.<br>
<br>
<b>Return values:<br>
<br>
</b>0 =
the Plug-in was successfully configured<br>
Non-zero the Plug-in was not configured, possib=
le error code (may be logged in future)<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.9. TBP_SetConfigData<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_SetConfigData(const void* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_SetConfigData (const ABuf; ABu=
fSize: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is used for passing Plug-in configuration data stored in =
the Plug-in configuration file. <br>
<br>
There are no any special requirements about the configuration data format; =
it is treated as a binary buffer that may contain any characters.<br>
<br>
The <b>TBP_SetConfigData</b> is called when the Plug-in is loaded and initi=
alised at the program’s start-up.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABuf <br>
</i>[in] Pointer to a binary buffer that contains Plug-in configuration dat=
a. <br>
<i>ABufSize <br>
</i>[in] Size of the binary buffer identified by <b><i>ABuf</i>,</b> in byt=
es. <br>
<br>
<b>Return values:<br>
<br>
</b>0 =
function completed successfully<br>
Non-zero a failure occurred during execution of=
the function, error code (may be logged in future)<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.10. TBP_GetConfigData<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetConfigData(void* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetConfigData (var ABuf; ABufS=
ize: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
<br>
</b>This function is used for retrieving Plug-in configuration data after t=
he Plug-in is configured using the <b>TBP_Setup</b> function in order to st=
ore the data in the Plug-in configuration file. <br>
<br>
There are no any special requirements about the configuration data format; =
it is treated as a binary buffer that may contain any characters.<br>
<br>
The <b>TBP_GetConfigData</b> is called when the <b>TBP_Setup</b> function r=
eturns zero (i.e. when the plug-in was successfully configured).<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABuf <br>
</i>[out] Pointer to a binary buffer that receives configuration data from =
the Plug-in. If <b><i>ABuf</i></b> is a null pointer, the function must ret=
urn value is the required buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the binary buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<b>Return values:<br>
<br>
</b>A positive value  =
; the number of bytes written in the <b><i>ABuf</i></b> or th=
e required buffer size<br>
Zero or a negative value function is not suppor=
ted<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.11. TBP_NeedCOM<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
</span></b><span style=3D" font-family:'times new roman';">fConfigNeeded<br>
<b>Description:<br>
<br>
</b>This function is called to determine whether the Plug-in requires COM s=
ubsystem initialisation, i.e. call to <i>CoInitialize</i> must be made befo=
re using functions of the Plug-in in a thread.<br>
<br>
If the Plug-in implements functions working with the <b>ITBPDataProvider</b=
> interface, the return value of this function is ignored because it requir=
es COM initialisation anyway.<br>
<br>
<b>Return values:<br>
<br>
</b>0 =
the Plug-in does not requi=
re COM<br>
Any non-zero value the Plug-in requires COM<br>
<br>
<span style=3D" font-family:'arial';"><b>5.1.12. TBP_SetCoreBridge<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp; int WINAPI TBP_SetCoreBridge (ITBPCoreBridge* ABridge);<br>
<br>
Object Pascal: function TBP_SetCor=
eBridge(ABridge: ITBPCoreBridge): Integer; stdcall;<br>
<br>
<br>
<b>Description:<br>
<br>
</b>ITBPCoreBridge is an interface that gives access to internal data of Th=
e Bat!. It gives access to mail items (mail accounts, folders, messages), w=
indows (viewers, editors, address book), and other data. It also allo=
ws you to call functionality of the S/MIME internal implementation of The B=
at!, i.e. allows to sign, verify, encrypt and decrypt data).<br>
<br>
This functionality is implemented since version 4.2.14 of The Bat!<br>
<br>
The Bat! calls this function only once, during the startup of The Bat! The =
plugin should save the interface to call it later.<br>
<br>
Detailed description of ITBPCoreBridge is given in a separate document.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ABridge <br>
</i>[in] The ITBPCoreBridge interface. <br>
<br>
<b>Return values:<br>
<br>
</b>The Bat! currently doesn’t check the return value of TBP_SetCoreB=
ridge<br>
<br>
<a name=3D"_Toc244601708"></a>
<span style=3D" font-family:'arial';"><b>5.1.13 TBP_MainWindowLoaded<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;int WINAPI TBP_ MainWindowLoaded();<br>
<br>
Object Pascal: function TBP_ MainW=
indowLoaded: Integer; stdcall;<br>
<br>
<b>Description:<br>
<br>
</b>This function is called from the main thread (GUI thread) to notify the=
plugin that the main window of The Bat! is loaded. <br>
<br>
This function is only supported from The Bat! version 5.<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>The return value of this function is ignored.<br>
<br>
<br>
<br>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>5.2. Anti-spam=
<br>
<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Th=
is section contains information about Anti-spam functions of Plug-ins. <br>
<br>
<span style=3D" font-family:'arial';"><b>5.2.1. TBP_GetSpamScore<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp; <span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAP=
I TBP_GetSpamScore(int MsgID, TBPGetDataProc* GetData);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetSpamScore(MsgID: Integer; G=
etData: TBPGetDataProc): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function calculates Spam Score of a message. <b>TBP_GetSpamScore</=
b> of each Plug-in is called when a message is about to be stored in the me=
ssage base after it is received and the final score is calculated according=
ly to the user settings. <b>TBP_GetSpamScore</b> must return a score out of=
100 points assigned to the message by the Plug-in. Zero score means the me=
ssage is considered as legitimate mail, 100 points means the message is sur=
ely spam. If the returned value is negative, The Bat! assumes that the mess=
age was not processed by the Plug-in and do not count the Plug-in in calcul=
ation of the final score for the given message (e.g. when two plug-ins are =
installed, if one of the Plug-ins returned -1 and the second one returned 8=
0, the average score will be 80, if both Plug-ins returned -1, the average =
score is 0)<br>
<br>
<b>TBP_GetSpamScore</b> can also be used for any preliminary processing of =
a message (for example, extracting some data from all incoming mail for sto=
ring into a database).<br>
<br>
<b>Parameters:<br>
<br>
</b><i>MsgID<br>
</i> [in] the identifier of the message =
being processed. <i>MsgID</i> passed to the <i>GetData</i> function togethe=
r with property identifier in order to retrieve required data from the mess=
age. This identifier is unique within The Bat! and cannot be reused after e=
xit from <b>TBP_GetSpamScore.<br>
</b><i>GetData<br>
</i> [in] a pointer to the <b>TBPGetData=
Proc</b> function which is used for retrieving data from a message<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>0-100 &n=
bsp; Spam Score (out of 100) assigned to a message by t=
he Plug-in<br>
A negative value the message was not processed =
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.2.1. TBP_FeedSpam<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp; <span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAP=
I TBP_FeedSpam(int MsgID, int IsSpam, TBPGetDataProc* GetData);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_FeedSpam(MsgID, IsSpam: Intege=
r; GetData: TBPGetDataProc): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function may be provided by the Plug-in in order to “educate=
” the Plug-in about spam and non-spam messages accordingly to the use=
r’s preferences. <b>TBP_FeedSpam</b> is called when a user selects me=
ssages and uses the “Mark as Junk” or “Mark as not Junk&#=
8221; command.<br>
<br>
Implementation of <b>TBP_FeedSpam</b> is optional and depends on algorithms=
used for detecting spam. <br>
<br>
A plug-in must store collected data separately from its configuration data =
that can be received by TBP_GetConfigData<br>
<br>
<b>Parameters:<br>
<br>
</b><i>MsgID<br>
</i> [in] the identifier of the message =
being processed. <i>MsgID</i> passed to the <i>GetData</i> function togethe=
r with property identifier in order to retrieve required data from the mess=
age. This identifier is unique within The Bat! and cannot be reused after e=
xit from <b>TBP_FeedSpam.<br>
</b><i>IsSpam <br>
</i> [in] if <i>IsSpam</i> is not zero, =
the message is considered as spam, otherwise the message is legitimate<br>
<i>GetData<br>
</i> [in] a pointer to the <b>TBPGetData=
Proc</b> function which is used for retrieving data from a message<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>0 =
the Plug-in collected new data from the message<br>
Non-zero the message was not processed or no ne=
w data was collected from it<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.2.3. TBPGetDataProc callback fun=
ction<br>
<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp; <span style=3D" font-family:'courier new'; font-size: 10pt;">typedef i=
nt (WINAPI TBPGetDataProc)(int MsgID, int DataID, char* ABuf, int ABufSize)=
;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">TBPGetDataProc =3D function(MsgID, DataID: =
Integer; ABuf: PChar; ABufSize: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>A <b>TBPGetDataProc</b> callback function is passed as a parameter to <=
b>TBP_GetSpamScore</b> and <br>
<b>TBP_FeedSpam</b> functions in order to provide access to data of the mes=
sage being processed.<br>
It is possible to get virtually all data from a message by calling this fun=
ction without need to parse the “raw” message source. <br>
<br>
The data returned by this function may be characterised as text (some parts=
may be encoded accordingly to various standards, though)<br>
<br>
<b>Parameters:<br>
<br>
</b><i>MsgID<br>
</i> [in] the identifier of the message =
being processed. <br>
<i>DataID <br>
</i> [in] the identifier of message prop=
erty to be retrieved. See the table of possible property identifiers in p. =
<b>5.2.4<br>
</b><i>ABuf<br>
</i> [out] a pointer to the string buffe=
r that receives data of the item identified by <b><i>DataID</i></b>; if <b>=
<i>Buf</i></b> is a null pointer, <b>TBPGetDataProc</b> returns the require=
d buffer size.<br>
<i>ABufSize<br>
</i> [in] size of the string buffer iden=
tified by <b><i>ABuf</i></b>, in bytes; if <b><i>ABufSize</i></b> is negati=
ve, <b>TBPGetDataProc</b> returns the required buffer size.<br>
<br>
Return values:<br>
<br>
0 or a positive value the number of bytes written in the buffe=
r identified by <b><i>Buf</i></b> or the requires buffer size<br>
Negative value the function failed=
or the item identified by <b><i>DataID</i></b> does not exist<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.2.4. Message Property Identifier=
s <br>
<br>
</b><span style=3D" font-family:'times new roman';">The table below describ=
es currently defined message property identifiers<br>
&nbs=
p; <br>
</span></span></span></span></span></span></span></span></span></span></spa=
n></span></span></span></span></span></span></span></span></span></span></s=
pan></span></span></span></span></span></span></span></span></span></span><=
/span></span></span></span></span></span></span></span></span></span></span=
></span></span></span></span></span></span></span></span></span></span></sp=
an></span></span></span></span></span></span></span></span></span></span></=
span></span></span></span></span></span></span></span></span></span></span>=
</span></span></span></span></span></span></span></span></span></span></spa=
n></span></span></span></span></span></span></span></span></span></span></s=
pan></span></span></span></span></span></span></span></span></span></div>
<table>
<tr>
<td width=3D228><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Name</td>
<td width=3D83><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Value</=
td>
<td width=3D343><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Used for retrieving…</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageHeader</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100000</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">RFC 82=
2 message header</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageBodyA</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100001</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d message text converted into Windows local code page. This property is obs=
olete, please use mpidMessageBodyW.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageAttachmentsA</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100002</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">List o=
f attachments separated by null character, converted into Windows local cod=
e page. The end of the list is determined by double null character. This pr=
operty is obsolete, please use mpidMessageBodyW.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageSenderA</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100003</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d list of senders converted into Windows local code page. This property is =
obsolete, please use mpidMessageSenderW.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageSubjectA</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100004</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d message subject converted into Windows local code page. This property is =
obsolete, please use mpidMessageSubjectW.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidRa=
wMessage</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100005</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">The en=
tire message source without any conversion made. This may be useful if the =
Plug-in parses messages by itself.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidRe=
ceivedDate</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100006</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">The da=
te and time when the message was received (stored to the message base). The=
format is Win32 SYSTEMTIME structure, given in local time.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageAttachmentsW</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100007</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">List o=
f attachments separated by CR character. The end of the list is determined =
by double CR character. The string is in the UTF-16 encoding.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageBodyW</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100008</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d message text in the UTF-16 encoding.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageSenderW</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100009</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d list of senders in the UTF-16 encoding.</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">mpidMe=
ssageSubjectW</td>
<td><div align=3Dcenter>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">100010</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Decode=
d message subject in UTF-16 encoding.</td>
</tr>
</table>
<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Other iden=
tifiers that can be used by the Plug-in (with self-descriptive names and va=
lues) are:<br>
<br>
<span style=3D" font-family:'courier new';"> midxSubject  =
; 1<br>
midxDate 2<br>
midxComment 3<br>
midxInReplyTo 4<br>
midxMessageID 5<br>
midxNewsgroups 6<br>
midxMailer 7<br>
midxContentType 8<br>
midxContentSubType 9<br>
midxExpireDate 10<br>
midxOrganization 11<br>
midxContentID 12<br>
midxContentMD5 13<br>
midxPriority 14<br>
midxImportance 15<br>
midxContentLocation 16<br>
<i> </i>midxEncoding 17<br>
midxCharset 18<br>
midxBoundary 19<br>
midxMsgEncoding 20<br>
midxC_Name 21<br>
midxCD_Name 22<br>
midxReportType 23<br>
midxReferences 24<br>
midxC_Description 25<br>
midxContentDisposition 26<br>
midxContentLanguage 27<br>
midxC_ID 29<br>
midxC_AccessType 30<br>
midxC_Expiration 31<br>
midxC_Size 32<br>
midxC_Permission 33<br>
midxC_Site 34<br>
midxC_Directory 35<br>
midxC_Mode 36<br>
midxC_Server 37<br>
midxC_Subject 38<br>
midxReturnPath 41<br>
midxFromName 42<br>
midxFromAddr 43<br>
midxReplyName 44<br>
midxReplyAddr 45<br>
midxToName 46<br>
midxToAddr 47<br>
midxServerID 48<br>
midxRRC 49<br>
midxRRQ 50<br>
midxFileSubst 51<br>
midxC_Number 52<br>
midxC_Total 53<br>
midxMDN_To 55<br>
midxMDN_Options 56<br>
midxRefList 57<br>
midxC_MICAlg 58<br>
midxC_SMIMEType 59<br>
midxC_Protocol 60<br>
midxC_ProtocolType 61<br>
<i> </i>midxC_ProtocolSubType 62<br>
<i> </i>midxMatter 63<br>
midxListHelp 64<br>
midxListUnsub 65<br>
midxListSub 66<br>
midxListPost 67<br>
midxListOwner 68<br>
midxListArchive 69<br>
midxDecodedFrom 70<br>
midxDecodedTo 71<br>
midxDecodedSubj 72<br>
midxDecodedToEtc 73<br>
midxFrom 74<br>
midxTo 75<br>
midxCC 76<br>
midxBCC 77<br>
midxReplyTo 78<br>
midxSender 79<br>
midxXSender 80<br>
midxImapURL 81<br>
midxMailChat 82<br>
midxMailingList 83<br>
midxC_Format 84<br>
midxC_Type 85<br>
midxC_Min 86<br>
midxC_Max 87<br>
midxC_Mandatory 88<br>
midxImapSize 89<br>
midxC_CrType 90<br>
midxExValName 91<br>
midxDefValue 92<br>
midxOrigRcpt 93<br>
midxCIntData 94<br>
midxCSpScope 95<br>
midxCLoadFrom 96<br>
midxCSaveTo 97<br>
midxSpScope 98<br>
midxLoadFrom 99<br>
midxSaveTo 100<br>
midxSendDelay 108 // See the %POSTPONE m=
acro <br>
midxSendDelayEvent 109<br>
midxTags 112<br>
midxRefferedMsgURL 113<br>
midxDecodedFromUTF8 114<br>
midxDecodedToUTF8 115<br>
midxDecodedSubjUTF8 116<br>
midxDecodedToEtcUTF8 117<br>
midxRSSFeedURL 118<br>
midxRSSItemLink 120<br>
<br>
<span style=3D" font-family:'times new roman';">Note: “midxC_” =
identifiers are used for retrieving values of corresponding Content-Type pa=
rameters.<br>
<br>
<a name=3D"_Toc244601709"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>5.3. Custom ma=
cros<br>
<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Th=
is sections describes functions for adding new macros to the existing set o=
f template macros (see The Bat! Help to find out the list of built-in macro=
s)<br>
<span style=3D" font-family:'arial';"><b>5.3.1. TBP_GetMacroList<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp;<span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAPI=
TBP_GetMacroList(char* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_GetMacroList(ABuf: PChar; ABuf=
Size: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
</b>This function is called in order to retrieve the CR LF – separate=
d list of macros implemented in the Plug-in. This list is used by The Bat! =
Template Processor to find the plug-in that implements an unknown macro. No=
te that Plug-ins cannot overwrite any of built-in macros, so before giving =
macro a name, the implementer should make sure the names of new macros do n=
ot conflict with existing ones.<br>
Name of macro may contain any number of characters; the set of allowed char=
acters is restricted to Latin letters (A-Z), decimal digits (0-9) and the u=
nderscore character ( _ ). Macro names are case insensitive.<br>
<b>Parameters:<br>
</b><i>ABuf <br>
</i>[out] Pointer to a string buffer that receives the string containing li=
st of macros implemented by the Plug-in separated by CR LF pair. If <b><i>A=
Buf</i></b> is a null pointer, the function must return value is the requir=
ed buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the string buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<b>Return values:<br>
<br>
</b>A positive value  =
; the number of bytes written in the <b><i>ABuf</i></b> or th=
e required buffer size<br>
Zero or a negative value function is not suppor=
ted<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>5.3.2. TBP_ExecMacro<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';"> C+=
+: &n=
bsp; <span style=3D" font-family:'courier new'; font-size: 10pt;">int WINAP=
I TBP_ExecMacro(char* AMacro, int MaxLen, ITBPDataProvider* Template, ITBPD=
ataProvider* Params): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> &n=
bsp;Object Pascal: <span style=3D" font-family:'=
courier new'; font-size: 10pt;">function TBP_ExecMacro(AMacro: PChar; MaxLe=
n: Integer; Template, Params: ITBPDataProvider): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is called each time the Template Processor executes a mac=
ro listed by the Plug-in. The Plug-in should execute the macro accord=
ingly to its rules and return either the index in the Template object where=
the replacing text should be taken from or negative value if macro is repl=
aced by empty string.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>AMacro <br>
</i>[in] Pointer to a string buffer that contains the null-terminated strin=
g specifying the name of the macro to be executed. <br>
<i>MaxLen <br>
</i>[in] Maximum length of the macro name located in <b><i>AMacro</i></b>.<=
br>
<i>Template <br>
</i>[in] Pointer to the Template Processor object; p. <b>5.3.3 </b>specifie=
s the list of property identifiers that could be used for setting and retri=
eving information. The <b><i>Template.ExecuteMacro</i></b> method can be us=
ed for execution of simple templates (this is especially useful for retriev=
ing information from the address book using %ABnnnPPP macros, use of regula=
r expression macros, setting custom message header fields), the <i>OutData<=
/i> object is used for passing back the result of template execution, the d=
ata index of the result is 0.<br>
<i>Params <br>
</i>[in] Pointer to the parameter list object. The <b><i>Params</i></b>.<b>=
ItemCount</b> method returns the number of parameters passed to the macro. =
To retrieve parameters, use call to <b><i>Params.GetDataByID(</i></b>Index<=
b>,…)</b>, where <i>Index</i> specifies the zero-based index of a par=
ameter. Note that parameters passed to the macro are templates themselves, =
they are executed once when and only if they are retrieved by using the <b>=
<i>Params.GetDataByID</i></b> method.<br>
<br>
<b>Return values:<br>
<br>
</b>0 or positive value &n=
bsp; The index in the Template object where the resulting string shou=
ld be taken from<br>
Negative value &nbs=
p; Macro was executed but in should be replaced by empty stri=
ng<br>
<br>
<br>
<a name=3D"_Toc112845546"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>5.3.3. TBP_Set=
LibEntryPoints<br>
<br>
</i><span style=3D" font-family:'times new roman'; font-size: 12pt;">Syntax=
:<br>
<br>
</span></b><span style=3D" font-family:'times new roman'; font-size: 12pt;"=
> C++: =
int WINAPI TBP_SetLibEntryPoints (void *AData, int AN=
umPoints);<br>
<br>
Object Pascal: function TBP_SetLib=
EntryPoints(const AData: Pointer; const ANumPoints: Integer): Integer; stdc=
all; <br>
<br>
<br>
<b>Description:<br>
<br>
</b>Sometimes a plugin may need access to functions already implemented in =
The Bat!, e.g. memory-allocation routines, a library that implements Perl-C=
ompatible Regular Expressions, etc.<br>
<br>
This function is called before TBP_Initialize in order to pass entry points=
to the functions above mentioned to the plugin. The plugin should save ent=
ry points of the functions to call them later.<br>
This function is called from The Bat! 3.60.04 and higher.<br>
<br>
Please see the complete list of the functions that The Bat! provides to the=
plugin in the separate document “LibEntryPoints”.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>AData <br>
</i>[in] Pointer to the array of pairs of entry point. Each pair consist of=
a 32-bit DWORD of the function ID and 32-bit or 64-bit pointer to the func=
tion entry point. This yields to 8 bytes for each pair for a 32-bit process=
and 12 bytes for a 64-bit process. Please see the complete list of the IDs=
of functions that The Bat! provides in the separate document “LibEnt=
ryPoints”. <br>
<i>ANumPoints<br>
</i>[in] Number of 8-byte (or 12-byte) pairs passed in AData.<br>
<br>
<b>Return values:<br>
<br>
</b>The Bat! currently doesn’t check the return value of TBP_SetLibEn=
tryPoints<br>
<br>
<a name=3D"_Toc244601711"></a>
<span style=3D" font-family:'arial'; font-size: 13pt;"><b><i>5.3.4. TBP_Nee=
dResave<br>
<br>
</i><span style=3D" font-family:'times new roman'; font-size: 12pt;">Syntax=
:<br>
<br>
</span></b><span style=3D" font-family:'times new roman'; font-size: 12pt;"=
> C++: =
BOOL int WINAPI TBP_NeedResave (void);<br>
<br>
Object Pascal: function TBP_NeedRe=
save:BOOL; stdcall; <br>
<br>
This function is called when the plug-in is just loaded, it should return T=
RUE when The Bat! should retrieve plug-in's configuration data and save it =
right away. This function is not called when the plug-in is added (TBP_Need=
Config is called instead), so this may be helpful sometimes for distinction=
of two ways of loading a plug-in.<br>
<br>
The logic of this function is can be illustrated by the following code:<br>
<br>
if (TBP_NeedResave)<br>
{ <br>
TBP_GetConfigData(); <br>
TBPIni.WriteStr(....) <br>
}<br>
<br>
<span style=3D" font-family:'arial';"><b>5.3.5. Template object index<br>
<br>
</b><span style=3D" font-family:'times new roman';">Below is the list of in=
dexes that can be used for setting and retrieving information of a Template=
object passed to <b>TBP_ExecMacro</b> . Index names are considered as self=
-explanatory. <br>
<br>
String indexes (string data can be accessed by <b>ITBPDataProvider::GetData=
ByID </b>and <b>ITBPDataProvider::SetDataByID</b>):<br>
<br>
<span style=3D" font-family:'courier new'; font-size: 9pt;"> tpxQuotePrefix=
200 // Current quotation prefix as it app=
ears in text<br>
tpxCharset 211<br>
tpxAccount 214<br>
tpxFrom 215<br>
tpxReplyTo 216<br>
tpxReturnPath 217<br>
tpxTo 218<br>
tpxCC 219<br>
tpxBCC 220<br>
tpxOrg 221<br>
tpxSubject 222<br>
tpxFullSubject 223<br>
tpxComment 224<br>
tpxOldTo 225<br>
tpxOldFrom 226<br>
tpxOldReplyTo 227<br>
tpxOldCC 228<br>
tpxOldBCC 229<br>
tpxOldSubject 230<br>
tpxOldComment 231<br>
tpxMatter 232<br>
tpxOldMatter 233<br>
tpxMsgID 234<br>
tpxOldMsgID 235<br>
tpxOldDate 236<br>
tpxOldRcvDate 237<br>
tpxOldReturn 238<br>
tpxOldOrg 239<br>
tpxOldText 240<br>
tpxText 241 // Text=
of the original message (selected part when initiated by “Reply quot=
ing selected text” command)<br>
tpxHeaders 243<br>
tpxAttachments 244<br>
tpxOldAttachments 245<br>
tpxOldCharset 247<br>
tpxTracking 248 // Message tracki=
ng number <br>
tpxQuoteStyle 249 // Defined quotation s=
tyle, empty string <br>
tpxRegExpPattern 251<br>
tpxRegExpText 252<br>
tpxFullText 254 // Full text of o=
riginal message<br>
tpxLastAddress 257<br>
tpxCursorHeader 261<br>
tpxReferences 265<br>
tpxOldRefs 266<br>
tpxIncludeMask 279<br>
tpxEventText 281<br>
tpxHtmlTextA 283<br>
tpxHtmlCharsetA 284<br>
tpxMemo 286<br>
tpxDelay 290 // See=
the %POSTPONE macro <br>
tpxTags 300<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Integer an=
d Boolean indexes (32-bit integer data can be accessed by <b>ITBPDataProvid=
er::GetIntValue</b> and <b>ITBPDataProvider::SetIntValue</b>). For Boolean =
data, 0 value mean False, any non-zero integer means True. <br>
<br>
</span></span></span></span></span></span></span></span></span></span></spa=
n></span></span></span></span></span></span></span></span></span></span></s=
pan></span></span></span><table>
<tr>
<td width=3D264><span style=3D" font-family:'courier new'; font-size: 12pt;=
"><b>Index</td>
<td width=3D66><span style=3D" font-family:'courier new'; font-size: 12pt;"=
><b>ID</td>
<td width=3D87><span style=3D" font-family:'times new roman'; font-size: 12=
pt;"><b>Type</td>
<td width=3D269><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Meaning</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxWrapJus=
tify</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">201</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">If Tru=
e, all subsequent calls to the %Wrapped macro will produce wrapped text ali=
gned by both left and right edges</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxClear</=
td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">202</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">If Tru=
e, the text produced by calling template will completely replace the text i=
n the message editor</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxIsSigna=
ture</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">203</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">If Tru=
e, the text produced by calling template will replace the current signature=
in the message editor</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxSignCom=
plete</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">204</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not sign message on completion<br>
0 Use default signing settings<br>
> 0 Sign message on completion</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxEncrypt=
Complete</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">205</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not encrypt message on completion<br>
0 Use default settings<br>
> 0 Encrypt message on completion</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxUseSMIM=
E</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">206</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not to use S/MIME<br>
0 Use default settings<br>
> 0 Use S/MIME</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxUsePGP<=
/td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">207</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not to use OpenPGP<br>
0 Use default settings<br>
> 0 Use OpenPGP</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxRCR</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">208</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not request Reading Confirmation<br>
0 Use default settings<br>
> 0 Request Reading Confirmation</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxRRQ</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">209</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not request Confirm Receipt <br>
0 Use default settings<br>
> 0 Request Confirm Receipt</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxSplit</=
td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">210</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Do not split large message <br>
0 Use default settings<br>
> 0 Split large message</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxPriorit=
y</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">212</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">< 0=
Message priority is <b><i>Low<br>
</i></b>0 Message priority is <b><i>Norma=
l<br>
</i></b>> 0 Message priority is <b><i>High</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxTotalPa=
ges</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">262</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">(Print=
ing header/footer only) Total number of pages</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxCurrent=
Page</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">263</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">(Print=
ing header/footer only) The current page number</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxFullTex=
tDifferent</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">259</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">True i=
f data items identified by tpxText and tpxFullText are different, false oth=
erwise. </td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxCursorB=
ody</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">260</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">1 R=
11; cursor should be positioned in message body<br>
100 – cursor was positioned, but not in the body</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxEditorT=
ype</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">276</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">See th=
e %SETEDITOR macro</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxInclude=
Original</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">277</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">See th=
e %ATTACHORIGINAL macro</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxOrigina=
lNoAttach</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">278</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Intege=
r</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">See th=
e %NoOriginalAttachments macro</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">tpxInclude=
OriginalHeader</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">280</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">See th=
e %crcATTACHORIGINALHeader</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxEve=
ntText</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">281</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxTex=
tSet</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">282</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxHtm=
lTextA</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">283</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxHtm=
lCharsetA</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">284</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxPGP=
mode</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">285</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxMem=
o</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">286</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxBas=
ePos</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">287</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxHas=
AttachMacro</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">288</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxIgn=
oreSeparator</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">289</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxDel=
ay</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">290</t=
d>
<td><br>
</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">See th=
e %POSTPONE macro</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxTag=
s</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">300</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">tpxOld=
Tags</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">301</t=
d>
<td><br>
</td>
<td><br>
</td>
</tr>
</table>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Note ab=
out using ITBPDataProvider::SetDataByID: </b>try to use<b> ITBPDataProvider=
::ExecuteMacro</b> method for setting standard template properties wherever=
it is possible.<br>
<br>
<br>
<a name=3D"_Toc244601712"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>6. ITBPDataPro=
vider – the universal interface for data exchange<br>
<br>
</i><span style=3D" font-family:'times new roman'; font-size: 12pt;">ITBPDa=
taProvider</span></b><span style=3D" font-family:'times new roman'; font-si=
ze: 12pt;"> is the universal interface for exchanging data and commands bet=
ween The Bat! and Plug-ins. This interface is supported by all The Bat! obj=
ects that are or will be accessible by a Plug-in to maintain simplicity (an=
d thus reliability) of communication with Plug-ins.<br>
<br>
<b>Syntax:<br>
<br>
</b>C++:<br>
<span style=3D" font-family:'courier new'; font-size: 10pt;">interface DEC=
LSPEC_UUID("9DD91B89-A551-4180-8A81-2CCF584CD4BF") ITBPDataProvider : publi=
c IUnknown <br>
{<br>
<i> </i>virtual int WINAPI GetDataByID(int ID, char* ABuf, int=
ABufSize) =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual int WINA=
PI SetDataByID(int ID, char* ABuf, int ABufSize) =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual int WINA=
PI GetIntValue(int ID) =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual int WINA=
PI SetIntValue(int ID, int Value) =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual int WINA=
PI GetIDType(int ID) =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual int WINA=
PI ItemCount() =3D 0;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">virtual HRESULT =
WINAPI ExecuteMacro(char* AMacro, int MaxLen, ITBPDataProvider* InData, ITB=
PDataProvider* OutData) =3D 0;<br>
}<br>
<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<br>
<br>
<span style=3D" font-family:'courier new'; font-size: 10pt;">ITBPDataProvid=
er =3D interface ['{9DD91B89-A551-4180-8A81-2CCF584CD4BF}']<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function GetData=
ByID(ID: Integer; ABuf: PChar; ABufSize: Integer): Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function SetData=
ByID(ID: Integer; ABuf: PChar; ABufSize: Integer): Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function GetIntV=
alue(ID: Integer): Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function SetIntV=
alue(ID, Value: Integer): Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function GetIDTy=
pe(ID: Integer): Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function ItemCou=
nt: Integer; stdcall;<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"> <s=
pan style=3D" font-family:'courier new'; font-size: 10pt;">function Execute=
Macro(AMacro: Pointer; MaxLen: Integer; InData, OutData: ITBPDataProvider):=
HResult; stdcall;<br>
end;<br>
<br>
<br>
<span style=3D" font-family:'arial'; font-size: 12pt;"><b>6.1. ITBPDa=
taProvider::GetDataByID<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++: &nbs=
p; <span style=3D" font-family:'co=
urier new'; font-size: 10pt;">virtual int WINAPI GetDataByID(int ID, char* =
ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> function =
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Get<span s=
tyle=3D" font-family:'courier new'; font-size: 10pt;">DataByID(ID: Integer;=
ABuf: PChar; ABufSize: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is used for retrieving text data from the object. Each ob=
ject’s readable property should be available at least for reading by =
using this function. Format of data being received is determined by the typ=
e returned by the <b>GetIDType</b> method and described in p. <b>6.5<br>
<br>
Parameters:<br>
<br>
</b><i>ID<br>
</i>[in] Identifier of the property to be retrieved. <br>
<i>ABuf <br>
</i>[out] Pointer to a string buffer that receives property data. If <b><i>=
ABuf</i></b> is a null pointer, the function must return value is the requi=
red buffer size in bytes.<br>
<i>ABufSize <br>
</i>[in] Size of the string buffer identified by <b><i>ABuf,</i></b> in byt=
es. If the <b><i>ABufSize</i></b> is negative, the function must return val=
ue is the required buffer size in bytes.<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>Zero or a positive value the number o=
f bytes written in the <b><i>ABuf</i></b> or the required buffer size<br>
A negative value &n=
bsp; function is not supported<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>6.2. ITBPDataProvider::SetDataByID=
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual int WINAPI SetDataByID(int ID, char* ABuf, int ABufSize);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> fun=
ction SetDataByID(ID: Integer; ABuf: PChar; ABufSize: Integer): Integer; st=
dcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is used for assigning data to object properties. . Format=
of data that could be stored into the property is determined by the type r=
eturned by the <b>GetIDType</b> method. <br>
<br>
Note: some objects many provide read-only access to their properties.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ID<br>
</i>[in] Identifier of the property to be changed. <br>
<i>ABuf <br>
</i>[in] Pointer to a memory buffer that contains property data. <br>
<i>ABufSize <br>
</i>[in] Size of the memory buffer identified by <b><i>ABuf,</i></b> in byt=
es. <br>
<br>
<br>
<b>Return values:<br>
<br>
</b>Zero or a positive value the number o=
f bytes written into the target property<br>
A negative value &n=
bsp; function is not supported<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>6.3. ITBPDataProvider::GetIntValue=
<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual int WINAPI GetIntValue(int ID);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> function =
GetIntValue(ID: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function returns integer value of a property. Even when a property=
is not numeric, it is encouraged that implementations tried to convert sto=
red data into numeric format. For example if a string property is ‘10=
01’, the result of <b>GetIntValue</b> with the ID if this property sh=
ould be 1001. Boolean data should be converted into integer values accordin=
gly to common conventions (0 means False, non-zero value means True)<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ID<br>
</i>[in] Identifier of the property to be retrieved. <br>
<br>
<b>Return values:<br>
<br>
</b>The function must always return the value corresponding to the property=
ID. For non-existing properties, zero (0) must be returned<br>
<br>
<span style=3D" font-family:'arial';"><b>6.4. ITBPDataProvider::SetIntValue=
<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual int WINAPI SetIntValue(int ID, int Value);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> function =
SetIntValue(ID, Value: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function should be used for assigning 32-bit integer values wit th=
e object’s property. <br>
<br>
Note: some objects many provide read-only access to their properties.<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ID<br>
</i>[in] Identifier of the property to be changed. <br>
<i>Value<br>
</i>[in] 32-bit integer value to be assigned to the property. <br>
<br>
<b>Return values:<br>
</b> <br>
0 &nb=
sp;The integer data was assigned successfully.<br>
Any other Object cannot change the property with=
provided ID.<br>
<br>
<span style=3D" font-family:'arial';"><b>6.5. ITBPDataProvider::GetIDType<b=
r>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual int WINAPI GetIDType(int ID);<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> function =
GetIDType(ID: Integer): Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function returns type identifier of the property specified by <b><=
i>ID</i></b>;<br>
<br>
<br>
<b>Parameters:<br>
<br>
</b><i>ID<br>
</i>[in] Identifier of the target property <br>
<br>
<br>
<b>Return values:<br>
<br>
</b>Property type identifier<br>
<br>
Below is the list of currently defined type identifiers:<br>
<br>
</span></span></span></span></span></span></span></span></span></span></spa=
n></span></span></span></span></span></span></span></span></span></span></s=
pan></span></span></span></span></span></span></span></span></span></span><=
/span></span></span></span></span></span></span></span></span></span></span=
></span></span></span></span></span></span></span></span></span></span></sp=
an></span></span></span></span></span></span></span></span></span></span><t=
able>
<tr>
<td width=3D134><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Name</td>
<td width=3D67><span style=3D" font-family:'times new roman'; font-size: 12=
pt;"><b>Value</td>
<td width=3D133><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Description</td>
<td width=3D309><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>GetDataByID / SetDataByID Conversion</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcChar</t=
d>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">0</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">String=
data</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">As is<=
/td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcInt</td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">1</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">32-bit=
integer</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Text r=
epresentation of the number</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcInt64</=
td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">2</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">64-bit=
integer</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Text r=
epresentation of the number</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcWChar</=
td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">3</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">UTF-16=
-encoded text</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Text c=
onverted in the local code page</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcBool</t=
d>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">5</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Boolea=
n</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">‘=
;0’ for False, ‘1’ for True</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcBinary<=
/td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">6</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Binary=
data</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Base64=
-encoded text</td>
</tr>
<tr>
<td><span style=3D" font-family:'courier new'; font-size: 10pt;">dtcFloat</=
td>
<td><span style=3D" font-family:'courier new'; font-size: 12pt;">7</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Floati=
ng-point value that corresponds to “Double” data type in Delphi=
, the Double precision floating-point value (8 bytes)</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Text r=
epresentation of the number</td>
</tr>
</table>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Negative v=
alue Property is not defined yet<b=
r>
<br>
<br>
<span style=3D" font-family:'arial';"><b>6.6. ITBPDataProvider::ItemCount<b=
r>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual int WINAPI ItemCount();<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> &n=
bsp; function ItemCount: Integer; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function returns the number of stored properties for numbered list=
objects (such as <b><i>Params</i></b> in <b>TBP_ExecMacro</b>)<br>
<br>
<b>Parameters:<br>
<br>
</b>None<br>
<br>
<b>Return values:<br>
<br>
</b>The number of counted properties.<br>
<br>
<br>
<span style=3D" font-family:'arial';"><b>6.7. ITBPDataProvider::ExecuteMacr=
o<br>
<br>
<span style=3D" font-family:'times new roman';">Syntax:<br>
<br>
</span></b><span style=3D" font-family:'times new roman';">C++:<span style=
=3D" font-family:'courier new'; font-size: 10pt;"> &nb=
sp; virtual HRESULT WINAPI ExecuteMacro(char* AMacro, int MaxLen, ITBPDataP=
rovider* InData, ITBPDataProvider* OutData);<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;">Object Pas=
cal:<span style=3D" font-family:'courier new'; font-size: 10pt;"> &n=
bsp; function ExecuteMacro(AMacro: PChar; MaxLen: Integer; InData, Ou=
tData: ITBPDataProvider): HResult; stdcall;<br>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Descrip=
tion:<br>
<br>
</b>This function is designed to give extra access to facilities provided b=
y an object. Each object that implements the <b>ITBPDataProvider</b> interf=
ace may have its own set of macros that is documented for that particular o=
bject. <br>
<br>
Below is the list of objects with documented behaviour of ExecuteMacro meth=
od: <br>
<br>
</span></span></span></span></span></span></span></span></span></span></spa=
n></span></span><table>
<tr>
<td width=3D315><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Object</td>
<td width=3D328><span style=3D" font-family:'times new roman'; font-size: 1=
2pt;"><b>Where documented</td>
</tr>
<tr>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">Templa=
te Processor objects</td>
<td><span style=3D" font-family:'times new roman'; font-size: 12pt;">p.<b>5=
.3.2</td>
</tr>
</table>
<br>
<span style=3D" font-family:'times new roman'; font-size: 12pt;"><b>Paramet=
ers:<br>
<br>
</b><i>AMacro <br>
</i>[in] Pointer to a string buffer that contains the null-terminated strin=
g specifying the text of the macro to be executed. <br>
<i>MaxLen <br>
</i>[in] Maximum length of the macro text located in <b><i>AMacro</i></b>.<=
br>
<br>
<i>InData<br>
</i>[in] Pointer to the <b>ITBPDataProvider</b> object containing input dat=
a for macro execution, if required. Property indexes and meaning are to be =
documented for each implementation. For most cases, <b><i>InData</i></b> is=
a numbered list of parameters.<br>
<i>OutData<br>
</i>[out] Pointer to the <b>ITBPDataProvider</b> object containing output d=
ata of macro execution, if required. Property indexes and meaning are to be=
documented for each implementation.<br>
For most cases, Property with zero index contains the result of execution o=
f the Macro.<br>
<br>
<br>
<b>Return values:<br>
<br>
</b>To be documented for each implementation<br>
<br>
<br>
<a name=3D"_Toc244601713"></a>
<span style=3D" font-family:'arial'; font-size: 14pt;"><b><i>7. History of =
changes<br>
</i></b><span style=3D" font-family:'times new roman'; font-size: 12pt;">Ve=
rsion 1.0 (2003) – Initial document;<br>
Version 1.9 (October 9th, 2009) clarifies the TBP_NeedResave and adds new v=
alues to the “Template object index”;<br>
Version 1.10 (November 27th, 2009) adds a description for TBP_SetCoreBridge=
;<br>
Version 1.11 (July 30th, 2010) clarifies thread safety and adds TBP_MainWin=
dowLoaded;<br>
Version 1.12 (June 8th, 2017) explains string encoding and data type sizes,=
adds new identifiers, replaces "UNICODE" to UTF-16, to be precise.<br>
<br>
<br>
<br>
<span style=3D" font-family:'arial'; font-size: 9pt; color: #c0c0c0;"><i>--=
<br>
Maxim Masiutin<br>
Director<br>
Ritlabs, SRL </body></html>
--===============8326932700465985844==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline