CopiaFacts Reference Manual

This DLL interface is provided to be called by the Copia SMTP Gateway, unlike the other DLL interfaces which are called from the COPIAFACTS engine.

The DLL allows a Copia Gateway user to control programmatically the (sender) template which will be applied to an incoming e-mail message.  Using the DLL avoids the need to create and maintain large numbers of sender template files to control and validate incoming e-mail.  Typically your DLL code would query a database to obtain the template image to be used.

Setup

The FAXFACTS.CFG configuration file should have two variables defined, for example:

$var_def TEMPLATE_DLL_PATH "@PFC\customtemplate.dll"

$var_def TEMPLATE_DLL_BUFFER_SIZE 3000

The first variable will cause the specified DLL to be loaded at service startup and called for each incoming e-mail.  The second will set the buffer size for the template contents to be returned.  Set this to suit your application requirements.  If not specified, the default value is 2048.  Values less than 256 will be replaced by a value 256.

DLL Entry Point

The DLL entry point must be named TemplateRead (case is significant).

The C prototype for the entry point is as follows:

typedef int (*TREAD)(wchar_t *, wchar_t *, wchar_t *, int); TREAD TemplateRead;

The parameters passed to the call are as follows:

•The first parameter is a null-terminated wide-character array containing the recipient domain name.  Currently the Gateway supports only ASCII characters for this field.

•The second parameter is a null-terminated wide-character array containing the sender e-mail address.  Currently the Gateway supports only ASCII characters for this field.

•The third parameter is a wide-character buffer provided for the DLL to return the FST template contents, null-terminated. If the DLL is called in a CopiaFacts version 7 environment, the returned text must be capable of being encoded with system default encoding.  If the DLL is called in a CopiaFacts version 8 or later environment, any valid Unicode data can be returned.  The use of wide-character parameters avoids the need to change parameter encoding between CopiaFacts version 7 and version 8.

•The fourth parameter is the size of the buffer in wide characters, obtained from the variable TEMPLATE_DLL_BUFFER_SIZE.

•The FST template format should be a single string containing one or more lines of text, each line terminated with a carriage-return / line-feed pair of characters.

Alternate DLL Entry Point

The DLL entry point must be named TemplateReadEx (case is significant). If present, this entrypoint is called instead of TemplateRead

The C prototype for the entry point is as follows:

typedef int (*TREAD)(wchar_t *, wchar_t *, wchar_t *, wchar_t *, int); TREAD TemplateRead;

The parameters passed to the call are as follows:

•The first parameter is a null-terminated wide-character array containing the recipient domain name.  Currently the Gateway supports only ASCII characters for this field.

•The second parameter is a null-terminated wide-character array containing the sender e-mail address.  Currently the Gateway supports only ASCII characters for this field.

•The third parameter is a wide-character buffer provided for the DLL to return the FST template contents, null-terminated. If the DLL is called in a CopiaFacts version 7 environment, the returned text must be capable of being encoded with system default encoding.  If the DLL is called in a CopiaFacts version 8 or later environment, any valid Unicode data can be returned.  The use of wide-character parameters avoids the need to change parameter encoding between CopiaFacts version 7 and version 8.

•The fourth parameter is the sender IP address

•The fifth parameter is the size of the buffer in wide characters, obtained from the variable TEMPLATE_DLL_BUFFER_SIZE.

•The FST template format should be a single string containing one or more lines of text, each line terminated with a carriage-return / line-feed pair of characters.

It is important to note that the entry point may be called concurrently from multiple threads in the Gateway.  It is also operating in a service environment so may not have access to the shares and drive mappings of any specific user.

The returned template text is saved in the .MIF file for use by the Gateway thread that processes incoming messages after receipt.

DLL Return Value

The DLL return value is interpreted as follows: