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