The rt_init function initialize utp stack. This function should be called before other functions.
int rt_init(const char* str, int len);
str: Reserved for later use, should be NULL.
len: Reserved for later use, should be zero.
rt_init returns utp version number.
The rt_set_callback set call back functions to utp library.
void rt_set_callback(socket_event_callback *event_callback, send_data_callback *sendproc);
event_callback: A function pointer which is used to notify utp socket event.
void socket_event_callback(RTSOCKET socket, int event)
| Event | Type | Meaning |
|---|---|---|
| RTTP_EVENT_CONNECT | int32 | Socket connected |
| RTTP_EVENT_READ | int32 | Data readable on socket |
| RTTP_EVENT_WRITE | int32 | Socket is writable now |
| RTTP_EVENT_ERROR | int32 | Error happened on socket |
sendproc: A function pointer which is used to send packet generated by utp library.
void send_proc(RTSOCKET socket, const char * buffer, int len, const char* addr, int addr_len)
This function has no return value.
The rt_socket function create a utp socket
RTSOCKET rt_socket(int mode);
mode: Reserved for later use.
If no error occurs, rt_socket returns a descriptor referencing the new utp socket.
The rt_connect function attempts to establish a connection to a specified socket. This function does not wait for the establish of connection.
int rt_connect(RTSOCKET s, const char *to, int tolen);
s: A descriptor identifying an unconnected socket returned by rt_socket function.
to: Remote address to which the connection should be established, utp saves this address and passes it back when call send_proc callback to send data.
tolen: Length of address, in bytes.
If no error occurs, rt_connect returns 0, otherwise it returns a error code.
The rt_recv function receives data from a connected utp socket.
int rt_recv(RTSOCKET s, char * buffer, int len, int flag);
s: A descriptor identifying a connected utp socket.
buffer: A pointer to the buffer to receive the incoming data.
len: The length, in bytes, of the buffer pointed to by the buffer parameter.
flag: Reserved for later use.
If no error occurs, rt_recv returns the number of bytes received and the buffer pointed to by the buffer parameter will contain this data received. If the connection has been gracefully closed, the return value is zero. If there is no data available, the return value is -1. If error occurs the return value is a negative error code.
The rt_send function sends data on a connected socket.
int rt_send(RTSOCKET s, const char * buffer, int len, int flag);
s: A descriptor identifying a connected utp socket.
buffer: A pointer to a buffer containing the data to be transmitted.
len: The length, in bytes, of the buffer pointed to by the buffer parameter.
flag: Reserved for later use.
If no error occurs, send returns the total number of bytes sent, which can be less than the number requested to be sent in the len parameter. If no data can be sent the return value is -1 which means the requested operation would block. If error occurs the return value is a negative error code.
Avoid to send data one byte by one byte which is very inefficient.
The rt_close function closes an existing socket.
void rt_close(RTSOCKET s);
s: A descriptor identifying the utp socket to close.
This function has no return value.
The rt_incoming_packet function input a packet to utp library. Rttp does not send and receive data itself which allows utp to keep out of socket io framework and ease to integrate.
RTSOCKET rt_incoming_packet(const char * buffer, int len, const char from, int fromlen, void userdata);
buffer: A pointer to a buffer containing the data
len: data length in bytes
from: The address which the incoming packet comes from
fromlen: The address length, in bytes.
userdata: The userdata will be set to utp socket when the utp socket is a incoming connection.
The return value is the new created utp socket descriptor if there is a incoming utp connection, otherwise the return value is 0.
The rt_tick function inputs a timer event to utp library. This function should be called periodically. The recommended time interval should be less than 20 ms.
void rt_tick();
This function has no parameter.
This function has no return value.
The rt_getpeername function retrieves the address of the peer to which a socket is connected.
int rt_getpeername(RTSOCKET s, char* name, int len)
s: A descriptor identifying the utp socket
name: A pointer to the buffer to receive the address which is identical with the parameter of rt_connect and rt_incoming_packet
len: The length, in bytes, of the buffer pointed to by the name parameter.
If len is smaller than the address size the return value is -1, otherwise the function returns the number of bytes copied.
The rt_get_error function returns the error status of utp socket.
int rt_get_error(RTSOCKET s);
s: A descriptor identifying the utp socket
The return value is the error code.
The rt_connected function determines whether the utp socket connection is established with remote
int rt_connected(RTSOCKET s);
s:
A descriptor identifying the utp socket
rt_connected return 1 if connected, otherwise the return value is 0
The rt_writable function determines whether rt_write will block on the utp socket
int rt_writable(RTSOCKET s);
s:
A descriptor identifying the utp socket
rt_writable return 1 if block will not happen, otherwise the return value is 0
The rt_readable function determines the incoming data status of utp socket
int rt_readable(RTSOCKET s);
s:
A descriptor identifying the utp socket
The rt_readable function returns 1 if there is data waiting for receiving in buffer and recv would not block, otherwise the return value is 0
The rt_setsockopt function sets a socket option.
int rt_setsockopt(RTSOCKET s, int optname, void *optval, int optlen);
s:
A descriptor identifying the utp socket
optname:
The utp socket option for which the value is to be set
| Value | Type | Meaning |
|---|---|---|
| RTSO_MTU | int32 | MTU |
| RTSO_FEC | int32 | Enable FEC or not |
| RTSO_FAST_ACK | int32 | Enable fast ack or not |
| RTSO_RCVBUF | int32 | Max utp socket recv buffer |
| RTSO_MODE | int32 | Rttp mode |
optval:
A pointer to the buffer in which the value for the requested option is specified.
optlen: The size, in bytes, of the buffer pointed to by the optval parameter.
If no error occurs, rt_setsockopt returns zero, otherwise the return value is -1.
The rt_getsockopt function sets a socket option.
int rt_getsockopt(RTSOCKET s, int optname, void *optval, int optlen);
s:
A descriptor identifying the utp socket
optname:
The utp socket option for which the value is to be retrieved
| Value | Type | Meaning |
|---|---|---|
| RTSO_MTU | int32 | MTU |
| RTSO_FEC | int32 | FEC enabled or not |
| RTSO_FAST_ACK | int32 | Fast ack enabled or not |
| RTSO_RCVBUF | int32 | Max utp socket recv buffer |
| RTSO_RTT | int64 | Round trip time, in micro seconds |
| RTSO_LOST_RATE | int32 | Packet lost percent since connection |
| RTSO_RECENT_LOST_RATE | int32 | Packet lost percent in recent 3 seconds |
optval:
A pointer to the buffer in which the value for the requested option is to be returned
optlen:
A pointer to the size, in bytes, of the optval buffer
If no error occurs, rt_setsockopt returns size of value saved in optval, otherwise the return value is -1.
The rt_set_userdata function sets a data to utp socket which can be retrieved later by rt_get_userdata function
void rt_set_userdata(RTSOCKET s, void *userdata);
s: A descriptor identifying the utp socket
userdata: data set to utp socket.
This function has no return value.
The rt_get_userdata function retrieves user data associated with utp socket
void* rt_get_userdata(RTSOCKET s);
s: A descriptor identifying the utp socket
rt_get_userdata returns user data set by rt_set_userdata function.
The rt_uninit function uninit utp stack.
void rt_uninit();
This function has no parameter.
This function has no return value.