XML-RPC が有効になると、多くの異なるプログラム言語で書かれた外部プログラムがこのサービスを使って POPFile と連携することができるようになります。POPFile の API は、0.22.0 のリリースで初めて一緒に提供された UI::XMLRPC モジュールをとおして提供されます。UI::XMLRPC モジュールは、標準的な POPFile インストレーションでは必要のない、いくつかの追加 Perl コンポーネントを必要とします。

API とメソッドについての詳細は、このページで見ることができます。

XML-RPC についての全般的な情報については、 XMLRPC.com で見ることができます。（訳注：リンク先は英語です）

Windows 版のインストーラは、UI::XMLRPC モジュールをオプションのコンポーネントとして扱っています（デフォルトではインストールされません）。オプションの UI::XMLRPC モジュールがインストールされる場合、Windows 版のインストーラはこのモジュールが必要とする追加 Perl コンポーネントもインストールします。

XMLRPC を使用して POPFile にアクセスするクライアントは、どんなマシンでも動かすことができ、また どんな プログラム言語 でも使用することができます（訳注：リンク先は英語です）。クライアントは提供されていませんので、自分で作らなければいけません。Perl、Python、Delphi、NSBasic/CE で書かれたクライアントの例が下に記載されています。

XML-RPC の接続待ちポートは POPFile の設定タブにあるモジュールオプションの欄で設定することができます。この設定は UI::XMLRPC.pm モジュールがインストールされ、POPFile が再起動してモジュールの存在を認識するまで表示されませんので注意してください。

インストールされると、POPFile UI のセキュリティタブのサーバ欄の下に新しいセキュリティオプションが追加されます。“ リモートマシンからの XML-RPC 接続を認める (POPFile の再起動が必要)” というオプションがあらわれるでしょう。POPFile が動作しているマシン以外からのアクセスを許可するためには、このオプションを「はい」にしなければいけません。

注意: Windows 版インストーラを使用して UI::XMLRPC モジュールをインストールした場合、これらの Perl コンポーネントは自動的にインストールされます。

以下の Perl モジュールは POPFile が動作しているマシンにインストールしなければいけません。さらに、SOAP::Lite モジュールは Perl クライアントを使って XMLRPC 経由で POPFile にアクセスするすべてのクライアントマシンにもインストールする必要があります。

• XMLRPC.pm は POPFile がインストールされたディレクトリの UI ディレクトリにインストールしなければいけません。これは CVS の ここ から入手することができます。このファイルを、XMLRPC.pm というファイル名で保存してください。このモジュールを認識させるためには、POPFile を再起動しなければいけません。

• XML-RPC の機能を使用するためには XMLRPC::Lite を含んでいる SOAP::Lite がインストールされている必要があります。SOAP::Lite モジュールは、 CPAN で入手することができます。Activestate Perl を使用している場合は ppm からインストールすることができます。例えば、

   ppm
   >install SOAP-Lite

とします。

use strict;
use XMLRPC::Lite;
 
my $sk = XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
         -> call('POPFile/API.get_session_key','admin',//)
         -> result;
 
print XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.classify',$sk,'spam.txt')
      -> result;
 
XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.release_session_key',$sk);

上記のソースを testxml.pl というファイル名で保存し、正しく設定されたシステムでテスト用のメッセージ 'spam.txt' に対して実行すれば、次のような結果が出力されるでしょう:

   perl testxml.pl
   spam

from xmlrpclib import ServerProxy
POPFile = ServerProxy("http://localhost:8081")
pf = POPFile.POPFile.API	# naming shortcut to make things easier
key = pf.get_session_key("admin","")
print pf.classify(key, "spam.txt")
pf.release_session_key(key)

上記のソースを testxml.py というファイル名で保存し、正しく設定されたシステムでテスト用のメッセージ 'spam.txt' に対して実行すれば、次のような結果が出力されるでしょう:

   python testxml.py
   spam

program popdelphi;
{$APPTYPE CONSOLE}
 
uses
  sysutils, xmlrpctypes, xmlrpcclient;
 
var
  caller: TCaller;
  func: TFunction;
  rslt: TResult;
  SessionKey: String;
  MessageBucket: String;
 
begin
  caller := TCaller.Create;
  caller.EndPoint := '/RPC2';
  caller.HostName := '127.0.0.1';
  caller.HostPort := 8081;
  func := TFunction.Create;
 
  func.ObjectMethod := 'POPFile/API.get_session_key';
  func.AddParam('admin');
  func.AddParam(//);
 
  rslt := caller.Execute(func);
  SessionKey := rslt.GetString;
 
  func.ObjectMethod := 'POPFile/API.classify';
  func.AddParam(SessionKey);
  func.AddParam(ExpandFileName(ParamStr(1)));
 
  rslt := caller.Execute(func);
  MessageBucket := rslt.GetString;
  Writeln(MessageBucket);
 
  func.ObjectMethod := 'POPFile/API.release_session_key';
  func.AddParam(SessionKey);
 
  caller.Free;
  func.Free;
end.

上記のソースの実装では、 Delphi XML-RPC library にある xmlrpctypes と xmlrpcclient を使用しています。 Indy - Internet Direct Components についても必要になるでしょう。

上記のソースを保存し、コンパイルすれば、popdelphi.exe ができるでしょう。これを DOS 窓で実行し、メッセージのファイル名を引数として渡し、正しく設定されたシステムを使用していれば、次のような結果が出力されるでしょう:

   popdelphi popfile99.msg
   spam

 AddObject "PocketXMLRPC.Factory","xmlrpc"
 Set popfile = xmlrpc.proxy("http://192.168.200.1:8081/RPC2","POPFile/API.")
 sessionKey = popfile.get_session_key("admin", "")
 message = MsgBox("POPFile Session Key is " & sessionKey, vbInformation, "POPFile Message")
 Print popfile.classify(sessionKey,"C:\spam.txt")
 popfile.release_session_key(sessionKey)

この実装では、 NS Basic/CE for Windows CE を使用しています。 PocketHTTP と PocketXML-RPC COM コンポーネントも必要になります。

覚えておきましょう、ここでは、localhost にアクセスしているのではなく、POPFile をインストールしたのとは別のマシンを使用しています。そのため、モバイルマシンが、POPFile が稼働しているマシンの有効なネットワーク IPアドレスをさす必要があります。上記の例では、192.168.200.1 が POPFile が稼働しているあなたのデスクトップ PC のIP アドレスです。あなたのモバイルマシンが ブルートゥースや無線LANを経由して、XMLRPC インターフェースにアクセスすることになります。 また、 リモートのマシンから、XML-RPC 接続を受け付けるように 設定する必要があります。これは、セキュリティ タブではいに設定することで行います。

use strict;
use XMLRPC::Lite;
 
my $xml= XMLRPC::Lite
   -> proxy('http://localhost:8081/RPC2')->on_fault(sub{});
 
# 
# POPFile からセッションキーを得る
#
 
my $sk = $xml->call("POPFile/API.get_session_key",'admin',//);
my $key = $sk->result;
my $method = "POPFile/API.$ARGV[0]";
my @params = @ARGV[1..10];
 
unshift @params,$key;
 
my $can = $xml->can($method);
my $res = eval {$xml->call($method,@params)};
 
if ($@) {
    print join("\n","syntax error: " ,$@);
    exit(1);
} elsif ($can && !UNIVERSAL::isa($res => 'XMLRPC::SOM')) {
    print $res;
} elsif (defined($res) && $res->fault) {
    print join ("\n","XMLRPC FAULT: ", @{$res->fault}{'faultCode','faultString'});
    exit(1);
} elsif (!$xml->transport->is_success) {
    print join ("\n","TRANSPORT ERROR: ", $xml->transport->status);  
} else  {
    print join ("\n",$res->paramsall);
}
 
#
# セッションキーを解放する
#
 
$xml->call("POPFile/API.release_session_key",$key);
 
#
# All Done
#
 
exit(0);

上記のソースを testxml.pl というファイル名で保存し、コマンドラインパラメータとともに実行すれば、指定した API の実行結果が返ってきます。

   perl testxml.pl get_bucket_parameter spam count
   9418

   perl testxml.pl get_bucket_parameter spam fpcount
   24

   perl testxml.pl get_bucket_parameter spam fncount
   43

   perl testxml.pl get_bucket_color spam
   red

   perl testxml.pl get_bucket_word_count spam
   37135

   perl testxml.pl get_bucket_unique_count spam
   9407

   perl testxml.pl get_buckets
   magnet
   normal
   spam

pipe.pl を XMLRPC のクライアントとして実装します。

#!/usr/bin/perl
use strict;
use XMLRPC::Lite;
 
# 安全な一時ファイルを使用したいのですが、このスクリプトはふつうひとりのユーザとして動くでしょう
use File::Temp qw/tempfile tempdir/;
 
# アクセスすることができるフォルダはスクリプトが終了したときに削除されるでしょう
my $temp_dir = tempdir( CLEANUP => 1);
 
# フルパスが指定された一時ファイル
my ($fh_in, $filename_in) = tempfile('popfileinXXXXXXX', SUFFIX => ".msg", UNLINK => 1 , DIR => $temp_dir);
 
# パイプとして動くため、標準入力 (STDIN) から読み込みます
while (<STDIN>) {
	print $fh_in $_;
}
 
# POPFile は、ファイルが閉じられていることを前提とします
close $fh_in;
 
# 安全な出力ファイルを作成します
my ($fh_out, $filename_out) = tempfile('popfileoutXXXXXXX', SUFFIX => ".msg", UNLINK => 1, DIR => $temp_dir);
 
# XMLRPC のプロキシ
my $xmlrpc = XMLRPC::Lite ->proxy('http://localhost:8086/RPC2');
 
# POPFile に挨拶して、セッションキーを取得します
my $sk = $xmlrpc-> call('POPFile/API.get_session_key','admin',//)
		-> result;
 
# ここで仕事をします
$xmlrpc-> call('POPFile/API.handle_message',$sk,$filename_in,$filename_out)
		-> result;
 
# POPFile にお別れをします
$xmlrpc-> call('POPFile/API.release_session_key',$sk);
 
# パイプとして動くために、標準出力 (STDOUT) に書き込みます
while (<$fh_out>) {
	print $_;
}
 
# 終了します。File::Temp が（一時ファイルを）片付けてくれます
exit(0);

UI::XMLRPC モジュールを通して、POPFile の API ( POPFile::API モジュールで定義されています) すべてにアクセスすることができます。 API の文法についての詳しいドキュメントについては、POPFile と一緒に配布されている Classifier::Bayes モジュールを参照してください。

すべての API を使用するためには、まず get_session_key API を使用してセッションキーを取得しなければいけません。終了するときには、release_session_key を使ってキーを解放すべきです。

XML-RPC に存在するメソッドは下記のとおりです:

call('POPFile/API.get_session_key', 'admin', '')

call('POPFile/API.release_session_key', 'session_key')

call('POPFile/API.classify', 'session_key', 'filename')

call('POPFile/API.handle_message', 'session_key', 'inputfilename', 'outputfilename')

call('POPFile/API.get_buckets', 'session_key')

call('POPFile/API.get_pseudo_buckets', 'session_key')

call('POPFile/API.get_all_buckets', 'session_key')

call('POPFile/API.is_bucket','session_key', 'bucketname')

call('POPFile/API.is_pseudo_bucket', 'session_key', 'bucketname')

call('POPFile/API.get_bucket_word_count', 'session_key', 'bucketname')

call('POPFile/API.get_bucket_word_list', 'session_key', 'bucketname')

call('POPFile/API.get_bucket_word_prefixes', 'session_key', 'bucketname')

call('POPFile/API.get_count_for_word', 'session_key', 'bucketname', 'someword')

call('POPFile/API.get_word_count', 'session_key')

call('POPFile/API.get_bucket_unique_count', 'session_key', 'bucketname')

call('POPFile/API.get_bucket_color', 'session_key', 'bucketname')

call('POPFile/API.set_bucket_color', 'session_key', 'bucketname', 'colorstring')

call('POPFile/API.get_bucket_parameter', 'session_key', 'bucketname', 'parameter')

call('POPFile/API.set_bucket_parameter', 'session_key', 'bucketname', 'parameter', 'value')

call('POPFile/API.get_html_colored_message', 'session_key', 'filename')

call('POPFile/API.create_bucket', 'session_key', 'bucketname')

call('POPFile/API.delete_bucket', 'session_key', 'bucketname')

call('POPFile/API.rename_bucket', 'session_key', 'bucketname', 'newname')

call('POPFile/API.add_message_to_bucket', 'session_key', 'bucketname', 'filename')

call('POPFile/API.add_messages_to_bucket', 'session_key', 'bucketname', 'filelist')

call('POPFile/API.remove_message_from_bucket', 'session_key', 'bucketname', 'filename')

call('POPFile/API.magnet_count', 'session_key',)

call('POPFile/API.get_buckets_with_magnets', 'session_key')

call('POPFile/API.get_magnet_types_in_bucket', 'session_key', 'bucketname')

call('POPFile/API.clear_bucket', 'session_key', 'bucketname')

call('POPFile/API.clear_magnets','session_key')

call('POPFile/API.get_magnets', 'session_key', 'bucketname','type')

call('POPFile/API.create_magnet', 'session_key', 'bucketname', 'magnettype', 'magnetvalue')

call('POPFile/API.get_magnet_types', 'session_key')

call('POPFile/API.delete_magnet', 'session_key', 'bucketname', 'magnettype', 'magnetvalue')

call('POPFile/API.get_stopword_list', 'session_key')

call('POPFile/API.add_stopword', 'session_key', 'mystopword')

call('POPFile/API.remove_stopword', 'session_key', 'mystopword')

注意: 上記の API の呼び出しにおいて、'session_key' は get_session_key API で取得することができるキーを使用します。

POPFile の古いバージョンでは、“Classifier/Bayes” を “POPFile/API” の代わりに使用してください。

原文