Trait parity_ws::Handler

source · [−]
pub trait Handler {
    fn on_shutdown(&mut self) { ... }

    fn on_open(&mut self, shake: Handshake) -> Result<()> { ... }

    fn on_message(&mut self, msg: Message) -> Result<()> { ... }

    fn on_close(&mut self, code: CloseCode, reason: &str) { ... }

    fn on_error(&mut self, err: Error) { ... }

    fn on_request(&mut self, req: &Request) -> Result<Response> { ... }

    fn on_response(&mut self, res: &Response) -> Result<()> { ... }

    fn on_timeout(&mut self, event: Token) -> Result<()> { ... }

    fn on_new_timeout(&mut self, _: Token, _: Timeout) -> Result<()> { ... }

    fn on_frame(&mut self, frame: Frame) -> Result<Option<Frame>> { ... }

    fn on_send_frame(&mut self, frame: Frame) -> Result<Option<Frame>> { ... }

    fn build_request(&mut self, url: &Url) -> Result<Request> { ... }
}
Expand description

The core trait of this library. Implementing this trait provides the business logic of the WebSocket application.

Provided methods

Called when a request to shutdown all connections has been received.

Called when the WebSocket handshake is successful and the connection is open for sending and receiving messages.

Called on incoming messages.

Called any time this endpoint receives a close control frame. This may be because the other endpoint is initiating a closing handshake, or it may be the other endpoint confirming the handshake initiated by this endpoint.

Called when an error occurs on the WebSocket.

A method for handling the low-level workings of the request portion of the WebSocket handshake.

Implementors should select a WebSocket protocol and extensions where they are supported.

Implementors can inspect the Request and must return a Response or an error indicating that the handshake failed. The default implementation provides conformance with the WebSocket protocol, and implementors should use the Response::from_request method and then modify the resulting response as necessary in order to maintain conformance.

This method will not be called when the handler represents a client endpoint. Use build_request to provide an initial handshake request.

Examples
ⓘ
let mut res = try!(Response::from_request(req));
if try!(req.extensions()).iter().find(|&&ext| ext.contains("myextension-name")).is_some() {
    res.add_extension("myextension-name")
}
Ok(res)

A method for handling the low-level workings of the response portion of the WebSocket handshake.

Implementors can inspect the Response and choose to fail the connection by returning an error. This method will not be called when the handler represents a server endpoint. The response should indicate which WebSocket protocol and extensions the server has agreed to if any.

Called when a timeout is triggered.

This method will be called when the eventloop encounters a timeout on the specified token. To schedule a timeout with your specific token use the Sender::timeout method.

Examples
ⓘ
const GRATI: Token = Token(1);

... Handler

fn on_open(&mut self, _: Handshake) -> Result<()> {
    // schedule a timeout to send a gratuitous pong every 5 seconds
    self.ws.timeout(5_000, GRATI)
}

fn on_timeout(&mut self, event: Token) -> Result<()> {
    if event == GRATI {
        // send gratuitous pong
        try!(self.ws.pong(vec![]))
        // reschedule the timeout
        self.ws.timeout(5_000, GRATI)
    } else {
        Err(Error::new(ErrorKind::Internal, "Invalid timeout token encountered!"))
    }
}

Called when a timeout has been scheduled on the eventloop.

This method is the hook for obtaining a Timeout object that may be used to cancel a timeout. This is a noop by default.

Examples
ⓘ
const PING: Token = Token(1);
const EXPIRE: Token = Token(2);

... Handler

fn on_open(&mut self, _: Handshake) -> Result<()> {
    // schedule a timeout to send a ping every 5 seconds
    try!(self.ws.timeout(5_000, PING));
    // schedule a timeout to close the connection if there is no activity for 30 seconds
    self.ws.timeout(30_000, EXPIRE)
}

fn on_timeout(&mut self, event: Token) -> Result<()> {
    match event {
        PING => {
            self.ws.ping(vec![]);
            self.ws.timeout(5_000, PING)
        }
        EXPIRE => self.ws.close(CloseCode::Away),
        _ => Err(Error::new(ErrorKind::Internal, "Invalid timeout token encountered!")),
    }
}

fn on_new_timeout(&mut self, event: Token, timeout: Timeout) -> Result<()> {
    if event == EXPIRE {
        if let Some(t) = self.timeout.take() {
            try!(self.ws.cancel(t))
        }
        self.timeout = Some(timeout)
    }
    Ok(())
}

fn on_frame(&mut self, frame: Frame) -> Result<Option<Frame>> {
    // some activity has occurred, let's reset the expiration
    try!(self.ws.timeout(30_000, EXPIRE));
    Ok(Some(frame))
}

A method for handling incoming frames.

This method provides very low-level access to the details of the WebSocket protocol. It may be necessary to implement this method in order to provide a particular extension, but incorrect implementation may cause the other endpoint to fail the connection.

Returning Ok(None) will cause the connection to forget about a particular frame. This is useful if you want ot filter out a frame or if you don’t want any of the default handler methods to run.

By default this method simply ensures that no reserved bits are set.

A method for handling outgoing frames.

This method provides very low-level access to the details of the WebSocket protocol. It may be necessary to implement this method in order to provide a particular extension, but incorrect implementation may cause the other endpoint to fail the connection.

Returning Ok(None) will cause the connection to forget about a particular frame, meaning that it will not be sent. You can use this approach to merge multiple frames into a single frame before sending the message.

For messages, this method will be called with a single complete, final frame before any fragmentation is performed. Automatic fragmentation will be performed on the returned frame, if any, based on the fragment_size setting.

By default this method simply ensures that no reserved bits are set.

A method for creating the initial handshake request for WebSocket clients.

The default implementation provides conformance with the WebSocket protocol, but this method may be overridden. In order to facilitate conformance, implementors should use the Request::from_url method and then modify the resulting request as necessary.

Implementors should indicate any available WebSocket extensions here.

Examples
ⓘ
let mut req = try!(Request::from_url(url));
req.add_extension("permessage-deflate; client_max_window_bits");
Ok(req)

Implementors