Socket Interface

Socket Overview

The socket interface stands as a foundational abstraction provided by operating systems, facilitating inter-process communication over a network. It serves as the backbone of network programming, enabling the creation of distributed applications that seamlessly communicate across various machines.

A socket serves as an endpoint in a network communication between two processes. It empowers processes to exchange data, regardless of whether they reside on the same machine or are distributed across different machines connected via a network.

Types of Sockets

  • Stream Sockets (TCP)

    Stream sockets deliver reliable, connection-oriented communication. They ensure data delivery in the order it was sent, guaranteeing data integrity during transmission. TCP (Transmission Control Protocol) stands out as the most prevalent protocol for stream sockets.

  • Datagram Sockets (UDP)

    Datagram sockets offer an unreliable, connectionless communication channel. They enable processes to dispatch individual data packets, termed datagrams, without necessitating a prior connection. UDP (User Datagram Protocol) often finds use in real-time applications demanding low latency, such as video streaming and online gaming.

Supported Communication Modes

The following modes of socket communication are supported:

  • Blocking - Here the read/write function waits(blocked) till the operation is performed or time out.

  • Non-Blocking - The read/write function returns immediately with appropriate return values.

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions

Function

Description

rs_socket_tcp_server_open

To open the TCP server socket.

rs_socket_tcp_client_open

To open the TCP client socket.

rs_socket_set_config

To configure the socket interface.

rs_socket_write

To write the data to the TCP socket interface.

rs_socket_read

To read the data from the TCP socket interface.

rs_socket_close

To close the socket interface.

rs_socket_listen

To listen for the incoming socket connection.

rs_socket_accept

To accept a new socket connection.

rs_socket_connect

To connect to the socket.

rs_socket_udp_server_open

To open the UDP server socket.

rs_socket_udp_client_open

To open the UDP client socket.

rs_socket_write_msg

To write the data to the UDP socket interface.

rs_socket_read_msg

To read the data from the UDP socket interface.

rs_socket_tcp_server_close

To close the tcp socket server connection

rs_socket_tcp_conn_close

To close the tcp socket accept connection

rs_socket_udp_server_close

To close the udp socket server connection

rs_socket_udp_conn_close

To close the udp socket accept connection

rs_socket_udp_set_opt

To sets options associated with a socket for UDP

Error Code

  • Every API’s for the Socket returns some success or failure values. Please refer below section,

Implementation Guide

This section explains how to implement the Socket interface using the RAPIDSEA stack, the steps to be followed are

  • Configure the preferred method of RX or TX communication(Blocking / Non-Blocking).

  • Configure the socket interface(Address, Port number and number of connection).

  • Then call the initialize call of the socket interface for the preferred protocol.

  • Perform the read and write functions as required and handle the error codes.

  • Close the Socket interface.

Note:

The configurations are done by loading the provided socket structure(rs_socket_config_t) from the application layer.

Documentation from the relevant header as follows:

Defines

RS_SOCKET_BLOCKING

Blocking Mode operation

RS_SOCKET_NON_BLOCKING

Non-Blocking Mode operation

RS_IP_ADDR_V4_LEN
RS_IP_ADDR_V6_LEN
RS_TCP_NUM_CONN_INSTANCE

Typedefs

typedef struct tag_ipv6_address rs_ipv6_addr_t

Structure for the IPv6 address.

typedef union tag_ip_address rs_ip_address_t

Structure for the IP address.

typedef struct tag_rs_sock_addr rs_sock_addr_t

Structure for the socket address information.

typedef struct tag_rs_socket_config rs_socket_config_t

Structure for the socket configuration.

typedef struct tag_rs_tcp_conn_instance rs_tcp_conn_instance_t

For connection/Client information - to be used for socket_read/write on both sides.

typedef struct tag_rs_tcp_server_instance rs_tcp_server_instance_t

Structure for the TCP socket instance information.

typedef struct tag_rs_udp_info rs_udp_conn_info_t

For connection/Client information - to be used for socket_read/write on both sides.

typedef struct tag_rs_udp_instance rs_udp_instance_t

Structure for the UDP socket instance information.

Functions

rs_handle_t rs_socket_tcp_server_open(rs_tcp_server_instance_t *ptr_instance, rs_socket_config_t *ptr_config)
rs_handle_t rs_socket_tcp_client_open(rs_tcp_conn_instance_t *ptr_instance, rs_socket_config_t *ptr_config)

Configures and open the Socket.

This function creates the TCP client socket for the provided configuration

Parameters:

  • ptr_instance – [in] - Pointer to the run time information structure

  • ptr_config – [in] - Pointer to the configuration structure

Returns:

Handle for the created socket

rs_ret_val_t rs_socket_listen(rs_handle_t server_handle)

Indicates a readiness to accept client connection requests.

This function causes a connection-oriented Socket to listen for incoming connection attempts.

Parameters:

s32_server_handle – [in] - Handle to the socket

Returns:

return 0 on success or negative error code

rs_handle_t rs_socket_accept(rs_handle_t server_handle)
rs_ret_val_t rs_socket_connect(rs_handle_t server_handle)

Connect a socket.

This function call attempts to establish a connection between two sockets.

Parameters:

server_handle – [in] - File descriptor of the server socket

Returns:

return 0 on success or negative error code

rs_ret_val_t rs_socket_read(rs_handle_t socket_handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Read data from TCP socket port.

This function reads data from TCP socket port

Parameters:

  • socket_handle – [in] - Handle to the socket

  • ptr_buf – [in] - Pointer to buffer of read data

  • u32_num_bytes – [in] - Number of bytes to read

  • u32_time_out – [in] - timeout of read data

Returns:

return number of bytes read on success or negative error code

rs_ret_val_t rs_socket_write(rs_handle_t socket_handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Send data to the TCP socket port.

This function Sends the data to the socket port

Parameters:

  • socket_handle – [in] - Handle to the socket

  • ptr_buf – [in] - Pointer to buffer of send data

  • u32_num_bytes – [in] - Number of bytes to send

  • u32_time_out – [in] - timeout of send data

Returns:

return number of bytes send on success or negative error code

rs_ret_val_t rs_socket_tcp_server_close(rs_handle_t socket_handle)

Close the socket server connection.

This function close the socket server connection

Parameters:

socket_handle – [in] - Handle to the socket

Returns:

return 0

rs_ret_val_t rs_socket_tcp_conn_close(rs_handle_t socket_handle)

Close the socket accept connection.

This function close the socket accept connection

Parameters:

socket_handle – [in] - Handle to the accept

Returns:

return 0

rs_handle_t rs_socket_udp_server_open(rs_udp_instance_t *ptr_instance, rs_socket_config_t *ptr_config)
rs_handle_t rs_socket_udp_client_open(rs_udp_instance_t *ptr_instance, rs_socket_config_t *ptr_config)
rs_ret_val_t rs_socket_read_msg(rs_handle_t socket_handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Read data from UDP socket.

This function reads data from UDP socket port

Parameters:

  • socket_handle – [in] - Handle to the socket

  • ptr_buf – [in] - Pointer to buffer of read data

  • u32_num_bytes – [in] - Number of bytes to read

  • u32_time_out – [in] - timeout of read data

Returns:

return number of bytes read on success or negative error code

rs_ret_val_t rs_socket_write_msg(rs_handle_t socket_handle, uint8_t *ptr_buf, uint32_t u32_num_bytes, uint32_t u32_time_out)

Send data to the UDP socket port.

This function Sends the data to the socket

Parameters:

  • socket_handle – [in] - Handle to the socket

  • ptr_buf – [in] - Pointer to buffer of send data

  • u32_num_bytes – [in] - Number of bytes to send

  • u32_time_out – [in] - timeout of send data

Returns:

return number of bytes send on success or negative error code

rs_ret_val_t rs_socket_udp_server_close(rs_handle_t socket_handle)

Close the socket server connection.

This function close the socket server connection

Parameters:

socket_handle – [in] - Handle to the socket

Returns:

return 0

rs_ret_val_t rs_socket_udp_conn_close(rs_handle_t socket_handle)
rs_ret_val_t rs_socket_set_config(rs_socket_config_t *ptr_config, uint8_t *ptr_addr, uint16_t u16_port, uint16_t u16_num_conn)

Updates the socket communication settings.

This function configures the socket with the given communication settings

Parameters:

  • ptr_config – [out] - Pointer to the socket configuration structure

  • ptr_addr – [in] - Pointer to the address

  • u16_port – [in] - Port number

Returns:

0 on success or error code on failure

rs_handle_t rs_socket_udp_set_opt(rs_handle_t socket_handle, int32_t s32_level, int32_t s32_option, char *ptr_opt_val, uint32_t u32_opt_val_len)

sets options associated with a socket for UDP

This function sets options associated with a socket for UDP

Parameters:

  • socket_handle – [in] - Handle to the socket

  • s32_level – [in] - level for which the option is being set.

  • s32_option – [in] - name of a specified socket option

  • ptr_opt_val – [in] - pointer to option data.

  • u32_opt_val_len – [in] - length of the option data.

Returns:

return zero on success or negative on failure

rs_handle_t rs_socket_getsockname(rs_handle_t socket_handle, rs_sock_addr_t *ptr_sock_addr, uint32_t *u32_sock_len)

used to discover the port assigned to a socket after the socket has been implicitly bound to a port.

This function used to discover the port assigned to a socket after the socket has been implicitly bound to a port.

Parameters:

  • socket_handle – [in] - Handle to the socket

  • ptr_sock_addr – [out] - Pointer to the socket data

  • u32_sock_len – [in] - socket data length

Returns:

return zero on success or negative on failure

struct tag_ipv6_address
#include <rs_socket.h>

Structure for the IPv6 address.

Public Members

uint8_t addr_bytes[RS_IP_ADDR_V6_LEN]
union tag_ip_address
#include <rs_socket.h>

Structure for the IP address.

Public Members

uint8_t ipv4_addr[RS_IP_ADDR_V4_LEN]

IPv4 address.

rs_ipv6_addr_t ipv6_addr

IPv6 address.

struct tag_rs_sock_addr
#include <rs_socket.h>

Structure for the socket address information.

Public Members

uint8_t sin_family
uint16_t sin_port
rs_ip_address_t sin_address
struct tag_rs_socket_config
#include <rs_socket.h>

Structure for the socket configuration.

Public Members

uint8_t non_blocking

Blocking / Non-blocking.

uint8_t num_conn_accept

Number of connections to accept.

uint16_t port_number

Port number.

uint8_t ip_version

IP version number.

rs_ip_address_t ip_addr

Structure for IP address.

struct tag_rs_tcp_conn_instance
#include <rs_socket.h>

For connection/Client information - to be used for socket_read/write on both sides.

Public Members

void *ptr_cfg

Can have *rs_socket_config_t for client or *tcp_server_instance_t for server.

rs_ip_address_t ip_addr

IP address structure.

uint16_t port_number

Port number.

int32_t valid

Connection validator.

rs_handle_t conn_handle

Handle for connection.

struct tag_rs_tcp_server_instance
#include <rs_socket.h>

Structure for the TCP socket instance information.

Public Members

rs_handle_t socket_handle

Handle for socket.

rs_socket_config_t *ptr_config

Pointer to configuration structure.

rs_tcp_conn_instance_t arr_client_conn_inst[RS_TCP_NUM_CONN_INSTANCE]

Array of connection instances for server.

struct tag_rs_udp_info
#include <rs_socket.h>

For connection/Client information - to be used for socket_read/write on both sides.

Public Members

rs_ip_address_t ip_addr

IP address structure.

uint16_t port_number

Port number.

struct tag_rs_udp_instance
#include <rs_socket.h>

Structure for the UDP socket instance information.

Public Members

rs_handle_t socket_handle

Handle for socket.

rs_socket_config_t *ptr_config

Pointer to configuration structure.

rs_udp_conn_info_t conn_info

UDP response info.