1LWP::Protocol(3) User Contributed Perl Documentation LWP::Protocol(3)
2
3
4
6 LWP::Protocol - Base class for LWP protocols
7
9 package LWP::Protocol::foo;
10 use base qw(LWP::Protocol);
11
13 This class is used as the base class for all protocol implementations
14 supported by the LWP library.
15
16 When creating an instance of this class using
17 "LWP::Protocol::create($url)", and you get an initialized subclass
18 appropriate for that access method. In other words, the "create" in
19 LWP::Protocol function calls the constructor for one of its subclasses.
20
21 All derived "LWP::Protocol" classes need to override the request()
22 method which is used to service a request. The overridden method can
23 make use of the collect() function to collect together chunks of data
24 as it is received.
25
27 The following methods and functions are provided:
28
29 new
30 my $prot = LWP::Protocol->new();
31
32 The LWP::Protocol constructor is inherited by subclasses. As this is a
33 virtual base class this method should not be called directly.
34
35 create
36 my $prot = LWP::Protocol::create($scheme)
37
38 Create an object of the class implementing the protocol to handle the
39 given scheme. This is a function, not a method. It is more an object
40 factory than a constructor. This is the function user agents should use
41 to access protocols.
42
43 implementor
44 my $class = LWP::Protocol::implementor($scheme, [$class])
45
46 Get and/or set implementor class for a scheme. Returns '' if the
47 specified scheme is not supported.
48
49 request
50 $response = $protocol->request($request, $proxy, undef);
51 $response = $protocol->request($request, $proxy, '/tmp/sss');
52 $response = $protocol->request($request, $proxy, \&callback, 1024);
53
54 Dispatches a request over the protocol, and returns a response object.
55 This method needs to be overridden in subclasses. Refer to
56 LWP::UserAgent for description of the arguments.
57
58 collect
59 my $res = $prot->collect(undef, $response, $collector); # stored in $response
60 my $res = $prot->collect($filename, $response, $collector);
61 my $res = $prot->collect(sub { ... }, $response, $collector);
62
63 Collect the content of a request, and process it appropriately into a
64 scalar, file, or by calling a callback. If the first parameter is
65 undefined, then the content is stored within the $response. If it's a
66 simple scalar, then it's interpreted as a file name and the content is
67 written to this file. If it's a code reference, then content is passed
68 to this routine.
69
70 The collector is a routine that will be called and which is responsible
71 for returning pieces (as ref to scalar) of the content to process. The
72 $collector signals "EOF" by returning a reference to an empty string.
73
74 The return value is the HTTP::Response object reference.
75
76 Note: We will only use the callback or file argument if
77 "$response->is_success()". This avoids sending content data for
78 redirects and authentication responses to the callback which would be
79 confusing.
80
81 collect_once
82 $prot->collect_once($arg, $response, $content)
83
84 Can be called when the whole response content is available as content.
85 This will invoke "collect" in LWP::Protocol with a collector callback
86 that returns a reference to $content the first time and an empty string
87 the next.
88
90 Inspect the LWP/Protocol/file.pm and LWP/Protocol/http.pm files for
91 examples of usage.
92
94 Copyright 1995-2001 Gisle Aas.
95
96 This library is free software; you can redistribute it and/or modify it
97 under the same terms as Perl itself.
98
99
100
101perl v5.26.3 2018-06-05 LWP::Protocol(3)