libnice Reference Manual: Pseudo TCP Socket

## Pseudo TCP Socket Pseudo TCP Socket — Pseudo TCP implementation |

## Stability Level

Stable, unless otherwise indicated

## Functions

PseudoTcpSocket * | pseudo_tcp_socket_new ()
gboolean | pseudo_tcp_socket_connect ()
gint | pseudo_tcp_socket_recv ()
gint | pseudo_tcp_socket_send ()
void | pseudo_tcp_socket_close ()
void | pseudo_tcp_socket_shutdown ()
gboolean | pseudo_tcp_socket_is_closed ()
gboolean | pseudo_tcp_socket_is_closed_remotely ()
int | pseudo_tcp_socket_get_error ()
gboolean | pseudo_tcp_socket_get_next_clock ()
void | pseudo_tcp_socket_notify_clock ()
void | pseudo_tcp_socket_notify_mtu ()
gboolean | pseudo_tcp_socket_notify_packet ()
void | pseudo_tcp_set_debug_level ()
gint | pseudo_tcp_socket_get_available_bytes ()
gboolean | pseudo_tcp_socket_can_send ()
gsize | pseudo_tcp_socket_get_available_send_space ()
gboolean | pseudo_tcp_socket_notify_message ()
void | pseudo_tcp_socket_set_time ()

## Properties

guint | ack-delay | Read / Write
gpointer | callbacks | Read / Write
guint | conversation | Read / Write / Construct Only
gboolean | no-delay | Read / Write
guint | rcv-buf | Read / Write
guint | snd-buf | Read / Write
guint | state | Read
gboolean | support-fin-ack | Read / Write / Construct Only

## Types and Values

struct | PseudoTcpSocket
enum | PseudoTcpState
enum | PseudoTcpWriteResult
| PseudoTcpCallbacks
enum | PseudoTcpDebugLevel
enum | PseudoTcpShutdown

## Object Hierarchy

        GObject
        ╰── PseudoTcpSocket

## Includes

    #include <pseudotcp.h>

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

## Functions

### pseudo_tcp_socket_new ()

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

Creates a new PseudoTcpSocket for the specified conversation

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`

#### Parameters

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

#### Parameters

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.

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.

#### Parameters

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.

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.

#### Parameters

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 for sending. If `force` is set to `FALSE`, the socket will finish sending pending data before closing. If it is set to `TRUE`, the socket will discard pending data and close the connection immediately (sending a TCP RST segment).

The socket will be closed in both directions – sending and receiving – and any pending received data must be read before calling this function, by calling `pseudo_tcp_socket_recv()` until it blocks. If any pending data is in the receive buffer when `pseudo_tcp_socket_close()` is called, a TCP RST segment will be sent to the peer to notify it of the data loss.

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()`

#### Parameters

self | The PseudoTcpSocket object. |
force | `TRUE` to close the socket forcefully, `FALSE` to close it gracefully |

Since 0.0.11

### pseudo_tcp_socket_shutdown ()

    void
    pseudo_tcp_socket_shutdown (PseudoTcpSocket *self,
                                PseudoTcpShutdown how);

Shut down sending, receiving, or both on the socket, depending on the value of `how` . The behaviour of `pseudo_tcp_socket_send()` and `pseudo_tcp_socket_recv()` will immediately change after this function returns (depending on the value of `how` ), though the socket may continue to process network traffic in the background even if sending or receiving data is forbidden.

This is equivalent to the POSIX `shutdown()` function. Setting `how` to `PSEUDO_TCP_SHUTDOWN_RDWR` is equivalent to calling `pseudo_tcp_socket_close()`.

#### Parameters

self | The PseudoTcpSocket object. |
how | The directions of the connection to shut down. |

Since 0.1.8

### pseudo_tcp_socket_is_closed ()

    gboolean
    pseudo_tcp_socket_is_closed (PseudoTcpSocket *self);

Gets whether the socket is closed, with the shutdown handshake completed, and both peers no longer able to read or write data to the connection.

#### Parameters

self | The PseudoTcpSocket object. |

#### Returns

`TRUE` if the socket is closed in both directions, `FALSE` otherwise

Since 0.1.8

### pseudo_tcp_socket_is_closed_remotely ()

    gboolean
    pseudo_tcp_socket_is_closed_remotely (PseudoTcpSocket *self);

Gets whether the socket has been closed on the remote peer’s side of the connection (i.e. whether `pseudo_tcp_socket_close()` has been called there). This is guaranteed to return `TRUE` if `pseudo_tcp_socket_is_closed()` returns `TRUE`. It will not return `TRUE` after `pseudo_tcp_socket_close()` is called until a FIN segment is received from the remote peer.

#### Parameters

self | The PseudoTcpSocket object. |

#### Returns

`TRUE` if the remote peer has closed its side of the connection, `FALSE` otherwise

Since 0.1.8

### pseudo_tcp_socket_get_error ()

    int
    pseudo_tcp_socket_get_error (PseudoTcpSocket *self);

Return the last encountered error.

The return value can be :

EINVAL (for `pseudo_tcp_socket_connect()`).

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

#### Parameters

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,
                                      guint64 *timeout);

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

#### Parameters

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()`

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

level | The level of debug to set |

Since 0.0.11

### pseudo_tcp_socket_get_available_bytes ()

    gint
    pseudo_tcp_socket_get_available_bytes (PseudoTcpSocket *self);

Gets the number of bytes of data in the buffer that can be read without receiving more packets from the network.

#### Parameters

self | The PseudoTcpSocket object. |

#### Returns

The number of bytes or -1 if the connection is not established

Since 0.1.5

### pseudo_tcp_socket_can_send ()

    gboolean
    pseudo_tcp_socket_can_send (PseudoTcpSocket *self);

Returns if there is space in the send buffer to send any data.

#### Parameters

self | The PseudoTcpSocket object. |

#### Returns

`TRUE` if data can be sent, `FALSE` otherwise

Since 0.1.5

### pseudo_tcp_socket_get_available_send_space ()

    gsize
    pseudo_tcp_socket_get_available_send_space
                                   (PseudoTcpSocket *self);

Gets the number of bytes of space available in the transmission buffer.

#### Parameters

self | The PseudoTcpSocket object. |

#### Returns

The number of bytes, or 0 if the connection is not established.

Since 0.1.5

### pseudo_tcp_socket_notify_message ()

    gboolean
    pseudo_tcp_socket_notify_message (PseudoTcpSocket *self,
                                      NiceInputMessage *message);

Notify the PseudoTcpSocket that a new message has arrived, and enqueue the data in its buffers to the PseudoTcpSocket’s receive buffer.

#### Parameters

self | The PseudoTcpSocket object. |
message | A NiceInputMessage containing the received data. |

#### Returns

`TRUE` if the packet was processed successfully, `FALSE` otherwise

Since 0.1.5

### pseudo_tcp_socket_set_time ()

    void
    pseudo_tcp_socket_set_time (PseudoTcpSocket *self,
                                guint32 current_time);

Sets the current monotonic time to be used by the TCP socket when calculating timeouts and expiry times. If this function is not called, or is called with `current_time` as zero, `g_get_monotonic_time()` will be used. Otherwise, the specified `current_time` will be used until it is updated by calling this function again.

This function is intended for testing only, and should not be used in production code.

#### Parameters

self | The PseudoTcpSocket object. |
current_time | Current monotonic time, in milliseconds; or zero to use the system monotonic clock. |

Since 0.1.8

## Types and Values

### struct PseudoTcpSocket

    struct PseudoTcpSocket;

The PseudoTcpSocket is the GObject implementing the Pseudo TCP Socket

Since 0.0.11

### enum PseudoTcpState

An enum representing the state of the PseudoTcpSocket. These states correspond to the TCP states in RFC 793.

See also: “state”

#### Members

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 |
TCP_FIN_WAIT_1 | The socket has been closed locally but not remotely (Since: 0.1.8) |
TCP_FIN_WAIT_2 | The socket has been closed locally but not remotely (Since: 0.1.8) |
TCP_CLOSING | The socket has been closed locally and remotely (Since: 0.1.8) |
TCP_TIME_WAIT | The socket has been closed locally and remotely (Since: 0.1.8) |
TCP_CLOSE_WAIT | The socket has been closed remotely but not locally (Since: 0.1.8) |
TCP_LAST_ACK | The socket has been closed locally and remotely (Since: 0.1.8) |

Since 0.0.11

### enum PseudoTcpWriteResult

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

See also: `PseudoTcpCallbacks`:WritePacket

#### Members

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

#### Members

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 (both sides) |
`WritePacket` () | This callback is called when the socket needs to send data. |

Since 0.0.11

### enum PseudoTcpDebugLevel

Valid values of debug levels to be set.

#### Members

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

### enum PseudoTcpShutdown

Options for which parts of a connection to shut down when calling `pseudo_tcp_socket_shutdown()`. These correspond to the values passed to POSIX `shutdown()`.

#### Members

PSEUDO_TCP_SHUTDOWN_RD | Shut down the local reader only |
PSEUDO_TCP_SHUTDOWN_WR | Shut down the local writer only |
PSEUDO_TCP_SHUTDOWN_RDWR | Shut down both reading and writing |

Since 0.1.8

## Property Details

### The `“ack-delay”` property

      “ack-delay”                guint

Delayed ACK timeout (in milliseconds).

Flags: Read / Write

Default value: 100

### The `“callbacks”` property

      “callbacks”                gpointer

Structure with the callbacks to call when PseudoTcp events happen.

Flags: Read / Write

### The `“conversation”` property

      “conversation”             guint

The TCP Conversation ID.

Flags: Read / Write / Construct Only

Default value: 0

### The `“no-delay”` property

      “no-delay”                 gboolean

Disable the Nagle algorithm (like the TCP_NODELAY option).

Flags: Read / Write

Default value: FALSE

### The `“rcv-buf”` property

      “rcv-buf”                  guint

Receive Buffer size.

Flags: Read / Write

Allowed values: >= 1

Default value: 61440

### The `“snd-buf”` property

      “snd-buf”                  guint

Send Buffer size.

Flags: Read / Write

Allowed values: >= 1

Default value: 92160

### The `“state”` property

      “state”                    guint

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

Flags: Read

Allowed values: <= 4

Default value: 0

### The `“support-fin-ack”` property

      “support-fin-ack”          gboolean

Whether to support the FIN–ACK extension to the pseudo-TCP protocol for this socket. The extension is only compatible with other libnice pseudo-TCP stacks, and not with Jingle pseudo-TCP stacks. If enabled, support is negotiatied on connection setup, so it is safe for a PseudoTcpSocket with support enabled to be used with one with it disabled, or with a Jingle pseudo-TCP socket which doesn’t support it at all.

Support is enabled by default.

Flags: Read / Write / Construct Only

Default value: TRUE

Since 0.1.8