.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AnyEvent::WebSocket::Client 3pm"
.TH AnyEvent::WebSocket::Client 3pm "2021-03-23" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AnyEvent::WebSocket::Client \- WebSocket client for AnyEvent
.SH "VERSION"
.IX Header "VERSION"
version 0.54
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use AnyEvent::WebSocket::Client 0.12;
\& 
\& my $client = AnyEvent::WebSocket::Client\->new;
\& 
\& $client\->connect("ws://localhost:1234/service")\->cb(sub {
\& 
\&   # make $connection an our variable rather than
\&   # my so that it will stick around.  Once the
\&   # connection falls out of scope any callbacks
\&   # tied to it will be destroyed.
\&   our $connection = eval { shift\->recv };
\&   if($@) {
\&     # handle error...
\&     warn $@;
\&     return;
\&   }
\& 
\&   # send a message through the websocket...
\&   $connection\->send(\*(Aqa message\*(Aq);
\& 
\&   # 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 the connection (either inside or
\&   # outside another callback)
\&   $connection\->close;
\& 
\& });
\& 
\& ## uncomment to enter the event loop before exiting.
\& ## Note that calling recv on a condition variable before
\& ## it has been triggered does not work on all event loops
\& #AnyEvent\->condvar\->recv;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides an interface to interact with a web server that provides
services via the WebSocket protocol in an AnyEvent context.  It uses
Protocol::WebSocket rather than reinventing the wheel.  You could use
AnyEvent and Protocol::WebSocket directly if you wanted finer grain
control, but if that is not necessary then this class may save you some time.
.PP
The recommended \s-1API\s0 was added to the AnyEvent::WebSocket::Connection
class with version 0.12, so it is recommended that you include that version
when using this module.  The older version of the \s-1API\s0 has since been
deprecated and removed.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "timeout"
.IX Subsection "timeout"
Timeout for the initial connection to the web server.  The default
is 30.
.SS "ssl_no_verify"
.IX Subsection "ssl_no_verify"
If set to true, then secure WebSockets (those that use \s-1SSL/TLS\s0) will
not be verified.  The default is false.
.SS "ssl_ca_file"
.IX Subsection "ssl_ca_file"
Provide your own \s-1CA\s0 certificates file instead of using the system default for
\&\s-1SSL/TLS\s0 verification.
.SS "protocol_version"
.IX Subsection "protocol_version"
The protocol version.  See Protocol::WebSocket for the list of supported
WebSocket protocol versions.
.SS "subprotocol"
.IX Subsection "subprotocol"
List of subprotocols to request from the server.  This class will throw an
exception if none of the protocols are supported by the server.
.SS "http_headers"
.IX Subsection "http_headers"
Extra headers to include in the initial request.  May be either specified
as a hash reference, or an array reference.  For example:
.PP
.Vb 6
\& AnyEvent::WebSocket::Client\->new(
\&   http_headers => {
\&     \*(AqX\-Foo\*(Aq => \*(Aqbar\*(Aq,
\&     \*(AqX\-Baz\*(Aq => [ \*(Aqabc\*(Aq, \*(Aqdef\*(Aq ],
\&   },
\& );
\& 
\& AnyEvent::WebSocket::Client\->new(
\&   http_headers => [
\&     \*(AqX\-Foo\*(Aq => \*(Aqbar\*(Aq,
\&     \*(AqX\-Baz\*(Aq => \*(Aqabc\*(Aq,
\&     \*(AqX\-Baz\*(Aq => \*(Aqdef\*(Aq,
\&   ],
\& );
.Ve
.PP
Will generate:
.PP
.Vb 3
\& X\-Foo: bar
\& X\-Baz: abc
\& X\-Baz: def
.Ve
.PP
Although, the order cannot be guaranteed when using the hash style.
.SS "max_payload_size"
.IX Subsection "max_payload_size"
The maximum payload size for received frames.  Currently defaults to whatever
Protocol::WebSocket defaults to.
.SS "max_fragments"
.IX Subsection "max_fragments"
The maximum number of fragments for received frames.  Currently defaults to whatever
Protocol::WebSocket defaults to.
.SS "env_proxy"
.IX Subsection "env_proxy"
If you set true to this boolean attribute, it loads proxy settings
from environment variables. If it finds valid proxy settings,
\&\f(CW\*(C`connect\*(C'\fR method will use that proxy.
.PP
Default: false.
.PP
For \f(CW\*(C`ws\*(C'\fR WebSocket end-points, first it reads \f(CW\*(C`ws_proxy\*(C'\fR (or
\&\f(CW\*(C`WS_PROXY\*(C'\fR) environment variable. If it is not set or empty string,
then it reads \f(CW\*(C`http_proxy\*(C'\fR (or \f(CW\*(C`HTTP_PROXY\*(C'\fR). For \f(CW\*(C`wss\*(C'\fR WebSocket
end-points, it reads \f(CW\*(C`wss_proxy\*(C'\fR (\f(CW\*(C`WSS_PROXY\*(C'\fR) and \f(CW\*(C`https_proxy\*(C'\fR
(\f(CW\*(C`HTTPS_PROXY\*(C'\fR) environment variables.
.SH "METHODS"
.IX Header "METHODS"
.SS "connect"
.IX Subsection "connect"
.Vb 2
\& my $cv = $client\->connect($uri)
\& my $cv = $client\->connect($uri, $host, $port);
.Ve
.PP
Open a connection to the web server and open a WebSocket to the resource
defined by the given \s-1URL.\s0  The \s-1URL\s0 may be either an instance of URI::ws,
URI::wss, or a string that represents a legal WebSocket \s-1URL.\s0
.PP
You can  override the connection host and port by passing them in as the
second and third argument.  These values (if provided) are passed directly
into AnyEvent::Socket's \f(CW\*(C`tcp_connect\*(C'\fR function, so please note that
function's idiosyncrasies in the AnyEvent::Socket documentation.  In
particular,  you can pass in \f(CW\*(C`unix/\*(C'\fR as the host and a filesystem path
as the \*(L"port\*(R" to connect to a unix domain socket.
.PP
This method will return an AnyEvent condition variable which you can
attach a callback to.  The value sent through the condition variable will
be either an instance of AnyEvent::WebSocket::Connection or a croak
message indicating a failure.  The synopsis above shows how to catch
such errors using \f(CW\*(C`eval\*(C'\fR.
.SH "FAQ"
.IX Header "FAQ"
.SS "My program exits before doing anything, what is up with that?"
.IX Subsection "My program exits before doing anything, what is up with that?"
See this \s-1FAQ\s0 from AnyEvent:
AnyEvent::FAQ#My\-program\-exits\-before\-doing\-anything\-whats\-going\-on.
.PP
It is probably also a good idea to review the AnyEvent documentation
if you are new to AnyEvent or event-based programming.
.SS "My callbacks aren't being called!"
.IX Subsection "My callbacks aren't being called!"
Make sure that the connection object is still in scope.  This often happens
if you use a \f(CW\*(C`my $connection\*(C'\fR variable and don't save it somewhere.  For
example:
.PP
.Vb 1
\& $client\->connect("ws://foo/service")\->cb(sub {
\& 
\&   my $connection = eval { shift\->recv };
\& 
\&   if($@)
\&   {
\&     warn $@;
\&     return;
\&   }
\& 
\&   ...
\& });
.Ve
.PP
Unless \f(CW$connection\fR is saved somewhere it will get deallocated along with
any associated message callbacks will also get deallocated once the connect
callback is executed.  One way to make sure that the connection doesn't
get deallocated is to make it a \f(CW\*(C`our\*(C'\fR variable (as in the synopsis above)
instead.
.SH "CAVEATS"
.IX Header "CAVEATS"
This is pretty simple minded and there are probably WebSocket features
that you might like to use that aren't supported by this distribution.
Patches are encouraged to improve it.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
AnyEvent::WebSocket::Connection
.IP "\(bu" 4
AnyEvent::WebSocket::Message
.IP "\(bu" 4
AnyEvent::WebSocket::Server
.IP "\(bu" 4
AnyEvent
.IP "\(bu" 4
URI::ws
.IP "\(bu" 4
URI::wss
.IP "\(bu" 4
Protocol::WebSocket
.IP "\(bu" 4
Net::WebSocket::Server
.IP "\(bu" 4
Net::Async::WebSocket
.IP "\(bu" 4
\&\s-1RFC 6455\s0 The WebSocket Protocol <http://tools.ietf.org/html/rfc6455>
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Toshio Ito (debug-ito, \s-1TOSHIOITO\s0)
.PP
José Joaquín Atria (\s-1JJATRIA\s0)
.PP
Kivanc Yazan (\s-1KYZN\s0)
.PP
Yanick Champoux (\s-1YANICK\s0)
.PP
Fayland Lam (\s-1FAYLAND\s0)
.PP
Daniel Kamil Kozar (xavery)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2013 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.