NAME

HTTunnel::Client - Client class for Apache::HTTunnel

SYNOPSIS

  my $hc = new HTTunnel::Client("http://localhost/httunnel") ;
  $hc->connect('tcp', $some_host, $some_port) ;

  $hc->print('some request') ;
  my $some_response = $hc->read(1024) ;

  $ch->close() ;
 

DESCRIPTION

HTTunnel::Client is the client class to Apache::HTTunnel. It allows the creation of a network connection tunnelled through HTTP. All data sent and received during this connection will be transported inside normal HTTP requests.

HTTunnel::Client extends LWP::UserAgent, so all LWP::UserAgent methods are available through HTTunnel::Client.

CONSTRUCTORS

new ( URL, [ARGS] )

Creates an HTTunnel::Client object that will use URL to contact the Apache::HTTunnel server. ARGS are is passed directly to the LWP::UserAgent constructor.

METHODS

connect ( PROTO, HOST, PORT, [TIMEOUT] )

Asks the Apache::HTTunnel server to establish a connection of protocol PROTO to HOST:PORT. An exception is thrown if an error occurs.

Accepted values for PROTO are 'tcp' and 'udp'.

print ( DATA )

Asks the Apache::HTTunnel server to write DATA to the established remote connection. An exception is thrown if an error occurs.

DATA can be a scalar or a list, in which case the list items are concatenated together.

read ( LEN, [TIMEOUT], [LIFELINE], [LIFELINE_CUT_ACTION] )

Asks the Apache::HTTunnel server to read up to LEN bytes from the established remote connection. An exception is thrown if an error occurs.

When trying to read, HTTunnel::Client will establish an HTTP connection to the Apache::HTTunnel server asking that LEN bytes be read. If no data is available after TIMEOUT seconds (the default value is 15 seconds), the HTTP connection is closed by the server and the read method will establish a new one. This will go on until some data or EOF is returned.

Therefore read will return only when some (or no more) data is available to be read (like the regular read).

LIFELINE can be any valid filehandle from which one can read. If used, read will interrupt its connection loop and execute LIFELINE_CUT_ACTION when data (or EOF) is available to be read from LIFELINE. It will then return undef.

LIFELINE_CUT_ACTION wust be a CODE ref. The default value is

  sub {die("lifeline cut\n")}

These features can be used if you want fork and to start a process that does nothing but reads and returns the data via a pipe. You can then use a second pipe to make sure the reader process terminates when the master process terminates.

Here is an example:

  my $lifeline = new IO::Pipe() ;
  my $reader = new IO::Pipe() ;
  my $pid = fork() ;
  if ($pid){
    $reader->reader() ;
    $lifeline->writer() ;
        
    # Read data from $reader...
  }
  else {
    $reader->writer() ;
    $reader->autoflush(1) ;
    $lifeline->reader() ;

    while (1){
      my $data = $hc->read(1024, 15, $lifeline, sub {exit()}) ;
      exit() unless defined($data) ;
      print $reader $data ;
    }
  }

close ( )

Asks the Apache::HTTunnel server to close a previously established connection.

get_peer_info ( )

The get_peer_info method returns information about the remote connection. A string containing the IP address and port number, separated by a colon (:) is returned. This method can be useful with UDP connections to validate the sender of each packet.

request_callback ( REQUEST )

The request_callback method is a callback method that can be used to access the HTTP::Request object just before it is sent. The default implementation does nothing.

response_callback ( RESPONSE )

The response_callback method is a callback method that can be used to access the HTTP::Response object just after it is received. The default implementation does nothing.

JAVA CLIENT

For those who might be interested, there is a Java version of HTTunnel::Client included in the distribution. The API is the basically the same.

BUGS

I'm sure there are some in there :)

SEE ALSO

LWP::UserAgent

AUTHOR

Patrick LeBoutillier, <patl@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Patrick LeBoutillier

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.