NAME

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

VERSION

       version 0.54

SYNOPSIS

        # send a message through the websocket...
        $connection->send('a message');

        # receive 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
       <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.

SEE ALSO

       •   AnyEvent::WebSocket::Client

       •   AnyEvent::WebSocket::Message

       •   AnyEvent::WebSocket::Server

       •   AnyEvent

       •   RFC 6455 The WebSocket Protocol <http://tools.ietf.org/html/rfc6455>

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