agconnect.h

STK的二次开发

/******************************************************************************/
/*****     Copyright 1997-1999, Analytical Graphics, Incorporated.        *****/
/******************************************************************************/

#if defined( CHECK_AGI_CONFIG )
#if !defined( AGI_UTIL_LEVEL )
#define
#endif
#endif

#ifndef AGCONNECT_H
#define AGCONNECT_H 1

#include "AgUtMsgCommon.h"

#if defined(__cplusplus)
extern "C" {
#endif

/******************************************************************************
 * Grouping: AgConnect
 * 
 * GroupDescription: Functions related to the Connect operational interface
 * 
 * Synopsis: #include "AgConnect.h"
 *
 * Introduction: provides a set of functions that allow external applications
 *               to easily open and manage socket connections to STK. 
 ******************************************************************************/

/******************************************************************************
 * Constants:   Socket Type Constants
 *
 * Description: Used to describe the socket type being used.
 *
 * Private:
 ******************************************************************************/

#define AgCUnixType "UNIXSOCKET"
#define AgCTcpType  "TCPSOCKET"

/******************************************************************************
 * Constants:   Connect Constants
 *
 * Description: Generic constants
 *
 * Private:
 ******************************************************************************/

#define AgCMsgVerboseEnvVariable "CON_VERBOSE"

#if !defined (AgCRMHAHdrTypeLen)
#define AgCRMHAHdrTypeLen 15
#endif

#if !defined (AgCRMHAHdrIdLen)
#define AgCRMHAHdrIdLen 6
#endif

/******************************************************************************
 * Constants:   Connect Error Codes
 *
 * Description: Generic error codes 
 *
 * Private:
 ******************************************************************************/

#if !defined (AgCError)

#define AgCError   -1
#define AgCNoError  0

#endif

#define AgCNackReturned    (AgCError - 1)

/******************************************************************************
 * Constants:   Connect Properties Masks
 *
 * Description: Bit masks for setting Connect properties 
 *
 * Private:
 ******************************************************************************/

#define AgCConVerboseOn     0x0001
#define AgCConAckOn         0x0002
#define AgCConErrorOn       0x0004
#define AgCConAsyncOn       0x0008

/******************************************************************************
 * Structure: AgTConReturnInfo
 *                                                                           
 * Description: used to store data returned by Connect commands.  The 'hdrType'
 *              and 'transId' fields are only used for asyncronous data.  They
 *              correspond to the Async Type and Identifier fields for an
 *              asynchronous message as listed on Page 2-9 of the Connect
 *              User's Manual.  'numEntries' is the number of pieces of data
 *              returned by STK, and 'returnList' is an array of strings that
 *              contains the returned data.
 ******************************************************************************/

typedef struct AgTConReturnInfo
{
    char   hdrType[AgCRMHAHdrTypeLen+1];
    char   transId[AgCRMHAHdrIdLen+1];
    int    numEntries;
    char **returnList;
    
}  AgTConReturnInfo;

/******************************************************************************
 * Function: AgConInit
 * 
 * Description: opens the Connect configuration file and reads and processes
 *              the information within. The parameter 'initFileName' is the
 *              name of the file to be used.  If none is supplied a default
 *              set of values will be used.  The file can also be specified
 *              via the AGCONNECTINIT environment variable.
 *
 * Diagnostics: returns AgCNoError on success and AgCError on failure.
 ******************************************************************************/

int
AgConInit ARGS((
    char *initFileName 
));

/******************************************************************************
 * Function: AgConOpenSTK
 * 
 * Description: opens a connection to an STK application and sends the initial 
 *              IPC Control setup.  The parameter 'connectType' specifies Unix 
 *              or TCP/IP socket.  'connectName' is the name of the socket. 
 *
 * Diagnostics: returns AgCNoError on success and AgCError on failure.
 ******************************************************************************/

int
AgConOpenSTK ARGS((
    char **context, 
    char  *connectType, 
    char  *connectName 
));

/******************************************************************************
 * Function: AgConCloseSTK
 * 
 * Description: closes the socket connection specified by the 'context' 
 *              parameter.
 *
 * Diagnostics: returns AgCNoError on success and AgCError on failure.
 ******************************************************************************/
     
int
AgConCloseSTK ARGS((
    char **context 
));

/******************************************************************************
 * Function: AgConProcessSTKCmd
 * 
 * Description: sends an IPC command to the STK application.  Any return data
 *              is stored in 'returnInfo.'  The 'cmdString' is the IPC command
 *              name (such as ALLACCESS).
 *
 * Memory: Inside of returnInfo is an array of strings.  Depending on the
 *         number of messages returned for a given command, that number
 *         of array elements is allocated.  Each array element is then
 *         allocated enough space to hold the returned message.  It is
 *         the responsibility of the user to free this memory.
 *
 * Diagnostics: returns AgCNoError on success, AgCError on failure,
 *              and AgCNackReturned in the event the command was
 *              sent successfully but was rejected by STK.
 ******************************************************************************/

int 
AgConProcessSTKCmd ARGS((
    char             *context, 
    char             *cmdString, 
    AgTConReturnInfo *returnInfo 
));

/******************************************************************************
 * Function: AgConGetAsync
 * 
 * Description: meant to be called when asynchronous data is expected from STK.
 *              This function will listen to STK and return the first
 *              batch of asynchronous data received.  The type and identifier
 *              of the command the data corresponds to can be found in the
 *              returnInfo structure, along with the actual data.  A typical
 *              usage of this function would be to send the AsyncLatLonPick
 *              command with the Once flag to STK, and then call this function
 *              which will wait for the returned pick. As with other socket
 *              reads, the function will wait the timeout period for data
 *              to be returned.  
 *
 * Memory: The returnList portion of the returnInfo must be deallocated as
 *         with AgConProcessSTKCmd().
 *
 * Diagnostics: returns AgCNoError on success and AgCError on failure.
 ******************************************************************************/

int 
AgConGetAsync ARGS((
    char             *context,  
    AgTConReturnInfo *returnInfo 
));

/******************************************************************************
 * Function: AgConSetTimeout
 * 
 * Description: sets the timeout value, in milliseconds, that will be used
 *              for a given connection when Connect is waiting for responses 
 *              from STK.  For instance, a higher timeout value would be useful 
 *              if you plan to send commands to STK that will take a long time 
 *              to process.  A timeout below zero will set the timeout
 *              back to the default specified in the run control file.
 ******************************************************************************/

void 
AgConSetTimeout ARGS((
    char *context,
    int   timeout
));

/******************************************************************************
 * Function: AgConSetProperties
 * 
 * Description: sets the Connect properties verbose, acknowledge, async, and 
 *              error.  Just OR together the bitmasks defined above and
 *              pass the result to this function. 
 ******************************************************************************/

void 
AgConSetProperties ARGS((
    char     *context,
    unsigned  props
));

/******************************************************************************
 * Function: AgConShutdownConnect
 * 
 * Description: frees all the memory associated with Connect in
 *              preparation for application shutdown.  All connections
 *              should be closed prior to calling this function.  If
 *              you wish to resume Connect operations after calling
 *              this function you must first call AgConInit() before
 *              opening any socket connections.
 ******************************************************************************/

void 
AgConShutdownConnect ARGS((
    NO_ARG_LIST
));

#if defined(__cplusplus)
}
#endif

#endif

/******************************************************************************/
/*****     Copyright 1997-1999, Analytical Graphics, Incorporated.        *****/
/******************************************************************************/