home *** CD-ROM | disk | FTP | other *** search
/ CICA 1994 September / CICA_Shareware_for_Windows_Walnut_Creek_September_1994.iso / win3 / demo / gcp_24.exe / GCP.H_ / GCP.H
C/C++ Source or Header  |  1994-04-07  |  15KB  |  370 lines
  1. /*
  2.  *  Dart Communications
  3.  *  1 April 94 for rel 2.4.2
  4.  */     
  5.  
  6. /*  NOTES for rel 2.4.2...important if you are upgrading from an older version
  7.  
  8. Dart Communications continues to refine this interface definition, GCP.H, to provide
  9. the most explicit and simple interface as possible.  We regret if any of these
  10. changes cause problems as you upgrade to this version, but out technical support
  11. staff stands ready to answer any questions you may have.
  12.  
  13. The following summarizes this upgrade from version 2.3 to 2.4.2
  14.  
  15. 1. The HAGENT type has been replaced with the HGCP_SESSION type.  This change makes
  16.     GCP more standard with other other interface definitions (such as Win SNMP).
  17.     Just replace HAGENT with HGCP_SESSION.
  18.     
  19. 2. The GCP_ERROR codes have dropped the "E" out of the name and some have been
  20.     modified or added.
  21.     
  22. 3. GCP_CLOSE and GCP_ABORT commands have been separated out as a new function,
  23.     GCPclose().  This makes GCPclose() the reciprocal of GCPopen(), which is more
  24.     standard with other interface definitions.  GCP_CLOSED has replaced GCP_CLOSE,
  25.     to be consistent with GCP_OPENED.
  26.     
  27. 4. GCP_OPEN_PARAMS has been deleted from the interface, and GCPopen() has been
  28.     changed to take these parameters explicitly.
  29.     
  30. 5. There was a little confusion as to how the GCP_MANUALCLOSE, GCP_AUTOCLOSE, and
  31.    GCP_RELEASE commands worked.  We have dropped these from the interface, and 
  32.    now rely on the simple GCP_HIDE and GCP_SHOW messages.  Calling GCP_SHOW always
  33.    shows the GCP server as an icon, and starts the server if it is not running.
  34.    Calling GCP_HIDE hides the server, and terminates its execution if no Sessions
  35.    are active.  Just use GCP_HIDE to ensure you have released the server and
  36.    GCP_SHOW to view it for debugging purposes. 
  37.    
  38. 6. The HGCP_SESSION is no longer a value starting at 1 and increasing for each
  39.     session created.  Consequently there is now no "ownership" problem, where a "bad"
  40.     program could control your session.  Since HGCP_SESSION is now virtually
  41.     random, it has been dropped out of the GCPdispatch() function as a parameter.
  42.     Just don't use it there anymore.
  43.     
  44. 7. In some places (like Params.Buffer.pAddress), the pointer reference has been
  45.     replaced with an array reference (like Params.Buffer.RemoteAddress[24]).
  46.     This change has simplified usage of the interface, and helps cut-down
  47.     on run-time errors (uninitialized pointers).  Just copy your address into
  48.     the array.  The only place pointers are still used are in the 
  49.     Params.Buffer.Ptr element.  This is absolutely necessary, as it may be of
  50.     any size.
  51.     
  52. 8. GCPcommand() has been replaced by GCPdispatch(), a name-only change that provides
  53.    consistency with the "dispatch" concept seen in windows and X-11 systems.
  54.    
  55. 9. Last, and most important, GCP_API.DLL and GCP.EXE are now tagged with version
  56.    numbers, ala GCP242C.DLL and GCP242.EXE.  This mechanism will ensure that
  57.    no conflicts arise when different GCP versions are being used to support
  58.    different applications.
  59.    
  60.    The convention now will be that GCPxxxC.DLL will be frozen at each major revision
  61.    number 'xxx', so that customers will be assured that once they link to GCPxxxC.LIB,
  62.    their app will always look for GCPxxxC.DLL (the 'C' is for client).  There
  63.    will always be a matching GCPxxx.EXE for the DLL.  We do not, however,
  64.    guarantee that over the life of a single xxx version, the interface between
  65.    the DLL and EXE halves will remain the same.  Therefore, you can assume that
  66.    any GCPxxC.DLL / GCPxx.EXE pair (distributed together) will work together, and
  67.    it is also safe to replace any pair with newer minor revisions as long as
  68.    the xxx matches (without re-compiling).  When a major revision occurs (xxx changes
  69.    and the GCP.H file changes), recompilation will be necessary.
  70.    
  71.    Going to all this trouble will ensure that developers X and Y, using different
  72.    version of GCP++, will coexist without difficulties.
  73.   
  74. */   
  75.  
  76.  
  77. #ifndef GCP_H
  78. #define GCP_H
  79.  
  80. /*
  81.  *    This file defines the interface to the GCP Server, GCP.DLL.
  82.  *        Section 1.  Structures and enums.
  83.  *        Section 2.  Function prototypes.
  84.  */
  85.  
  86. /***************************************************************************
  87. ****************************************************************************
  88.                             Section 1.  Structures and enums
  89. ****************************************************************************
  90. ***************************************************************************/
  91.  
  92. /*  error codes returned by API functions or included in GCP_STATUS */
  93. typedef enum {
  94.     GCP_OK=0,                /* OK return */
  95.     GCP_UNKNOWN=600,        /* An error of unknown origin has occurred */
  96.     GCP_NOWINSOCK,            /* WINSOCK.DLL not located on system */
  97.     GCP_ZEROCNT,            /* buffer of zero count has been presented */
  98.     GCP_RESERVED3,            /* reserved */
  99.     GCP_RESERVED4,            /* reserved */
  100.     GCP_RESERVED5,            /* reserved */
  101.     GCP_RESERVED6,            /* reserved */
  102.     GCP_RESERVED7,            /* reserved */
  103.     GCP_NOGCPMEM,            /* GCP Server cannot be started due to insufficient memory */
  104.     GCP_RDOS,                /*    There was a DOS error on the remote workstation */
  105.     GCP_DOS,                    /*    There was a DOS error on the local workstation */
  106.     GCP_RNOENT,                /* remote file not found */
  107.     GCP_NOENT,                /* local file not found */
  108.     GCP_NOMEM,                /* Insufficient resources - object not created */
  109.     GCP_NETWORK,            /* Unspecified network error */
  110.     GCP_ALREADYOPEN,        /* Daemon was previously opened on specified socket */
  111.     GCP_BADSESSION,        /* Session handle is not known */
  112.     GCP_BADSESSIONTYPE,    /* Session type not supported */
  113.     GCP_BADCALLBACK,        /* Callback window does not exist */
  114.     GCP_EOF,                    /* end of file reached */
  115.     GCP_BADMSG,             /* Msg Request Not Supported by Function/Session */
  116.     GCP_RCLOSE,                /* Remote party has closed connection or hung up phone */
  117.     GCP_NOGCP,                /* GCP Server is not running and cannot be found */
  118.     GCP_BADNAME,            /* host name given is unknown */
  119.     GCP_BADVERSION,        /* GCP Server and GCP.DLL versions do not match */
  120.     GCP_NOLICENSE,            /* DLL interface is not licensed for distribution */
  121.     GCP_BUSY,                /* GCP Server cannot get processor to clear messages */
  122.     GCP_CONNREFUSED,        /* host reached, but connection refused (not listening?) */
  123.     GCP_ELAST
  124.     }        GCP_ERROR;
  125.  
  126. /* messages to be handled  */
  127. #define GCP_BASE 2000
  128.  
  129. typedef enum
  130.     {
  131.     GCP_OPENED=GCP_BASE,    /* session has been opened successfully or failed with error */
  132.     GCP_CLOSED,            /* session was closed */
  133.     GCP_RESERVED,        /* reserved for later use */
  134.     GCP_SEND,            /* send a buffer or confirms a buffer was sent */
  135.     GCP_RECV,            /* a buffer has been received */
  136.     GCP_PUT_TFTP_FILE,        /* send a file or confirms that a file was sent */
  137.     GCP_GET_TFTP_FILE,        /* get a file or confirms that a file was received */
  138.     GCP_TELNET,            /* for negotiating Telnet host options and commands */
  139.     GCP_SHOW,            /* show the GCP Server as an icon */
  140.     GCP_HIDE,            /* hide the display of the GCP Server (default) */
  141.     GCP_SEND_DATAGRAM,    /* parameters include destination address and port */
  142.     GCP_RECV_DATAGRAM,    /* parameters include source address and port */
  143.     GCP_LAST            /* place-holder */
  144.     }        GCP_COMMAND;
  145.  
  146. DECLARE_HANDLE (HGCP_SESSION);        /* used to reference created Sessions */
  147.  
  148. typedef enum     /* currently supported sessions and daemons */
  149.     {
  150.     UDP_SESSION=GCP_BASE+100,    /* a UDP sessions handles send/recv of datagrams */
  151.     TCP_SESSION,                    /* a TCP session provides buffered streams */
  152.     TCP_DAEMON,                        /* will spawn a TCP_SESSION when connected to */
  153.     TELNET_SESSION,                /* a TELNET session provides buffered streams and option neg */
  154.     TELNET_DAEMON,                    /* will spawn a TELNET_SESSION when connected to */
  155.     TFTP_SESSION,                    /* will send/recv files to/from any TFTP server */
  156.     TFTP_DAEMON                     /* will serve files to/from any TFTP client */
  157.     }             GCP_SESSION_TYPE;
  158.  
  159. /***************************************************************************
  160.  
  161.  this section includes descriptions for the GCPdispatch function parameters
  162.  
  163. ***************************************************************************/
  164.  
  165. /* for convenience, make a define for (const BYTE far *) */
  166. typedef const BYTE far * LPCBYTE;
  167.  
  168. /* following typedef from MSVC */
  169. #ifndef _SIZE_T_DEFINED
  170. typedef unsigned int size_t;
  171. #define _SIZE_T_DEFINED
  172. #endif 
  173.  
  174.  
  175. typedef struct
  176.     {
  177.     LPCBYTE Ptr;        /* pointer to buffer for reading only */
  178.     size_t Cnt;            /* byte count in buffer */
  179.     unsigned long CommandInstance;    /* user data */
  180.     char RemoteAddress[24];        /* remote name or address for UDP sessions only */
  181.     unsigned short RemotePort;    /* remote port for UDP sessions only */
  182.     }        GCP_BUFFER_PARAMS;
  183.  
  184. typedef enum
  185.     {
  186.     NETASCII,
  187.     OCTET } TFTP_MODE;            /* transfer mode for TFTP sessions */
  188.  
  189. typedef struct
  190.     {
  191.     char LocalFileSpec[64];        /* local filespec or name */
  192.     char RemoteFileSpec[64];    /* remote filespec of name */
  193.     unsigned long CommandInstance;    /* user data */
  194.     char RemoteAddress[24];        /* remote address (dot notation or name) for TFTP sessions only */
  195.     TFTP_MODE Mode;
  196.     }        GCP_TFTP_PARAMS;  
  197.     
  198. #define GO_AHEAD_CMD 249
  199. #define WILL_CMD 251
  200. #define WONT_CMD 252
  201. #define DO_CMD 253
  202. #define DONT_CMD 254
  203. #define SB_CMD 250 /* suboption negotiation */
  204.  
  205. typedef struct
  206.     {
  207.     BYTE Cmd;    /* option command WILL_CMD, WONT_CMD, DO_CMD, DONT_CMD */
  208.     BYTE Option;        /* TELNET option to be negotiated */
  209.     BYTE SubOption[256];    /* TELNET suboption string (if applicable) */
  210.     size_t SubOptionCnt; /* length of suboption control sequence */
  211.     }        GCP_TELNET_PARAMS;
  212.  
  213. #define ECHO_OPTION 1    /* the ECHO option is popular */
  214.  
  215. typedef union    /* currently supported request types */
  216.     {
  217.     GCP_BUFFER_PARAMS Buffer;    /* Params for GCP_SEND and GCP_SEND_DATAGRAM */
  218.     GCP_TFTP_PARAMS Tftp;        /* Params for GCP_TFTP_PUT_FILE and GCP_TFTP_GET_FILE */
  219.     GCP_TELNET_PARAMS Telnet;    /* Params for GCP_TFTP */
  220.     }        GCP_COMMAND_PARAMS;
  221.  
  222.  
  223. /***************************************************************************
  224.  
  225.   this section includes descriptions for the GCPquery function parameters
  226.  
  227. ***************************************************************************/
  228.  
  229. typedef enum
  230.     {
  231.     GCP_GET_LOCAL_HOST=GCP_BASE+300,        /* gets local host from the host table */
  232.     GCP_GET_FIRST_HOST,                        /* gets first remote host from the host table */
  233.     GCP_GET_NEXT_HOST,                        /* gets next remote host from the host table */
  234.     GCP_GET_STATUS,                            /* lParam is pointer to session Status structure */
  235.     }        GCP_QUERY;
  236.  
  237. typedef struct /* definition of host structure */
  238.     {
  239.     char                Name[64];                /* official name of host (null terminated) */
  240.     char                   Addr[16];                /* net address in dot notation (null terminated) */
  241.     }            HOST;
  242.  
  243. typedef HOST far * LPHOST;
  244.  
  245. typedef struct /* describes statistics available to user */
  246.     {
  247.     unsigned long    StartTime,        /* seconds since 1 Jan 1970 */
  248.                         StopTime,        /* seconds since 1 Jan 1970 */
  249.                         InCnt,            /* file or buffer bytes transferred in over session */
  250.                         OutCnt,            /* file or buffer bytes transferred out over session */
  251.                         InRate,
  252.                         OutRate;            /* bytes/sec */
  253.     }            GCP_STATISTICS;
  254.  
  255. typedef struct
  256.     {
  257.     HGCP_SESSION hSession;                /* identification of Session */
  258.     GCP_SESSION_TYPE SessionType;        /* identification of Session type */
  259.     unsigned long OpenInstance;        /* instance from GCPopen() */
  260.     GCP_COMMAND_PARAMS Params;            /* parameters specific to GCP_COMMAND received */
  261.    GCP_STATISTICS Stats;                /* statistics structure */
  262.     GCP_ERROR Error;                        /* Error code, if any */
  263.     GCP_COMMAND Reserved;                /* reserved for internal use */
  264.     }            GCP_STATUS;
  265.  
  266. typedef GCP_STATUS far *LPGCP_STATUS;
  267.  
  268. typedef union
  269.     {
  270.     HOST Host;
  271.     GCP_STATUS Status;
  272.     }            GCP_QUERY_RESULTS;
  273.  
  274.  
  275. /***************************************************************************
  276. ****************************************************************************
  277.                             Section 2.  Function prototypes
  278. ****************************************************************************
  279. ***************************************************************************/
  280.  
  281. #ifdef __cplusplus
  282. extern "C"
  283. {
  284. #endif            
  285.  
  286. /*
  287. GCPopen() establishes a Session or Daemon for the client applications
  288.     Success/failure is confirmed via a GCP_OPENED callback message
  289.     An error returned indicates an invalid parameter 
  290. */
  291. GCP_ERROR far pascal _export GCPopen
  292.     (
  293.     GCP_SESSION_TYPE Type,                /* type of Session being used */
  294.     HWND hCallbackWnd,                    /* callback window handle */
  295.     WORD CallbackMsg,                        /* callback window message */
  296.     unsigned long OpenInstance,        /* instance specific data for app */
  297.     const char far *pAddress,            /* address in dot notation or name from host table */
  298.     unsigned short Port                    /* local (passive connect) or remote (active connect) port */
  299.     );
  300.  
  301. /*
  302. GCPdispatch() commands the GCP server to perform an action
  303.     Success/failure is confirmed via a callback message
  304.     An error returned indicates an invalid parameter 
  305. */
  306. GCP_ERROR far pascal _export GCPdispatch
  307.     (
  308.     HGCP_SESSION hSession,                /* identification of Session, if applicable */
  309.     GCP_COMMAND Command,                    /* Command */
  310.     GCP_COMMAND_PARAMS far *pParams    /* parameters specific to Command, if applicable */
  311.     );
  312.     
  313. /*
  314. GCPclose() closes a Session or Daemon, releasing system resources
  315.     Success/failure is confirmed via a GCP_CLOSED callback message
  316.     An error returned indicates an invalid parameter 
  317. */
  318. GCP_ERROR far pascal _export GCPclose
  319.     (
  320.     HGCP_SESSION hSession,                /* identification of Session or Daemon to close */
  321.     BOOL Abort                        /* specify TRUE to immediately release unsent buffers, files */
  322.                                                 /* use FALSE to finish gracefully before closing */
  323.     );
  324.  
  325. /*
  326. GCPquery() queries the GCP server synchronously
  327.     An error returned indicates an invalid parameter
  328.     For TCP_SESSION's, the GCP_GET_STATUS msg causes the server to poll for received data
  329.       and to attempt to send buffered data 
  330. */
  331. GCP_ERROR far pascal _export GCPquery
  332.     (
  333.     HGCP_SESSION hSession,                    /* identification of Session, if applicable */
  334.     GCP_QUERY Msg,                                /* identification of utility function */
  335.     GCP_QUERY_RESULTS far *pResults        /* parameters for the function */
  336.     );
  337.     
  338. /*
  339. GCPalloc() duplicates a GCP_STATUS structure, including large buffers referenced
  340.     An NULL returned indicates an allocation failure
  341.     This is useful upon receipt of a callback message, where the client must save a
  342.       copy of the GCP_STATUS structure for later processing 
  343. */
  344. LPARAM far pascal _export GCPalloc    
  345.     (
  346.     WPARAM Msg,                /* */
  347.     LPARAM pStatus         /* makes copy of GCP_STATUS structure and data */
  348.     );
  349.     
  350. /*
  351. GCPfree() frees the GCP_STATUS struction allocated by GCPalloc()
  352. */
  353. BOOL far pascal _export GCPfree
  354.     (
  355.     LPARAM pStatus
  356.     );
  357.     
  358. /*
  359. GCPferror () provides a textual description of the error for presentation
  360. */
  361. LPSTR far pascal _export GCPperror
  362.     (
  363.     GCP_ERROR Error        /* error code from GCP server */
  364.     ); 
  365.  
  366. #ifdef __cplusplus
  367. }
  368. #endif
  369. #endif
  370.