/ 
Mail-Karmasphere-Client-2.10
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().

$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.

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.