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 with a trailing call to ->get return Future instances.

send_frame

   $self->send_frame( @args )->get

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

   $self->send_text_frame( $text, %params )->get

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

   $self->send_binary_frame( $bytes, %params )->get

   $self->send_ping_frame( $bytes, %params )->get

   $self->send_pong_frame( $bytes, %params )->get

   $self->send_close_frame( $bytes, %params )->get

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>

cpanm Net::Async::WebSocket

perl -MCPAN -e shell
install Net::Async::WebSocket