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

  PseudoTcpSocket
enum PseudoTcpState
enum PseudoTcpWriteResult
  PseudoTcpCallbacks
enum PseudoTcpDebugLevel
enum PseudoTcpShutdown

Object Hierarchy

    GEnum
    ├── PseudoTcpDebugLevel
    ├── PseudoTcpShutdown
    ├── PseudoTcpState
    ╰── PseudoTcpWriteResult
    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

PseudoTcpSocket

typedef struct _PseudoTcpSocket 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

PSEUDO_TCP_LISTEN

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

  

PSEUDO_TCP_SYN_SENT

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

  

PSEUDO_TCP_SYN_RECEIVED

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

  

PSEUDO_TCP_ESTABLISHED

The socket is connected

  

PSEUDO_TCP_CLOSED

The socket has been closed

  

PSEUDO_TCP_FIN_WAIT_1

The socket has been closed locally but not remotely (Since: 0.1.8)

  

PSEUDO_TCP_FIN_WAIT_2

The socket has been closed locally but not remotely (Since: 0.1.8)

  

PSEUDO_TCP_CLOSING

The socket has been closed locally and remotely (Since: 0.1.8)

  

PSEUDO_TCP_TIME_WAIT

The socket has been closed locally and remotely (Since: 0.1.8)

  

PSEUDO_TCP_CLOSE_WAIT

The socket has been closed remotely but not locally (Since: 0.1.8)

  

PSEUDO_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: TRUE

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

Generated by GTK-Doc V1.28