agent/pseudotcp.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2010 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6
   7  *
   8  * The contents of this file are subject to the Mozilla Public License Version
   9  * 1.1 (the "License"); you may not use this file except in compliance with
  10  * the License. You may obtain a copy of the License at
  11  * http://www.mozilla.org/MPL/
  12  *
  13  * Software distributed under the License is distributed on an "AS IS" basis,
  14  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  15  * for the specific language governing rights and limitations under the
  16  * License.
  17  *
  18  * The Original Code is the Nice GLib ICE library.
  19  *
  20  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  21  * Corporation. All Rights Reserved.
  22  *
  23  * Contributors:
  24  *   Youness Alaoui, Collabora Ltd.
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of the
  27  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  28  * case the provisions of LGPL are applicable instead of those above. If you
  29  * wish to allow use of your version of this file only under the terms of the
  30  * LGPL and not to allow others to use your version of this file under the
  31  * MPL, indicate your decision by deleting the provisions above and replace
  32  * them with the notice and other provisions required by the LGPL. If you do
  33  * not delete the provisions above, a recipient may use your version of this
  34  * file under either the MPL or the LGPL.
  35  */
  36
  37 #ifndef _PSEUDOTCP_H
  38 #define _PSEUDOTCP_H
  39
  40 /**
  41  * SECTION:pseudotcp
  42  * @short_description: Pseudo TCP implementation
  43  * @include: pseudotcp.h
  44  * @stability: Stable
  45  *
  46  * The #PseudoTcpSocket is an object implementing a Pseudo Tcp Socket for use
  47  * over UDP.
  48  * The socket will implement a subset of the TCP stack to allow for a reliable
  49  * transport over non-reliable sockets (such as UDP).
  50  *
  51  * See the file tests/test-pseudotcp.c in the source package for an example
  52  * of how to use the object.
  53  *
  54  * Since: 0.0.11
  55  */
  56
  57
  58
  59 #include <glib-object.h>
  60
  61 #ifdef G_OS_WIN32
  62 #  include <winsock2.h>
  63 #  define ECONNABORTED WSAECONNABORTED
  64 #  define ENOTCONN WSAENOTCONN
  65 #  define EWOULDBLOCK WSAEWOULDBLOCK
  66 #  define ECONNRESET WSAECONNRESET
  67 #endif
  68
  69 G_BEGIN_DECLS
  70
  71 /**
  72  * PseudoTcpSocket:
  73  *
  74  * The #PseudoTcpSocket is the GObject implementing the Pseudo TCP Socket
  75  *
  76  * Since: 0.0.11
  77  */
  78 typedef struct _PseudoTcpSocket PseudoTcpSocket;
  79
  80 typedef struct _PseudoTcpSocketClass PseudoTcpSocketClass;
  81
  82 GType pseudo_tcp_socket_get_type (void);
  83
  84 /* TYPE MACROS */
  85 #define PSEUDO_TCP_SOCKET_TYPE \
  86   (pseudo_tcp_socket_get_type ())
  87 #define PSEUDO_TCP_SOCKET(obj) \
  88   (G_TYPE_CHECK_INSTANCE_CAST((obj), PSEUDO_TCP_SOCKET_TYPE, \
  89                               PseudoTcpSocket))
  90 #define PSEUDO_TCP_SOCKET_CLASS(klass) \
  91   (G_TYPE_CHECK_CLASS_CAST((klass), PSEUDO_TCP_SOCKET_TYPE, \
  92                            PseudoTcpSocketClass))
  93 #define IS_PSEUDO_TCP_SOCKET(obj) \
  94   (G_TYPE_CHECK_INSTANCE_TYPE((obj), PSEUDO_TCP_SOCKET_TYPE))
  95 #define IS_PSEUDO_TCP_SOCKET_CLASS(klass) \
  96   (G_TYPE_CHECK_CLASS_TYPE((klass), PSEUDO_TCP_SOCKET_TYPE))
  97 #define PSEUDOTCP_SOCKET_GET_CLASS(obj) \
  98   (G_TYPE_INSTANCE_GET_CLASS ((obj), PSEUDO_TCP_SOCKET_TYPE, \
  99                               PseudoTcpSocketClass))
 100
 101 struct _PseudoTcpSocketClass {
 102     GObjectClass parent_class;
 103 };
 104
 105 typedef struct _PseudoTcpSocketPrivate PseudoTcpSocketPrivate;
 106
 107 struct _PseudoTcpSocket {
 108     GObject parent;
 109     PseudoTcpSocketPrivate *priv;
 110 };
 111
 112 /**
 113  * PseudoTcpDebugLevel:
 114  * @PSEUDO_TCP_DEBUG_NONE: Disable debug messages
 115  * @PSEUDO_TCP_DEBUG_NORMAL: Enable basic debug messages
 116  * @PSEUDO_TCP_DEBUG_VERBOSE: Enable verbose debug messages
 117  *
 118  * Valid values of debug levels to be set.
 119  *
 120  * Since: 0.0.11
 121  */
 122 typedef enum {
 123   PSEUDO_TCP_DEBUG_NONE = 0,
 124   PSEUDO_TCP_DEBUG_NORMAL,
 125   PSEUDO_TCP_DEBUG_VERBOSE,
 126 } PseudoTcpDebugLevel;
 127
 128 /**
 129  * PseudoTcpState:
 130  * @TCP_LISTEN: The socket's initial state. The socket isn't connected and is
 131  * listening for an incoming connection
 132  * @TCP_SYN_SENT: The socket has sent a connection request (SYN) packet and is
 133  * waiting for an answer
 134  * @TCP_SYN_RECEIVED: The socket has received a connection request (SYN) packet.
 135  * @TCP_ESTABLISHED: The socket is connected
 136  * @TCP_CLOSED: The socket has been closed
 137  *
 138  * An enum representing the state of the #PseudoTcpSocket.
 139  * <para> See also: #PseudoTcpSocket:state </para>
 140  *
 141  * Since: 0.0.11
 142  */
 143 typedef enum {
 144   TCP_LISTEN,
 145   TCP_SYN_SENT,
 146   TCP_SYN_RECEIVED,
 147   TCP_ESTABLISHED,
 148   TCP_CLOSED
 149 } PseudoTcpState;
 150
 151 /**
 152  * PseudoTcpWriteResult:
 153  * @WR_SUCCESS: The write operation was successful
 154  * @WR_TOO_LARGE: The socket type requires that message be sent atomically
 155  * and the size of the message to be sent made this impossible.
 156  * @WR_FAIL: There was an error sending the message
 157  *
 158  * An enum representing the result value of the write operation requested by
 159  * the #PseudoTcpSocket.
 160  * <para> See also: %PseudoTcpCallbacks:WritePacket </para>
 161  *
 162  * Since: 0.0.11
 163  */
 164 typedef enum {
 165   WR_SUCCESS,
 166   WR_TOO_LARGE,
 167   WR_FAIL
 168 } PseudoTcpWriteResult;
 169
 170 /**
 171  * PseudoTcpCallbacks:
 172  * @user_data: A user defined pointer to be passed to the callbacks
 173  * @PseudoTcpOpened: The #PseudoTcpSocket is now connected
 174  * @PseudoTcpReadable: The socket is readable
 175  * @PseudoTcpWritable: The socket is writable
 176  * @PseudoTcpClosed: The socket was closed
 177  * @WritePacket: This callback is called when the socket needs to send data.
 178  *
 179  * A structure containing callbacks functions that will be called by the
 180  * #PseudoTcpSocket when some events happen.
 181  * <para> See also: #PseudoTcpWriteResult </para>
 182  *
 183  * Since: 0.0.11
 184  */
 185 typedef struct {
 186   gpointer user_data;
 187   void  (*PseudoTcpOpened) (PseudoTcpSocket *tcp, gpointer data);
 188   void  (*PseudoTcpReadable) (PseudoTcpSocket *tcp, gpointer data);
 189   void  (*PseudoTcpWritable) (PseudoTcpSocket *tcp, gpointer data);
 190   void  (*PseudoTcpClosed) (PseudoTcpSocket *tcp, guint32 error, gpointer data);
 191   PseudoTcpWriteResult (*WritePacket) (PseudoTcpSocket *tcp,
 192       const gchar * buffer, guint32 len, gpointer data);
 193 } PseudoTcpCallbacks;
 194
 195 /**
 196  * pseudo_tcp_socket_new:
 197  * @conversation: The conversation id for the socket.
 198  * @callbacks: A pointer to the #PseudoTcpCallbacks structure for getting
 199  * notified of the #PseudoTcpSocket events.
 200  *
 201  * Creates a new #PseudoTcpSocket for the specified conversation
 202  *
 203  <note>
 204    <para>
 205      The @callbacks must be non-NULL, in order to get notified of packets the
 206      socket needs to send.
 207    </para>
 208    <para>
 209      If the @callbacks structure was dynamicly allocated, it can be freed
 210      after the call @pseudo_tcp_socket_new
 211    </para>
 212  </note>
 213  *
 214  * Returns: The new #PseudoTcpSocket object, %NULL on error
 215  *
 216  * Since: 0.0.11
 217  */
 218 PseudoTcpSocket *pseudo_tcp_socket_new (guint32 conversation,
 219     PseudoTcpCallbacks *callbacks);
 220
 221
 222 /**
 223  * pseudo_tcp_socket_connect:
 224  * @self: The #PseudoTcpSocket object.
 225  *
 226  * Connects the #PseudoTcpSocket to the peer with the same conversation id.
 227  * The connection will only be successful after the
 228  * %PseudoTcpCallbacks:PseudoTcpOpened callback is called
 229  *
 230  * Returns: %TRUE on success, %FALSE on failure (not in %TCP_LISTEN state)
 231  * <para> See also: pseudo_tcp_socket_get_error() </para>
 232  *
 233  * Since: 0.0.11
 234  */
 235 gboolean pseudo_tcp_socket_connect(PseudoTcpSocket *self);
 236
 237
 238 /**
 239  * pseudo_tcp_socket_recv:
 240  * @self: The #PseudoTcpSocket object.
 241  * @buffer: The buffer to fill with received data
 242  * @len: The length of @buffer
 243  *
 244  * Receive data from the socket.
 245  *
 246  <note>
 247    <para>
 248      Only call this on the %PseudoTcpCallbacks:PseudoTcpReadable callback.
 249    </para>
 250    <para>
 251      This function should be called in a loop. If this function does not
 252      return -1 with EWOULDBLOCK as the error, the
 253      %PseudoTcpCallbacks:PseudoTcpReadable callback will not be called again.
 254    </para>
 255  </note>
 256  *
 257  * Returns: The number of bytes received or -1 in case of error
 258  * <para> See also: pseudo_tcp_socket_get_error() </para>
 259  *
 260  * Since: 0.0.11
 261  */
 262 gint  pseudo_tcp_socket_recv(PseudoTcpSocket *self, char * buffer, size_t len);
 263
 264
 265 /**
 266  * pseudo_tcp_socket_send:
 267  * @self: The #PseudoTcpSocket object.
 268  * @buffer: The buffer with data to send
 269  * @len: The length of @buffer
 270  *
 271  * Send data on the socket.
 272  *
 273  <note>
 274    <para>
 275      If this function return -1 with EWOULDBLOCK as the error, or if the return
 276      value is lower than @len, then the %PseudoTcpCallbacks:PseudoTcpWritable
 277      callback will be called when the socket will become writable.
 278    </para>
 279  </note>
 280  *
 281  * Returns: The number of bytes sent or -1 in case of error
 282  * <para> See also: pseudo_tcp_socket_get_error() </para>
 283  *
 284  * Since: 0.0.11
 285  */
 286 gint pseudo_tcp_socket_send(PseudoTcpSocket *self, const char * buffer,
 287     guint32 len);
 288
 289
 290 /**
 291  * pseudo_tcp_socket_close:
 292  * @self: The #PseudoTcpSocket object.
 293  * @force: %TRUE to close the socket forcefully, %FALSE to close it gracefully
 294  *
 295  * Close the socket. IF @force is set to %FALSE, the socket will finish sending
 296  * pending data before closing.
 297  *
 298  <note>
 299    <para>
 300      The %PseudoTcpCallbacks:PseudoTcpClosed callback will not be called once
 301      the socket gets closed. It is only used for aborted connection.
 302      Instead, the socket gets closed when the pseudo_tcp_socket_get_next_clock()
 303      function returns FALSE.
 304    </para>
 305  </note>
 306  *
 307  * <para> See also: pseudo_tcp_socket_get_next_clock() </para>
 308  *
 309  * Since: 0.0.11
 310  */
 311 void pseudo_tcp_socket_close(PseudoTcpSocket *self, gboolean force);
 312
 313
 314 /**
 315  * pseudo_tcp_socket_get_error:
 316  * @self: The #PseudoTcpSocket object.
 317  *
 318  * Return the last encountered error.
 319  *
 320  <note>
 321    <para>
 322      The return value can be :
 323      <para>
 324        EINVAL (for pseudo_tcp_socket_connect()).
 325      </para>
 326      <para>
 327        EWOULDBLOCK or ENOTCONN (for pseudo_tcp_socket_recv() and
 328        pseudo_tcp_socket_send()).
 329      </para>
 330    </para>
 331  </note>
 332  *
 333  * Returns: The error code
 334  * <para> See also: pseudo_tcp_socket_connect() </para>
 335  * <para> See also: pseudo_tcp_socket_recv() </para>
 336  * <para> See also: pseudo_tcp_socket_send() </para>
 337  *
 338  * Since: 0.0.11
 339  */
 340 int pseudo_tcp_socket_get_error(PseudoTcpSocket *self);
 341
 342
 343 /**
 344  * pseudo_tcp_socket_get_next_clock:
 345  * @self: The #PseudoTcpSocket object.
 346  * @timeout: A pointer to be filled with the new timeout.
 347  *
 348  * Call this to determine the timeout needed before the next time call
 349  * to pseudo_tcp_socket_notify_clock() should be made.
 350  *
 351  * Returns: %TRUE if @timeout was filled, %FALSE if the socket is closed and
 352  * ready to be destroyed.
 353  *
 354  * <para> See also: pseudo_tcp_socket_notify_clock() </para>
 355  *
 356  * Since: 0.0.11
 357  */
 358 gboolean pseudo_tcp_socket_get_next_clock(PseudoTcpSocket *self, long *timeout);
 359
 360
 361 /**
 362  * pseudo_tcp_socket_notify_clock:
 363  * @self: The #PseudoTcpSocket object.
 364  *
 365  * Start the processing of receiving data, pending data or syn/acks.
 366  * Call this based on timeout value returned by
 367  * pseudo_tcp_socket_get_next_clock().
 368  * It's ok to call this too frequently.
 369  *
 370  * <para> See also: pseudo_tcp_socket_get_next_clock() </para>
 371  *
 372  * Since: 0.0.11
 373  */
 374 void pseudo_tcp_socket_notify_clock(PseudoTcpSocket *self);
 375
 376
 377 /**
 378  * pseudo_tcp_socket_notify_mtu:
 379  * @self: The #PseudoTcpSocket object.
 380  * @mtu: The new MTU of the socket
 381  *
 382  * Set the MTU of the socket
 383  *
 384  * Since: 0.0.11
 385  */
 386 void pseudo_tcp_socket_notify_mtu(PseudoTcpSocket *self, guint16 mtu);
 387
 388
 389 /**
 390  * pseudo_tcp_socket_notify_packet:
 391  * @self: The #PseudoTcpSocket object.
 392  * @buffer: The buffer containing the received data
 393  * @len: The length of @buffer
 394  *
 395  * Notify the #PseudoTcpSocket when a new packet arrives
 396  *
 397  * Returns: %TRUE if the packet was processed successfully, %FALSE otherwise
 398  *
 399  * Since: 0.0.11
 400  */
 401 gboolean pseudo_tcp_socket_notify_packet(PseudoTcpSocket *self,
 402     const gchar * buffer, guint32 len);
 403
 404
 405 /**
 406  * pseudo_tcp_set_debug_level:
 407  * @level: The level of debug to set
 408  *
 409  * Sets the debug level to enable/disable normal/verbose debug messages.
 410  *
 411  * Since: 0.0.11
 412  */
 413 void pseudo_tcp_set_debug_level (PseudoTcpDebugLevel level);
 414
 415 G_END_DECLS
 416
 417 #endif /* _PSEUDOTCP_H */
 418