[−][src]Trait ws::Handler

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> { ... }
}

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

ⓘThis example is not tested
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_timeout(&mut self, event: Token) -> Result<()>

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

ⓘThis example is not tested
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!"))
    }
}

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

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

ⓘThis example is not tested
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))
}

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

ⓘThis example is not tested
let mut req = try!(Request::from_url(url));
req.add_extension("permessage-deflate; client_max_window_bits");
Ok(req)
Loading content...

Implementors

impl<F> Handler for F where
    F: Fn(Message) -> Result<()>, [src]

Loading content...