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: プロキシサーバにアクセスするためのパスワード。

Note: 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 勧告で説明されています。

Note: 現在は、文字列 "-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 ( $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 )

$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 のネイティブデータ型に変換します。