162
162
A I<process_connection> handler accepts a connection record object as
163
163
its only argument, a socket object can be retrieved from the
164
connection record object.
164
connection record object. Here is a simplified handler skeleton:
168
my $socket = $c->client_socket;
168
my $sock = $c->client_socket;
169
$sock->opt_set(APR::SO_NONBLOCK, 0);
170
171
return Apache::OK;
174
Most likely you'll need to set the socket to perform blocking IO. On
175
some platforms (e.g. Linux) Apache gives us a socket which is set for
176
blocking, on other platforms (.e.g. Solaris) it doesn't. Unless you
177
know which platforms your application will be running on, always
178
explicitly set it to the blocking IO mode as in the example
179
above. Alternatively, you could query whether the socket is already
180
set to a blocking IO mode with help of C<L<the opt_get()
181
method|docs::2.0::api::APR::Socket/C_opt_get_>>.
175
183
Now let's look at the following two examples of connection
176
184
handlers. The first using the connection socket to read and write the
228
236
use APR::Socket ();
230
238
use Apache::Const -compile => 'OK';
239
use APR::Const -compile => 'SO_NONBLOCK';
232
241
use constant BUFF_LEN => 1024;
236
my $socket = $c->client_socket;
245
my $sock = $c->client_socket;
247
# set the socket to the blocking mode
248
$sock->opt_set(APR::SO_NONBLOCK => 0);
241
$socket->recv($buff, $rlen);
243
last if $rlen <= 0 or $buff =~ /^[\r\n]+$/;
246
$socket->send($buff, $wlen);
248
last if $wlen != $rlen;
251
# read from the socket
252
my $buff = $sock->recv(BUFF_LEN);
253
my $rlen = length $buff;
254
last if $rlen == 0; # EOF
255
last if $buff =~ /^[\r\n]+$/;
257
# write to the socket
258
my $wlen = $sock->send($buff);
259
last if $wlen != $rlen; # shouldn't happen
258
269
protocol handler, the first argument is not a C<request_rec>, but a
259
270
C<conn_rec> blessed into the C<Apache::Connection> class. We have
260
271
direct access to the client socket via C<Apache::Connection>'s
261
I<client_socket> method. This returns an object blessed into the
262
C<APR::Socket> class.
272
I<client_socket> method. This returns an object, blessed into the
273
C<APR::Socket> class. Before using the socket, we make sure that it's
274
set to perform blocking IO, by using the C<APR::SO_NONBLOCK> constant,
264
Inside the read/send loop, the handler attempts to read C<BUFF_LEN>
265
bytes from the client socket into the C<$buff> buffer. The C<$rlen>
266
parameter will be set to the number of bytes actually read. The
267
C<APR::Socket::recv()> method returns an APR status value, but we need
268
only to check the read length to break out of the loop if it is less
269
than or equal to C<0> bytes. The handler also breaks the loop after
270
processing an input including nothing but new lines characters, which
271
is how we abort the connection in the interactive mode.
277
Inside the recv/send loop, the handler attempts to read C<BUFF_LEN>
278
bytes from the client socket into the C<$buff> buffer. The handler
279
breaks the loop if the returned buffer is empty, (there was nothing
280
more to read (EOF)) or if the buffer contains nothing but new line
281
character(s), which is how we know to abort the connection in the
273
284
If the handler receives some data, it sends it unmodified back to the
274
285
client with the C<APR::Socket::send()> method. When the loop is
347
my $rv = $c->input_filters->get_brigade($bb_in, Apache::MODE_GETLINE);
358
my $rv = $c->input_filters->get_brigade($bb_in,
359
Apache::MODE_GETLINE);
348
360
if ($rv != APR::SUCCESS && $rv != APR::EOF) {
349
361
my $error = APR::strerror($rv);
350
362
warn __PACKAGE__ . ": get_brigade: $error\n";
added
removed
docs/user/handlers/protocols.pod
