Pseudo TCP Socket

## 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