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>