Net::Async::WebSocket::Protocol(3pm)

NAME
"Net::Async::WebSocket::Protocol" - send and receive WebSocket frames

DESCRIPTION
This subclass of IO::Async::Stream implements an established WebSocket connection, that has already completed its setup handshaking and is ready to pass frames.

Objects of this type would not normally be constructed directly. For WebSocket clients, see Net::Async::WebSocket::Client, which is a subclass of this. For WebSocket servers, see Net::Async::WebSocket::Server, which constructs objects in this class when it accepts a new connection and passes it to its event handler.

EVENTS
The following events are invoked, either using subclass methods or CODE references in parameters:

  on_text_frame
   $self->on_text_frame( $text );
   $on_text_frame->( $self, $text );

Invoked when a text frame is received. It is passed a Unicode character string formed by decoding the received UTF-8 bytes.

  on_frame
   $self->on_frame( $text );
   $on_frame->( $self, $text );

A synonym for "on_text_frame", provided for backward compatibility.

This may be removed in a later version.

  on_binary_frame, on_ping_frame, on_pong_frame, on_close_frame
   $self->on_..._frame( $bytes );
   $on_..._frame->( $self, $bytes );

Invoked when other types of frame are received. These will be passed plain byte strings.

  on_raw_frame
   $self->on_raw_frame( $frame, $bytes );
   $on_raw_frame->( $self, $frame, $bytes );

Invoked when a frame is received that does not have a specific handler defined of one of the above types. $frame will be an instance of Protocol::WebSocket::Frame.

PARAMETERS
The following named parameters may be passed to "new" or "configure":

on_frame => CODE
on_text_frame => CODE
on_binary_frame, on_ping_frame, on_pong_frame, on_close_frame => CODE
on_raw_frame => CODE
    CODE references for event handlers.

masked => BOOL
    Whether frames constructed and sent by this instance will be masked.

METHODS
The following methods documented in an "await" expression return Future instances.

  send_frame
   await $self->send_frame( @args );

Sends a frame to the peer containing containing the given string. The arguments are passed to Protocol::WebSocket::Frame's "new" method.

This method is discouraged in favour of the more specific ones listed below, and is only provided for back-compatibility or for sending new frame types not recognised by the specific methods.

  send_text_frame
   await $self->send_text_frame( $text, %params );

Sends a text frame to the peer. The given string will be treated as a Unicode character string, and sent as UTF-8 encoded bytes.

Any additional arguments will be passed as parameters to the underlying "write" in IO::Async::Stream call.

  send_TYPE_frame
   await $self->send_binary_frame( $bytes, %params );

   await $self->send_ping_frame( $bytes, %params );

   await $self->send_pong_frame( $bytes, %params );

   await $self->send_close_frame( $bytes, %params );

Sends a frame of the given type to the peer.

Any additional arguments will be passed as parameters to the underlying "write" in IO::Async::Stream call.

AUTHOR
Paul Evans <leonerd@leonerd.org.uk>