/* @(#)ex_lpiprim.h	128.1 1/20/93 19:42:39 */
/***************************************************************************
Copyright (C) 1990 Lotus Development Corporation.  All rights reserved.

Name:    lpiprim.h (External Version)
Author:  R. Suitor
Date:    07 Sep 1989

Description:  Contains the LPI CEF definitions, 123r3 version
Dependencies: ltsdefs.h  lpiprim.h

Change History:
----------------------------------------------------------------------------
Date       Ver#  Pgmr  SPR#    Change
----------------------------------------------------------------------------
22-Mar-91  0073  jdm   917086  Completely cleaned up header for external use.

                               Made LpiProto, LpiBindProto, LpiMainProto, and
                               LpiUnbindProto compatible w/non-ANSI compilers.
!
14-Feb-91  0072  spl   none    Added definition for LpiMainProto.

06-Feb-91  0071  jdm   none    Removed LPL-specific support and made changes
                               for non-ANSI C compilers.

09-Jan-91  0070  dbt   none    Cond. removed SetupHandleCall and
                               HandleCall from LpiImport struct for C add-ins.

20-Dec-90  0069  dbt   none    Cond. removed InterpCalls from CONTEXT for
                               C add-ins.

12-Nov-90  0068  sir   121524  Upgrade LpiGetEnumString to work in new
                               interpreter.
 
26-Oct-90  0067  dgr   121198  Change get/set double to use interpreter funcs
                               Note: in C 5.1 performing GetDouble or
                               GetInDouble will result in compiler warning
                               that DS!=SS--which can be ignored.
 
16-Oct-90  0066  dgr   121220  Fix LpiSetRecord to have 5 parameters
 
15-Oct-90  0065  dgr   121218  Fix LpiSetAssignmentMode and LpiSignalCount to
                               work as doc-ed
 
12-Sep-90  0064  rfs   none    Fix conditionals for SetDouble so that NC
                               platform uses interpreter manip. functions
                               Replace 'double' decl. with lfloat8
 
12-Sep-90  0063  mce   none    Add macros LpiSetADTutil and LpiSetOutADTutil
                               to set Utility vector of ADT slot element.
 
02-Aug-90  0062  rfs   none    Killed LpiDupADT, created LpiDuplicate and
                               LpiClearAlias0
 
01-Aug-90  0061  rfs   none    Created LpiDupADT and LpiDupOutADT as copies of
                               Ver 6 SetADT/SetOutADT.  These are to be used
                               in the utilities, particularly the duplicator.
                               SetOutADT is to be used in procedures.
 
17-Jul-90  0060  rfs   none    Fixed GetString definition
 
17-Jul-90  0059  rfs   none    Moved GetString to descriptor manipulation func
 
12-Jul-90  0058  rfs   none    Made compare field in utility vector distinct
                               from assign for compatibility.
 
05-jul-90  0057  dgr   none    Added Reserved4-Reserved6 for future expansion
 
28-Jun-90  0056  sir   none    Added LpiSetAlias and LpiClearAlias macros
 
19-Jun-90  0055  rfs   none    Removed StringConcat.
                               Left SetString/StringCreate taking pointers
                               Made SetStringH/StringHCreate to take lmhdl
                               Made StringType version dependent
                               Removed // comments
 
13-Jun-90  0054  mce           Moved GlobalVersionNumber to LpiHdr.H and
                               redefined LpiSetxxx Macros for both LEAF
                               Interpreter Versions.
 
03-Jun-90  0053  ram           Added typedef's for pointers to functions
                               for all exported interpreter functions.
 
23-May-90  0052  pwg           Change LpiPROC structure member names to match
                               macro references.
 
29-Apr-90  0051  sir           Added support for reference parameters
 
18-Apr-90  0050  mce           Changed LPENUM..._P to LPIENUM..._P.

20-Mar-90  0049  mce           Corrected last updates to manipulators.

15-Mar-90  0039  mce           Added Steve Ross's changes to Manipulator
                               calls. Changed data types of fields
                               RuntimeContext and Reserved1 of GPLATFORM
                               CONTEXT structure to lslong.
 
14-Mar-90  0038  jrc           Changed Description and other comments
 
07-Mar-90  0037  jsm           Correctly typed ClientId in CONTEXT
                               and removed PLPOINTER from same
 
02-Mar-90  0036  mce           Added definitions for LPI_GPLATFORM
                               and re-aligned existing definitions
 
02-Mar-90  0035  jrc           Updated change history area
 
14-Feb-90  0034  rfs           LPI_ENVIRONMENT is now conditional
 
06-feb-90  0033  dgr           Work around for GetInDouble bug
                               Work-around for SetOutDouble bug
 
30-Jan-90  0032  rfs           Put explicit defines in for double indirections
 
16-Jan-90  0031  jrc           LPI and other name changes
 
07-Sep-89  0030  jrc           Release 1.0 Version
***************************************************************************/

#if !defined(LPIPRIM_H)
#define LPIPRIM_H
#define lpiprim_h

#if !defined(LTSSTRCT_H)
#include "ltsstrct.h"     /* definition of environment block */
#endif

/***************************************************************************
 These macros declare and define the add-in module bind function.
***************************************************************************/

#if defined STATIC_CAT
#if L_ANSI_C
#define LpiBindProto(x) lexportf(LpiPrimReturn) x (lptr(CONTEXT), LpiAltExport)
#else /* !L_ANSI_C */
#define LpiBindProto(x) lexportf(LpiPrimReturn) x ()
#endif /* L_ANSI_C */

#define LpiBind(x) lexportf(LpiPrimReturn) x (LpiContext, AltExports) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */               \
   LpiAltExport  AltExports; /* pointer to export vector output */

#else

#if L_ANSI_C
#define LpiBindProto(x) lexportf(LpiPrimReturn) lpibind (lptr(CONTEXT), LpiAltExport)
#else /* !L_ANSI_C */
#define LpiBindProto(x) lexportf(LpiPrimReturn) lpibind ()
#endif /* L_ANSI_C */

#define LpiBind(x) lexportf(LpiPrimReturn) lpibind (LpiContext, AltExports) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */               \
   LpiAltExport  AltExports; /* pointer to export vector output */
#endif /* STATIC_CAT */


/***************************************************************************
 These macros declare and define the add-in module unbind function.
***************************************************************************/

#if defined STATIC_CAT
#if L_ANSI_C
#define LpiUnbindProto(x) lexportf(LpiPrimReturn) x (lptr(CONTEXT))
#else /* !L_ANSI_C */
#define LpiUnbindProto(x) lexportf(LpiPrimReturn) x ()
#endif /* L_ANSI_C */

#define LpiUnbind(x) lexportf(LpiPrimReturn) x (LpiContext) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */

#else

#if L_ANSI_C
#define LpiUnbindProto(x) lexportf(LpiPrimReturn) lpiunbind (lptr(CONTEXT))
#else /* !L_ANSI_C */
#define LpiUnbindProto(x) lexportf(LpiPrimReturn) lpiunbind ()
#endif /* L_ANSI_C */

#define LpiUnbind(x) lexportf(LpiPrimReturn) lpiunbind (LpiContext) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */
#endif /* STATIC_CAT */

/***************************************************************************
 These macros declare and define the add-in module main function.
***************************************************************************/

#if defined STATIC_CAT
#if L_ANSI_C
#define LpiMainProto(x) lexportf(void) x (lptr(CONTEXT))
#else /* !L_ANSI_C */
#define LpiMainProto(x) lexportf(void) x ()
#endif /* L_ANSI_C */

#define LpiMain(x) lexportf(void) x (LpiContext) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */

#else

#if L_ANSI_C
#define LpiMainProto(x) lexportf(void) lpimain (lptr(CONTEXT))
#else /* !L_ANSI_C */
#define LpiMainProto(x) lexportf(void) lpimain ()
#endif /* L_ANSI_C */

#define LpiMain(x) lexportf(void) lpimain (LpiContext) \
   lptr(CONTEXT) LpiContext; /* module global data pointer */
#endif /* STATIC_CAT */

/***************************************************************************
 These macros define the export mechanism for an add-in module's
 C callable interface, if one exists, and are used to develop
 shared add-in library modules.

 Note:  The add-in library module must provide a definition for
 AltExportType for these macros to expand properly.  AltExportType
 defines a struct containing pointers to the module's C callable
 interface functions.
***************************************************************************/

#define LpiAltSetBegin   static AltExportType AltExportVector = {
#define LpiAltSet(x)     x,
#define LpiAltSetEnd     };

#define LpiAltSetCode    *AltExports = &AltExportVector


/***************************************************************************
 These macros define LpiContext (CONTEXT) struct elements for easier access.
***************************************************************************/

#define LpiPImport         (LpiContext->Import)
#define LpiPEnvblk         (LpiContext->Environment)
#define LpiPRuntimeContext (LpiContext->RuntimeContext)


/***************************************************************************
 These macros set and get the handle to an add-in module's private
 dynamically allocated storage, if the add-in allocates any.
***************************************************************************/

#define LpiSetLibData(x)      LpiSetLpiContext(x)
#define LpiGetLibData         LpiLibData

#define LpiSetLpiContext(x)   LpiContext->LibData = (lmhdl(void)) (x)
#define LpiLibData            LpiContext->LibData


/***************************************************************************
 These macros permit add-ins to call the runtime support entry points.
***************************************************************************/

#define LpiDynamicLoad(Name, ProcedureCount)          \
   (*(LpiPImport->DynamicLoad))   (Name,              \
                                   ProcedureCount,    \
                                   LpiPRuntimeContext)

#define LpiDynamicUnload(VectorPtr)                   \
   (*(LpiPImport->DynamicUnload)) (VectorPtr,         \
                                   LpiPRuntimeContext)

#define LpiSetupAltCall(Name, VectorPtr, xLpiContext) \
   (*(LpiPImport->SetupAltCall))  (Name,              \
                                   VectorPtr,         \
                                   xLpiContext,       \
                                   LpiPRuntimeContext)

#define LpiRuntimeInfo()                              \
   (*(LpiPImport->RuntimeInfo))   (LpiPRuntimeContext)


/***************************************************************************
 These macros permit add-ins to suppress compiler warnings about unused
 function input arguments.
***************************************************************************/

#define IgnoreLpiContext LpiContext
#define IgnoreParameters {IgnoreLpiContext;}


/***************************************************************************
 These macros define two standard C callable interface status return codes.
***************************************************************************/

#define LPI_SUCCESS  0
#define LPI_FAILURE -1


/***************************************************************************
 These macros permit add-in functions to return C callable interface status
 return codes, including signals, in a platform independent manner.
***************************************************************************/

#define LpiSucceed   return(LPI_SUCCESS)
#define LpiFail      return(LPI_FAILURE)
#define LpiSignal(x) return(x)


/***************************************************************************
 This section contains internal definitions and structures used by the
 macros in this file and by the 1-2-3 add-in loader.

 Note:  Do not rely on these definitions directly.
***************************************************************************/

typedef lslong  LpiSTATUS;     /* status from interpreter calls */
typedef lsshort LpiPrimReturn; /* status from primitives and runtime */


/* Pointer to routines for calling other primitive code.
   (generic function pointer: cast to call!)
*/
typedef LpiPrimReturn (*Vector) ();


#if L_ANSI_C

typedef struct {
   /* To load any library */
   lexportp(lmhdl(lptr(Vector)), DynamicLoad) (
      lptr(char) Name,
      lsshort    ProcedureCount,
      lslong     RuntimeContext
   );

   /* To unload any library */
   lexportp(LpiSTATUS, DynamicUnload) (
      lmhdl(lptr(Vector)) FunctionVector,
      lslong              RuntimeContext
   );

   /* Prepare to call an add-in module's C callable interface */
   lexportp(LpiSTATUS, SetupAltCall) (
      lptr(char) Name,
      /* these are both actually pointers to pointers */
      lptr(void) FunctionVectorPtr,
      lptr(void) ForeignLpiContext,
      lslong     RuntimeContext
   );

   /* Retrieve runtime state information */
   lexportp(lulong, RuntimeInfo) (
      lslong RuntimeContext
   );
} LpiImport;

#else /* !L_ANSI_C */

typedef struct {
   /* To load any library */
   lexportp(lmhdl(lptr(Vector)), DynamicLoad) ();

   /* To unload any library*/
   lexportp(LpiSTATUS, DynamicUnload) ();

   /* Prepare to call an add-in module's C callable interface */
   lexportp(LpiSTATUS, SetupAltCall) ();

   /* Retrieve runtime state information */
   lexportp(lulong, RuntimeInfo) ();
} LpiImport;

#endif /* L_ANSI_C */


/* LpiContext (CONTEXT) module globals struct definition. */

#if LPI_ENVIRONMENT == LPI_GENERAL

typedef struct PLglobals {
   lsshort                   Version;        /* version of CONTEXT struct */
   lmhdl(void)               LibData;        /* handle to module's private storage */
} CONTEXT;

#else /* LPI_ENVIRONMENT != LPI_GENERAL */

typedef struct PLglobals {
   lsshort                   Version;        /* version of CONTEXT struct */
   lmhdl(void)               LibData;        /* handle to module's private storage */
   lptr(LCONSTANT envblk)    Environment;    /* pointer to environment block */
   lptr(LCONSTANT LpiImport) Import;         /* pointer to runtime service routines */
   lslong                    RuntimeContext; /* runtime state information */
   lptr(void)                Reserved1;
   lptr(void)                Reserved2;
   lptr(void)                Reserved3;
   lptr(void)                Reserved4;
   lptr(void)                Reserved5;
   lptr(void)                Reserved6;
   lptr(void)                InterpContext;
} CONTEXT;

#endif /* LPI_ENVIRONMENT == LPI_GENERAL */


/* Bind function input type: address of pointer variable for bind function
   to initialize with a pointer to the module's C callable interface struct.
*/

typedef lptr(lptr(void)) LpiAltExport;

#endif /* !defined(LPIPRIM_H) */
