これは、XML-RPC サーバのクライアントを表現するために使用されます。
コンストラクタは以下のような構文です。
リクエストを送信したい RPC サーバスクリプトのパスと名前。
接続先リモートサーバの URL 。プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
リモートサーバに接続する際のポート。デフォルトは 80 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
もし使用するなら、プロキシサーバの URL 。 プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
リモートサーバに接続する際のポート。デフォルトは 8080 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
プロキシサーバにアクセスするためのユーザ名。
プロキシサーバにアクセスするためのパスワード。
注意 SSL 接続を使用するには、 openssl 拡張モジュールを有効にして PHP がインストールされている必要があります。
betty.userland.com にある Userland の XML-RPC サーバに問い合わせるためのクライアント設定の例は このようになります。
$client = new XML_RPC_Client('/RPC2', 'betty.userland.com'); |
このクラスは以下のメソッドをサポートしています。
このメソッドは以下のような書式です。
$xmlrpc_message は XML_RPC_Message のインスタンスで、 $response は XML_RPC_Response のインスタンスです（XML_RPC_Response を参照ください）。
$timeout はオプションで、指定しなかった場合は 0（永遠に待ち続ける）となります。この値は fsockopen() に渡されます。
もし $response の内容が XML_RPC_Response ではなく 0 であった場合、それは I/O エラーが発生したことを 表します。発生した I/O エラーの内容については、 $client->errno および $client->errstring の値から知ることができます。
低レベルのエラーに加え、問い合わせ先の XML-RPC サーバが XML_RPC_Response オブジェクトの中でエラーを 返すこともあります。これらのエラーを処理する方法については XML_RPC_Response を参照ください。
このメソッドは、クライアントがサーバに対する認証処理を行う際の ユーザ名とパスワードを指定します。デフォルトの通信（HTTP）では、 これらの情報が HTTP ベーシック認証に使用されます。
このクラスは XML-RPC サーバへのリクエストを表します。クライアントは XML_RPC_Message をサーバに送信し、 XML_RPC_Response を受け取ります。
コンストラクタは以下のような構文です。
$methodName は起動したいメソッドの名前で、 $parameterArray は XML_RPC_Value オブジェクトの配列です。 US state name サーバにメッセージを送信する例です。
require_once "XML/RPC.php";
$msg = new XML_RPC_Message("examples.getStateName", array(new XML_RPC_Value(23, "int"))); |
この例では州番号 23 の州の名前を問い合わせています。 XML_RPC_Value オブジェクトについての 詳細な情報は XML_RPC_Value を参照ください。
このメソッドのコールにより、パラメータリストに XML_RPC_Value オブジェクト $xmlrpcVal を追加します。
XML_RPC_Value オブジェクトを返します。 パラメータが存在しない場合は XML_RPC_Response オブジェクトが返されます。
文字列 $xmlString に含まれる XML-RPC サーバからの 応答を受け取り、XML_RPC_Response オブジェクトを 構築してそれを返します。また適切なエラーコードを設定します。
このメソッドは、見つかった HTTP/MIME ヘッダをすべて処理します。
このクラスは、XML-RPC リクエストに対する応答を格納するために使用されます。 サーバのメソッドハンドラは XML_RPC_Response を 作成し、返り値としてそれを渡します。 XML_RPC_Client クラスの send() メソッドを実行した際に、これと同じ値が返されます。
ひとつめのインスタンスは、何の問題もなく処理が実行された際に使用されます。 $xmlrpcval は XML_RPC_Value の値で、メソッドの実行結果が 格納されています。
2 番目の形式のコンストラクタは、失敗時に使用されます。どこに問題が あったのかを示すために、$errcode および $errstring が使用されます。渡されるエラーコードの 詳細については XML_RPC_Server を参照ください。
これは、多くの大変な仕事を担当するものです。このクラスは、XML-RPC で使用する値の作成とカプセル化を可能にします。
事前に http://www.xmlrpc.com/stories/storyReader$7 で XML-RPC の仕様を読んでおくと、これ以降の内容を理解しやすくなるでしょう。
XML_RPC_Value クラスは、以下の型を利用して 任意の複雑な値を格納することが可能です。 i4、 int、 boolean、 string、 double、 dateTime.iso8601、 base64、 array あるいは struct。 これらの型についての詳細な情報は 仕様 を参照ください。
この型を使用すると、Base64 エンコーディングが透過的に行われます。 そのため、これはバイナリデータ型として扱うべきで、7 ビットクリーン ではないデータを渡したい場合に使用します。デコード処理もまた 透過的に行われます。
<、 >、 " および & の各文字は、 XML-RPC での通信の際に各々と等価なエンティティ <、 >、 " および & に変換されます。現在の XML-RPC の仕様では エンコードするよう推奨されているのは < および & だけですが、この実装ではさらに一歩先を行っています。 その理由は XML 1.0 勧告 で説明されています。
注意 現在は、文字列 "-1" を XML_RPC_Value のコンストラクタに渡すと、空の結果を作成します。"-1" は特別な値として扱われます。
TODO: ' エンティティは現在サポートされていません。
コンストラクタは、XML_RPC_Value を生成するための一般的な方法です。コンストラクタは以下のような構文です。
最初のコンストラクタは空の値を生成します。使用する前に、必ず addScalar()、 addArray() あるいは addStruct() で初期化しなければなりません。
2 番目のコンストラクタはシンプルな文字列値を生成します。
3 番目のコンストラクタはスカラ値を生成するために使用されます。 第 2 パラメータは、以下の例のように XML-RPC 型の名前である必要があります。
$myInt = new XML_RPC_Value(1267, "int");
$myString= new XML_RPC_Value("Hello, World!", "string");
$myBool = new XML_RPC_Value(1, "boolean"); |
4 番目の形式のコンストラクタは、複雑な XML-RPC の値を作成するのに 使用されます。値が XML-RPC の 配列 である場合は 単純な配列、構造体 の場合は連想配列を 第 1 パラメータに指定します。配列の要素は XML_RPC_Value オブジェクトである必要があります 。例えば以下のようになります。
$myArray = new XML_RPC_Value(array(
new XML_RPC_Value("Tom"), new XML_RPC_Value("Dick"),
new XML_RPC_Value("Harry")), "array");
$myStruct = new XML_RPC_Value(array(
"name" => new XML_RPC_Value("Tom"),
"age" => new XML_RPC_Value(34, "int"),
"geek" => new XML_RPC_Value(1, "boolean")), "struct"); |
$val が空の XML_RPC_Value だった場合、このメソッドは そこにスカラ値を設定します。すでに $val に スカラ値が設定されていた場合、新たにスカラ値が追加されることはなく 0 が返されます。すべての処理がうまく終了した場合は 1 が返されます。
$val が 配列 だった場合は特別で、スカラ値が配列に追加されます。
このクラスの現在の実装は、できる限りシンプルであることを心がけています。 基本的には、コンストラクタがすべての仕事をこなします。最低限の例は 以下のとおりです。
function foo ($params) {
...
}
$s = new XML_RPC_Server(array("examples.myFunc" => array("function" => "foo"))); |
これは、サーバで実行させたい仕事をすべて行ってくれます。たったひとつの 引数は連想配列であり、メソッド名と関数名を対応させます。リクエストが 解析されると適切な関数が呼び出され、関数が返す XML_RPC_Response オブジェクトはシリアライズされて コール元に返されます。
ハンドラ関数 foo() が何を行うのかについて、 もうすこし詳しく見てみましょう。
function foo ($params) {
global $XML_RPC_erruser; // ユーザエラーコードの値をインポート
// $params は、受信した XML_RPC_Message オブジェクト
if ($err) {
// エラーが発生した場合
return new XML_RPC_Response(0, $XML_RPC_erruser+1, // ユーザエラー 1
"艦長、問題が発生しました。");
} else {
// 処理が成功した際に返す値
return new XML_RPC_Response(new XML_RPC_Value("万事順調!", "string"));
}
} |
XML_RPC_Server() コンストラクタの最初の引数は配列で、 ディスパッチマップと呼ばれます。この配列の中にあるのは、 あなたが定義した XML-RPC メソッドを提供するために必要な情報です。
ディスパッチマップは、連想配列の連想配列という形式になります。 外側の配列は個々のメソッドに対してひとつのエントリを持ち、 メソッド名が連想配列のキーとなります。キーに対応する値は別の連想配列で、 以下のようなメンバを保持します。
function - このエントリは必須です。 XML-RPC メソッドを提供するために使用するグローバルスコープの関数名である 必要があります。
正規表現・クラス名とメソッド名・オブジェクトとメソッド名 などが使用可能です。このマニュアル内の例で、 これらのすべての方法の使用例を示しています。
signature - このエントリは、メソッドがとりうる シグネチャ（Signatures を参照ください）を含む配列です。このエントリが存在する場合、 メソッドを割り振る前にサーバ側で引数の数や型のチェックを行います。
docstring - このエントリは、メソッドの ドキュメントを含む文字列です。ドキュメントには HTML マークアップを 含めることが可能です。
シグネチャとは、メソッドの返り値の型やそのパラメータの型を示すものです。 メソッドは、すくなくともひとつのシグネチャを持っています。
サーバのディスパッチマップ内では、個々のメソッドはとりうるシグネチャの 配列を保持しています。各シグネチャの中身は型の配列で、最初のエントリは 返り値の型です。
例を実行してみましょう。このような普通の PHP 関数を書こうとしている状況を 想定してください。
function is_8($input, $strict = false) {
if ($strict) {
return ($input === 8);
} else {
return ($input == 8);
}
} |
この関数を XML_RPC サーバで動作させようとすると、このように 書く必要があります。
function is_8($params) {
// このパラメータは必須
$param = $params->getParam(0);
if (!XML_RPC_Value::isValue($param)) {
return $param;
}
$input = $param->scalarval();
// このパラメータはオプション
$param = $params->getParam(1);
if (!XML_RPC_Value::isValue($param)) {
$strict = false;
} else {
$strict = $param->scalarval();
}
if ($strict) {
$answer = ($input === 8);
} else {
$answer = ($input == 8);
}
$val = new XML_RPC_Value($answer, 'boolean');
return new XML_RPC_Response($val);
} |
これは、とりうる順番のシグネチャをすべて網羅したものです。
array(
array('boolean', 'int'),
array('boolean', 'int', 'boolean'),
array('boolean', 'string'),
array('boolean', 'string', 'boolean'),
) |
サーバはこのようにしてインスタンス化します。
$server = new XML_RPC_Server(
array(
'isan8' =>
array(
'function' => 'is_8',
'signature' =>
array(
array('boolean', 'int'),
array('boolean', 'int', 'boolean'),
array('boolean', 'string'),
array('boolean', 'string', 'boolean'),
),
'docstring' => '値は 8 ですか?'
),
),
1,
0
); |
使いやすさを考慮し、XML-RPC の型を表す文字列がグローバル変数として コード化されています。
$GLOBALS['XML_RPC_I4'] = 'i4'; $GLOBALS['XML_RPC_Int'] = 'int'; $GLOBALS['XML_RPC_Boolean'] = 'boolean'; $GLOBALS['XML_RPC_Double'] = 'double'; $GLOBALS['XML_RPC_String'] = 'string'; $GLOBALS['XML_RPC_DateTime'] = 'dateTime.iso8601'; $GLOBALS['XML_RPC_Base64'] = 'base64'; $GLOBALS['XML_RPC_Array'] = 'array'; $GLOBALS['XML_RPC_Struct'] = 'struct'; |
あなたが作ろうとしているサーバでは、何らかの理由（たとえば セキュリティ認証など）によりリクエストに対する応答をいったん保留したい こともあるでしょう。コンストラクタの 2 番目の引数に 0 を渡すと、お望みの効果が得られます。その後、 サーバクラスの service() メソッドを使用して リクエストを処理すればよいのです。たとえば以下のようになります。
$s = new XML_RPC_Server($myDispMap, 0); // ... 何らかの他の処理をここで行う $s->service(); |
サーバが返す失敗コードは、グローバルの $xmlrpcerruser が指す値に 1 を加えた値から開始するべきです。
サーバが返す標準的なエラーには以下のようなものがあります。
サーバが関知しないメソッドの実行を要求された際に返されます。
このエラーは、実際のところサーバやコードではなくクライアント側で 発生します。しかし、これはサーバが自分で理解できない何かを返したことを 示します。
サーバがメソッドに対応したシグネチャを保持しており、クライアントから 渡されたパラメータがいずれのシグネチャにも一致しなかった際に発生します。
このエラーは、組み込みの system.*() メソッドから 発生するもので、サーバ上で未定義のメソッドを実行しようとした際に起こります。
このエラーは、サーバからの応答として HTTP/1.1 200 OK が戻ってこなかった際に クライアント側で発生します。エラーの詳細な情報は、上のメッセージの最後に 付け加えられます。
発生した障害の XML パーサエラーコードに 100 を加えたものを返します。 返される faultString の中には、入力 XML ストリームの どこでパースエラーが発生したのかが示されています。