--- name: "AnyEvent::WebSocket::Connection" section: "3pm" platform: "linux" package: "libanyevent-websocket-client-perl" version: "0.55-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/AnyEvent::WebSocket::Connection" --- # AnyEvent::WebSocket::Connection(3pm) WebSocket connection for AnyEvent ## NAME AnyEvent::WebSocket::Connection - WebSocket connection for AnyEvent ## VERSION version 0.55 ## 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 \ 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 - • AnyEvent::WebSocket::Client - • AnyEvent::WebSocket::Message - • AnyEvent::WebSocket::Server - • AnyEvent - • RFC 6455 The WebSocket Protocol \ ## AUTHOR Author: Graham Ollis \ 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.