home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / gsocket.h < prev    next >
C/C++ Source or Header  |  2002-09-12  |  11KB  |  333 lines
  1. /* -------------------------------------------------------------------------
  2.  * Project: GSocket (Generic Socket)
  3.  * Name:    gsocket.h
  4.  * Author:  Guilhem Lavaux
  5.  *          Guillermo Rodriguez Garcia <guille@iies.es> (maintainer)
  6.  * Purpose: GSocket include file (system independent)
  7.  * CVSID:   $Id: gsocket.h,v 1.26 2002/09/12 13:48:55 VZ Exp $
  8.  * -------------------------------------------------------------------------
  9.  */
  10.  
  11. #ifndef __GSOCKET_H
  12. #define __GSOCKET_H
  13.  
  14. #ifndef __GSOCKET_STANDALONE__
  15. #include "wx/setup.h"
  16.  
  17. /* kludge for GTK..  gsockgtk.c craps out miserably if we include
  18.    defs.h ...  no idea how other files get away with it.. */
  19.  
  20. #if !defined( __WXMSW__ ) && !defined(  WXDLLEXPORT )
  21. #define WXDLLEXPORT
  22. #endif
  23.  
  24. #endif
  25.  
  26. #if wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__)
  27.  
  28. #include <stddef.h>
  29.  
  30. /*
  31.    Including sys/types.h under cygwin results in the warnings about "fd_set
  32.    having been defined in sys/types.h" when winsock.h is included later and
  33.    doesn't seem to be necessary anyhow. It's not needed under Mac neither.
  34.  */
  35. #if !defined(__WXMAC__) && !defined(__CYGWIN__)
  36. #include <sys/types.h>
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. typedef struct _GSocket GSocket;
  44. typedef struct _GAddress GAddress;
  45.  
  46. typedef enum {
  47.   GSOCK_NOFAMILY = 0,
  48.   GSOCK_INET,
  49.   GSOCK_INET6,
  50.   GSOCK_UNIX
  51. } GAddressType;
  52.  
  53. typedef enum {
  54.   GSOCK_STREAMED,
  55.   GSOCK_UNSTREAMED
  56. } GSocketStream;
  57.  
  58. typedef enum {
  59.   GSOCK_NOERROR = 0,
  60.   GSOCK_INVOP,
  61.   GSOCK_IOERR,
  62.   GSOCK_INVADDR,
  63.   GSOCK_INVSOCK,
  64.   GSOCK_NOHOST,
  65.   GSOCK_INVPORT,
  66.   GSOCK_WOULDBLOCK,
  67.   GSOCK_TIMEDOUT,
  68.   GSOCK_MEMERR
  69. } GSocketError;
  70.  
  71. /* See below for an explanation on how events work.
  72.  */
  73. typedef enum {
  74.   GSOCK_INPUT  = 0,
  75.   GSOCK_OUTPUT = 1,
  76.   GSOCK_CONNECTION = 2,
  77.   GSOCK_LOST = 3,
  78.   GSOCK_MAX_EVENT = 4
  79. } GSocketEvent;
  80.  
  81. enum {
  82.   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
  83.   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
  84.   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
  85.   GSOCK_LOST_FLAG = 1 << GSOCK_LOST
  86. };
  87.  
  88. typedef int GSocketEventFlags;
  89.  
  90. typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
  91.                                 char *cdata);
  92.  
  93.  
  94. /* Global initializers */
  95.  
  96. /* GSocket_Init() must be called at the beginning */
  97. int GSocket_Init(void);
  98.  
  99. /* GSocket_Cleanup() must be called at the end */
  100. void GSocket_Cleanup(void);
  101.  
  102.  
  103. /* Constructors / Destructors */
  104.  
  105. GSocket *GSocket_new(void);
  106. void GSocket_destroy(GSocket *socket);
  107.  
  108.  
  109.  
  110. /* GSocket_Shutdown:
  111.  *  Disallow further read/write operations on this socket, close
  112.  *  the fd and disable all callbacks.
  113.  */
  114. void GSocket_Shutdown(GSocket *socket);
  115.  
  116. /* Address handling */
  117.  
  118. /* GSocket_SetLocal:
  119.  * GSocket_GetLocal:
  120.  * GSocket_SetPeer:
  121.  * GSocket_GetPeer:
  122.  *  Set or get the local or peer address for this socket. The 'set'
  123.  *  functions return GSOCK_NOERROR on success, an error code otherwise.
  124.  *  The 'get' functions return a pointer to a GAddress object on success,
  125.  *  or NULL otherwise, in which case they set the error code of the
  126.  *  corresponding GSocket.
  127.  *
  128.  *  Error codes:
  129.  *    GSOCK_INVSOCK - the socket is not valid.
  130.  *    GSOCK_INVADDR - the address is not valid.
  131.  */
  132. GSocketError GSocket_SetLocal(GSocket *socket, GAddress *address);
  133. GSocketError GSocket_SetPeer(GSocket *socket, GAddress *address);
  134. GAddress *GSocket_GetLocal(GSocket *socket);
  135. GAddress *GSocket_GetPeer(GSocket *socket);
  136.  
  137. /* Server specific parts */
  138.  
  139. /* GSocket_SetServer:
  140.  *  Sets up this socket as a server. The local address must have been
  141.  *  set with GSocket_SetLocal() before GSocket_SetServer() is called.
  142.  *  Returns GSOCK_NOERROR on success, one of the following otherwise:
  143.  *
  144.  *  Error codes:
  145.  *    GSOCK_INVSOCK - the socket is in use.
  146.  *    GSOCK_INVADDR - the local address has not been set.
  147.  *    GSOCK_IOERR   - low-level error.
  148.  */
  149. GSocketError GSocket_SetServer(GSocket *socket);
  150.  
  151. /* GSocket_WaitConnection:
  152.  *  Waits for an incoming client connection. Returns a pointer to
  153.  *  a GSocket object, or NULL if there was an error, in which case
  154.  *  the last error field will be updated for the calling GSocket.
  155.  *
  156.  *  Error codes (set in the calling GSocket)
  157.  *    GSOCK_INVSOCK    - the socket is not valid or not a server.
  158.  *    GSOCK_TIMEDOUT   - timeout, no incoming connections.
  159.  *    GSOCK_WOULDBLOCK - the call would block and the socket is nonblocking.
  160.  *    GSOCK_MEMERR     - couldn't allocate memory.
  161.  *    GSOCK_IOERR      - low-level error.
  162.  */
  163. GSocket *GSocket_WaitConnection(GSocket *socket);
  164.  
  165.  
  166. /* Client specific parts */
  167.  
  168. /* GSocket_Connect:
  169.  *  For stream (connection oriented) sockets, GSocket_Connect() tries
  170.  *  to establish a client connection to a server using the peer address
  171.  *  as established with GSocket_SetPeer(). Returns GSOCK_NOERROR if the
  172.  *  connection has been succesfully established, or one of the error
  173.  *  codes listed below. Note that for nonblocking sockets, a return
  174.  *  value of GSOCK_WOULDBLOCK doesn't mean a failure. The connection
  175.  *  request can be completed later; you should use GSocket_Select()
  176.  *  to poll for GSOCK_CONNECTION | GSOCK_LOST, or wait for the
  177.  *  corresponding asynchronous events.
  178.  *
  179.  *  For datagram (non connection oriented) sockets, GSocket_Connect()
  180.  *  just sets the peer address established with GSocket_SetPeer() as
  181.  *  default destination.
  182.  *
  183.  *  Error codes:
  184.  *    GSOCK_INVSOCK    - the socket is in use or not valid.
  185.  *    GSOCK_INVADDR    - the peer address has not been established.
  186.  *    GSOCK_TIMEDOUT   - timeout, the connection failed.
  187.  *    GSOCK_WOULDBLOCK - connection in progress (nonblocking sockets only)
  188.  *    GSOCK_MEMERR     - couldn't allocate memory.
  189.  *    GSOCK_IOERR      - low-level error.
  190.  */
  191. GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
  192.  
  193.  
  194. /* Datagram sockets */
  195.  
  196. /* GSocket_SetNonOriented:
  197.  *  Sets up this socket as a non-connection oriented (datagram) socket.
  198.  *  Before using this function, the local address must have been set
  199.  *  with GSocket_SetLocal(), or the call will fail. Returns GSOCK_NOERROR
  200.  *  on success, or one of the following otherwise.
  201.  *
  202.  *  Error codes:
  203.  *    GSOCK_INVSOCK - the socket is in use.
  204.  *    GSOCK_INVADDR - the local address has not been set.
  205.  *    GSOCK_IOERR   - low-level error.
  206.  */
  207. GSocketError GSocket_SetNonOriented(GSocket *socket);
  208.  
  209.  
  210. /* Generic IO */
  211.  
  212. /* Like recv(), send(), ... */
  213.  
  214. /* For datagram sockets, the incoming / outgoing addresses
  215.  * are stored as / read from the 'peer' address field.
  216.  */
  217. int GSocket_Read(GSocket *socket, char *buffer, int size);
  218. int GSocket_Write(GSocket *socket, const char *buffer,
  219.                   int size);
  220.  
  221. /* GSocket_Select:
  222.  *  Polls the socket to determine its status. This function will
  223.  *  check for the events specified in the 'flags' parameter, and
  224.  *  it will return a mask indicating which operations can be
  225.  *  performed. This function won't block, regardless of the
  226.  *  mode (blocking | nonblocking) of the socket.
  227.  */
  228. GSocketEventFlags GSocket_Select(GSocket *socket, GSocketEventFlags flags);
  229.  
  230.  
  231. /* Attributes */
  232.  
  233. /* GSocket_SetNonBlocking:
  234.  *  Sets the socket to non-blocking mode. All IO calls will return
  235.  *  immediately.
  236.  */
  237. void GSocket_SetNonBlocking(GSocket *socket, int non_block);
  238.  
  239. /* GSocket_SetTimeout:
  240.  *  Sets the timeout for blocking calls. Time is expressed in
  241.  *  milliseconds.
  242.  */
  243. void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);
  244.  
  245. /* GSocket_GetError:
  246.  *  Returns the last error occured for this socket. Note that successful
  247.  *  operations do not clear this back to GSOCK_NOERROR, so use it only
  248.  *  after an error.
  249.  */
  250. GSocketError WXDLLEXPORT GSocket_GetError(GSocket *socket);
  251.  
  252.  
  253. /* Callbacks */
  254.  
  255. /* GSOCK_INPUT:
  256.  *   There is data to be read in the input buffer. If, after a read
  257.  *   operation, there is still data available, the callback function will
  258.  *   be called again.
  259.  * GSOCK_OUTPUT:
  260.  *   The socket is available for writing. That is, the next write call
  261.  *   won't block. This event is generated only once, when the connection is
  262.  *   first established, and then only if a call failed with GSOCK_WOULDBLOCK,
  263.  *   when the output buffer empties again. This means that the app should
  264.  *   assume that it can write since the first OUTPUT event, and no more
  265.  *   OUTPUT events will be generated unless an error occurs.
  266.  * GSOCK_CONNECTION:
  267.  *   Connection succesfully established, for client sockets, or incoming
  268.  *   client connection, for server sockets. Wait for this event (also watch
  269.  *   out for GSOCK_LOST) after you issue a nonblocking GSocket_Connect() call.
  270.  * GSOCK_LOST:
  271.  *   The connection is lost (or a connection request failed); this could
  272.  *   be due to a failure, or due to the peer closing it gracefully.
  273.  */
  274.  
  275. /* GSocket_SetCallback:
  276.  *  Enables the callbacks specified by 'flags'. Note that 'flags'
  277.  *  may be a combination of flags OR'ed toghether, so the same
  278.  *  callback function can be made to accept different events.
  279.  *  The callback function must have the following prototype:
  280.  *
  281.  *  void function(GSocket *socket, GSocketEvent event, char *cdata)
  282.  */
  283. void GSocket_SetCallback(GSocket *socket, GSocketEventFlags flags,
  284.                          GSocketCallback fallback, char *cdata);
  285.  
  286. /* GSocket_UnsetCallback:
  287.  *  Disables all callbacks specified by 'flags', which may be a
  288.  *  combination of flags OR'ed toghether.
  289.  */
  290. void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags flags);
  291.  
  292.  
  293. /* GAddress */
  294.  
  295. GAddress *GAddress_new(void);
  296. GAddress *GAddress_copy(GAddress *address);
  297. void GAddress_destroy(GAddress *address);
  298.  
  299. void GAddress_SetFamily(GAddress *address, GAddressType type);
  300. GAddressType GAddress_GetFamily(GAddress *address);
  301.  
  302. /* The use of any of the next functions will set the address family to
  303.  * the specific one. For example if you use GAddress_INET_SetHostName,
  304.  * address family will be implicitly set to AF_INET.
  305.  */
  306.  
  307. GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
  308. GSocketError GAddress_INET_SetAnyAddress(GAddress *address);
  309. GSocketError GAddress_INET_SetHostAddress(GAddress *address,
  310.                                           unsigned long hostaddr);
  311. GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
  312.                                        const char *protocol);
  313. GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
  314.  
  315. GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
  316.                                        size_t sbuf);
  317. unsigned long GAddress_INET_GetHostAddress(GAddress *address);
  318. unsigned short GAddress_INET_GetPort(GAddress *address);
  319.  
  320. /* TODO: Define specific parts (INET6, UNIX) */
  321.  
  322. GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
  323. GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
  324.  
  325. #ifdef __cplusplus
  326. }
  327. #endif /* __cplusplus */
  328.  
  329.  
  330. #endif    /* wxUSE_SOCKETS || defined(__GSOCKET_STANDALONE__) */
  331.  
  332. #endif    /* __GSOCKET_H */
  333.