NAME

LWP::UserAgent::FramesReady - a frames-capable version of LWP::UserAgent

SYNOPSIS

 use LWP::UserAgent::FramesReady;

 $ua = new LWP::UserAgent::FramesReady;
 $ua = new LWP::UserAgent::FramesReady({'callback'=>\&callback
      [,'size'=>$size]});
 $ua = new LWP::UserAgent::FramesReady({'nomax'=>1,
      'callback'=>\&LWP::UserAgent::FramesReady::callback
      [,'size'=>$size]});

 $response = $ua->request($http_request);

DESCRIPTION

LWP::UserAgent::FramesReady is a version of LWP::UserAgent that is smart enough to recognize the presence of frames in HTML and load them automatically.

The subroutine variant requires a hash reference to a callback routine that is supplied to the request to process the content in chunks to look for, for instance, immediate refreshes and alter them to be redirects which LWP::UserAgent->request will follow out as it does all other redirects. If size (supplied as an additional hash element) is supplied it will be the suggested chunk size. If the subroutine variant is requested without a size, the size will default to 8K. The default is to use the callback() function defined with the class object.

The LWP::UserAgent::FramesReady::callback is supplied as the default callback routine and the $cnf->{'nomax'} can be supplied and used by that routine to enforce truncation of received content even if the request to do so is not honored by the server called for the content.

To override the default behavior and not use the internal callback, the input parameter or $ua->callbk should be called supplying something other than 'undef' as the subroutine to use as in '$ua->callbk(undef)'. Not defining a code ref will default to the callback defined here as following out redirects (refreshes) is required by this processing method.

Because a framed HTML page actually consists of several HTML pages and requires more than one HTTP response, LWP::UserAgent::FramesReady returns framed pages as HTTP::Response::Tree objects. Responses that don't have the Content-type of 'text/html' or have a return code outside of the 200-399 range are returned as HTTP::Response objects as frames processing is probably not valid for them.

Note: a $response->isa('HTTP::Response::FramesReady') type check should be done before attempting to use this module's methods.

METHODS

LWP::UserAgent::FramesReady inherits most of its methods from LWP::UserAgent. The following method overrides the LWP::UserAgent version:

$ua->request($request)

This behaves like LWP::UserAgent's request method, except that it takes only one parameter (an HTTP::Request object as usual). Further parameters may generate a warning and be ignored. Such attempts usually are due to a proxy request, redirect override, authentication or moved file condition that the base class function can handle properly, anyway.

In addition to request()'s usual behavior (authenticating, following redirects, etc.), this will attempt to follow frames if it detects an HTML page that contains them. All responses collected as a result of following frames will be returned in an HTTP::Response::Tree object except as denoted above.

The following method is new:

$ua->max_depth([$depth])

This gets or sets the maximum depth that the user agent is allowed to go to fetch framed pages. 0 means it will not fetch any frames, 1 means it will fetch only the frames for the topmost page and not any sub-frames, and so on. The default is 3.

$ua->callbk([\&callback])

Get/set the callback subroutine to use to process input as it is gathered. This causes the input to be chunked and the routine must either process the data itself or append it to the $response-{_content}> in order for the final content to be processed all at one time.

$ua->size([$size])

Get/Set the size suggested for chunks when the callback routine is used.

$ua->nomax([$max])

Get/set the $self-{'nomax'}> can be used by the included callback routine to enforce truncation of received content even if the request to do so is not honored by the server called for the content.

$ua->credent([$credentials])

Get/set the credentials for authentification if called for.

$ua->errors()

Get the last error encountered if a return was an undef. This routine has only been tested in development so there is no guarantee that it will work within your functions.

callback()

The callback routine is a sample of how to revise the way the immediate refresh responses are processed by converting them into redirects. Since the routine is called whenever there is chunked response data available by use of the alternate LWP::UserAgent::request() method, and we only change headers for immediate refreshes. We must also deal with the fact that the callback was originally designed for processing the content. The $resp->{_content} field must have the unprocessed data element appended back in.. appended, as this data is chunked and there may already be content from a previous chunk that was processed.

$ua->valid_scheme()

The valid_scheme validates the frame src entry to scheme types we can process.

$ua->get_basic_credentials()

This routine overloads the LWP::UserAgent::get_basic_credentials in order to supply authorization if it has been pre-loaded an initial/new or by use of the $ua->credent() routine. Supplies a return in a list context of a UserID and a Password to LWP::UserAgent::credentials().

NOTES

Processing other embedded objects in an HTML page is similar to processing frames. Perhaps someday there will be yet another version of this that can also handle things like in-line images, layers, etc.

BUGS

Any known bugs will be noted here and documented in the source with "BUG:" in the comments.

COPYRIGHT

Copyright 2002 N2H2, Inc. All rights reserved.

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