home *** CD-ROM | disk | FTP | other *** search
/ CICA 1994 September / CICA_Shareware_for_Windows_Walnut_Creek_September_1994.iso / win3 / winsock / gcp_24.exe / GCP.H_ / GCP.H
C/C++ Source or Header  |  1994-04-02  |  14KB  |  351 lines
  1. /*
  2.  *  Dart Communications
  3.  *  26 Mar 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. */   
  56.  
  57.  
  58. #ifndef GCP_H
  59. #define GCP_H
  60.  
  61. /*
  62.  *    This file defines the interface to the GCP Server, GCP.DLL.
  63.  *        Section 1.  Structures and enums.
  64.  *        Section 2.  Function prototypes.
  65.  */
  66.  
  67. /***************************************************************************
  68. ****************************************************************************
  69.                             Section 1.  Structures and enums
  70. ****************************************************************************
  71. ***************************************************************************/
  72.  
  73. /*  error codes returned by API functions or included in GCP_STATUS */
  74. typedef enum {
  75.     GCP_OK=0,                /* OK return */
  76.     GCP_UNKNOWN=600,        /* An error of unknown origin has occurred */
  77.     GCP_RESERVED1,            /* reserved */
  78.     GCP_ZEROCNT,            /* buffer of zero count has been presented */
  79.     GCP_RESERVED3,            /* reserved */
  80.     GCP_RESERVED4,            /* reserved */
  81.     GCP_RESERVED5,            /* reserved */
  82.     GCP_RESERVED6,            /* reserved */
  83.     GCP_RESERVED7,            /* reserved */
  84.     GCP_NOGCPMEM,            /* GCP Server cannot be started due to insufficient memory */
  85.     GCP_RDOS,                /*    There was a DOS error on the remote workstation */
  86.     GCP_DOS,                    /*    There was a DOS error on the local workstation */
  87.     GCP_RNOENT,                /* remote file not found */
  88.     GCP_NOENT,                /* local file not found */
  89.     GCP_NOMEM,                /* Insufficient resources - object not created */
  90.     GCP_NETWORK,            /* Unspecified network error */
  91.     GCP_ALREADYOPEN,        /* Daemon was previously opened on specified socket */
  92.     GCP_BADSESSION,        /* Session handle is not known */
  93.     GCP_BADSESSIONTYPE,    /* Session type not supported */
  94.     GCP_BADCALLBACK,        /* Callback window does not exist */
  95.     GCP_EOF,                    /* end of file reached */
  96.     GCP_BADMSG,             /* Msg Request Not Supported by Function/Session */
  97.     GCP_RCLOSE,                /* Remote party has closed connection or hung up phone */
  98.     GCP_NOGCP,                /* GCP Server is not running and cannot be found */
  99.     GCP_BADNAME,            /* host name given is unknown */
  100.     GCP_BADVERSION,        /* GCP Server and GCP.DLL versions do not match */
  101.     GCP_NOLICENSE,            /* DLL interface is not licensed for distribution */
  102.     GCP_BUSY,                /* GCP Server cannot get processor to clear messages */
  103.     GCP_CONNREFUSED,        /* host reached, but connection refused (not listening?) */
  104.     GCP_ELAST
  105.     }        GCP_ERROR;
  106.  
  107. /* messages to be handled  */
  108. #define GCP_BASE 2000
  109.  
  110. typedef enum
  111.     {
  112.     GCP_OPENED=GCP_BASE,    /* session has been opened successfully or failed with error */
  113.     GCP_CLOSED,            /* session was closed */
  114.     GCP_RESERVED,        /* reserved for later use */
  115.     GCP_SEND,            /* send a buffer or confirms a buffer was sent */
  116.     GCP_RECV,            /* a buffer has been received */
  117.     GCP_PUT_TFTP_FILE,        /* send a file or confirms that a file was sent */
  118.     GCP_GET_TFTP_FILE,        /* get a file or confirms that a file was received */
  119.     GCP_TELNET,            /* for negotiating Telnet host options and commands */
  120.     GCP_SHOW,            /* show the GCP Server as an icon */
  121.     GCP_HIDE,            /* hide the display of the GCP Server (default) */
  122.     GCP_SEND_DATAGRAM,    /* parameters include destination address and port */
  123.     GCP_RECV_DATAGRAM,    /* parameters include source address and port */
  124.     GCP_LAST            /* place-holder */
  125.     }        GCP_COMMAND;
  126.  
  127. DECLARE_HANDLE (HGCP_SESSION);        /* used to reference created Sessions */
  128.  
  129. typedef enum     /* currently supported sessions and daemons */
  130.     {
  131.     UDP_SESSION=GCP_BASE+100,    /* a UDP sessions handles send/recv of datagrams */
  132.     TCP_SESSION,                    /* a TCP session provides buffered streams */
  133.     TCP_DAEMON,                        /* will spawn a TCP_SESSION when connected to */
  134.     TELNET_SESSION,                /* a TELNET session provides buffered streams and option neg */
  135.     TELNET_DAEMON,                    /* will spawn a TELNET_SESSION when connected to */
  136.     TFTP_SESSION,                    /* will send/recv files to/from any TFTP server */
  137.     TFTP_DAEMON                     /* will serve files to/from any TFTP client */
  138.     }             GCP_SESSION_TYPE;
  139.  
  140. /***************************************************************************
  141.  
  142.  this section includes descriptions for the GCPdispatch function parameters
  143.  
  144. ***************************************************************************/
  145.  
  146. /* for convenience, make a define for (const BYTE far *) */
  147. typedef const BYTE far * LPCBYTE;
  148.  
  149. /* following typedef from MSVC */
  150. #ifndef _SIZE_T_DEFINED
  151. typedef unsigned int size_t;
  152. #define _SIZE_T_DEFINED
  153. #endif 
  154.  
  155.  
  156. typedef struct
  157.     {
  158.     LPCBYTE Ptr;        /* pointer to buffer for reading only */
  159.     size_t Cnt;            /* byte count in buffer */
  160.     unsigned long CommandInstance;    /* user data */
  161.     char RemoteAddress[24];        /* remote name or address for UDP sessions only */
  162.     unsigned short RemotePort;    /* remote port for UDP sessions only */
  163.     }        GCP_BUFFER_PARAMS;
  164.  
  165. typedef enum
  166.     {
  167.     NETASCII,
  168.     OCTET } TFTP_MODE;            /* transfer mode for TFTP sessions */
  169.  
  170. typedef struct
  171.     {
  172.     char LocalFileSpec[64];        /* local filespec or name */
  173.     char RemoteFileSpec[64];    /* remote filespec of name */
  174.     unsigned long CommandInstance;    /* user data */
  175.     char RemoteAddress[24];        /* remote address (dot notation or name) for TFTP sessions only */
  176.     TFTP_MODE Mode;
  177.     }        GCP_TFTP_PARAMS;  
  178.     
  179. #define GO_AHEAD_CMD 249
  180. #define WILL_CMD 251
  181. #define WONT_CMD 252
  182. #define DO_CMD 253
  183. #define DONT_CMD 254
  184. #define SB_CMD 250 /* suboption negotiation */
  185.  
  186. typedef struct
  187.     {
  188.     BYTE Cmd;    /* option command WILL_CMD, WONT_CMD, DO_CMD, DONT_CMD */
  189.     BYTE Option;        /* TELNET option to be negotiated */
  190.     BYTE SubOption[256];    /* TELNET suboption string (if applicable) */
  191.     size_t SubOptionCnt; /* length of suboption control sequence */
  192.     }        GCP_TELNET_PARAMS;
  193.  
  194. #define ECHO_OPTION 1    /* the ECHO option is popular */
  195.  
  196. typedef union    /* currently supported request types */
  197.     {
  198.     GCP_BUFFER_PARAMS Buffer;    /* Params for GCP_SEND and GCP_SEND_DATAGRAM */
  199.     GCP_TFTP_PARAMS Tftp;        /* Params for GCP_TFTP_PUT_FILE and GCP_TFTP_GET_FILE */
  200.     GCP_TELNET_PARAMS Telnet;    /* Params for GCP_TFTP */
  201.     }        GCP_COMMAND_PARAMS;
  202.  
  203.  
  204. /***************************************************************************
  205.  
  206.   this section includes descriptions for the GCPquery function parameters
  207.  
  208. ***************************************************************************/
  209.  
  210. typedef enum
  211.     {
  212.     GCP_GET_LOCAL_HOST=GCP_BASE+300,        /* gets local host from the host table */
  213.     GCP_GET_FIRST_HOST,                        /* gets first remote host from the host table */
  214.     GCP_GET_NEXT_HOST,                        /* gets next remote host from the host table */
  215.     GCP_GET_STATUS,                            /* lParam is pointer to session Status structure */
  216.     }        GCP_QUERY;
  217.  
  218. typedef struct /* definition of host structure */
  219.     {
  220.     char                Name[64];                /* official name of host (null terminated) */
  221.     char                   Addr[16];                /* net address in dot notation (null terminated) */
  222.     }            HOST;
  223.  
  224. typedef HOST far * LPHOST;
  225.  
  226. typedef struct /* describes statistics available to user */
  227.     {
  228.     unsigned long    StartTime,        /* seconds since 1 Jan 1970 */
  229.                         StopTime,        /* seconds since 1 Jan 1970 */
  230.                         InCnt,            /* file or buffer bytes transferred in over session */
  231.                         OutCnt,            /* file or buffer bytes transferred out over session */
  232.                         InRate,
  233.                         OutRate;            /* bytes/sec */
  234.     }            GCP_STATISTICS;
  235.  
  236. typedef struct
  237.     {
  238.     HGCP_SESSION hSession;                /* identification of Session */
  239.     GCP_SESSION_TYPE SessionType;        /* identification of Session type */
  240.     unsigned long OpenInstance;        /* instance from GCPopen() */
  241.     GCP_COMMAND_PARAMS Params;            /* parameters specific to GCP_COMMAND received */
  242.    GCP_STATISTICS Stats;                /* statistics structure */
  243.     GCP_ERROR Error;                        /* Error code, if any */
  244.     GCP_COMMAND Reserved;                /* reserved for internal use */
  245.     }            GCP_STATUS;
  246.  
  247. typedef GCP_STATUS far *LPGCP_STATUS;
  248.  
  249. typedef union
  250.     {
  251.     HOST Host;
  252.     GCP_STATUS Status;
  253.     }            GCP_QUERY_RESULTS;
  254.  
  255.  
  256. /***************************************************************************
  257. ****************************************************************************
  258.                             Section 2.  Function prototypes
  259. ****************************************************************************
  260. ***************************************************************************/
  261.  
  262. #ifdef __cplusplus
  263. extern "C"
  264. {
  265. #endif            
  266.  
  267. /*
  268. GCPopen() establishes a Session or Daemon for the client applications
  269.     Success/failure is confirmed via a GCP_OPENED callback message
  270.     An error returned indicates an invalid parameter 
  271. */
  272. GCP_ERROR far pascal _export GCPopen
  273.     (
  274.     GCP_SESSION_TYPE Type,                /* type of Session being used */
  275.     HWND hCallbackWnd,                    /* callback window handle */
  276.     WORD CallbackMsg,                        /* callback window message */
  277.     unsigned long OpenInstance,        /* instance specific data for app */
  278.     const char far *pAddress,            /* address in dot notation or name from host table */
  279.     unsigned short Port                    /* local (passive connect) or remote (active connect) port */
  280.     );
  281.  
  282. /*
  283. GCPdispatch() commands the GCP server to perform an action
  284.     Success/failure is confirmed via a callback message
  285.     An error returned indicates an invalid parameter 
  286. */
  287. GCP_ERROR far pascal _export GCPdispatch
  288.     (
  289.     HGCP_SESSION hSession,                /* identification of Session, if applicable */
  290.     GCP_COMMAND Command,                    /* Command */
  291.     GCP_COMMAND_PARAMS far *pParams    /* parameters specific to Command, if applicable */
  292.     );
  293.     
  294. /*
  295. GCPclose() closes a Session or Daemon, releasing system resources
  296.     Success/failure is confirmed via a GCP_CLOSED callback message
  297.     An error returned indicates an invalid parameter 
  298. */
  299. GCP_ERROR far pascal _export GCPclose
  300.     (
  301.     HGCP_SESSION hSession,                /* identification of Session or Daemon to close */
  302.     BOOL Abort                        /* specify TRUE to immediately release unsent buffers, files */
  303.                                                 /* use FALSE to finish gracefully before closing */
  304.     );
  305.  
  306. /*
  307. GCPquery() queries the GCP server synchronously
  308.     An error returned indicates an invalid parameter
  309.     For TCP_SESSION's, the GCP_GET_STATUS msg causes the server to poll for received data
  310.       and to attempt to send buffered data 
  311. */
  312. GCP_ERROR far pascal _export GCPquery
  313.     (
  314.     HGCP_SESSION hSession,                    /* identification of Session, if applicable */
  315.     GCP_QUERY Msg,                                /* identification of utility function */
  316.     GCP_QUERY_RESULTS far *pResults        /* parameters for the function */
  317.     );
  318.     
  319. /*
  320. GCPalloc() duplicates a GCP_STATUS structure, including large buffers referenced
  321.     An NULL returned indicates an allocation failure
  322.     This is useful upon receipt of a callback message, where the client must save a
  323.       copy of the GCP_STATUS structure for later processing 
  324. */
  325. LPARAM far pascal _export GCPalloc    
  326.     (
  327.     WPARAM Msg,                /* */
  328.     LPARAM pStatus         /* makes copy of GCP_STATUS structure and data */
  329.     );
  330.     
  331. /*
  332. GCPfree() frees the GCP_STATUS struction allocated by GCPalloc()
  333. */
  334. BOOL far pascal _export GCPfree
  335.     (
  336.     LPARAM pStatus
  337.     );
  338.     
  339. /*
  340. GCPferror () provides a textual description of the error for presentation
  341. */
  342. LPSTR far pascal _export GCPperror
  343.     (
  344.     GCP_ERROR Error        /* error code from GCP server */
  345.     ); 
  346.  
  347. #ifdef __cplusplus
  348. }
  349. #endif
  350. #endif
  351.