Improve documentation.

Signed-off-by: Alexey Galakhov <agalakhov@snapview.de>
pull/7/head
Alexey Galakhov 8 years ago
parent b057cf0096
commit e2b7b73e72
  1. 2
      Cargo.toml
  2. 17
      src/client.rs
  3. 2
      src/handshake/mod.rs
  4. 2
      src/protocol/frame/coding.rs
  5. 2
      src/protocol/frame/mod.rs
  6. 7
      src/protocol/mod.rs
  7. 9
      src/server.rs
  8. 6
      src/stream.rs
  9. 2
      src/util.rs

@ -6,6 +6,8 @@ keywords = ["websocket", "io", "web"]
authors = ["Alexey Galakhov"]
license = "MIT"
readme = "README.md"
homepage = "https://github.com/snapview/tungstenite-rs"
documentation = "https://docs.rs/tungstenite"
repository = "https://github.com/snapview/tungstenite-rs"
version = "0.1.1"

@ -1,3 +1,5 @@
//! Methods to connect to an WebSocket as a client.
use std::net::{TcpStream, SocketAddr, ToSocketAddrs};
use std::result::Result as StdResult;
use std::io::{Read, Write};
@ -25,6 +27,14 @@ pub type AutoStream = TcpStream;
///
/// The URL may be either ws:// or wss://.
/// To support wss:// URLs, feature "tls" must be turned on.
///
/// This function "just works" for those who wants a simple blocking solution
/// similar to `std::net::TcpStream`. If you want a non-blocking or other
/// custom stream, call `client` instead.
///
/// This function uses `native_tls` to do TLS. If you want to use other TLS libraries,
/// use `client` instead. There is no need to enable the "tls" feature if you don't call
/// `connect` since it's the only function that uses native_tls.
pub fn connect(url: Url) -> Result<WebSocket<AutoStream>> {
let mode = url_mode(&url)?;
let addrs = url.to_socket_addrs()?;
@ -77,7 +87,8 @@ fn connect_to_some<A>(addrs: A, url: &Url, mode: Mode) -> Result<AutoStream>
/// Get the mode of the given URL.
///
/// This function may be used in non-blocking implementations.
/// This function may be used to ease the creation of custom TLS streams
/// in non-blocking algorithmss or for use with TLS libraries other than `native_tls`.
pub fn url_mode(url: &Url) -> Result<Mode> {
match url.scheme() {
"ws" => Ok(Mode::Plain),
@ -88,7 +99,9 @@ pub fn url_mode(url: &Url) -> Result<Mode> {
/// Do the client handshake over the given stream.
///
/// Use this function if you need a nonblocking handshake support.
/// Use this function if you need a nonblocking handshake support or if you
/// want to use a custom stream like `mio::tcp::TcpStream` or `openssl::ssl::SslStream`.
/// Any stream supporting `Read + Write` will do.
pub fn client<Stream: Read + Write>(url: Url, stream: Stream)
-> StdResult<WebSocket<Stream>, HandshakeError<Stream, ClientHandshake>>
{

@ -1,3 +1,5 @@
//! WebSocket handshake control.
pub mod headers;
pub mod client;
pub mod server;

@ -1,3 +1,5 @@
//! Various codes defined in RFC 6455.
use std::fmt;
use std::convert::{Into, From};

@ -1,3 +1,5 @@
//! Utilities to work with raw WebSocket frames.
pub mod coding;
mod frame;

@ -1,4 +1,4 @@
//! Generic WebSocket protocol implementation
//! Generic WebSocket message stream.
pub mod frame;
@ -25,7 +25,10 @@ pub enum Role {
Client,
}
/// WebSocket input-output stream
/// WebSocket input-output stream.
///
/// This is THE structure you want to create to me able to talk the WebSocket protocol.
/// It may be created by calling `connect`, `accept` or `client` functions.
pub struct WebSocket<Stream> {
/// Server or client?
role: Role,

@ -1,3 +1,5 @@
//! Methods to accept an incoming WebSocket connection on a server.
pub use handshake::server::ServerHandshake;
use handshake::HandshakeError;
@ -5,7 +7,12 @@ use protocol::WebSocket;
use std::io::{Read, Write};
/// Accept the given TcpStream as a WebSocket.
/// Accept the given Stream as a WebSocket.
///
/// This function starts a server WebSocket handshake over the given stream.
/// If you want TLS support, use `native_tls::TlsStream` or `openssl::ssl::SslStream`
/// for the stream here. Any `Read + Write` streams are supported, including
/// those from `Mio` and others.
pub fn accept<Stream: Read + Write>(stream: Stream)
-> Result<WebSocket<Stream>, HandshakeError<Stream, ServerHandshake>>
{

@ -1,3 +1,9 @@
//! Convenience wrapper for streams to switch between plain TCP and TLS at runtime.
//!
//! There is no dependency on actual TLS implementations. Everything like
//! `native_tls` or `openssl` will work as long as there is a TLS stream supporting standard
//! `Read + Write` traits.
use std::io::{Read, Write, Result as IoResult};
/// Stream mode, either plain TCP or TLS.

@ -1,3 +1,5 @@
//! Helper traits to ease non-blocking handling.
use std::io::{Error as IoError, ErrorKind as IoErrorKind};
use std::result::Result as StdResult;

Loading…
Cancel
Save