Trait Handler

pub trait Handler {
    // Provided methods
    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_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> { ... }
}

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

Provided Methods

fn on_shutdown(&mut self)

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

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

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

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

Called on incoming messages.

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

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.

fn on_error(&mut self, err: Error)

Called when an error occurs on the WebSocket.

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

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)

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

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.

fn on_frame(&mut self, frame: Frame) -> Result<Option<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.

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

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.

fn build_request(&mut self, url: &Url) -> Result<Request>

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 overriden. 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

impl<F> Handler for F

where F: Fn(Message) -> Result<()>,