1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
// Copyright 2015 Nathan Sizemore <nathanrsizemore@gmail.com>
//
// This Source Code Form is subject to the terms of the
// Mozilla Public License, v. 2.0. If a copy of the MPL was not
// distributed with this file, You can obtain one at
// http://mozilla.org/MPL/2.0/.
//! simple-stream is a buffered stream wrapper over anything that implements
//! `std::io::Read` and `std::io::Write`. It works by buffering all reads and
//! checking the buffers against a `FrameBuilder`, which will inform the stream
//! that a complete `Frame` has been received, and removes it out of the buffer.
//!
//! The crate comes with a few types of Framing options, and provides both a plain
//! text and encrypted stream via [rust-openssl][rust-openssl-repo].
//!
//! ## Example Usage
//!
//! ```ignore
//! extern crate simple_stream as ss;
//!
//! use std::net::TcpStream;
//!
//! use ss::frame::{SimpleFrame, SimpleFrameBuilder};
//! use ss::{Plain, NonBlocking};
//!
//!
//! fn main() {
//! // Create some non-blocking type that implements Read + Write
//! let stream = TcpStream::connect("rust-lang.org:80").unwrap();
//! stream.set_nonblocking(true).unwrap();
//!
//! // Create a Plain Text stream that sends and receives messages in the
//! // `SimpleFrame` format.
//! let mut plain_stream = Plain::<TcpStream, SimpleFrameBuilder>::new(stream);
//!
//! // Perform a non-blocking write
//! let buf = vec!(1, 2, 3, 4);
//! let frame = SimpleFrame::new(&buf[..]);
//! match plain_stream.nb_send(&frame) {
//! Ok(_) => { }
//! Err(e) => println!("Error during write: {}", e)
//! };
//!
//! // Perform a non-blocking read
//! match plain_stream.nb_recv() {
//! Ok(frames) => {
//! for _ in frames {
//! // Do stuff with received frames
//! }
//! }
//! Err(e) => println!("Error during read: {}", e)
//! };
//! }
//! ```
//!
//!
//! [rust-openssl-repo]: https://github.com/sfackler/rust-openssl
#[macro_use]
extern crate bitflags;
extern crate libc;
#[macro_use]
extern crate log;
#[cfg(feature = "openssl")]
extern crate openssl;
pub mod frame;
mod plain;
#[cfg(feature = "openssl")]
mod secure;
use std::io;
use frame::Frame;
pub use plain::*;
#[cfg(feature = "openssl")]
pub use secure::*;
/// The `Blocking` trait provides method definitions for use with blocking streams.
pub trait Blocking {
/// Performs a blocking read on the underlying stream until a complete Frame has been read
/// or an `std::io::Error` has occurred.
fn b_recv(&mut self) -> io::Result<Box<dyn Frame>>;
/// Performs a blocking send on the underlying stream until a complete frame has been sent
/// or an `std::io::Error` has occurred.
fn b_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
}
/// The `NonBlocking` trait provides method definitions for use with non-blocking streams.
pub trait NonBlocking {
/// Performs a non-blocking read on the underlying stream until `ErrorKind::WouldBlock` or an
/// `std::io::Error` has occurred.
///
/// # `simple_stream::Secure` notes
///
/// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
/// `ErrorKind::Other` with various OpenSSL error information as strings in the description
/// field of the `std::io::Error`.
fn nb_recv(&mut self) -> io::Result<Vec<Box<dyn Frame>>>;
/// Performs a non-blocking send on the underlying stream until `ErrorKind::WouldBlock` or an
/// `std::io::Error` has occurred.
///
/// # `simple_stream::Secure` notes
///
/// Unlike its blocking counterpart, errors received on the OpenSSL level will be returned as
/// `ErrorKind::Other` with various OpenSSL error information as strings in the description
/// field of the `std::io::Error`.
fn nb_send(&mut self, frame: &dyn Frame) -> io::Result<()>;
}