Mail::Karmasphere::Client - Client for Karmasphere Reputation Server
use Mail::Karmasphere::Client qw(:all); my $client = new Mail::Karmasphere::Client( PeerAddr => 'query.karmasphere.com', PeerPort => 8666, Principal => "my_assigned_query_username", Credentials => "my_assigned_query_password", # see http://my.karmasphere.com/devzone/client/configuration#credentials # quickstart: use temporary credentials for "generic perl". # recommended: use permanent credentials -- register for an account. ); my $query = new Mail::Karmasphere::Query(); $query->identity('127.0.0.2', IDT_IP4); $query->composite('karmasphere.email-sender'); my $response = $client->ask($query, 6); print $response->as_string; my $id = $client->send($query); my $response = $client->recv($query, 12); my $response = $client->recv($id, 12); my $response = $client->query( Identities => [ ... ] Composite => 'karmasphere.email-sender', );
The Perl Karma Client API consists of three objects: The Query, the Response, and the Client. The user constructs a Query and passes it to a Client, which returns a Response.
The class method new(...) constructs a new Client object. All arguments are optional. The following parameters are recognised as arguments to new():
The IP address or hostname to contact. See IO::Socket::INET. The default is 'query.karmasphere.com'.
The TCP or UDP to contact. See IO::Socket::INET. The default is 8666.
Either 'udp' or 'tcp'. The default is 'udp' because it is faster.
A username and password are required to authenticate client connections. They are assigned by Karmasphere. See http://my.karmasphere.com/devzone/client/configuration#credentials
"Principal" corresponds to "username", and "Credentials" corresponds to "password". Note that these are not the same username and password you use to sign in to the website.
Either a true value for debugging to stderr, or a custom debug handler. The custom handler will be called with N arguments, the first of which is a string 'debug context'. The custom handler may choose to ignore messages from certain contexts.
Returns a Mail::Karmasphere::Response to a Mail::Karmasphere::Query. The core of this method is equivalent to
$client->recv($client->send($query), $timeout)
The method retries up to 3 times, doubling the timeout each time. If the application requires more control over retries or backoff, it should use send() and recv() individually. $timeout is optional.
Sends a Mail::Karmasphere::Query to the server, and returns the id of the query, which may be passed to recv(). Note that any query longer than 64KB will be rejected by the server with a message advising that the maximum message length has been exceeded.
Returns a Mail::Karmasphere::Response to the query with id $id, assuming that the query has already been sent using send(). If no matching response is read before the timeout, undef is returned.
A convenience method, equivalent to
$client->ask(new Mail::Karmasphere::Query(...));
See Mail::Karmasphere::Query for more details.
Identity type constants.
Identity tags, indicating the context of an identity to the server.
A flag indicating that all facts must be returned explicitly in the Response.
The server will discard any packet in TCP mode which exceeds 64K. Although the packet length field is 4 bytes, it is relatively common to get non-Karmasphere clients connecting to the port. Therefore the server checks that the top two bytes are \0 before accepting the packet. This saves everybody a headache.
Some flags, notably those which generate large response packets, are totally ignored for UDP queries, even in the case that they would not generate a large response. This also saves many headaches.
UDP retries are not yet implemented.
Mail::Karmasphere::Query, Mail::Karmasphere::Response, http://www.karmasphere.com/, http://my.karmasphere.com/devzone/client/configuration, Mail::SpamAssassin::Plugin::Karmasphere
Copyright (c) 2005-2006 Shevek, Karmasphere. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Mail::Karmasphere::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Karmasphere::Client
CPAN shell
perl -MCPAN -e shell install Mail::Karmasphere::Client
For more information on module installation, please visit the detailed CPAN module installation guide.