$Id: Gotcha_api.txt,v 1.0.0.0 2007/11/21 09:45:31 promes Exp $

Implementing spam detection in a (e-mail) form

There are two functions the gotcha module provides for developpers of other
modules.

	gotcha_api_gotcha_fields
	gotcha_api_gotcha_check


==================
1 -  gotcha_api_gotcha_fields($form_id, &$form)
==================
This function adds the formfields Gotcha uses to detect spam. Just call this
function after building the fields.

==================
2 - $suspect = gotcha_api_gotcha_check($log, $goto, $subject, $recipients, $body, $sendername, $sendermail, $site_name, $type)
==================
This function must be called in the validation- or the submit function of your form.
If you don't have a validation function just put it at the top of the submit.
You can choose:
- whether the api should log a spam attempt
- whether the api, if spam is detected, should go to the Gotcha Go Away-page or return
to your own function with an error code.

Input fields:
  $log:		1 / 0: yes / no logging a spam attempt message and the info.
  $goto:	1 / 0: yes / no goto goaway page at a a spam attempt

  The names of the following fields are based on those in the contact form ==> e-mail to send
  $subject:	subject of the e-mail
  $recipients:	recipients of the e-mail
  $body:	body of the e-mail: all formfields not mentioned elsewhere in the input fields, separated by "\n"
  $sendername:	name of the sender of the e-mail
  $sendermail:	e-mail address of the sender of the e-mail
  $site_name:	the result of variable_get('site_name', 'Drupal');
  $type:	your formtype name in 4 characters (e.g. user or mail).

Returns:
  $suspect:	0=no spam, 1=spam_content_filter reports spam, 2=Private Message contains data