RTTP Socket API

The RTTP (Real-Time Transport Protocol) Socket API provides a set of interfaces similar to traditional BSD Sockets, used to implement reliable, low-latency data transmission over UDP. It is specifically designed for application scenarios with extremely high real-time requirements.

Core Concepts

1. RTTP Engine (RTEngine)

The RTTP engine is the heart of the SDK, responsible for managing all connections, timers, and protocol states. Before calling any other API, an engine instance must be created via rt_init.

• Thread Safety: The RTTP engine instance is not thread-safe. Users must ensure that a single engine instance and all its associated sockets are accessed only by the same thread at any given time.

2. RTTP Socket (RTSOCKET)

Similar to a system's native SOCKET, RTSOCKET is an abstraction of a connection. It supports stream transmission and provides reliability guarantees.

3. Callback Mechanism

RTTP uses an asynchronous event-driven model. Users need to register two core callbacks via rt_set_callback:

• Event Callback (RTTP_EVENT_CALLBACK): Notifies status changes of the socket.
  • Signature: void on_event(RTEngine engine, RTSOCKET socket, int event)
  • Event types include: RTTP_EVENT_CONNECT, RTTP_EVENT_READ, RTTP_EVENT_WRITE, RTTP_EVENT_ERROR.
• Packet Send Callback (RTTP_PACKET_SEND_IMP): RTTP delegates low-level UDP transmission to the application. When the protocol stack needs to send a data packet, it calls this callback.
  • Signature: void on_send_packet(RTEngine engine, RTSOCKET socket, const char* data, int len, const struct sockaddr* sa, int sock_len)
  • Users should send the data via the native UDP sendto within this callback.

Basic Workflow

RTTP runs in user space and requires the user to actively drive its operation.

1. Initialization

1. Call rt_init to create the engine.
2. Call rt_set_callback to register callback functions.

2. Main Loop

Users must continuously perform the following operations in their main loop:

1. Receive UDP Data: Use native recvfrom to receive UDP packets and feed them into the RTTP engine via rt_incoming_packet.
2. Drive Protocol Stack: Regularly call rt_tick (recommended every 5-10ms) to handle retransmissions, timeouts, and state updates.
3. Handle Events: Process READ, WRITE, CONNECT, and other events within the registered event callback.

3. Data Transmission

• Sending: Use rt_send to send data. If EAGAIN is returned or the returned length is less than the requested length, wait for a WRITE event.
• Receiving: After receiving a READ event, use rt_recv to read data.

Core API Overview

Function	Description
rt_init	Initializes the engine instance
rt_set_callback	Sets event and send callbacks
rt_socket	Creates an RTTP Socket
rt_connect	Initiates a connection (Client)
rt_accept	Accepts a connection (Server)
rt_send	Sends data
rt_recv	Receives data
rt_incoming_packet	Inputs low-level UDP data packets
rt_tick	Drives protocol stack logic (timers/retransmissions, etc.)
rt_close	Closes the socket
rt_setsockopt	Sets socket options (e.g., transmission mode)

Example Code Snippets

Client Initiates Connection

RTSOCKET client_rtsocket = rt_socket(engine, RTSM_LOW_LATENCY);
rt_connect(engine, client_rtsocket, (const struct sockaddr*)&remote_addr, sizeof(remote_addr));

Server Accepts Connection

// In the receive loop
RTSOCKET s = rt_incoming_packet(engine, buf, len, (const struct sockaddr*)&from_addr, from_len);
if (s != NULL) {
    rt_accept(engine, s);
}

Driving the Engine

while (running) {
    // 1. Handle UDP receive
    int bytes = recvfrom(udp_sock, buf, sizeof(buf), 0, ...);
    if (bytes > 0) {
        rt_incoming_packet(engine, buf, bytes, ...);
    }
    
    // 2. Drive protocol stack logic
    rt_tick(engine);
    
    // 3. Other logic (e.g., select/epoll waiting)
}

Multi-Language SDK

The SDK package provides example applications and full source code for languages such as C++, Java, and C#, and platforms including iOS, Android, and Unity3D. Users can directly integrate the source code from the examples into their own applications.