これは、XML-RPC サーバのクライアントを表現するために使用されます。
コンストラクタは以下のような構文です。
$client = new XML_RPC_Client (
string $path
,
string $server
,
integer $port
,
string $proxy
,
integer $proxy_port
,
string $proxy_user
,
string $proxy_pass
)
$path
リクエストを送信したい RPC サーバスクリプトのパスと名前。
$server
接続先リモートサーバの URL 。プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
$port
リモートサーバに接続する際のポート。デフォルトは 80 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
$proxy
もし使用するなら、プロキシサーバの URL 。 プロトコルが指定されておらず、 かつ $port が 443 であった場合は ssl:// が使用されます。
$proxy_port
リモートサーバに接続する際のポート。デフォルトは 8080 で、 http:// 接続を表します。443 を指定すると https:// および ssl:// 接続となります。
$proxy_user
プロキシサーバにアクセスするためのユーザ名。
$proxy_pass
プロキシサーバにアクセスするためのパスワード。
SSL 接続を使用するには、
openssl
拡張モジュールを有効にして PHP がインストールされている必要があります。
betty.userland.com にある Userland の XML-RPC サーバに問い合わせるためのクライアント設定の例は このようになります。
<?php
$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');
?>
このクラスは以下のメソッドをサポートしています。
このメソッドは以下のような書式です。
$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 を参照ください。
$client->setCredentials (
$username
, $password
)
このメソッドは、クライアントがサーバに対する認証処理を行う際の ユーザ名とパスワードを指定します。デフォルトの通信(HTTP)では、 これらの情報が HTTP ベーシック認証に使用されます。
$client->setDebug (
$debugOn
)
$debugOn
は 0
あるいは
1
のどちらかで、クライアントのブラウザにデバッグ情報を
表示するか否かを指定します。デフォルトではこの情報を表示しません。
デバッグ情報の中には XML-RPC サーバが返す問い合わせ結果の生データが含まれ、 またサーバから返された値を表すためにクライアントが作成しようとした PHP の値も含まれます。サーバが返す内容を正確に確認することができるので、 このオプションはサーバのデバッグ時に有用です。
このクラスは 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 を参照ください。
$outString = $msg->serialize (
)
XML-RPC メッセージを表す XML 文字列を返します。
$msg->addParam (
$xmlrpcVal
)
このメソッドのコールにより、パラメータリストに
XML_RPC_Value オブジェクト
$xmlrpcVal
を追加します。
XML_RPC_Value オブジェクトを返します。 パラメータが存在しない場合は XML_RPC_Response オブジェクトが返されます。
$xmlrpcVal = $msg->getParam (
$n
)
メッセージ中の $n
番目のパラメータを取得します。
このメソッドが使用できるかどうかはサーバの実装に依存します。
もしパラメータが存在しない場合は undef
を返します。
$n = $msg->getNumParams (
)
メッセージに付属するパラメータの数を返します。
$methName=$msg->method (
)
$msg->method (
$methName
)
XML-RPC メッセージ中に含まれるメソッドを取得あるいは設定します。
$response = $msg->parseResponse (
$xmlString
)
文字列 $xmlString
に含まれる XML-RPC サーバからの
応答を受け取り、XML_RPC_Response オブジェクトを
構築してそれを返します。また適切なエラーコードを設定します。
このメソッドは、見つかった HTTP/MIME ヘッダをすべて処理します。
$response = $msg->parseResponseFile (
$fileHandle
)
ファイルハンドル $fileHandle
から
XML-RPC サーバの応答を読み込み、それを
parseResponse() に渡します。
このメソッドは、事前に用意されたファイルから応答を生成する際に有用です。 また、見つかった HTTP ヘッダをすべて処理します。
このクラスは、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 を参照ください。
$fn = $resp->faultCode (
)
XML-RPC レスポンス $resp
から、失敗のコードを
整数値で返します。ゼロは成功を、それ以外の値は失敗を意味します。
$fs = $resp->faultString (
)
$resp->faultCode
が示す失敗の内容を、
人間が読める形式で返します。
$xmlrpcVal = $resp->value (
)
サーバから送信された返り値が含まれる XML_RPC_Value
オブジェクトを返します。応答の faultCode
がゼロ以外の
場合、このメソッドが返す値を使用するべきではありません(返り値は
オブジェクトですらないかもしれません)。
$outString = $resp->serialize (
)
応答を、XML 文字列形式で返します。
これは、多くの大変な仕事を担当するものです。このクラスは、XML-RPC で使用する値の作成とカプセル化を可能にします。
事前に http://www.xmlrpc.com/stories/storyReader$7 で XML-RPC の仕様を読んでおくと、これ以降の内容を理解しやすくなるでしょう。
XML_RPC_Value クラスは、以下の型を利用して
任意の複雑な値を格納することが可能です。
i4
、
int
、
boolean
、
string
、
double
、
dateTime.iso8601
、
base64
、
array
あるいは
struct
。
これらの型についての詳細な情報は
仕様
を参照ください。
i4 型は int の別名です。コード中で値を解析する際には 自動的に i4 が int に変換されます。この実装では、int のほうを 正式名とみなしています。
この型を使用すると、Base64 エンコーディングが透過的に行われます。 そのため、これはバイナリデータ型として扱うべきで、7 ビットクリーン ではないデータを渡したい場合に使用します。デコード処理もまた 透過的に行われます。
true
および 1
は
true
にマップされます。それ以外のすべての値
(空文字列を含む)は false
に変換されます。
<
、
>
、
"
および
&
の各文字は、
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 オブジェクトである必要があります 。例えば以下のようになります。
$ok = $val->addScalar (
$stringVal
)
$ok = $val->addScalar (
$scalarVal
, 'int' | 'boolean' | 'string' | 'double' | 'dateTime.iso8601' | 'base64'
)
$val
が空の
XML_RPC_Value だった場合、このメソッドは
そこにスカラ値を設定します。すでに $val
に
スカラ値が設定されていた場合、新たにスカラ値が追加されることはなく
0
が返されます。すべての処理がうまく終了した場合は
1
が返されます。
$val
が 配列
だった場合は特別で、スカラ値が配列に追加されます。
$ok = $val->addArray (
$arrayVal
)
空の XML_RPC_Value を、
$arrayVal
で指定した内容の
配列 に変換します。詳細な情報は、4 番目の
コンストラクタの書式を参照ください。
$ok = $val->addStruct (
$assocArrayVal
)
空の XML_RPC_Value を、
$assocArrayVal
で指定した内容の
構造体 に変換します。詳細な情報は、4 番目の
コンストラクタの書式を参照ください。
$kind = $val->kindOf (
)
値の型を表す文字列 struct
、array
あるいは scalar
を返します。もし値が
まだ初期化されていない場合は undef
を返します。
$outString = $val->serialize (
)
値を、XML-RPC 形式の文字列で返します。
$scalarVal = $val->scalarval (
)
$val->kindOf() == 'scalar' の場合、 このメソッドは PHP 言語のスカラ値を返します(Base64 デコード処理は自動的に行われます)。
$typeName = $val->scalartyp (
)
$val->kindOf() == 'scalar' の場合、
このメソッドはスカラの型を表す文字列を返します。先に述べたとおり、
i4
は常に int
に変換されます。
$xmlrpcVal = $val->arraymem (
$n
)
$val
で表される配列から、
$n
番目の要素を返します。
返される値は XML_RPC_Value オブジェクトです。
$len = $val->arraysize (
)
$val
が array
の場合、その配列の要素数を返します。
$xmlrpcVal = $val->structmem (
$memberName
)
$val
で表される構造体から、
$memberName
に対応する要素を返します。
返される値は XML_RPC_Value オブジェクトです。
list($key,$value) = $val->structeach (
)
$val
が構造体の場合に、次の
「キー・値」の組み合わせを返します。API
も参照ください。
$val->structreset (
)
$val
で表される構造体について、
structeach() の内部ポインタを構造体の先頭に戻します。
このクラスの現在の実装は、できる限りシンプルであることを心がけています。 基本的には、コンストラクタがすべての仕事をこなします。最低限の例は 以下のとおりです。
<?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_Value オブジェクト内のデータの 文字列表現を生成します。
以下は XML_RPC オブジェクトの外部にある関数です。
$rpc = XML_RPC_encode (
$php_val
)
PHP のネイティブデータ型を受け取り、それを XML_RPC オブジェクト型に 変換します。
$values = XML_RPC_decode (
$XML_RPC_val
)
XML_RPC オブジェクト型のメッセージを受け取り、それを PHP の ネイティブデータ型に変換します。