Added _GSOCKET_STANDALONE_ symbol

[wxWidgets.git] / include / wx / gsocket.h

diff --git a/include/wx/gsocket.h b/include/wx/gsocket.h
index fce739e20e225f26e237a8863bdc64bffab1cfb3..ecc65f37f636d7f86114a8f57fbae5474b8d1039 100644 (file)
--- a/include/wx/gsocket.h
+++ b/include/wx/gsocket.h
@@ -8,12 +8,15 @@
 #ifndef __GSOCKET_H
 #define __GSOCKET_H
 
 #ifndef __GSOCKET_H
 #define __GSOCKET_H
 

+#include "wx/setup.h"
+
+#if wxUSE_SOCKETS
+
+#include <stddef.h>

 #include <sys/types.h>
 
 #if !defined(__cplusplus)
 #include <sys/types.h>
 
 #if !defined(__cplusplus)

-

 typedef int bool;
 typedef int bool;

-

 #endif
 
 #ifndef TRUE
 #endif
 
 #ifndef TRUE


@@ -24,6 +27,11 @@ typedef int bool;
 #define FALSE 0
 #endif
 
 #define FALSE 0
 #endif
 

+
+#ifdef __cplusplus
+extern "C" {
+#endif
+

 typedef struct _GSocket GSocket;
 typedef struct _GAddress GAddress;
 
 typedef struct _GSocket GSocket;
 typedef struct _GAddress GAddress;
 


@@ -46,7 +54,10 @@ typedef enum {
   GSOCK_INVADDR,
   GSOCK_INVSOCK,
   GSOCK_NOHOST,
   GSOCK_INVADDR,
   GSOCK_INVSOCK,
   GSOCK_NOHOST,

-  GSOCK_INVPORT
+  GSOCK_INVPORT,
+  GSOCK_WOULDBLOCK,
+  GSOCK_TIMEDOUT,
+  GSOCK_MEMERR

 } GSocketError;
 
 typedef enum {
 } GSocketError;
 
 typedef enum {


@@ -61,24 +72,28 @@ enum {
   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,
   GSOCK_INPUT_FLAG = 1 << GSOCK_INPUT,
   GSOCK_OUTPUT_FLAG = 1 << GSOCK_OUTPUT,
   GSOCK_CONNECTION_FLAG = 1 << GSOCK_CONNECTION,

-  GSOCK_LOST_FLAG = 1 << GSOCK_LOST,
+  GSOCK_LOST_FLAG = 1 << GSOCK_LOST

 };
 
 typedef int GSocketEventFlags;
 
 };
 
 typedef int GSocketEventFlags;
 

-typedef void (*GSocketFallback)(GSocket *socket, GSocketEvent event,
-                               char *cdata);
+typedef void (*GSocketCallback)(GSocket *socket, GSocketEvent event,
+                                char *cdata);

 
 

-#ifdef __cplusplus
-extern "C" {
-#endif
+
+/* Global initializers */
+
+/* GSocket_Init() must be called at the beginning */
+bool GSocket_Init();
+/* GSocket_Cleanup() must be called at the ending */
+void GSocket_Cleanup();

 
 /* Constructors / Destructors */
 
 GSocket *GSocket_new();
 void GSocket_destroy(GSocket *socket);
 
 
 /* Constructors / Destructors */
 
 GSocket *GSocket_new();
 void GSocket_destroy(GSocket *socket);
 

-/* This will disable all IO calls to this socket but errors are still available */
+/* This will disable all further IO calls to this socket */

 void GSocket_Shutdown(GSocket *socket);
 
 /* Address handling */
 void GSocket_Shutdown(GSocket *socket);
 
 /* Address handling */


@@ -94,82 +109,107 @@ GSocketError GSocket_SetNonOriented(GSocket *socket);
 
 /* Server specific parts */
 
 
 /* Server specific parts */
 

-/*
-  GSocket_SetServer() setup the socket as a server. It uses the "Local" field
-  of GSocket. "Local" must be set by GSocket_SetLocal() before
-  GSocket_SetServer() is called. In the other case, it returns GSOCK_INVADDR.
-*/
+/* GSocket_SetServer:
+ *  Sets up the socket as a server. It uses the "Local" field of GSocket.
+ *  "Local" must be set by GSocket_SetLocal() before GSocket_SetServer()
+ *  is called. Possible error codes are: GSOCK_INVSOCK if socket has not
+ *  been initialized, GSOCK_INVADDR if the local address has not been
+ *  defined and GSOCK_IOERR for other internal errors.
+ */

 GSocketError GSocket_SetServer(GSocket *socket);
 
 GSocketError GSocket_SetServer(GSocket *socket);
 

-/*
-  GSocket_WaitConnection() waits for an incoming client connection.
-*/
+/* GSocket_WaitConnection:
+ *  Waits for an incoming client connection.
+ */

 GSocket *GSocket_WaitConnection(GSocket *socket);
 
 /* Client specific parts */
 
 GSocket *GSocket_WaitConnection(GSocket *socket);
 
 /* Client specific parts */
 

-/*
-  GSocket_Connect() establishes a client connection to a server using the "Peer"
-  field of GSocket. "Peer" must be set by GSocket_SetPeer() before
-  GSocket_Connect() is called. In the other case, it returns GSOCK_INVADDR.
-*/
+/* GSocket_Connect:
+ *  Establishes a client connection to a server using the "Peer"
+ *  field of GSocket. "Peer" must be set by GSocket_SetPeer() before
+ *  GSocket_Connect() is called. Possible error codes are GSOCK_INVSOCK,
+ *  GSOCK_INVADDR, GSOCK_TIMEDOUT, GSOCK_WOULDBLOCK and GSOCK_IOERR.
+ *  If a socket is nonblocking and Connect() returns GSOCK_WOULDBLOCK,
+ *  the connection request can be completed later. Use GSocket_Select()
+ *  to check it, or wait for a GSOCK_CONNECTION event.
+ */

 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
 
 /* Generic IO */
 
 /* Like recv(), send(), ... */
 GSocketError GSocket_Connect(GSocket *socket, GSocketStream stream);
 
 /* Generic IO */
 
 /* Like recv(), send(), ... */

-/* 
-   NOTE: In case we read from a non-oriented connection, the incoming (outgoing)
-   connection address is stored in the "Local" ("Peer") field. 
-*/
+
+/* NOTE: In case we read from a non-oriented connection, the incoming
+ * (outgoing) connection address is stored in the "Local" ("Peer")
+ * field.
+ */

 int GSocket_Read(GSocket *socket, char *buffer, int size);
 int GSocket_Write(GSocket *socket, const char *buffer,
 int GSocket_Read(GSocket *socket, char *buffer, int size);
 int GSocket_Write(GSocket *socket, const char *buffer,

-                 int size);
-bool GSocket_DataAvailable(GSocket *socket);
+                  int size);
+
+/* GSocket_Select:
+ *  Polls the socket to determine its status. This function will
+ *  check for the events specified in the 'flags' parameter, and
+ *  it will return a mask indicating which operations can be
+ *  performed. This function won't block, regardless of the
+ *  mode (blocking|nonblocking) of the socket.
+ */
+GSocketEventFlags GSocket_Select(GSocket *socket, GSocketEventFlags flags);

 
 

-/* Flags */
+/* Flags/Parameters */

 
 

-/*
-  GSocket_SetBlocking() puts the socket in non-blocking mode. This is useful
-  if we don't want to wait.
-*/
-void GSocket_SetBlocking(GSocket *socket, bool block);
+/* GSocket_SetTimeout:
+ *  Sets the timeout for blocking calls. Time is
+ *  expressed in milliseconds.
+ */
+void GSocket_SetTimeout(GSocket *socket, unsigned long millisec);

 
 

-/*
-  GSocket_GetError() returns the last error occured on the socket stream.
-*/
+/* GSocket_SetNonBlocking:
+ *  Sets the socket to non-blocking mode. This is useful if
+ *  we don't want to wait.
+ */
+void GSocket_SetNonBlocking(GSocket *socket, bool non_block);

 
 

+/* GSocket_GetError:
+ *  Returns the last error occured for this socket.
+ */

 GSocketError GSocket_GetError(GSocket *socket);
 
 /* Callbacks */
 
 GSocketError GSocket_GetError(GSocket *socket);
 
 /* Callbacks */
 

-/* 
-   Only one fallback is possible for each event (INPUT, OUTPUT, CONNECTION, LOST)
-   INPUT: The function is called when there is at least a byte in the 
-          input buffer
-   OUTPUT: The function is called when the system is sure the next write call
-           will not block
-   CONNECTION: Two cases is possible:
-             Client socket -> the connection is established
-            Server socket -> a client request a connection
-   LOST: the connection is lost
-
-   SetFallback accepts a combination of these flags so a same callback can
-   receive different events.
-
-   An event is generated only once and its state is reseted when the relative
-   IO call is requested.
-   For example: INPUT -> GSocket_Read()
-                CONNECTION -> GSocket_Accept()
-*/
-void GSocket_SetFallback(GSocket *socket, GSocketEventFlags event,
-                        GSocketFallback fallback, char *cdata);
-
-/*
-  UnsetFallback will disables all fallbacks specified by "event".
-  NOTE: event may be a combination of flags
-*/
-void GSocket_UnsetFallback(GSocket *socket, GSocketEventFlags event);
+/* Only one callback is possible for each event (INPUT, OUTPUT, CONNECTION
+ * and LOST). The callbacks are called in the following situations:
+ *
+ * INPUT: There is at least one byte in the input buffer
+ * OUTPUT: The system is sure that the next write call will not block
+ * CONNECTION: Two cases are possible:
+ *           Client socket -> the connection is established
+ *           Server socket -> a client requests a connection
+ * LOST: The connection is lost
+ *
+ * An event is generated only once and its state is reseted when the
+ * relative IO call is requested.
+ * For example: INPUT -> GSocket_Read()
+ *              CONNECTION -> GSocket_Accept()
+ */
+
+/* GSocket_SetCallback:
+ *  Enables the callbacks specified by 'flags'. Note that 'flags'
+ *  may be a combination of flags OR'ed toghether, so the same
+ *  callback function can be made to accept different events.
+ *  The callback function must have the following prototype:
+ *
+ *  void function(GSocket *socket, GSocketEvent event, char *cdata)
+ */
+void GSocket_SetCallback(GSocket *socket, GSocketEventFlags flags,
+                         GSocketCallback fallback, char *cdata);
+
+/* GSocket_UnsetCallback:
+ *  Disables all callbacks specified by 'flags', which may be a
+ *  combination of flags OR'ed toghether.
+ */
+void GSocket_UnsetCallback(GSocket *socket, GSocketEventFlags flags);

 
 /* GAddress */
 
 
 /* GAddress */
 


@@ -180,16 +220,16 @@ void GAddress_destroy(GAddress *address);
 void GAddress_SetFamily(GAddress *address, GAddressType type);
 GAddressType GAddress_GetFamily(GAddress *address);
 
 void GAddress_SetFamily(GAddress *address, GAddressType type);
 GAddressType GAddress_GetFamily(GAddress *address);
 

-/* 
-   The use of any of the next functions will set the address family to the adapted
-   one. For example if you use GAddress_INET_SetHostName, address family will be AF_INET
-   implicitely
-*/
+/* The use of any of the next functions will set the address family to
+ * the specific one. For example if you use GAddress_INET_SetHostName,
+ * address family will be implicitly set to AF_INET.
+ */

 
 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
                                           unsigned long hostaddr);
 
 GSocketError GAddress_INET_SetHostName(GAddress *address, const char *hostname);
 GSocketError GAddress_INET_SetHostAddress(GAddress *address,
                                           unsigned long hostaddr);

-GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port);
+GSocketError GAddress_INET_SetPortName(GAddress *address, const char *port,
+                                       const char *protocol);

 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 
 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,
 GSocketError GAddress_INET_SetPort(GAddress *address, unsigned short port);
 
 GSocketError GAddress_INET_GetHostName(GAddress *address, char *hostname,


@@ -202,19 +242,11 @@ unsigned short GAddress_INET_GetPort(GAddress *address);
 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 
 GSocketError GAddress_UNIX_SetPath(GAddress *address, const char *path);
 GSocketError GAddress_UNIX_GetPath(GAddress *address, char *path, size_t sbuf);
 

-/*
- * System specific functions
- */
-
-/* On systems needing an event id */
-void GSocket_SetEventID(GSocket *socket, unsigned long evt_id);
-
-/* On systems which don't have background refresh */
-void GSocket_DoEvent(unsigned long evt_id);
-

 #ifdef __cplusplus
 };
 #ifdef __cplusplus
 };

-#endif
+#endif /* __cplusplus */

 
 

-#endif
- /* __GSOCKET_H */
+
+#endif    /* wxUSE_SOCKETS */
+
+#endif    /* __GSOCKET_H */