You can write a DLL that conforms to an interface, and then load it into HL7Connect. DLLs such as the examples in this document, can be used to interface non-HL7 compliant systems or directly interface databases.

Warning

DLLs are loaded into the address space of HL7Connect, and so, are able to hang or crash HL7Connect. Developers wishing to develop DLLs should take care to make sure this does not happen.

Interface Specification

The interface revolves around the following record structure, which is passed between the HL7Connect Kernel and the DLL for each call.

The record structure is a static structure in which the DLL can store pointers to the internal structure.

For each interface, there will be a different instance of this structure, allowing a single DLL to host multiple interfaces.

C++ :

typedef struct DLLCONTEXT
  {
  long Size;
  void *KernelPointer;
  long Version;
  char *KernelVersion;
  long Listening;
  char *ConfigParam;
  void *ReceiveCall;
  void *FreeMemCall;
  void *StatusCall;
  void *LogErrorCall;
  void *UserValue; } TDLLContext;

  TDLLContext* pDLLContext;

Delphi :

  pDLLContext = ^TDLLContext;
  TDLLContext = record
    Size: Cardinal;
    KernelPointer: pointer;
    Version: cardinal;
    KernelVersion: PChar;
    Listening: Cardinal;
    ConfigParam: PChar;
    ReceiveCall: pointer;
    FreeMemCall: pointer;
    StatusCall: pointer;
    LogErrorCall: pointer;
    UserValue: pointer;
  end;

The following fields are Read Only and should not be modified by the DLL:

Field    Description
Size    The size of the structure
KernelPointer    Internal pointer used by HL7Connect
Version    The version of the DLL Interface
KernelVersion       Version of the HL7Connect Kernel
Listening    Set to 1 if the Kernel is expecting messages from the DLL, otherwise 0 
ConfigParam    A configuration parameter in the Kernel
ReceiveCall    Pointer to a callback
FreeMemCall    Pointer to a callback
StatusCall    Pointer to a callback
LogErrorCall    Pointer to a callback

UserValue

The UserValue, which is set by the DLL, is read/write, and so it can be used to store an object or context pointer. The UserValue cannot be modified by the Kernel.

Attributes

Callbacks

ReceiveCall

  typedef int (*ReceiveCall)(pDLLContext Context, char * Message, char** Reply);
  ReceiveCall = function (Context:pDLLContext; Message:pchar; var Reply:pchar):integer;  stdcall;

The DLL calls this function to pass an HL7 message to the kernel.

Function Attributes

StatusCall

  typedef int (*StatusCall)(pDLLContext Context, long Status, char* Comment);
  StatusCall = function (Context:pDLLContext; Status:Cardinal; Comment:pchar):integer;  stdcall;

This function is used to send a change in status to the kernel.

Function Attributes

LogErrorCall

  typedef int (*LogErrorCall)(pDLLContext Context, int Level, char *ErrMsg);
  LogErrorCall = function (Context:pDLLContext; Level:Integer; ErrMsg:pchar):integer;   stdcall;

Logs errors in the Kernel.

Function Attributes

The level indicates the severity of the message, and as a rough guide should run a long the following lines:

Level    Value    Description
FATAL    1    Kernel will halt immediately
SERIOUS    2      
ANNOUNCE    3      
ERROR/WRONG    4      
MEMORY ERROR      5      
EXCEPTION    6      
ERROR    7      
WARNING    8      
INTERESTING    9      

These messages are routed into the internal logging system of the Kernel, and filtered according to priorities set in global settings.

FreeMem

  typedef int (*FreeMem)(pDLLContext Context,void * Mem);
  FreeMem = function (Context:pDLLContext; Mem:pointer):integer;     stdcall;

This function must be called by the DLL, to free up any memory, allocated by the kernel.

Functions exported by the DLL

EntryProc

Only required for outgoing Interfaces.

  __declspec(dllexport) int EntryProc(pDLLContext Context, int SrcID, char * Msg, char** reply, int size);
  TMessage = function (Context:pDLLContext; SrcID:integer; Msg:pchar; var reply:pchar; var size:integer):integer; stdcall;

The entry point for new messages to be accepted from the gateway.

Function Attributes

This function should return 0 for success, or a windows 32 API error code to indicate a failure.

StartUp

  __declspec(dllexport) int startup (pDLLContext Context);
  Tstartup = function(Context:pDLLContext):integer;stdcall;

Function Attributes

This function should return 0 for success, or a windows 32 API error code to indicate a failure.

Status

   __declspec(dllexport) int status (pDLLContext Context, char** reply, int * size);
   TStatus = function(Context:pDLLContext; var reply:pchar; var size:integer):integer; stdcall;

Function Attributes

This function should return 0 for success, or a windows 32 API error code to indicate a failure.

FreeMem

  __declspec(dllexport) int freemem (pDLLContext Context, void* mem, int size);
  Tfreemem = function(Context:pDLLContext; mem:pointer; size:integer):integer;stdcall;

This function is used to return to the DLL memory, allocated by the DLL, and is now to be returned.

Function Attributes

This function should return zero for success, or a windows 32 API error code to indicate a failure.

Close

  __declspec(dllexport) int close(pDLLContext Context);
  TClose = function (Context:pDLLContext):integer;stdcall;

This function is called when the Kernel is planning to stop and unload the DLL. All processing should be halted, and any internal threads stopped.

This function returns zero for success, or a windows 32 API error code, to indicate a failure.


© Kestral Computing P/L 2000-2012. HL7Connect v2.00-054 generated on 13-Nov 2012
Keywords: DLL, Specification, DLL Interfaces / Specifications