Pseudo TCP Socket

Pseudo TCP Socket — Pseudo TCP implementation

Stability Level

Stable, unless otherwise indicated

Functions

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

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