API
XML_RPC_Client
これは、XML-RPC サーバのクライアントを表現するために使用されます。
生成
コンストラクタは以下のような構文です。
$client = new XML_RPC_Client (
string $path
,
string $server
,
integer $port
,
string $proxy
,
integer $proxy_port
,
string $proxy_user
,
string $proxy_pass
)
- string $path
-
リクエストを送信したい RPC サーバスクリプトのパスと名前。
- string $server
-
接続先リモートサーバの URL 。プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
- integer $port
-
リモートサーバに接続する際のポート。デフォルトは 80 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
- string $proxy
-
もし使用するなら、プロキシサーバの URL 。 プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
- integer $proxy_port
-
リモートサーバに接続する際のポート。デフォルトは 8080 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
- string $proxy_user
-
プロキシサーバにアクセスするためのユーザ名。
- string $proxy_pass
-
プロキシサーバにアクセスするためのパスワード。
SSL 接続を使用するには、 openssl 拡張モジュールを有効にして PHP がインストールされている必要があります。
betty.userland.com にある Userland の XML-RPC サーバに問い合わせるためのクライアント設定の例は このようになります。
<?php
$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');
?>
メソッド
このクラスは以下のメソッドをサポートしています。
send()
このメソッドは以下のような書式です。
$response = $client->send (
$xmlrpc_message
, $timeout
)
$xmlrpc_message は XML_RPC_Message のインスタンスで、 $response は XML_RPC_Response のインスタンスです（API を参照ください）。
$timeout はオプションで、指定しなかった場合は 0（永遠に待ち続ける）となります。この値は fsockopen() に渡されます。
もし $response の内容が XML_RPC_Response ではなく 0 であった場合、それは I/O エラーが発生したことを 表します。発生した I/O エラーの内容については、 $client->errno および $client->errstring の値から知ることができます。
低レベルのエラーに加え、問い合わせ先の XML-RPC サーバが XML_RPC_Response オブジェクトの中でエラーを 返すこともあります。これらのエラーを処理する方法については API を参照ください。
setCredentials()
$client->setCredentials (
$username
, $password
)
このメソッドは、クライアントがサーバに対する認証処理を行う際の ユーザ名とパスワードを指定します。デフォルトの通信（HTTP）では、 これらの情報が HTTP ベーシック認証に使用されます。
setDebug()
$client->setDebug (
$debugOn
)
$debugOn は 0 あるいは 1 のどちらかで、クライアントのブラウザにデバッグ情報を 表示するか否かを指定します。デフォルトではこの情報を表示しません。
デバッグ情報の中には XML-RPC サーバが返す問い合わせ結果の生データが含まれ、 またサーバから返された値を表すためにクライアントが作成しようとした PHP の値も含まれます。サーバが返す内容を正確に確認することができるので、 このオプションはサーバのデバッグ時に有用です。
XML_RPC_Message
このクラスは XML-RPC サーバへのリクエストを表します。クライアントは XML_RPC_Message をサーバに送信し、 XML_RPC_Response を受け取ります。
生成
コンストラクタは以下のような構文です。
$msg = new XML_RPC_Message (
$methodName
, $parameterArray
)
$methodName は起動したいメソッドの名前で、 $parameterArray は XML_RPC_Value オブジェクトの配列です。 US state name サーバにメッセージを送信する例です。
<?php
require_once "XML/RPC.php";
$msg = new XML_RPC_Message("examples.getStateName", array(new XML_RPC_Value(23, "int")));
?>
この例では州番号 23 の州の名前を問い合わせています。 XML_RPC_Value オブジェクトについての 詳細な情報は API を参照ください。
メソッド
serialize()
$outString = $msg->serialize (
)
XML-RPC メッセージを表す XML 文字列を返します。
addParam()
$msg->addParam (
$xmlrpcVal
)
このメソッドのコールにより、パラメータリストに XML_RPC_Value オブジェクト $xmlrpcVal を追加します。
XML_RPC_Value オブジェクトを返します。 パラメータが存在しない場合は XML_RPC_Response オブジェクトが返されます。
getParam()
$xmlrpcVal = $msg->getParam (
$n
)
メッセージ中の $n 番目のパラメータを取得します。 このメソッドが使用できるかどうかはサーバの実装に依存します。 もしパラメータが存在しない場合は undef を返します。
getNumParams()
$n = $msg->getNumParams (
)
メッセージに付属するパラメータの数を返します。
method()
$methName=$msg->method (
)
$msg->method (
$methName
)
XML-RPC メッセージ中に含まれるメソッドを取得あるいは設定します。
parseResponse()
$response = $msg->parseResponse (
$xmlString
)
文字列 $xmlString に含まれる XML-RPC サーバからの 応答を受け取り、XML_RPC_Response オブジェクトを 構築してそれを返します。また適切なエラーコードを設定します。
このメソッドは、見つかった HTTP/MIME ヘッダをすべて処理します。
parseResponseFile()
$response = $msg->parseResponseFile (
$fileHandle
)
ファイルハンドル $fileHandle から XML-RPC サーバの応答を読み込み、それを parseResponse() に渡します。
このメソッドは、事前に用意されたファイルから応答を生成する際に有用です。 また、見つかった HTTP ヘッダをすべて処理します。
XML_RPC_Response
このクラスは、XML-RPC リクエストに対する応答を格納するために使用されます。 サーバのメソッドハンドラは XML_RPC_Response を 作成し、返り値としてそれを渡します。 XML_RPC_Client クラスの send() メソッドを実行した際に、これと同じ値が返されます。
生成
$resp = new XML_RPC_Response (
$xmlrpcval
)
$resp = new XML_RPC_Response (
0
, $errcode
, $errstring
)
ひとつめのインスタンスは、何の問題もなく処理が実行された際に使用されます。 $xmlrpcval は XML_RPC_Value の値で、メソッドの実行結果が 格納されています。
2 番目の形式のコンストラクタは、失敗時に使用されます。どこに問題が あったのかを示すために、$errcode および $errstring が使用されます。渡されるエラーコードの 詳細については API を参照ください。
メソッド
faultCode()
$fn = $resp->faultCode (
)
XML-RPC レスポンス $resp から、失敗のコードを 整数値で返します。ゼロは成功を、それ以外の値は失敗を意味します。
faultString()
$fs = $resp->faultString (
)
$resp->faultCode が示す失敗の内容を、 人間が読める形式で返します。
value()
$xmlrpcVal = $resp->value (
)
サーバから送信された返り値が含まれる XML_RPC_Value オブジェクトを返します。応答の faultCode がゼロ以外の 場合、このメソッドが返す値を使用するべきではありません（返り値は オブジェクトですらないかもしれません）。
serialize()
$outString = $resp->serialize (
)
応答を、XML 文字列形式で返します。
XML_RPC_Value
これは、多くの大変な仕事を担当するものです。このクラスは、XML-RPC で使用する値の作成とカプセル化を可能にします。
事前に http://www.xmlrpc.com/stories/storyReader$7 で XML-RPC の仕様を読んでおくと、これ以降の内容を理解しやすくなるでしょう。
XML_RPC_Value クラスは、以下の型を利用して 任意の複雑な値を格納することが可能です。 i4、 int、 boolean、 string、 double、 dateTime.iso8601、 base64、 array あるいは struct。 これらの型についての詳細な情報は 仕様 を参照ください。
型についての注意
int
i4 型は int の別名です。コード中で値を解析する際には 自動的に i4 が int に変換されます。この実装では、int のほうを 正式名とみなしています。
base64
この型を使用すると、Base64 エンコーディングが透過的に行われます。 そのため、これはバイナリデータ型として扱うべきで、7 ビットクリーン ではないデータを渡したい場合に使用します。デコード処理もまた 透過的に行われます。
boolean
true および 1 は true にマップされます。それ以外のすべての値 （空文字列を含む）は false に変換されます。
string
<、 >、 " および & の各文字は、 XML-RPC での通信の際に各々と等価なエンティティ <、 >、 " および & に変換されます。現在の XML-RPC の仕様では エンコードするよう推奨されているのは < および & だけですが、この実装ではさらに一歩先を行っています。 その理由は XML 1.0 勧告 で説明されています。
現在は、文字列 "-1" を XML_RPC_Value のコンストラクタに渡すと、空の結果を作成します。"-1" は特別な値として扱われます。
TODO: ' エンティティは現在サポートされていません。
生成
コンストラクタは、XML_RPC_Value を生成するための一般的な方法です。コンストラクタは以下のような構文です。
$myVal = new XML_RPC_Value (
)
$myVal = new XML_RPC_Value (
$stringVal
)
$myVal = new XML_RPC_Value (
$scalarVal
, 'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64'
)
$myVal = new XML_RPC_Value (
$arrayVal
, 'array' | 'struct'
)
最初のコンストラクタは空の値を生成します。使用する前に、必ず addScalar()、 addArray() あるいは addStruct() で初期化しなければなりません。
2 番目のコンストラクタはシンプルな文字列値を生成します。
3 番目のコンストラクタはスカラ値を生成するために使用されます。 第 2 パラメータは、以下の例のように XML-RPC 型の名前である必要があります。
<?php
$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");
メソッド
addScalar()
$ok = $val->addScalar (
$stringVal
)
$ok = $val->addScalar (
$scalarVal
, 'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64'
)
$val が空の XML_RPC_Value だった場合、このメソッドは そこにスカラ値を設定します。すでに $val に スカラ値が設定されていた場合、新たにスカラ値が追加されることはなく 0 が返されます。すべての処理がうまく終了した場合は 1 が返されます。
$val が 配列 だった場合は特別で、スカラ値が配列に追加されます。
addArray()
$ok = $val->addArray (
$arrayVal
)
空の XML_RPC_Value を、 $arrayVal で指定した内容の 配列 に変換します。詳細な情報は、4 番目の コンストラクタの書式を参照ください。
addStruct()
$ok = $val->addStruct (
$assocArrayVal
)
空の XML_RPC_Value を、 $assocArrayVal で指定した内容の 構造体 に変換します。詳細な情報は、4 番目の コンストラクタの書式を参照ください。
kindOf()
$kind = $val->kindOf (
)
値の型を表す文字列 struct、array あるいは scalar を返します。もし値が まだ初期化されていない場合は undef を返します。
serialize()
$outString = $val->serialize (
)
値を、XML-RPC 形式の文字列で返します。
scalarval()
$scalarVal = $val->scalarval (
)
$val->kindOf() == 'scalar' の場合、 このメソッドは PHP 言語のスカラ値を返します（Base64 デコード処理は自動的に行われます）。
scalartyp()
$typeName = $val->scalartyp (
)
$val->kindOf() == 'scalar' の場合、 このメソッドはスカラの型を表す文字列を返します。先に述べたとおり、 i4 は常に int に変換されます。
arraymem()
$xmlrpcVal = $val->arraymem (
$n
)
$val で表される配列から、 $n 番目の要素を返します。 返される値は XML_RPC_Value オブジェクトです。
arraysize()
$len = $val->arraysize (
)
$val が array の場合、その配列の要素数を返します。
structmem()
$xmlrpcVal = $val->structmem (
$memberName
)
$val で表される構造体から、 $memberName に対応する要素を返します。 返される値は XML_RPC_Value オブジェクトです。
structeach()
list($key,$value) = $val->structeach (
)
$val が構造体の場合に、次の 「キー・値」の組み合わせを返します。API も参照ください。
structreset()
$val->structreset (
)
$val で表される構造体について、 structeach() の内部ポインタを構造体の先頭に戻します。
XML_RPC_Server
このクラスの現在の実装は、できる限りシンプルであることを心がけています。 基本的には、コンストラクタがすべての仕事をこなします。最低限の例は 以下のとおりです。
<?php
function foo ($params) {
...
}
$s = new XML_RPC_Server(array("examples.myFunc" => array("function" => "foo")));
?>
これは、サーバで実行させたい仕事をすべて行ってくれます。たったひとつの 引数は連想配列であり、メソッド名と関数名を対応させます。リクエストが 解析されると適切な関数が呼び出され、関数が返す XML_RPC_Response オブジェクトはシリアライズされて コール元に返されます。
ハンドラ関数 foo() が何を行うのかについて、 もうすこし詳しく見てみましょう。
<?php
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 - このエントリは、メソッドがとりうる シグネチャ（API を参照ください）を含む配列です。このエントリが存在する場合、 メソッドを割り振る前にサーバ側で引数の数や型のチェックを行います。
-
docstring - このエントリは、メソッドの ドキュメントを含む文字列です。ドキュメントには HTML マークアップを 含めることが可能です。
メソッドのシグネチャ
シグネチャとは、メソッドの返り値の型やそのパラメータの型を示すものです。 メソッドは、すくなくともひとつのシグネチャを持っています。
サーバのディスパッチマップ内では、個々のメソッドはとりうるシグネチャの 配列を保持しています。各シグネチャの中身は型の配列で、最初のエントリは 返り値の型です。
例を実行してみましょう。このような普通の PHP 関数を書こうとしている状況を 想定してください。
<?php
function is_8($input, $strict = false) {
if ($strict) {
return ($input === 8);
} else {
return ($input == 8);
}
}
?>
この関数を XML_RPC サーバで動作させようとすると、このように 書く必要があります。
<?php
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);
}
?>
これは、とりうる順番のシグネチャをすべて網羅したものです。
<?php
array(
array('boolean', 'int'),
array('boolean', 'int', 'boolean'),
array('boolean', 'string'),
array('boolean', 'string', 'boolean'),
)
?>
サーバはこのようにしてインスタンス化します。
<?php
$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 の型を表す文字列がグローバル変数として コード化されています。
<?php
$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() メソッドを使用して リクエストを処理すればよいのです。たとえば以下のようになります。
<?php
$s = new XML_RPC_Server($myDispMap, 0);
// ... 何らかの他の処理をここで行う
$s->service();
?>
失敗の報告
サーバが返す失敗コードは、グローバルの $xmlrpcerruser が指す値に 1 を加えた値から開始するべきです。
サーバが返す標準的なエラーには以下のようなものがあります。
- 1 Unknown method
-
サーバが関知しないメソッドの実行を要求された際に返されます。
- 2 Invalid return payload
-
このエラーは、実際のところサーバやコードではなくクライアント側で 発生します。しかし、これはサーバが自分で理解できない何かを返したことを 示します。
- 3 Incorrect parameters
-
サーバがメソッドに対応したシグネチャを保持しており、クライアントから 渡されたパラメータがいずれのシグネチャにも一致しなかった際に発生します。
- 4 Can't introspect: method unknown
-
このエラーは、組み込みの system.*() メソッドから 発生するもので、サーバ上で未定義のメソッドを実行しようとした際に起こります。
- 5 Didn't receive 200 OK from remote server
-
このエラーは、サーバからの応答として HTTP/1.1 200 OK が戻ってこなかった際に クライアント側で発生します。エラーの詳細な情報は、上のメッセージの最後に 付け加えられます。
- 100- XML parse errors
-
発生した障害の XML パーサエラーコードに 100 を加えたものを返します。 返される faultString の中には、入力 XML ストリームの どこでパースエラーが発生したのかが示されています。
XML_RPC_Dump
このクラスは、XML_RPC_Value オブジェクト内のデータの 文字列表現を生成します。
その他の関数
以下は XML_RPC オブジェクトの外部にある関数です。
XML_RPC_encode()
$rpc = XML_RPC_encode (
$php_val
)
PHP のネイティブデータ型を受け取り、それを XML_RPC オブジェクト型に 変換します。
XML_RPC_decode()
$values = XML_RPC_decode (
$XML_RPC_val
)
XML_RPC オブジェクト型のメッセージを受け取り、それを PHP の ネイティブデータ型に変換します。
忘却曲線を使ってこの知識を確実に記憶に残す
