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 G_BEGIN_DECLS
  62
  63 /**
  64  * PseudoTcpSocket:
  65  *
  66  * The #PseudoTcpSocket is the GObject implementing the Pseudo TCP Socket
  67  *
  68  * Since: 0.0.11
  69  */
  70 typedef struct _PseudoTcpSocket PseudoTcpSocket;
  71
  72 typedef struct _PseudoTcpSocketClass PseudoTcpSocketClass;
  73
  74 GType pseudo_tcp_socket_get_type (void);
  75
  76 /* TYPE MACROS */
  77 #define PSEUDO_TCP_SOCKET_TYPE \
  78   (pseudo_tcp_socket_get_type ())
  79 #define PSEUDO_TCP_SOCKET(obj) \
  80   (G_TYPE_CHECK_INSTANCE_CAST((obj), PSEUDO_TCP_SOCKET_TYPE, \
  81                               PseudoTcpSocket))
  82 #define PSEUDO_TCP_SOCKET_CLASS(klass) \
  83   (G_TYPE_CHECK_CLASS_CAST((klass), PSEUDO_TCP_SOCKET_TYPE, \
  84                            PseudoTcpSocketClass))
  85 #define IS_PSEUDO_TCP_SOCKET(obj) \
  86   (G_TYPE_CHECK_INSTANCE_TYPE((obj), PSEUDO_TCP_SOCKET_TYPE))
  87 #define IS_PSEUDO_TCP_SOCKET_CLASS(klass) \
  88   (G_TYPE_CHECK_CLASS_TYPE((klass), PSEUDO_TCP_SOCKET_TYPE))
  89 #define PSEUDOTCP_SOCKET_GET_CLASS(obj) \
  90   (G_TYPE_INSTANCE_GET_CLASS ((obj), PSEUDO_TCP_SOCKET_TYPE, \
  91                               PseudoTcpSocketClass))
  92
  93 struct _PseudoTcpSocketClass {
  94     GObjectClass parent_class;
  95 };
  96
  97 typedef struct _PseudoTcpSocketPrivate PseudoTcpSocketPrivate;
  98
  99 struct _PseudoTcpSocket {
 100     GObject parent;
 101     PseudoTcpSocketPrivate *priv;
 102 };
 103
 104 /**
 105  * PseudoTcpDebugLevel:
 106  * @PSEUDO_TCP_DEBUG_NONE: Disable debug messages
 107  * @PSEUDO_TCP_DEBUG_NORMAL: Enable basic debug messages
 108  * @PSEUDO_TCP_DEBUG_VERBOSE: Enable verbose debug messages
 109  *
 110  * Valid values of debug levels to be set.
 111  *
 112  * Since: 0.0.11
 113  */
 114 typedef enum {
 115   PSEUDO_TCP_DEBUG_NONE = 0,
 116   PSEUDO_TCP_DEBUG_NORMAL,
 117   PSEUDO_TCP_DEBUG_VERBOSE,
 118 } PseudoTcpDebugLevel;
 119
 120 /**
 121  * PseudoTcpState:
 122  * @TCP_LISTEN: The socket's initial state. The socket isn't connected and is
 123  * listening for an incoming connection
 124  * @TCP_SYN_SENT: The socket has sent a connection request (SYN) packet and is
 125  * waiting for an answer
 126  * @TCP_SYN_RECEIVED: The socket has received a connection request (SYN) packet.
 127  * @TCP_ESTABLISHED: The socket is connected
 128  * @TCP_CLOSED: The socket has been closed
 129  *
 130  * An enum representing the state of the #PseudoTcpSocket.
 131  * <para> See also: #PseudoTcpSocket:state </para>
 132  *
 133  * Since: 0.0.11
 134  */
 135 typedef enum {
 136   TCP_LISTEN,
 137   TCP_SYN_SENT,
 138   TCP_SYN_RECEIVED,
 139   TCP_ESTABLISHED,
 140   TCP_CLOSED
 141 } PseudoTcpState;
 142
 143 /**
 144  * PseudoTcpWriteResult:
 145  * @WR_SUCCESS: The write operation was successful
 146  * @WR_TOO_LARGE: The socket type requires that message be sent atomically
 147  * and the size of the message to be sent made this impossible.
 148  * @WR_FAIL: There was an error sending the message
 149  *
 150  * An enum representing the result value of the write operation requested by
 151  * the #PseudoTcpSocket.
 152  * <para> See also: %PseudoTcpCallbacks:WritePacket </para>
 153  *
 154  * Since: 0.0.11
 155  */
 156 typedef enum {
 157   WR_SUCCESS,
 158   WR_TOO_LARGE,
 159   WR_FAIL
 160 } PseudoTcpWriteResult;
 161
 162 /**
 163  * PseudoTcpCallbacks:
 164  * @user_data: A user defined pointer to be passed to the callbacks
 165  * @PseudoTcpOpened: The #PseudoTcpSocket is now connected
 166  * @PseudoTcpReadable: The socket is readable
 167  * @PseudoTcpWritable: The socket is writable
 168  * @PseudoTcpClosed: The socket was closed
 169  * @WritePacket: This callback is called when the socket needs to send data.
 170  *
 171  * A structure containing callbacks functions that will be called by the
 172  * #PseudoTcpSocket when some events happen.
 173  * <para> See also: #PseudoTcpWriteResult </para>
 174  *
 175  * Since: 0.0.11
 176  */
 177 typedef struct {
 178   gpointer user_data;
 179   void  (*PseudoTcpOpened) (PseudoTcpSocket *tcp, gpointer data);
 180   void  (*PseudoTcpReadable) (PseudoTcpSocket *tcp, gpointer data);
 181   void  (*PseudoTcpWritable) (PseudoTcpSocket *tcp, gpointer data);
 182   void  (*PseudoTcpClosed) (PseudoTcpSocket *tcp, guint32 error, gpointer data);
 183   PseudoTcpWriteResult (*WritePacket) (PseudoTcpSocket *tcp,
 184       const gchar * buffer, guint32 len, gpointer data);
 185 } PseudoTcpCallbacks;
 186
 187 /**
 188  * pseudo_tcp_socket_new:
 189  * @conversation: The conversation id for the socket.
 190  * @callbacks: A pointer to the #PseudoTcpCallbacks structure for getting
 191  * notified of the #PseudoTcpSocket events.
 192  *
 193  * Creates a new #PseudoTcpSocket for the specified conversation
 194  *
 195  <note>
 196    <para>
 197      The @callbacks must be non-NULL, in order to get notified of packets the
 198      socket needs to send.
 199    </para>
 200    <para>
 201      If the @callbacks structure was dynamicly allocated, it can be freed
 202      after the call @pseudo_tcp_socket_new
 203    </para>
 204  </note>
 205  *
 206  * Returns: The new #PseudoTcpSocket object, %NULL on error
 207  *
 208  * Since: 0.0.11
 209  */
 210 PseudoTcpSocket *pseudo_tcp_socket_new (guint32 conversation,
 211     PseudoTcpCallbacks *callbacks);
 212
 213
 214 /**
 215  * pseudo_tcp_socket_connect:
 216  * @self: The #PseudoTcpSocket object.
 217  *
 218  * Connects the #PseudoTcpSocket to the peer with the same conversation id.
 219  * The connection will only be successful after the
 220  * %PseudoTcpCallbacks:PseudoTcpOpened callback is called
 221  *
 222  * Returns: %TRUE on success, %FALSE on failure (not in %TCP_LISTEN state)
 223  * <para> See also: pseudo_tcp_socket_get_error() </para>
 224  *
 225  * Since: 0.0.11
 226  */
 227 gboolean pseudo_tcp_socket_connect(PseudoTcpSocket *self);
 228
 229
 230 /**
 231  * pseudo_tcp_socket_recv:
 232  * @self: The #PseudoTcpSocket object.
 233  * @buffer: The buffer to fill with received data
 234  * @len: The length of @buffer
 235  *
 236  * Receive data from the socket.
 237  *
 238  <note>
 239    <para>
 240      Only call this on the %PseudoTcpCallbacks:PseudoTcpReadable callback.
 241    </para>
 242    <para>
 243      This function should be called in a loop. If this function does not
 244      return -1 with EWOULDBLOCK as the error, the
 245      %PseudoTcpCallbacks:PseudoTcpReadable callback will not be called again.
 246    </para>
 247  </note>
 248  *
 249  * Returns: The number of bytes received or -1 in case of error
 250  * <para> See also: pseudo_tcp_socket_get_error() </para>
 251  *
 252  * Since: 0.0.11
 253  */
 254 gint  pseudo_tcp_socket_recv(PseudoTcpSocket *self, char * buffer, size_t len);
 255
 256
 257 /**
 258  * pseudo_tcp_socket_send:
 259  * @self: The #PseudoTcpSocket object.
 260  * @buffer: The buffer with data to send
 261  * @len: The length of @buffer
 262  *
 263  * Send data on the socket.
 264  *
 265  <note>
 266    <para>
 267      If this function return -1 with EWOULDBLOCK as the error, or if the return
 268      value is lower than @len, then the %PseudoTcpCallbacks:PseudoTcpWritable
 269      callback will be called when the socket will become writable.
 270    </para>
 271  </note>
 272  *
 273  * Returns: The number of bytes sent or -1 in case of error
 274  * <para> See also: pseudo_tcp_socket_get_error() </para>
 275  *
 276  * Since: 0.0.11
 277  */
 278 gint pseudo_tcp_socket_send(PseudoTcpSocket *self, const char * buffer,
 279     guint32 len);
 280
 281
 282 /**
 283  * pseudo_tcp_socket_close:
 284  * @self: The #PseudoTcpSocket object.
 285  * @force: %TRUE to close the socket forcefully, %FALSE to close it gracefully
 286  *
 287  * Close the socket. IF @force is set to %FALSE, the socket will finish sending
 288  * pending data before closing.
 289  *
 290  <note>
 291    <para>
 292      The %PseudoTcpCallbacks:PseudoTcpClosed callback will not be called once
 293      the socket gets closed. It is only used for aborted connection.
 294      Instead, the socket gets closed when the pseudo_tcp_socket_get_next_clock()
 295      function returns FALSE.
 296    </para>
 297  </note>
 298  *
 299  * <para> See also: pseudo_tcp_socket_get_next_clock() </para>
 300  *
 301  * Since: 0.0.11
 302  */
 303 void pseudo_tcp_socket_close(PseudoTcpSocket *self, gboolean force);
 304
 305
 306 /**
 307  * pseudo_tcp_socket_get_error:
 308  * @self: The #PseudoTcpSocket object.
 309  *
 310  * Return the last encountered error.
 311  *
 312  <note>
 313    <para>
 314      The return value can be :
 315      <para>
 316        EINVAL (for pseudo_tcp_socket_connect()).
 317      </para>
 318      <para>
 319        EWOULDBLOCK or ENOTCONN (for pseudo_tcp_socket_recv() and
 320        pseudo_tcp_socket_send()).
 321      </para>
 322    </para>
 323  </note>
 324  *
 325  * Returns: The error code
 326  * <para> See also: pseudo_tcp_socket_connect() </para>
 327  * <para> See also: pseudo_tcp_socket_recv() </para>
 328  * <para> See also: pseudo_tcp_socket_send() </para>
 329  *
 330  * Since: 0.0.11
 331  */
 332 int pseudo_tcp_socket_get_error(PseudoTcpSocket *self);
 333
 334
 335 /**
 336  * pseudo_tcp_socket_get_next_clock:
 337  * @self: The #PseudoTcpSocket object.
 338  * @timeout: A pointer to be filled with the new timeout.
 339  *
 340  * Call this to determine the timeout needed before the next time call
 341  * to pseudo_tcp_socket_notify_clock() should be made.
 342  *
 343  * Returns: %TRUE if @timeout was filled, %FALSE if the socket is closed and
 344  * ready to be destroyed.
 345  *
 346  * <para> See also: pseudo_tcp_socket_notify_clock() </para>
 347  *
 348  * Since: 0.0.11
 349  */
 350 gboolean pseudo_tcp_socket_get_next_clock(PseudoTcpSocket *self, long *timeout);
 351
 352
 353 /**
 354  * pseudo_tcp_socket_notify_clock:
 355  * @self: The #PseudoTcpSocket object.
 356  *
 357  * Start the processing of receiving data, pending data or syn/acks.
 358  * Call this based on timeout value returned by
 359  * pseudo_tcp_socket_get_next_clock().
 360  * It's ok to call this too frequently.
 361  *
 362  * <para> See also: pseudo_tcp_socket_get_next_clock() </para>
 363  *
 364  * Since: 0.0.11
 365  */
 366 void pseudo_tcp_socket_notify_clock(PseudoTcpSocket *self);
 367
 368
 369 /**
 370  * pseudo_tcp_socket_notify_mtu:
 371  * @self: The #PseudoTcpSocket object.
 372  * @mtu: The new MTU of the socket
 373  *
 374  * Set the MTU of the socket
 375  *
 376  * Since: 0.0.11
 377  */
 378 void pseudo_tcp_socket_notify_mtu(PseudoTcpSocket *self, guint16 mtu);
 379
 380
 381 /**
 382  * pseudo_tcp_socket_notify_packet:
 383  * @self: The #PseudoTcpSocket object.
 384  * @buffer: The buffer containing the received data
 385  * @len: The length of @buffer
 386  *
 387  * Notify the #PseudoTcpSocket when a new packet arrives
 388  *
 389  * Returns: %TRUE if the packet was processed successfully, %FALSE otherwise
 390  *
 391  * Since: 0.0.11
 392  */
 393 gboolean pseudo_tcp_socket_notify_packet(PseudoTcpSocket *self,
 394     const gchar * buffer, guint32 len);
 395
 396
 397 /**
 398  * pseudo_tcp_set_debug_level:
 399  * @level: The level of debug to set
 400  *
 401  * Sets the debug level to enable/disable normal/verbose debug messages.
 402  *
 403  * Since: 0.0.11
 404  */
 405 void pseudo_tcp_set_debug_level (PseudoTcpDebugLevel level);
 406
 407 G_END_DECLS
 408
 409 #endif /* _PSEUDOTCP_H */
 410