NAME

AnyEvent::WebSocket::Connection - WebSocket connection for AnyEvent

VERSION

version 0.44

SYNOPSIS

 # send a message through the websocket...
 $connection->send('a message');
 
 # recieve message from the websocket...
 $connection->on(each_message => sub {
   # $connection is the same connection object
   # $message isa AnyEvent::WebSocket::Message
   my($connection, $message) = @_;
   ...
 });
 
 # handle a closed connection...
 $connection->on(finish => sub {
   # $connection is the same connection object
   my($connection) = @_;
   ...
 });
 
 # close an opened connection
 # (can do this either inside or outside of
 # a callback)
 $connection->close;

(See AnyEvent::WebSocket::Client or AnyEvent::WebSocket::Server on how to create a connection)

DESCRIPTION

This class represents a WebSocket connection with a remote server or a client.

If the connection object falls out of scope then the connection will be closed gracefully.

This class was created for a client to connect to a server via AnyEvent::WebSocket::Client, and was later extended to work on the server side via AnyEvent::WebSocket::Server. Once a WebSocket connection is established, the API for both client and server is identical.

ATTRIBUTES

handle

The underlying AnyEvent::Handle object used for the connection. WebSocket handshake MUST be already completed using this handle. You should not use the handle directly after creating AnyEvent::WebSocket::Connection object.

Usually only useful for creating server connections, see below.

masked

If set to true, it masks outgoing frames. The default is false.

subprotocol

The subprotocol returned by the server. If no subprotocol was requested, it may be "undef".

max_payload_size

The maximum payload size for received frames. Currently defaults to whatever Protocol::WebSocket defaults to.

close_code

If provided by the other side, the code that was provided when the connection was closed.

close_reason

If provided by the other side, the reason for closing the connection.

close_error

If the connection is closed due to a network error, this will hold the message.

METHODS

send

 $connection->send($message);

Send a message to the other side. $message may either be a string (in which case a text message will be sent), or an instance of AnyEvent::WebSocket::Message.

on

 $connection->on(each_message => $cb);
 $connection->on(each_message => $cb);
 $connection->on(finish => $cb);

For each event $connection is the AnyEvent::WebSocket::Connection and and $message is an AnyEvent::WebSocket::Message (if available).

Returns a coderef that unregisters the callback when invoked.

 my $cancel = $connection->on( each_message => sub { ...  });
 
 # later on...
 $cancel->();

each_message

 $cb->($connection, $message, $unregister)

Called each time a message is received from the WebSocket. $unregister is a coderef that removes this callback from the active listeners when invoked.

next_message

 $cb->($connection, $message)

Called only for the next message received from the WebSocket.

parse_error

 $cb->($connection, $text_error_message)

Called if there is an error parsing a message sent from the remote end. After this callback is called, the connection will be closed. Among other possible errors, this event will trigger if a frame has a payload which is larger that "max_payload_size".

finish

 $cb->($connection, $message)

Called when the connection is terminated. If the connection is terminated due to an error, the message will be provided as the second argument. On a cleanly closed connection this will be `undef`.

close

 $connection->close;
 $connection->close($code);
 $connection->close($code, $reason);

Close the connection. You may optionally provide a code and a reason. See section 5.5.1 <https://tools.ietf.org/html/rfc6455#section-5.5.1> and section 7.4.1 <https://tools.ietf.org/html/rfc6455#section-7.4.1> of RFC6455.

The code is a 16-bit unsigned integer value that indicates why you close the connection. By default the code is 1005.

The reason is a character string (not an octet string) that further describes why you close the connection. By default the reason is an empty string.

SERVER CONNECTIONS

Although written originally to work with AnyEvent::WebSocket::Client, this class was designed to be used for either client or server WebSocket connections. For details, contact the author and/or take a look at the source for AnyEvent::WebSocket::Client and the examples that come with Protocol::WebSocket.

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Toshio Ito (debug-ito, TOSHIOITO)

José Joaquín Atria (JJATRIA)

Kivanc Yazan (KYZN)

Yanick Champoux (YANICK)

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.