AnyEven...nnection(3)

📦
version 0.55 · 5 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay bestie, welcome to the AnyEven...nnection(3) page from User Contributed Perl Documentation 💅 this one is all about AnyEvent::WebSocket::Connection — the WebSocket connection class for AnyEvent. slay.

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

If the connection object falls out of scope then the connection will be closed gracefully. so cute of it, honestly.

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. no cap — same vibes either way 💖

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

bestie, that MUST is doing main character energy — handshake already done, or it's not it 🙈

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. so if you're on old versions, that's the glitch, bestie 💀

💌 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 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)

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.

mwah 💋 that's the page, bestie. the footer vibe is perl v5.42.0, dated 2023-05-05, and the manual name is AnyEven...nnection(3). go slay your WebSocket era 🫶✨

📦 where this page comes from