Variants

• GenericConnectErr(~str, ~str) - Some unplanned-for error. The first and second fields correspond to libuv's err_name and err_msg fields, respectively.

• ConnectionRefused - Invalid IP or invalid port

Variants

• GenericListenErr(~str, ~str) - Some unplanned-for error. The first and second fields correspond to libuv's err_name and err_msg fields, respectively.

• AddressInUse - Failed to bind to the requested IP/Port, because it is already in use.

  Possible Causes

  • Attempting to bind to a port already bound to another listener

• AccessDenied - Request to bind to an IP/Port was denied by the system.

  Possible Causes

  • Attemping to binding to an IP/Port as a non-Administrator on Windows Vista+
  • Attempting to bind, as a non-priv'd user, to 'privileged' ports (< 1024) on *nix

Method drop

fn drop(&self)

Method read_start

fn read_start(&self) ->
 result::Result<@Port<result::Result<~[u8], TcpErrData>>, TcpErrData>

Method read_stop

fn read_stop(&self) -> result::Result<(), TcpErrData>

Method read

fn read(&self, timeout_msecs: uint) -> result::Result<~[u8], TcpErrData>

Method read_future

fn read_future(&self, timeout_msecs: uint) ->
 future::Future<result::Result<~[u8], TcpErrData>>

Method write

fn write(&self, raw_write_data: ~[u8]) -> result::Result<(), TcpErrData>

Method write_future

fn write_future(&self, raw_write_data: ~[u8]) ->
 future::Future<result::Result<(), TcpErrData>>

Method get_peer_addr

fn get_peer_addr(&self) -> ip::IpAddr

Method read

fn read(&self, buf: &mut [u8], len: uint) -> uint

Method read_byte

fn read_byte(&self) -> int

Method eof

fn eof(&self) -> bool

Method seek

fn seek(&self, dist: int, seek: io::SeekStyle)

Method tell

fn tell(&self) -> uint

Method write

fn write(&self, data: &[u8])

Method seek

fn seek(&self, dist: int, seek: io::SeekStyle)

Method tell

fn tell(&self) -> uint

Method flush

fn flush(&self) -> int

Method get_type

fn get_type(&self) -> io::WriterType

Method to_tcp_err

fn to_tcp_err(&self) -> TcpErrData

Notes

It is safe to call net::tcp::accept only within the context of the new_connect_cb callback provided as the final argument to the net::tcp::listen function.

The new_conn opaque value is provided only as the first argument to the new_connect_cb provided as a part of net::tcp::listen. It can be safely sent to another task but it must be used (via net::tcp::accept) before the new_connect_cb call it was provided to returns.

This implies that a port/chan pair must be used to make sure that the new_connect_cb call blocks until an attempt to create a net::tcp::TcpSocket is completed.

Example

Here, the new_conn is used in conjunction with accept from within a task spawned by the new_connect_cb passed into listen

do net::tcp::listen(remote_ip, remote_port, backlog, iotask,
    // this callback is ran once after the connection is successfully
    // set up
    |kill_ch| {
      // pass the kill_ch to your main loop or wherever you want
      // to be able to externally kill the server from
    })
    // this callback is ran when a new connection arrives
    |new_conn, kill_ch| {
    let (cont_po, cont_ch) = comm::stream::<option::Option<TcpErrData>>();
    do task::spawn {
        let accept_result = net::tcp::accept(new_conn);
        match accept_result {
            Err(accept_error) => {
                cont_ch.send(Some(accept_error));
                // fail?
            },
            Ok(sock) => {
                cont_ch.send(None);
                // do work here
            }
        }
    };
    match cont_po.recv() {
      // shut down listen()
      Some(err_data) => kill_ch.send(Some(err_data)),
      // wait for next connection
      None => ()
    }
};

Arguments

• new_conn - an opaque value used to create a new TcpSocket

Returns

On success, this function will return a net::tcp::TcpSocket as the Ok variant of a Result. The net::tcp::TcpSocket is anchored within the task that accept was called within for its lifetime. On failure, this function will return a net::tcp::TcpErrData record as the Err variant of a Result.

Arguments

• input_ip - The IP address (versions 4 or 6) of the remote host
• port - the unsigned integer of the desired remote host port
• iotask - a uv::iotask that the tcp request will run on

Returns

A result that, if the operation succeeds, contains a net::net::TcpSocket that can be used to send and receive data to/from the remote host. In the event of failure, a net::tcp::TcpConnectErrData instance will be returned

Arguments

• host_ip - a net::ip::IpAddr representing a unique IP (versions 4 or 6)
• port - a uint representing the port to listen on
• backlog - a uint representing the number of incoming connections to cache in memory
• hl_loop - a uv_iotask::IoTask that the tcp request will run on
• on_establish_cb - a callback that is evaluated if/when the listener is successfully established. it takes no parameters
• new_connect_cb - a callback to be evaluated, on the libuv thread, whenever a client attempts to conect on the provided ip/port. the callback's arguments are:
  • new_conn - an opaque type that can be passed to net::tcp::accept in order to be converted to a TcpSocket.
  • kill_ch - channel of type std::comm::Chan<Option<tcp_err_data>>. this channel can be used to send a message to cause listen to begin closing the underlying libuv data structures.

returns

a Result instance containing empty data of type () on a successful/normal shutdown, and a TcpListenErrData enum in the event of listen exiting because of an error

Arguments

• sock - a net::tcp::TcpSocket that you wish to read from
• timeout_msecs - a uint value, in msecs, to wait before dropping the read attempt. Pass 0u to wait indefinitely

Arguments

• sock -- a net::tcp::TcpSocket for the connection to read from

Returns

• A Result instance that will either contain a std::comm::Port<Result<~[u8], TcpErrData>> that the user can read (and * optionally, loop on) from until read_stop is called, or a TcpErrData record

Arguments

• sock - a net::tcp::TcpSocket that you wish to stop reading on

Arguments

• sock -- a net::tcp::TcpSocket that you want to buffer

Returns

A buffered wrapper that you can cast as an io::Reader or io::Writer

Arguments

• sock - a TcpSocket to write to
• raw_write_data - a vector of ~[u8] that will be written to the stream. This value must remain valid for the duration of the write call

Returns

A Result object with a () value as the Ok variant, or a TcpErrData value as the Err variant

Safety

This function can produce unsafe results if:

1. the call to write_future is made
2. the future::Future value returned is never resolved via Future::get
3. and then the TcpSocket passed in to write_future leaves scope and is destructed before the task that runs the libuv write operation completes.

As such: If using write_future, always be sure to resolve the returned Future so as to ensure libuv doesn't try to access a released write handle. Otherwise, use the blocking tcp::write function instead.

Arguments

• sock - a TcpSocket to write to
• raw_write_data - a vector of ~[u8] that will be written to the stream. This value must remain valid for the duration of the write call

Returns

A Future value that, once the write operation completes, resolves to a Result object with a nil value as the Ok variant, or a TcpErrData value as the Err variant