NAME 

WebService::CaptchasDotNet - routines for captchas.net free captcha service

SYNOPSIS

  # create the object
  my $o = WebService::CaptchasDotNet->new(secret   => 'secret',
                                          username => 'demo');

  # generate a random string using a convenience method
  my $random = $o->random;

  # generate an image url
  my $url = $o->url($random);

  # verify that the typed captcha and image are a match
  my $ok = $o->verify($user_input, $random);

DESCRIPTION

WebService::CaptchasDotNet contains several useful routines for using the
free captcha service at http://captchas.net.

to use these routines you will need to visit http://captchas.net and
register with them.  they will provide you with a username and a
shared secret key that you will need for these routines to work.

CONSTRUCTOR

new()

instantiate a new WebService::CaptchasDotNet object.

  my $o = WebService::CaptchasDotNet->new(secret   => 'secret',
                                          username => 'demo');

the 'secret' parameter represents the secret key assigned to
you when you registered with the captchas.net service.  the
'username' parameter is your assigned username.  both are
required for things to work properly, but you will always get
a valid object back.

METHODS

verify()

this is the heart of the interface, the verification routine.
basically it takes the captcha phrase that the user entered and
checks whether it matches the image presented by captchas.net.

  my $ok = $o->verify($user_input, $random_string);

here '$user_input' is what the user keyed in, and '$random_string'
is the random string you attached to the captchas.net URL.  for
example, if the URL you presented on the webpage was

  http://image.captchas.net?client=demo&random=RandomZufall

then the call would look like

  my $ok = $o->verify($user_input, 'RandomZufall');

so basically you need to keep track of the random string
yourself between calls.

verify() returns true if the user correctly identified the
captcha image string and false otherwise.

random()

random() is a utility method that will generate random strings for
you.  

  # object method
  my $random = $o->random;

  # class method
  my $random = WebService::CaptchasDotNet->random;

the captchas.net service suggests that you never use the same
random string twice in your urls, so this method is there to help.
it isn't guaranteed to be completely random given an infinite number
of calls, but it should be sufficiently random for these specific
purposes.

url()

generate a suitable captchas.net URL for embedding within a webpage.

  my $url = $o->url($random_string);

the returned URL will have both the passed random string and the
username provided with the class constructor embedded within it.
for example

  my $o = WebService::CaptchasDotNet->new(secret   => 'secret',
                                          username => 'demo');

  my $random = 'RandomZufall';

  # http://image.captchas.net?client=demo&random=RandomZufall
  my $url = $o->url($random);

it is important to note that the returned URL is not encoded with
the exception of the ampersand - if you use your own random routine
and it included funky characters you're on your own.

SEE ALSO

http://captchas.net/

AUTHOR

Geoffrey Young <geoff@modperlcookbook.org>

COPYRIGHT

Copyright (c) 2005, Geoffrey Young
All rights reserved.

This module is free software.  It may be used, redistributed
and/or modified under the same terms as Perl itself.