/ 
Mail-Karmasphere-Client-2.15
River stage zero No dependents
/ Mail::Karmasphere::Client

NAME

Mail::Karmasphere::Client - Client for Karmasphere Reputation Server

SYNOPSIS

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',
		);

DESCRIPTION

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.

CONSTRUCTOR

The class method new(...) constructs a new Client object. All arguments are optional. The following parameters are recognised as arguments to new():

PeerAddr

The IP address or hostname to contact. See IO::Socket::INET. The default is 'query.karmasphere.com'.

PeerPort

The TCP or UDP to contact. See IO::Socket::INET. The default is 8666.

Proto

Either 'udp' or 'tcp'. The default is 'udp' because it is faster.

Principal
Credentials

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.

Debug

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.

METHODS

$response = $client->ask($query, $timeout)

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.

$id = $client->send($query)

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.

$response = $client->recv($id, $timeout)

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.

$response = $client->query(...)

A convenience method, equivalent to

$client->ask(new Mail::Karmasphere::Query(...));

See Mail::Karmasphere::Query for more details.

EXPORTS

IDT_IP4 IDT_IP6 IDT_DOMAIN IDT_EMAIL IDT_URL

Identity type constants.

AUTHENTIC SMTP_CLIENT_IP SMTP_ENV_HELO SMTP_ENV_MAIL_FROM SMTP_ENV_RCPT_TO SMTP_HEADER_FROM_ADDRESS

Identity tags, indicating the context of an identity to the server.

FL_FACTS

A flag indicating that all facts must be returned explicitly in the Response.

NOTES ON THE IMPLEMENTATION

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.

BUGS

UDP retries are not yet implemented.

SEE ALSO

Mail::Karmasphere::Query, Mail::Karmasphere::Response, http://www.karmasphere.com/, http://my.karmasphere.com/devzone/client/configuration, Mail::SpamAssassin::Plugin::Karmasphere

COPYRIGHT

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.