Pseudo TCP Socket

Pseudo TCP Socket — Pseudo TCP implementation

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <pseudotcp.h>

                    PseudoTcpSocket;
enum                PseudoTcpState;
enum                PseudoTcpWriteResult;
                    PseudoTcpCallbacks;
enum                PseudoTcpDebugLevel;
PseudoTcpSocket *   pseudo_tcp_socket_new               (guint32 conversation,
                                                         PseudoTcpCallbacks *callbacks);
gboolean            pseudo_tcp_socket_connect           (PseudoTcpSocket *self);
gint                pseudo_tcp_socket_recv              (PseudoTcpSocket *self,
                                                         char *buffer,
                                                         size_t len);
gint                pseudo_tcp_socket_send              (PseudoTcpSocket *self,
                                                         const char *buffer,
                                                         guint32 len);
void                pseudo_tcp_socket_close             (PseudoTcpSocket *self,
                                                         gboolean force);
int                 pseudo_tcp_socket_get_error         (PseudoTcpSocket *self);
gboolean            pseudo_tcp_socket_get_next_clock    (PseudoTcpSocket *self,
                                                         long *timeout);
void                pseudo_tcp_socket_notify_clock      (PseudoTcpSocket *self);
void                pseudo_tcp_socket_notify_mtu        (PseudoTcpSocket *self,
                                                         guint16 mtu);
gboolean            pseudo_tcp_socket_notify_packet     (PseudoTcpSocket *self,
                                                         const gchar *buffer,
                                                         guint32 len);
void                pseudo_tcp_set_debug_level          (PseudoTcpDebugLevel level);

Object Hierarchy

  GObject
   +----PseudoTcpSocket

Properties

  "callbacks"                gpointer              : Read / Write
  "conversation"             guint                 : Read / Write / Construct Only
  "state"                    guint                 : Read

Description

The PseudoTcpSocket is an object implementing a Pseudo Tcp Socket for use over UDP. The socket will implement a subset of the TCP stack to allow for a reliable transport over non-reliable sockets (such as UDP).

See the file tests/test-pseudotcp.c in the source package for an example of how to use the object.

Details

PseudoTcpSocket

typedef struct _PseudoTcpSocket PseudoTcpSocket;

The PseudoTcpSocket is the GObject implementing the Pseudo TCP Socket

Since 0.0.11


enum PseudoTcpState

typedef enum {
  TCP_LISTEN,
  TCP_SYN_SENT,
  TCP_SYN_RECEIVED,
  TCP_ESTABLISHED,
  TCP_CLOSED
} PseudoTcpState;

An enum representing the state of the PseudoTcpSocket.

See also: "state"

TCP_LISTEN

The socket's initial state. The socket isn't connected and is listening for an incoming connection

TCP_SYN_SENT

The socket has sent a connection request (SYN) packet and is waiting for an answer

TCP_SYN_RECEIVED

The socket has received a connection request (SYN) packet.

TCP_ESTABLISHED

The socket is connected

TCP_CLOSED

The socket has been closed

Since 0.0.11


enum PseudoTcpWriteResult

typedef enum {
  WR_SUCCESS,
  WR_TOO_LARGE,
  WR_FAIL
} PseudoTcpWriteResult;

An enum representing the result value of the write operation requested by the PseudoTcpSocket.

See also: PseudoTcpCallbacks:WritePacket

WR_SUCCESS

The write operation was successful

WR_TOO_LARGE

The socket type requires that message be sent atomically and the size of the message to be sent made this impossible.

WR_FAIL

There was an error sending the message

Since 0.0.11


PseudoTcpCallbacks

typedef struct {
  gpointer user_data;
  void  (*PseudoTcpOpened) (PseudoTcpSocket *tcp, gpointer data);
  void  (*PseudoTcpReadable) (PseudoTcpSocket *tcp, gpointer data);
  void  (*PseudoTcpWritable) (PseudoTcpSocket *tcp, gpointer data);
  void  (*PseudoTcpClosed) (PseudoTcpSocket *tcp, guint32 error, gpointer data);
  PseudoTcpWriteResult (*WritePacket) (PseudoTcpSocket *tcp,
      const gchar * buffer, guint32 len, gpointer data);
} PseudoTcpCallbacks;

A structure containing callbacks functions that will be called by the PseudoTcpSocket when some events happen.

See also: PseudoTcpWriteResult

gpointer user_data;

A user defined pointer to be passed to the callbacks

PseudoTcpOpened ()

The PseudoTcpSocket is now connected

PseudoTcpReadable ()

The socket is readable

PseudoTcpWritable ()

The socket is writable

PseudoTcpClosed ()

The socket was closed

WritePacket ()

This callback is called when the socket needs to send data.

Since 0.0.11


enum PseudoTcpDebugLevel

typedef enum {
  PSEUDO_TCP_DEBUG_NONE = 0,
  PSEUDO_TCP_DEBUG_NORMAL,
  PSEUDO_TCP_DEBUG_VERBOSE,
} PseudoTcpDebugLevel;

Valid values of debug levels to be set.

PSEUDO_TCP_DEBUG_NONE

Disable debug messages

PSEUDO_TCP_DEBUG_NORMAL

Enable basic debug messages

PSEUDO_TCP_DEBUG_VERBOSE

Enable verbose debug messages

Since 0.0.11


pseudo_tcp_socket_new ()

PseudoTcpSocket *   pseudo_tcp_socket_new               (guint32 conversation,
                                                         PseudoTcpCallbacks *callbacks);

Creates a new PseudoTcpSocket for the specified conversation

Note

The callbacks must be non-NULL, in order to get notified of packets the socket needs to send.

If the callbacks structure was dynamicly allocated, it can be freed after the call pseudo_tcp_socket_new

conversation :

The conversation id for the socket.

callbacks :

A pointer to the PseudoTcpCallbacks structure for getting notified of the PseudoTcpSocket events.

Returns :

The new PseudoTcpSocket object, NULL on error

Since 0.0.11


pseudo_tcp_socket_connect ()

gboolean            pseudo_tcp_socket_connect           (PseudoTcpSocket *self);

Connects the PseudoTcpSocket to the peer with the same conversation id. The connection will only be successful after the PseudoTcpCallbacks:PseudoTcpOpened callback is called

self :

The PseudoTcpSocket object.

Returns :

TRUE on success, FALSE on failure (not in TCP_LISTEN state)

See also: pseudo_tcp_socket_get_error()

Since 0.0.11


pseudo_tcp_socket_recv ()

gint                pseudo_tcp_socket_recv              (PseudoTcpSocket *self,
                                                         char *buffer,
                                                         size_t len);

Receive data from the socket.

Note

Only call this on the PseudoTcpCallbacks:PseudoTcpReadable callback.

This function should be called in a loop. If this function does not return -1 with EWOULDBLOCK as the error, the PseudoTcpCallbacks:PseudoTcpReadable callback will not be called again.

self :

The PseudoTcpSocket object.

buffer :

The buffer to fill with received data

len :

The length of buffer

Returns :

The number of bytes received or -1 in case of error

See also: pseudo_tcp_socket_get_error()

Since 0.0.11


pseudo_tcp_socket_send ()

gint                pseudo_tcp_socket_send              (PseudoTcpSocket *self,
                                                         const char *buffer,
                                                         guint32 len);

Send data on the socket.

Note

If this function return -1 with EWOULDBLOCK as the error, or if the return value is lower than len, then the PseudoTcpCallbacks:PseudoTcpWritable callback will be called when the socket will become writable.

self :

The PseudoTcpSocket object.

buffer :

The buffer with data to send

len :

The length of buffer

Returns :

The number of bytes sent or -1 in case of error

See also: pseudo_tcp_socket_get_error()

Since 0.0.11


pseudo_tcp_socket_close ()

void                pseudo_tcp_socket_close             (PseudoTcpSocket *self,
                                                         gboolean force);

Close the socket. IF force is set to FALSE, the socket will finish sending pending data before closing.

Note

The PseudoTcpCallbacks:PseudoTcpClosed callback will not be called once the socket gets closed. It is only used for aborted connection. Instead, the socket gets closed when the pseudo_tcp_socket_get_next_clock() function returns FALSE.

See also: pseudo_tcp_socket_get_next_clock()

self :

The PseudoTcpSocket object.

force :

TRUE to close the socket forcefully, FALSE to close it gracefully

Since 0.0.11


pseudo_tcp_socket_get_error ()

int                 pseudo_tcp_socket_get_error         (PseudoTcpSocket *self);

Return the last encountered error.

Note

The return value can be :

EINVAL (for pseudo_tcp_socket_connect()).

EWOULDBLOCK or ENOTCONN (for pseudo_tcp_socket_recv() and pseudo_tcp_socket_send()).

self :

The PseudoTcpSocket object.

Returns :

The error code

See also: pseudo_tcp_socket_connect()

See also: pseudo_tcp_socket_recv()

See also: pseudo_tcp_socket_send()

Since 0.0.11


pseudo_tcp_socket_get_next_clock ()

gboolean            pseudo_tcp_socket_get_next_clock    (PseudoTcpSocket *self,
                                                         long *timeout);

Call this to determine the timeout needed before the next time call to pseudo_tcp_socket_notify_clock() should be made.

self :

The PseudoTcpSocket object.

timeout :

A pointer to be filled with the new timeout.

Returns :

TRUE if timeout was filled, FALSE if the socket is closed and ready to be destroyed.

See also: pseudo_tcp_socket_notify_clock()

Since 0.0.11


pseudo_tcp_socket_notify_clock ()

void                pseudo_tcp_socket_notify_clock      (PseudoTcpSocket *self);

Start the processing of receiving data, pending data or syn/acks. Call this based on timeout value returned by pseudo_tcp_socket_get_next_clock(). It's ok to call this too frequently.

See also: pseudo_tcp_socket_get_next_clock()

self :

The PseudoTcpSocket object.

Since 0.0.11


pseudo_tcp_socket_notify_mtu ()

void                pseudo_tcp_socket_notify_mtu        (PseudoTcpSocket *self,
                                                         guint16 mtu);

Set the MTU of the socket

self :

The PseudoTcpSocket object.

mtu :

The new MTU of the socket

Since 0.0.11


pseudo_tcp_socket_notify_packet ()

gboolean            pseudo_tcp_socket_notify_packet     (PseudoTcpSocket *self,
                                                         const gchar *buffer,
                                                         guint32 len);

Notify the PseudoTcpSocket when a new packet arrives

self :

The PseudoTcpSocket object.

buffer :

The buffer containing the received data

len :

The length of buffer

Returns :

TRUE if the packet was processed successfully, FALSE otherwise

Since 0.0.11


pseudo_tcp_set_debug_level ()

void                pseudo_tcp_set_debug_level          (PseudoTcpDebugLevel level);

Sets the debug level to enable/disable normal/verbose debug messages.

level :

The level of debug to set

Since 0.0.11

Property Details

The "callbacks" property

  "callbacks"                gpointer              : Read / Write

Structure with the callbacks to call when PseudoTcp events happen.


The "conversation" property

  "conversation"             guint                 : Read / Write / Construct Only

The TCP Conversation ID.

Default value: 0


The "state" property

  "state"                    guint                 : Read

The current state (enum PseudoTcpState) of the PseudoTcp socket.

Allowed values: <= 4

Default value: 0