The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
AnyEvent-WebSocket-Client-0.55
River stage two • 11 direct dependents • 15 total dependents
8 ++
/ AnyEvent::WebSocket::Connection

NAME

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

VERSION

version 0.55

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.

max_fragments

The maximum number of fragments 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);

Register a callback to a particular event.

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.

[0.49]

Adding a next_message callback from within a next_message callback will result in a callback called on the next message instead of the current one. There was a bug in previous versions where the callback would be called immediately after current set of callbacks with the same message.

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 and 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 1000.

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.

SEE ALSO

AUTHOR

Author: Graham Ollis <plicease@cpan.org>

Contributors:

Toshio Ito (debug-ito, TOSHIOITO)

José Joaquín Atria (JJATRIA)

Kivanc Yazan (KYZN)

Yanick Champoux (YANICK)

Fayland Lam (FAYLAND)

Daniel Kamil Kozar (xavery)

COPYRIGHT AND LICENSE

This software is copyright (c) 2013-2022 by Graham Ollis.

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