README
1NAME
2
3 AnyEvent::WebSocket::Client - WebSocket client for AnyEvent
4
5VERSION
6
7 version 0.44
8
9SYNOPSIS
10
11 use AnyEvent::WebSocket::Client 0.12;
12
13 my $client = AnyEvent::WebSocket::Client->new;
14
15 $client->connect("ws://localhost:1234/service")->cb(sub {
16
17 # make $connection an our variable rather than
18 # my so that it will stick around. Once the
19 # connection falls out of scope any callbacks
20 # tied to it will be destroyed.
21 our $connection = eval { shift->recv };
22 if($@) {
23 # handle error...
24 warn $@;
25 return;
26 }
27
28 # send a message through the websocket...
29 $connection->send('a message');
30
31 # recieve message from the websocket...
32 $connection->on(each_message => sub {
33 # $connection is the same connection object
34 # $message isa AnyEvent::WebSocket::Message
35 my($connection, $message) = @_;
36 ...
37 });
38
39 # handle a closed connection...
40 $connection->on(finish => sub {
41 # $connection is the same connection object
42 my($connection) = @_;
43 ...
44 });
45
46 # close the connection (either inside or
47 # outside another callback)
48 $connection->close;
49
50 });
51
52 ## uncomment to enter the event loop before exiting.
53 ## Note that calling recv on a condition variable before
54 ## it has been triggered does not work on all event loops
55 #AnyEvent->condvar->recv;
56
57DESCRIPTION
58
59 This class provides an interface to interact with a web server that
60 provides services via the WebSocket protocol in an AnyEvent context. It
61 uses Protocol::WebSocket rather than reinventing the wheel. You could
62 use AnyEvent and Protocol::WebSocket directly if you wanted finer grain
63 control, but if that is not necessary then this class may save you some
64 time.
65
66 The recommended API was added to the AnyEvent::WebSocket::Connection
67 class with version 0.12, so it is recommended that you include that
68 version when using this module. The older version of the API has since
69 been deprecated and removed.
70
71ATTRIBUTES
72
73 timeout
74
75 Timeout for the initial connection to the web server. The default is
76 30.
77
78 ssl_no_verify
79
80 If set to true, then secure WebSockets (those that use SSL/TLS) will
81 not be verified. The default is false.
82
83 ssl_ca_file
84
85 Provide your own CA certificates file instead of using the system
86 default for SSL/TLS verification.
87
88 protocol_version
89
90 The protocol version. See Protocol::WebSocket for the list of supported
91 WebSocket protocol versions.
92
93 subprotocol
94
95 List of subprotocols to request from the server. This class will throw
96 an exception if none of the protocols are supported by the server.
97
98 http_headers
99
100 Extra headers to include in the initial request. May be either
101 specified as a hash reference, or an array reference. For example:
102
103 AnyEvent::WebSocket::Client->new(
104 http_headers => {
105 'X-Foo' => 'bar',
106 'X-Baz' => [ 'abc', 'def' ],
107 },
108 );
109
110 AnyEvent::WebSocket::Client->new(
111 http_headers => [
112 'X-Foo' => 'bar',
113 'X-Baz' => 'abc',
114 'X-Baz' => 'def',
115 ],
116 );
117
118 Will generate:
119
120 X-Foo: bar
121 X-Baz: abc
122 X-Baz: def
123
124 Although, the order cannot be guaranteed when using the hash style.
125
126 max_payload_size
127
128 The maximum payload size for received frames. Currently defaults to
129 whatever Protocol::WebSocket defaults to.
130
131METHODS
132
133 connect
134
135 my $cv = $client->connect($uri)
136
137 Open a connection to the web server and open a WebSocket to the
138 resource defined by the given URL. The URL may be either an instance of
139 URI::ws, URI::wss, or a string that represents a legal WebSocket URL.
140
141 This method will return an AnyEvent condition variable which you can
142 attach a callback to. The value sent through the condition variable
143 will be either an instance of AnyEvent::WebSocket::Connection or a
144 croak message indicating a failure. The synopsis above shows how to
145 catch such errors using eval.
146
147FAQ
148
149 My program exits before doing anything, what is up with that?
150
151 See this FAQ from AnyEvent:
152 AnyEvent::FAQ#My-program-exits-before-doing-anything-whats-going-on.
153
154 It is probably also a good idea to review the AnyEvent documentation if
155 you are new to AnyEvent or event-based programming.
156
157 My callbacks aren't being called!
158
159 Make sure that the connection object is still in scope. This often
160 happens if you use a my $connection variable and don't save it
161 somewhere. For example:
162
163 $client->connect("ws://foo/service")->cb(sub {
164
165 my $connection = eval { shift->recv };
166
167 if($@)
168 {
169 warn $@;
170 return;
171 }
172
173 ...
174 });
175
176 Unless $connection is saved somewhere it will get deallocated along
177 with any associated message callbacks will also get deallocated once
178 the connect callback is executed. One way to make sure that the
179 connection doesn't get deallocated is to make it a our variable (as in
180 the synopsis above) instead.
181
182CAVEATS
183
184 This is pretty simple minded and there are probably WebSocket features
185 that you might like to use that aren't supported by this distribution.
186 Patches are encouraged to improve it.
187
188SEE ALSO
189
190 * AnyEvent::WebSocket::Connection
191
192 * AnyEvent::WebSocket::Message
193
194 * AnyEvent::WebSocket::Server
195
196 * AnyEvent
197
198 * URI::ws
199
200 * URI::wss
201
202 * Protocol::WebSocket
203
204 * Net::WebSocket::Server
205
206 * Net::Async::WebSocket
207
208 * RFC 6455 The WebSocket Protocol
209 <http://tools.ietf.org/html/rfc6455>
210
211AUTHOR
212
213 Author: Graham Ollis <plicease@cpan.org>
214
215 Contributors:
216
217 Toshio Ito (debug-ito, TOSHIOITO)
218
219 José Joaquín Atria (JJATRIA)
220
221 Kivanc Yazan (KYZN)
222
223 Yanick Champoux (YANICK)
224
225COPYRIGHT AND LICENSE
226
227 This software is copyright (c) 2013 by Graham Ollis.
228
229 This is free software; you can redistribute it and/or modify it under
230 the same terms as the Perl 5 programming language system itself.
231
232