Mail::SPF::Result(3pm)

1Mail::SPF::Result(3)  User Contributed Perl Documentation Mail::SPF::Result(3)
2
3
4

NAME

6       Mail::SPF::Result - SPF result class
7

SYNOPSIS

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
13   Throwing results
14           package Mail::SPF::Foo;
15           use Error ':try';
16           use Mail::SPF::Result;
17
18           sub foo {
19               if (...) {
20                   $server->throw_result('pass', $request)
21               }
22               else {
23                   $server->throw_result('permerror', $request, 'Invalid foo');
24               }
25           }
26
27   Catching results
28           package Mail::SPF::Bar;
29           use Error ':try';
30           use Mail::SPF::Foo;
31
32           try {
33               Mail::SPF::Foo->foo();
34           }
35           catch Mail::SPF::Result with {
36               my ($result) = @_;
37               ...
38           };
39
40   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

DESCRIPTION

50       An object of class Mail::SPF::Result represents the result of an SPF
51       request.
52
53       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
60   Constructor
61       The following constructor is provided:
62
63       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
69   Class methods
70       The following class methods are provided:
71
72       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
78           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
83       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
91           This method must be implemented by sub-classes of Mail::SPF::Result
92           for which the result name differs from the result code.
93
94       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
101       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
107           For example,
108           "Mail::SPF::Result::NeutralByDefault->isa_by_name('neutral')"
109           returns true.
110
111       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
118           This method is abstract and must be implemented by sub-classes of
119           Mail::SPF::Result.
120
121       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
126           Note:  The "isa_by_name" method provides a superset of this
127           method's functionality.
128
129       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
137   Instance methods
138       The following instance methods are provided:
139
140       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
149       server: returns Mail::SPF::Server
150           Returns the Mail::SPF server object that produced the result at
151           hand.
152
153       request: returns Mail::SPF::Request
154           Returns the SPF request that led to the result at hand.
155
156       text: returns string
157           Returns the text message of the result object.
158
159       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
164       local_explanation: returns string; throws Mail::SPF::EDNSError,
165       Mail::SPF::EInvalidMacroString
166           Returns a locally generated explanation for the result.
167
168           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
175               example.com: <local-explanation>
176
177           The authority domain "example.com"'s sender policy is directly
178           responsible for the result.
179
180               example.com ... other.example.org: <local-explanation>
181
182           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
186       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

OVERLOADING

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

RESULT CLASSES

196       The following result classes are provided:
197
198       ·   Mail::SPF::Result::Pass
199
200       ·   Mail::SPF::Result::Fail
201
202       ·   Mail::SPF::Result::SoftFail
203
204       ·   Mail::SPF::Result::Neutral
205
206           ·   Mail::SPF::Result::NeutralByDefault
207
208               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
212       ·   Mail::SPF::Result::None
213
214       ·   Mail::SPF::Result::Error
215
216           ·   Mail::SPF::Result::PermError
217
218           ·   Mail::SPF::Result::TempError
219
220       The following result classes have additional functionality:
221
222       Mail::SPF::Result::Fail
223           The following additional instance method is provided:
224
225           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

AUTHORS

241       Julian Mehnle <julian@mehnle.net>
242
243
244
245perl v5.30.1                      2020-01-30              Mail::SPF::Result(3)

NAME

SYNOPSIS

DESCRIPTION

OVERLOADING

RESULT CLASSES

SEE ALSO

AUTHORS