Struct udt::UdtSocket

pub struct UdtSocket {
    // some fields omitted
}

A UDT Socket

Internally, a UDT socket is represented as a 32-bit int. As such, a UdtSocket can be copied and cloned

Methods

impl UdtSocket

fn new(address_family: SocketFamily, ty: SocketType) -> Result<UdtSocket, UdtError>

Creates a new UDT Socket.

Creates a new socket. There is no limits for the number of UDT sockets in one system, as long as there is enough system resources. UDT supports both IPv4 and IPv6, which can be selected by the address_family parameter.

Two socket types are supported in UDT: Stream for data streaming and Datagram for messaging. Note that UDT sockets are connection oriented in all cases.

fn bind(&self, name: SocketAddr) -> Result<(), UdtError>

Binds a UDT socket to a known or an available local address.

The bind method is usually to assign a UDT socket a local address, including IP address and port number. If INADDR_ANY is used, a proper IP address will be used once the UDT connection is set up. If 0 is used for the port, a randomly available port number will be used. The method getsockname can be used to retrieve this port number.

The bind call is necessary in all cases except for a socket to listen. If bind is not called, UDT will automatically bind a socket to a randomly available address when a connection is set up.

By default, UDT allows to reuse existing UDP port for new UDT sockets, unless UDT_REUSEADDR is set to false. When UDT_REUSEADDR is false, UDT will create an exclusive UDP port for this UDT socket. UDT_REUSEADDR must be called before bind. To reuse an existing UDT/UDP port, the new UDT socket must explicitly bind to the port. If the port is already used by a UDT socket with UDT_REUSEADDR as false, the new bind will return error. If 0 is passed as the port number, bind always creates a new port, no matter what value the UDT_REUSEADDR sets.

fn bind_from(&self, other: UdpSocket) -> Result<(), UdtError>

Binds a UDT socket to an existing UDP socket.

This second form of bind allows UDT to bind directly on an existing UDP socket. This is usefule for firewall traversing in certain situations: 1) a UDP socket is created and its address is learned from a name server, there is no need to close the UDP socket and open a UDT socket on the same address again; 2) for certain firewall, especially some on local system, the port mapping maybe changed or the "hole" may be closed when a UDP socket is closed and reopened, thus it is necessary to use the UDP socket directly in UDT.

Use the second form of bind with caution, as it violates certain programming rules regarding code robustness. Once the UDP socket descriptor is passed to UDT, it MUST NOT be touched again. DO NOT use this unless you clearly understand how the related systems work.

fn connect(&self, name: SocketAddr) -> Result<(), UdtError>

Connects to a server socket (in regular mode) or a peer socket (in rendezvous mode) to set up a UDT connection

UDT is connection oriented, for both of its Stream and Datagram mode. connect must be called in order to set up a UDT connection. The name parameter is the address of the server or the peer side. In regular (default) client/server mode, the server side must has called bind and listen. In rendezvous mode, both sides must call bind and connect to each other at (approximately) the same time. Rendezvous connect may not be used for more than one connections on the same UDP port pair, in which case UDT_REUSEADDR may be set to false.

UDT connect takes at least one round trip to finish. This may become a bottleneck if applications frequently connect and disconnect to the same address.

When UDT_RCVSYN is set to false, the connect call will return immediately and perform the actual connection setup at background. Applications may use epoll to wait for the connect to complete.

When connect fails, the UDT socket can still be used to connect again. However, if the socket was not bound before, it may be bound implicitly, as mentioned above, even if the connect fails. In addition, in the situation when the connect call fails, the UDT socket will not be automatically released, it is the applications' responsibility to close the socket, if the socket is not needed anymore (e.g., to re-connect).

fn listen(&self, backlog: i32) -> Result<(), UdtError>

Enables a user UDT entity to wait for clients to connect.

The listen method lets a UDT socket enter a listening state. The sock must call bind before a listen call. In addition, if the socket is enabled for rendezvous mode, neither listen nor accept can be used on the socket. A UDT socket can call listen more than once, in which case only the first call is effective, while all subsequent calls will be ignored if the socket is already in the listening state.

backlog specifies the maximum number of pending connections.

fn accept(&self) -> Result<(UdtSocket, SocketAddr), UdtError>

Retrieves an incoming connection.

Once a UDT socket is in listening state, it accepts new connections and maintains the pending connections in a queue. An accept call retrieves the first connection in the queue, removes it from the queue, and returns the associate socket descriptor.

If there is no connections in the queue when accept is called, a blocking socket will wait until a new connection is set up, whereas a non-blocking socket will return immediately with an error.

The accepted sockets will inherit all proper attributes from the listening socket.

Returns

Returns a tuple containing the new UdtSocket and a SockAddr structure containing the address of the new peer

fn close(self) -> Result<(), UdtError>

Close a UDT connection

The close method gracefully shutdowns the UDT connection and releases all related data structures associated with the UDT socket. If there is no connection associated with the socket, close simply release the socket resources.

On a blocking socket, if UDT_LINGER is non-zero, the close call will wait until all data in the sending buffer are sent out or the waiting time has exceeded the expiration time set by UDT_LINGER. However, if UDT_SYNSND is set to false (i.e., non-blocking sending), close will return immediately and any linger data will be sent at background until the linger timer expires.

The closing UDT socket will send a shutdown message to the peer side so that the peer socket will also be closed. This is a best-effort message. If the message is not successfully delivered, the peer side will also be closed after a time-out. In UDT, shutdown is not supported.

All sockets should be closed if they are not used any more.

fn getpeername(&self) -> Result<SocketAddr, UdtError>

Retrieves the address information of the peer side of a connected UDT socket

The getpeername retrieves the address of the peer side associated to the connection. The UDT socket must be connected at the time when this method is called.

fn getsockname(&self) -> Result<SocketAddr, UdtError>

Retrieves the local address associated with a UDT socket.

The getsockname retrieves the local address associated with the socket. The UDT socket must be bound explicitly (via bind) or implicitly (via connect), otherwise this method will fail because there is no meaningful address bound to the socket.

If getsockname is called after an explicit bind, but before connect, the IP address returned will be exactly the IP address that is used for bind and it may be 0.0.0.0 if ADDR_ANY is used. If getsockname is called after connect, the IP address returned will be the address that the peer socket sees. In the case when there is a proxy (e.g., NAT), the IP address returned will be the translated address by the proxy, but not a local address. If there is no proxy, the IP address returned will be a local address. In either case, the port number is local (i.e, not the translated proxy port).

Because UDP is connection-less, using getsockname on a UDP port will almost always return 0.0.0.0 as IP address (unless it is bound to an explicit IP) . As a connection oriented protocol, UDT will return a meaningful IP address by getsockname if there is no proxy translation exist.

UDT has no multihoming support yet. When there are multiple local addresses and more than one of them can be routed to the destination address, UDT may not behave properly due to the multi-path effect. In this case, the UDT socket must be explicitly bound to one of the local addresses.

fn sendmsg(&self, buf: &[u8]) -> Result<i32, UdtError>

Sends a message to the peer side.

The sendmsg method sends a message to the peer side. The UDT socket must be in SOCK_DGRAM mode in order to send or receive messages. Message is the minimum data unit in this situation. In particular, sendmsg always tries to send the message out as a whole, that is, the message will either to completely sent or it is not sent at all.

In blocking mode (default), sendmsg waits until there is enough space to hold the whole message. In non-blocking mode, sendmsg returns immediately and returns error if no buffer space available.

If UDT_SNDTIMEO is set and the socket is in blocking mode, sendmsg only waits a limited time specified by UDT_SNDTIMEO option. If there is still no buffer space available when the timer expires, error will be returned. UDT_SNDTIMEO has no effect for non-blocking socket.

The ttl parameter gives the message a limited life time, which starts counting once the first packet of the message is sent out. If the message has not been delivered to the receiver after the TTL timer expires and each packet in the message has been sent out at least once, the message will be discarded. Lost packets in the message will be retransmitted before TTL expires.

On the other hand, the inorder option decides if this message should be delivered in order. That is, the message should not be delivered to the receiver side application unless all messages prior to it are either delivered or discarded.

Finally, if the message size is greater than the size of the receiver buffer, the message will never be received in whole by the receiver side. Only the beginning part that can be hold in the receiver buffer may be read and the rest will be discarded.

Returns

On success, sendmsg returns the actual size of message that has just been sent. The size should be equal to len. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_SNDTIMEO is set to a positive value, zero will be returned if the message cannot be sent before the timer expires.

fn send(&self, buf: &[u8]) -> Result<i32, UdtError>

Sends out a certain amount of data from an application buffer.

The send method sends certain amount of data from the application buffer. If the the size limit of sending buffer queue is reached, send only sends a portion of the application buffer and returns the actual size of data that has been sent.

In blocking mode (default), send waits until there is some sending buffer space available. In non-blocking mode, send returns immediately and returns error if the sending queue limit is already limited.

If UDT_SNDTIMEO is set and the socket is in blocking mode, send only waits a limited time specified by UDT_SNDTIMEO option. If there is still no buffer space available when the timer expires, error will be returned. UDT_SNDTIMEO has no effect for non-blocking socket.

Returns

On success, returns the actual size of the data that as been sent. Otherwise, a UdtError is returned with specific error information.

If UDT_SNDTIMEO is set to a positive value, zero will be returned if no data is sent before the time expires.

fn recvmsg(&self, buf: &mut [u8]) -> Result<usize, UdtError>

The recvmsg method receives a valid message.

The recvmsg method reads a message from the protocol buffer. The UDT socket must be in SOCK_DGRAM mode in order to send or receive messages. Message is the minimum data unit in this situation. Each recvmsg will read no more than one message, even if the message is smaller than the size of buf and there are more messages available. On the other hand, if the buf is not enough to hold the first message, only part of the message will be copied into the buffer, but the message will still be discarded after this recvmsg call.

In blocking mode (default), recvmsg waits until there is a valid message received into the receiver buffer. In non-blocking mode, recvmsg returns immediately and returns error if no message available.

If UDT_RCVTIMEO is set and the socket is in blocking mode, recvmsg only waits a limited time specified by UDT_RCVTIMEO option. If there is still no message available when the timer expires, error will be returned. UDT_RCVTIMEO has no effect for non-blocking socket.

Returns

On success, recvmsg returns the actual size of received message. Otherwise UDT::ERROR is returned and specific error information can be retrieved by getlasterror. If UDT_RCVTIMEO is set to a positive value, zero will be returned if no message is received before the timer expires.

fn recv(&self, buf: &mut [u8], len: usize) -> Result<i32, UdtError>

Reads a certain amount of data into a local memory buffer.

The recv method reads certain amount of data from the protocol buffer. If there is not enough data in the buffer, recv only reads the available data in the protocol buffer and returns the actual size of data received. However, recv will never read more data than the buffer size indicates by len.

In blocking mode (default), recv waits until there is some data received into the receiver buffer. In non-blocking mode, recv returns immediately and returns error if no data available.

If UDT_RCVTIMEO is set and the socket is in blocking mode, recv only waits a limited time specified by UDT_RCVTIMEO option. If there is still no data available when the timer expires, error will be returned. UDT_RCVTIMEO has no effect for non-blocking socket.

fn getsockopt<B: Default, T: UdtOption<B>>(&self, opt: T) -> Result<B, UdtError>

Gets UDT options

See the UdtOpts module for all the supported option types.

Example

use udt::*;

let sock = UdtSocket::new(SocketFamily::AFInet, SocketType::Stream).unwrap();
let recv_buf: i32 = sock.getsockopt(UdtOpts::UDP_RCVBUF).unwrap();

fn setsockopt<B, T: UdtOption<B>>(&self, opt: T, value: B) -> Result<(), UdtError>

Sets UDT options

See the UdtOpts module for all the supported option types.

fn getstate(&self) -> UdtStatus

Trait Implementations

impl Hash for UdtSocket

fn hash<__H: Hasher>(&self, __arg_0: &mut __H)

Feeds this value into the state given, updating the hasher as necessary.

fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher

Feeds a slice of this type into the state provided.

impl Clone for UdtSocket

fn clone(&self) -> UdtSocket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for UdtSocket

impl Eq for UdtSocket

impl PartialEq for UdtSocket

fn eq(&self, __arg_0: &UdtSocket) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &UdtSocket) -> bool

This method tests for !=.

impl Debug for UdtSocket

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.