1Mail::SPF::Result(3) User Contributed Perl Documentation Mail::SPF::Result(3)
2
6 Mail::SPF::Result - SPF result class
7
9 For the general usage of Mail::SPF::Result objects in code that calls
10 Mail::SPF, see Mail::SPF. For the detailed interface of
11 Mail::SPF::Result and its derivatives, see below.
12 Throwing results
14 package Mail::SPF::Foo;
15 use Error ':try';
16 use Mail::SPF::Result;
17 sub foo {
19 if (...) {
20 $server->throw_result('pass', $request)
21 }
22 else {
23 $server->throw_result('permerror', $request, 'Invalid foo');
24 }
25 }
26 Catching results
28 package Mail::SPF::Bar;
29 use Error ':try';
30 use Mail::SPF::Foo;
31 try {
33 Mail::SPF::Foo->foo();
34 }
35 catch Mail::SPF::Result with {
36 my ($result) = @_;
37 ...
38 };
39 Using results
41 my $result_name = $result->name;
42 my $result_code = $result->code;
43 my $request = $result->request;
44 my $local_exp = $result->local_explanation;
45 my $authority_exp = $result->authority_explanation
46 if $result->can('authority_explanation');
47 my $spf_header = $result->received_spf_header;
48
50 An object of class Mail::SPF::Result represents the result of an SPF
51 request.
52 There is usually no need to construct an SPF result object directly
54 using the "new" constructor. Instead, use the "throw" class method to
55 signal to the calling code that a definite SPF result has been
56 determined. In other words, use Mail::SPF::Result and its derivatives
57 just like exceptions. See Error or "eval" in perlfunc for how to
58 handle exceptions in Perl.
59 Constructor
61 The following constructor is provided:
62 new($server, $request): returns Mail::SPF::Result
64 new($server, $request, $text): returns Mail::SPF::Result
65 Creates a new SPF result object and associates the given
66 Mail::SPF::Server and Mail::SPF::Request objects with it. An
67 optional result text may be specified.
68 Class methods
70 The following class methods are provided:
71 throw($server, $request): throws Mail::SPF::Result
73 throw($server, $request, $text): throws Mail::SPF::Result
74 Throws a new SPF result object, associating the given
75 Mail::SPF::Server and Mail::SPF::Request objects with it. An
76 optional result text may be specified.
77 Note: Do not write code invoking "throw" on literal result class
79 names as this would ignore any derivative result classes provided
80 by Mail::SPF extension modules. Invoke the "throw_result" method
81 on a Mail::SPF::Server object instead.
82 name: returns string
84 Abstract. Returns the result name of the result class (or object).
85 For classes of the Mail::SPF::Result::* hierarchy, this roughly
86 corresponds to the trailing part of the class name. For example,
87 returns "neutral-by-default" if invoked on
88 Mail::SPF::Result::NeutralByDefault. Also see the "code" method.
89 This method may also be used as an instance method.
90 This method must be implemented by sub-classes of Mail::SPF::Result
92 for which the result name differs from the result code.
93 class: returns class
95 class($name): returns class
96 Maps the given result name to the corresponding
97 Mail::SPF::Result::* class, or returns the result base class (the
98 class on which it is invoked) if no result name is given. If an
99 unknown result name is specified, returns undef.
100 isa_by_name($name): returns boolean
102 If the class (or object) on which this method is invoked represents
103 the given result name (or a derivative name), returns true.
104 Returns false otherwise. This method may also be used as an
105 instance method.
106 For example,
108 "Mail::SPF::Result::NeutralByDefault->isa_by_name('neutral')"
109 returns true.
110 code: returns string
112 Abstract. Returns the basic SPF result code ("pass", "fail",
113 "softfail", "neutral", "none", "error", "permerror", "temperror")
114 of the result class on which it is invoked. All valid result codes
115 are valid result names as well, the reverse however does not apply.
116 This method may also be used as an instance method.
117 This method is abstract and must be implemented by sub-classes of
119 Mail::SPF::Result.
120 is_code($code): returns boolean
122 If the class (or object) on which this method is invoked represents
123 the given result code, returns true. Returns false otherwise.
124 This method may also be used as an instance method.
125 Note: The "isa_by_name" method provides a superset of this
127 method's functionality.
128 received_spf_header_name: returns string
130 Returns 'Received-SPF' as the field name for "Received-SPF" header
131 fields. This method should be overridden by Mail::SPF extension
132 modules that provide non-standard features (such as local policy)
133 with the capacity to dilute the purity of SPF results, in order not
134 to deceive users of the header field into mistaking it as an
135 indication of a natural SPF result.
136 Instance methods
138 The following instance methods are provided:
139 throw: throws Mail::SPF::Result
141 throw($server, $request): throws Mail::SPF::Result
142 throw($server, $request, $text): throws Mail::SPF::Result
143 Re-throws an existing SPF result object. If Mail::SPF::Server and
144 Mail::SPF::Request objects are specified, associates them with the
145 result object, replacing the prior server and request objects. If
146 a result text is specified as well, overrides the prior result
147 text.
148 server: returns Mail::SPF::Server
150 Returns the Mail::SPF server object that produced the result at
151 hand.
152 request: returns Mail::SPF::Request
154 Returns the SPF request that led to the result at hand.
155 text: returns string
157 Returns the text message of the result object.
158 stringify: returns string
160 Returns the result's name and text message formatted as a string.
161 You can simply use a Mail::SPF::Result object as a string for the
162 same effect, see "OVERLOADING".
163 local_explanation: returns string; throws Mail::SPF::EDNSError,
165 Mail::SPF::EInvalidMacroString
166 Returns a locally generated explanation for the result.
167 The local explanation is prefixed with the authority domain whose
169 sender policy is responsible for the result. If the responsible
170 sender policy referred to another domain's policy (using the
171 "include" mechanism or the "redirect" modifier), that other domain
172 which is directly responsible for the result is also included in
173 the local explanation's head. For example:
174 example.com: <local-explanation>
176 The authority domain "example.com"'s sender policy is directly
178 responsible for the result.
179 example.com ... other.example.org: <local-explanation>
181 The authority domain "example.com" (directly or indirectly)
183 referred to the domain "other.example.org", whose sender policy
184 then led to the result.
185 received_spf_header: returns string
187 Returns a string containing an appropriate "Received-SPF" header
188 field for the result object. The header field is not line-wrapped
189 and contains no trailing newline character.
190
192 If a Mail::SPF::Result object is used as a string, the "stringify"
193 method is used to convert the object into a string.
194
196 The following result classes are provided:
197 • Mail::SPF::Result::Pass
199 • Mail::SPF::Result::Fail
201 • Mail::SPF::Result::SoftFail
203 • Mail::SPF::Result::Neutral
205 • Mail::SPF::Result::NeutralByDefault
207 This is a special case of the "neutral" result that is thrown
209 as a default when "falling off" the end of the record during
210 evaluation. See RFC 4408, 4.7.
211 • Mail::SPF::Result::None
213 • Mail::SPF::Result::Error
215 • Mail::SPF::Result::PermError
217 • Mail::SPF::Result::TempError
219 The following result classes have additional functionality:
221 Mail::SPF::Result::Fail
223 The following additional instance method is provided:
224 authority_explanation: returns string; throws Mail::SPF::EDNSError,
226 Mail::SPF::EInvalidMacroString
227 Returns the authority domain's explanation for the result. Be
228 aware that the authority domain may be a malicious party and
229 thus the authority explanation should not be trusted blindly.
230 See RFC 4408, 10.5, for a detailed discussion of this issue.
231
233 Mail::SPF, Mail::SPF::Server, Error, "eval" in perlfunc
234 <http://tools.ietf.org/html/rfc4408>
236 For availability, support, and license information, see the README file
238 included with Mail::SPF.
239
241 Julian Mehnle <julian@mehnle.net>
242perl v5.32.1 2021-01-27 Mail::SPF::Result(3)