Biosym/MSI IPC C Language Structures

Background

The following describes the data structures used by the Biosym/MSI IPC Application Program Interfaces. The file ipc.h must be used at the top of a client C language program using #include "ipc.h" in order to define prototypes and structures used by the C API.

IPC Frames

Biosym/MSI IPC data is exchanged using a simple protocol consisting of a header followed by (binary) data. The following define the keywords used in IPC frame headers:



#define BIOSYM_IPC_VERSION      "BiosymIpcVersion"
#define BIOSYM_IPC_MESSAGE      "Message"
#define BIOSYM_IPC_DATATYPE     "DataType"
#define BIOSYM_IPC_NUMITEM      "NumItem"
#define BIOSYM_IPC_NUMELEMENT   "NumElement"
#define BIOSYM_IPC_NUMBYTE      "NumByte"
#define BIOSYM_IPC_END_HEADER   "EndBiosymIpcHeader"

The header keywords have the following meanings:


Keyword             Description
=====================================================================
#                   comment character; ignore line
---------------------------------------------------------------------
BiosymIpcVersion    indicates the version of IPC protocol used
---------------------------------------------------------------------
Message             arbitrary message
                    < BIOSYM_IPC_MESSAGE_MAX bytes, currently 128
---------------------------------------------------------------------
DataType            see table below
---------------------------------------------------------------------
NumItem             # of distinct items, e.g., coordinate triples
---------------------------------------------------------------------
NumElement          # of data per item, e.g. 3 for coordinates
---------------------------------------------------------------------
NumByte             total # of bytes in the subsequent data block
---------------------------------------------------------------------
EndBiosymIpcHeader  binary data begins immediately after the newline
---------------------------------------------------------------------

No ordering is imposed on the header information with the exception that EndBiosymIpcHeader must appear last. Not all header records are needed for a particular IPC frame; the byte count will not appear for non-string data.

The following enumerated type is used to specify the type of data to be exchanged:



typedef enum {
  BiosymIpcType_Integer, /* long */
  BiosymIpcType_Real8, /* double */
  BiosymIpcType_String
} BiosymIpcType;

The following define the keyword strings corresponding to each BiosymIpcType:



#define BIOSYM_IPC_TYPE_INTEGER "integer"
#define BIOSYM_IPC_TYPE_REAL8   "real8"
#define BIOSYM_IPC_TYPE_STRING  "string"

The following define various constants and limits used in the Biosym/MSI IPC code.



#define BIOSYM_IPC_VERSION_CUR "94.0"
#define BIOSYM_IPC_VERSION_LEN 64    /* max length of remove version string */
#define BIOSYM_IPC_MESSAGE_MAX 128   /* max IPC frame message length */
#define BIOSYM_IPC_HEADER_MAX  256   /* max length of any ASCII header line */

The BiosymIpcData structure encapsulates all the information needed to encode an IPC frame to be sent. Conversely, a BiosymIpcData structure is filled when an incoming IPC frame is decoded.



typedef struct {
  char message[BIOSYM_IPC_MESSAGE_MAX];
  BiosymIpcType type;   /* Data type for this entry */
  long numItem;	        /* # of items for this entry */
  long numElement;      /* # of data elements per item (e.g., 3 for coordinates) */
  long numByte;         /* # of bytes total in data block (only needed for strings) */
  union {               /* Pointer to the actual data */
    void *data;
    long *integer;
    double *real8;
    char **string;
  } data;
} BiosymIpcData;

Main access page

Advanced-Use access.

IPC Main Page C Application Program Interface FORTRAN Application Program Interface