Mail::SPF::Result - SPF result class
For the general usage of Mail::SPF::Result objects in code that calls Mail::SPF, see Mail::SPF. For the detailed interface of Mail::SPF::Result and its derivatives, see below.
package Mail::SPF::Foo;
use Error ':try';
use Mail::SPF::Result;
sub foo {
if (...) {
throw Mail::SPF::Result::Pass($server, $request);
}
else {
throw Mail::SPF::Result::PermError($server, $request, 'Invalid foo');
}
}
package Mail::SPF::Bar;
use Error ':try';
use Mail::SPF::Foo;
try {
Mail::SPF::Foo->foo();
}
catch Mail::SPF::Result with {
my ($result) = @_;
...
};
my $result_code = $result->code;
my $request = $result->request;
my $local_exp = $result->local_explanation;
my $authority_exp = $result->authority_explanation
if $result->can('authority_explanation');
my $spf_header = $result->received_spf_header;
An object of class Mail::SPF::Result represents the result of an SPF request.
There is usually no need to construct an SPF result object directly using the
new constructor. Instead, use the throw class method to signal to the
calling code that a definite SPF result has been determined. In other words,
use Mail::SPF::Result and its derivatives just like exceptions. See Error
or perlfunc/eval for how to handle exceptions in Perl.
The following constructor is provided:
Creates a new SPF result object and associates the given Mail::SPF::Server and Mail::SPF::Request objects with it. An optional result text may be specified.
The following class methods are provided:
Throws a new SPF result object, associating the given Mail::SPF::Server and Mail::SPF::Request objects with it. An optional result text may be specified.
Returns the trailing part of the name of the Mail::SPF::Result::* class on
which it is invoked. For example, returns NeutralByDefault if invoked on
Mail::SPF::Result::NeutralByDefault. This method may also be used as an
instance method.
"pass", "fail", "softfail", "neutral",
"none", "error", "permerror", "permerror") of the
Mail::SPF::Result::* class on which it is invoked. This method may also be
used as an instance method.
Maps the given result code to the corresponding Mail::SPF::Result::* class. If an unknown result code was specified, returns undef.
If the class (or object) on which this method is invoked represents the given result code (or a derivative code), returns true. Returns false otherwise. This method may also be used as an instance method.
For example, Mail::SPF::Result::Pass->is_code('pass') returns true.
The following instance methods are provided:
Returns the SPF request that led to the result at hand.
Returns the result's name and text message formatted as a string. You can simply use a Mail::SPF::Result object as a string for the same effect, see /OVERLOADING.
Returns a locally generated explanation for the result.
The local explanation is prefixed with the authority domain whose sender policy
is responsible for the result. If the responsible sender policy referred to
another domain's policy (using the include mechanism or the redirect
modifier), that other domain which is directly responsible for the result is
also included in the local explanation's head. For example:
example.com: <local-explanation>
The authority domain example.com's sender policy is directly responsible for
the result.
example.com ... other.example.org: <local-explanation>
The authority domain example.com (directly or indirectly) referred to the
domain other.example.org, whose sender policy then led to the result.
Returns a string containing an appropriate Received-SPF header field for the
result object. The header field is not line-wrapped and contains no trailing
newline character.
If a Mail::SPF::Result object is used as a string, the /stringify method is used to convert the object into a string.
The following result classes are provided:
The following additional instance method is provided:
neutral result that is thrown as a default
when "falling off" the end of the record during evaluation. See RFC 4408,
4.7.
The following sub-classes of Mail::SPF::Result::Error are provided:
Mail::SPF, Mail::SPF::Server, Error, perlfunc/eval
http://www.ietf.org/rfc/rfc4408.txt
For availability, support, and license information, see the README file included with Mail::SPF.
Julian Mehnle <julian@mehnle.net>