testComment
The testComment function of our API allows you to test whether a submitted comment is SPAM or not.
The Input Paramater
The testComment function accepts a single parameter, which is an XML::RPC struct. (XML-RPC mandates the format of several parameter types such as "string", "int", "struct". In this case consider a "struct" analagous to a perl hash or a PHP array).
The structure you pass may have the following members. Members which are not recognised will be ignored.
Name Description comment The body of the submitted comment. required ip The IP address the comment was submitted from. required agent The user-agent the submitter supplied. The email address the submitter supplied. link The homepage link the submitter supplied. name The name the submitter supplied. options Additional options to control how things should work. site A link to your site. subject The subject/title the submitter supplied. version The version of the plugin that you're using, if any.
The Return Value
The return value of the function call is a single string. This string will contain one of three values:
ERROR:[message] There was a fatal error during the processing of your request. OK The submitted content was judged to be non-spam. SPAM:[reason] The submitted content was judged to be spam. The error and spam results will return an optional reason, separated by a colon (:) character. This reason might be missing, but if present should provide sufficient diagnostic information to be useful.
If you receive a timeout, or other transient failure, it is up to you to decide how to handle this. Personally if I were coding a new plugin I'd simply allow the comment - rather than retrying.
Customizing The Testing
In the input parameter table above you'll notice there is an "options" parameter. You may submit a number of flags in this field to affect the testing of your submitted comment.
Set the value of this parameter to a comma-separated string - with the following possible components:
Name Description Default blacklist=1.2.3.4 Blacklist the given IP (*) exclude=foo Don't run the plugin test "foo" (**) fail If you pass this option your query will always return a SPAM result.
Useful for testing.whitelist=1.2.3.4 Whitelist the given IP (*) mandatory=subject Specify that the given field should always be present.
See the table on above for valid field names.max-links=5 The comment body must contain fewer than 5 links 10 max-size=2k The comment body must be smaller than 2k to be approved. min-size=2k The comment body must be at least 2k to be approved. min-words=10 The comment body must contain at least 10 words to be approved. 4 Multiple Values
Values may be specified multiple times. For example you might wish to blacklist the two IP addresses 1.2.3.4 and 8.7.6.5 This could be done by passing an "options" string of:
blacklist=1.2.3.4,blacklist=8.7.6.5[*] - You may use either a literal IP address ("192.168.1.1") or a CIDR range ("192.168.1.0/8").
[**] - You can find a list of plugin names here along with their code or use the getPlugins method to return a list.