1POE::Component::Client:U:sTeCrP(C3o)ntributed Perl DocumPeOnEt:a:tCioomnponent::Client::TCP(3)
2
6 POE::Component::Client::TCP - a simplified TCP client
7
9 use POE qw(Component::Client::TCP);
10 # Basic usage.
12 POE::Component::Client::TCP->new
14 ( RemoteAddress => "127.0.0.1",
15 RemotePort => "chargen",
16 Domain => AF_INET, # Optional.
17 Alias => $session_alias # Optional.
18 ServerInput => sub {
19 my $input = $_[ARG0];
20 print "from server: $input\n";
21 }
22 );
23 # Complete usage.
25 my $session_id = POE::Component::Client::TCP->new
27 ( RemoteAddress => "127.0.0.1",
28 RemotePort => "chargen",
29 BindAddress => "127.0.0.1",
30 BindPort => 8192,
31 Domain => AF_INET, # Optional.
32 Alias => $session_alias # Optional.
33 ConnectTimeout => 5, # Seconds; optional.
34 SessionType => "POE::Session::Abc", # Optional.
36 SessionParams => [ options => { debug => 1 } ], # Optional.
37 Started => \&handle_starting, # Optional.
39 Args => [ "arg0", "arg1" ], # Optional. Start args.
40 Connected => \&handle_connect,
42 ConnectError => \&handle_connect_error,
43 Disconnected => \&handle_disconnect,
44 ServerInput => \&handle_server_input,
46 ServerError => \&handle_server_error,
47 ServerFlushed => \&handle_server_flush,
48 Filter => "POE::Filter::Something",
50 InlineStates => { ... },
52 PackageStates => [ ... ],
53 ObjectStates => [ ... ],
54 );
55 # Sample callbacks.
57 sub handle_start {
59 my @args = @_[ARG0..$#_];
60 }
61 sub handle_connect {
63 my ($socket, $peer_address, $peer_port) = @_[ARG0, ARG1, ARG2];
64 }
65 sub handle_connect_error {
67 my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
68 }
69 sub handle_disconnect {
71 # no special parameters
72 }
73 sub handle_server_input {
75 my $input_record = $_[ARG0];
76 }
77 sub handle_server_error {
79 my ($syscall_name, $error_number, $error_string) = @_[ARG0, ARG1, ARG2];
80 }
81 sub handle_server_flush {
83 # no special parameters
84 }
85 # Reserved HEAP variables:
87 $heap->{server} = ReadWrite wheel representing the server.
89 $heap->{shutdown} = Shutdown flag (check to see if shutting down).
90 $heap->{connected} = Connected flag (check to see if session is connected).
91 $heap->{shutdown_on_error} = Automatically disconnect on error.
92 # Accepted public events.
94 $kernel->yield( "connect", $host, $port ) # connect to a new host/port
96 $kernel->yield( "reconnect" ) # reconnect to the previous host/port
97 $kernel->yield( "shutdown" ) # shut down a connection gracefully
98 # Responding to a server.
100 $heap->{server}->put(@things_to_send);
102
104 The TCP client component hides the steps needed to create a client
105 using Wheel::SocketFactory and Wheel::ReadWrite. The steps aren't
106 many, but they're still tiresome after a while.
107 POE::Component::Client::TCP supplies common defaults for most callbacks
109 and handlers. The authors hope that clients can be created with as
110 little work as possible.
111
113 new The new() method can accept quite a lot of parameters. It will
114 return the session ID of the accecptor session. One must use call‐
115 backs to check for errors rather than the return value of new().
116 Alias
118 Alias is an optional component alias. It's used to post events to
119 the TCP client component from other sessions. The most common use of
120 Alias is to allow a client component to receive "shutdown" and
121 "reconnect" events from a user interface session.
122 SessionType
124 SessionType specifies what type of sessions will be created within
125 the TCP server. It must be a scalar value.
126 SessionType => "POE::Session::MultiDispatch"
128 SessionType is optional. The component will supply a "POE::Session"
130 type if none is specified.
131 SessionParams
133 Initialize parameters to be passed to the SessionType when it is cre‐
134 ated. This must be an array reference.
135 SessionParams => [ options => { debug => 1, trace => 1 } ],
137 It is important to realize that some of the arguments to SessionHan‐
139 dler may get clobbered when defining them for your SessionHandler.
140 It is advised that you stick to defining arguments in the "options"
141 hash such as trace and debug. See POE::Session for an example list of
142 options.
143 Args ARRAYREF
145 Args passes the contents of a ARRAYREF to the Started callback via
146 @_[ARG0..$#_]. It allows a program to pass extra information to the
147 session created to handle the client connection.
148 BindAddress
150 BindPort
151 Specifies the local interface address and/or port to bind to before
152 connecting. This allows the client's connection to come from spe‐
153 cific addresses on a multi-host system.
154 ConnectError
156 ConnectError is an optional callback to handle SocketFactory errors.
157 These errors happen when a socket can't be created or connected to a
158 remote host.
159 ConnectError must contain a subroutine reference. The subroutine
161 will be called as a SocketFactory error handler. In addition to the
162 usual POE event parameters, ARG0 will contain the name of the syscall
163 that failed. ARG1 will contain the numeric version of $! after the
164 failure, and ARG2 will contain $!'s string version.
165 Depending on the nature of the error and the type of client, it may
167 be useful to post a reconnect event from ConnectError's callback.
168 sub handle_connect_error {
170 $_[KERNEL]->delay( reconnect => 60 );
171 }
172 The component will shut down after ConnectError if a reconnect isn't
174 requested.
175 Connected
177 Connected is an optional callback to notify a program that SocketFac‐
178 tory succeeded. This is an advisory callback, and it should not cre‐
179 ate a ReadWrite wheel itself. The component will handle setting up
180 ReadWrite.
181 ARG0 contains a socket handle. It's not necessary to save this under
183 most circumstances. ARG1 and ARG2 contain the peer address and port
184 as returned from getpeername().
185 ConnectTimeout
187 ConnectTimeout is the maximum time in seconds to wait for a connec‐
188 tion to be established. If it is omitted, Client::TCP relies on the
189 operating system to abort stalled connect() calls.
190 Upon a connection timeout, Client::TCP will send a ConnectError
192 event. Its ARG0 will be 'connect' and ARG1 will be the POSIX/Errno
193 ETIMEDOUT value.
194 Disconnected
196 Disconnected is an optional callback to notify a program that an
197 established server connection has shut down. It has no special
198 parameters.
199 For persistent connections, such as MUD bots or long-running ser‐
201 vices, a useful thing to do from a Disconnected handler is reconnect.
202 For example, this reconnects after waiting a minute:
203 sub handle_disconnect {
205 $_[KERNEL]->delay( reconnect => 60 );
206 }
207 The component will shut down after disconnecting if a reconnect isn't
209 requested.
210 Domain
212 Specifies the domain within which communication will take place. It
213 selects the protocol family which should be used. Currently sup‐
214 ported values are AF_INET, AF_INET6, PF_INET or PF_INET6. This
215 parameter is optional and will default to AF_INET if omitted.
216 Note: AF_INET6 and PF_INET6 are supplied by the Socket6 module, which
218 is available on the CPAN. You must have Socket6 loaded before
219 POE::Component::Server::TCP will create IPv6 sockets.
220 Filter
222 Filter specifies the type of filter that will parse input from a
223 server. It may either be a scalar, a list reference or a POE::Filter
224 reference. If it is a scalar, it will contain a POE::Filter class
225 name.
226 Filter => "POE::Filter::Line",
228 If it is a list reference, the first item in the list will be a
230 POE::Filter class name, and the remaining items will be constructor
231 parameters for the filter. For example, this changes the line sepa‐
232 rator to a vertical pipe:
233 Filter => [ "POE::Filter::Line", Literal => "⎪" ],
235 If it is an object, it will be clone()'d.
237 Filter => POE::Filter::Line->new()
239 Filter is optional. The component will supply a "POE::Filter::Line"
241 instance none is specified. If you supply a different value for Fil‐
242 ter, then you must also "use" that filter class.
243 InlineStates
245 InlineStates holds a hashref of inline coderefs to handle events.
246 The hashref is keyed on event name. For more information, see
247 POE::Session's create() method.
248 ObjectStates
250 ObjectStates holds a list reference of objects and the events they
251 handle. For more information, see POE::Session's create() method.
252 PackageStates
254 PackageStates holds a list reference of Perl package names and the
255 events they handle. For more information, see POE::Session's cre‐
256 ate() method.
257 RemoteAddress
259 RemoteAddress contains the address to connect to. It is required and
260 may be a host name ("poe.perl.org") a dotted quad ("127.0.0.1") or a
261 packed socket address.
262 RemotePort
264 RemotePort contains the port to connect to. It is required and may
265 be a service name ("echo") or number (7).
266 ServerError
268 ServerError is an optional callback to notify a program that an
269 established server connection has encountered some kind of error.
270 Like with ConnectError, it accepts the traditional error parameters:
271 ARG0 contains the name of the syscall that failed. ARG1 contains the
273 numeric failure code from $!. ARG2 contains the string version of
274 $!.
275 The component will shut down after a server error if a reconnect
277 isn't requested.
278 ServerFlushed
280 ServerFlushed is an optional callback to notify a program that Read‐
281 Write's output buffers have completely flushed. It has no special
282 parameters.
283 The component will shut down after a server flush if $heap->{shut‐
285 down} is set.
286 ServerInput
288 ServerInput is a required callback. It is called for each input
289 record received from a server. ARG0 contains the input record, the
290 format of which is determined by POE::Component::Client::TCP's Filter
291 parameter.
292 The ServerInput function will stop being called when $heap->{shut‐
294 down} is true.
295 Started
297 Started is an optional callback. It is called after Client::TCP is
298 initialized but before a connection has been established.
299 The Args parameter can be used to pass initialization values to the
301 Started callback, eliminating the need for closures to get values
302 into the component. These values are included in the @_[ARG0..$#_]
303 parameters.
304
306 connect
307 Cause the TCP client to connect, optionally providing a new Remote‐
308 Host and RemotePort (which will also be used for subsequent "recon‐
309 nect"s. If the client is already connected, it will disconnect
310 harshly, as with reconnect, discarding any pending input or output.
311 reconnect
313 Instruct the TCP client component to reconnect to the server. If
314 it's already connected, it will disconnect harshly, discarding any
315 pending input or output data.
316 shutdown
318 When a Client::TCP component receives a shutdown event, it initiates
319 a graceful shutdown. Any subsequent server input will be ignored,
320 and any pending output data will be flushed. Once the connection is
321 dealt with, the component will self-destruct.
322
324 POE::Component::Server::TCP, POE::Wheel::SocketFactory,
325 POE::Wheel::ReadWrite, POE::Filter
326
328 This may not be suitable for complex client tasks. After a point, it
329 becomes easier to roll a custom client using POE::Wheel::SocketFactory
330 and POE::Wheel::ReadWrite.
331 This looks nothing like what Ann envisioned.
333
335 POE::Component::Client::TCP is Copyright 2001-2006 by Rocco Caputo.
336 All rights are reserved. POE::Component::Client::TCP is free software,
337 and it may be redistributed and/or modified under the same terms as
338 Perl itself.
339 POE::Component::Client::TCP is based on code, used with permission,
341 from Ann Barcomb <kudra@domaintje.com>.
342 POE::Component::Client::TCP is based on code, used with permission,
344 from Jos Boumans <kane@cpan.org>.
345perl v5.8.8 2006-09-01 POE::Component::Client::TCP(3)