[−][src]Struct brokaw::client::NntpClient

pub struct NntpClient { /* fields omitted */ }

A client that returns typed responses and provides state management

NntpClient is built on top of NntpConnection and offers several niceties:

  1. Responses from the server are typed and semantically validated
  2. Management of the connection state (e.g. current group, known capabilities)

In exchange for these niceties, NntpClient does not provide the low-allocation guarantees that NntpConnection does. If you are really concerned about memory management, you may want to use the NntpConnection.

Implementations

impl NntpClient[src]

pub fn conn(&mut self) -> &mut NntpConnection[src]

Get the raw NntpConnection for the client

Usage

NNTP is a STATEFUL PROTOCOL and misusing the underlying connection may mess up the state in the client that owns the connection.

For example, manually sending a GROUP command would leave change the group of the connection but will not update the NntpClient's internal record.

Caveat emptor!

pub fn command(&mut self, c: impl NntpCommand) -> Result<RawResponse>[src]

Send a command

This is useful if you want to use a command you have implemented or one that is not provided by a client method

Example

Say we have a server that uses mode switching for whatever reason. Brokaw implements a ModeReader command but it does not provide a return type. We implement one in the following example

MOTD 
use std::convert::{TryFrom, TryInto};
use brokaw::types::prelude::*;
use brokaw::types::command as cmd;

struct Motd {
    posting_allowed: bool,
    motd: String,
}

impl TryFrom<RawResponse> for Motd {
    type Error = String;

    fn try_from(resp: RawResponse) -> Result<Self, Self::Error> {
        let posting_allowed = match resp.code() {
            ResponseCode::Known(Kind::PostingAllowed) => true,
            ResponseCode::Known(Kind::PostingNotPermitted) => false,
            ResponseCode::Known(Kind::PermanentlyUnavailable) => {
                return Err("Server is gone forever".to_string());
            }
            ResponseCode::Known(Kind::TemporarilyUnavailable) => {
                return Err("Server is down?".to_string());
            }
            code => return Err(format!("Unexpected {:?}", code))
        };
        let mut motd = String::from_utf8_lossy(resp.first_line_without_code())
            .to_string();

        Ok(Motd { posting_allowed, motd })
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    use brokaw::client::{NntpClient, ClientConfig};
    let mut client = ClientConfig::default()
        .connect(("news.modeswitching.notreal", 119))?;

    let resp: Motd = client.command(cmd::ModeReader)?.try_into()?;
    println!("Motd: {}", resp.motd);
    Ok(())
}

pub fn config(&self) -> &ClientConfig[src]

Get the currently selected group

pub fn group(&self) -> Option<&Group>[src]

Get the last selected group

pub fn select_group(&mut self, name: impl AsRef<str>) -> Result<Group>[src]

Select a newsgroup

pub fn capabilities(&self) -> &Capabilities[src]

The capabilities cached in the client

pub fn update_capabilities(&mut self) -> Result<&Capabilities>[src]

Retrieve updated capabilities from the server

pub fn article(&mut self, article: Article) -> Result<BinaryArticle>[src]

Retrieve an article from the server

Text Articles

Binary articles can be converted to text using the to_text and to_text_lossy methods. Note that the former is fallible as it will validate that the body of the article is UTF-8.

use brokaw::client::NntpClient;
use brokaw::error::Result;
use brokaw::types::prelude::*;
use brokaw::types::command::Article;

fn checked_conversion(client: &mut NntpClient) -> Result<TextArticle> {
    client.article(Article::Number(42))
        .and_then(|b| b.to_text())
}

fn lossy_conversion(client: &mut NntpClient) -> Result<TextArticle> {
    client.article(Article::Number(42))
        .map(|b| b.to_text_lossy())
}

pub fn body(&mut self, body: Body) -> Result<Body>[src]

Retrieve the body for an article

pub fn head(&mut self, head: Head) -> Result<Head>[src]

Retrieve the headers for an article

pub fn stat(&mut self, stat: Stat) -> Result<Option<Stat>>[src]

Retrieve the status of an article

pub fn close(&mut self) -> Result<RawResponse>[src]

Close the connection to the server

Trait Implementations

impl Debug for NntpClient[src]

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.