API

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_messageXML_RPC_Message のインスタンスで、 $responseXML_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 )

$debugOn0 あるいは 1 のどちらかで、クライアントのブラウザにデバッグ情報を 表示するか否かを指定します。デフォルトではこの情報を表示しません。

デバッグ情報の中には XML-RPC サーバが返す問い合わせ結果の生データが含まれ、 またサーバから返された値を表すためにクライアントが作成しようとした PHP の値も含まれます。サーバが返す内容を正確に確認することができるので、 このオプションはサーバのデバッグ時に有用です。

XML_RPC_Message

このクラスは XML-RPC サーバへのリクエストを表します。クライアントは XML_RPC_Message をサーバに送信し、 XML_RPC_Response を受け取ります。

生成

コンストラクタは以下のような構文です。

$msg = new XML_RPC_Message ( $methodName , $parameterArray )

$methodName は起動したいメソッドの名前で、 $parameterArrayXML_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 )

ひとつめのインスタンスは、何の問題もなく処理が実行された際に使用されます。 $xmlrpcvalXML_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 クラスは、以下の型を利用して 任意の複雑な値を格納することが可能です。 i4intbooleanstringdoubledateTime.iso8601base64array あるいは struct。 これらの型についての詳細な情報は 仕様 を参照ください。

型についての注意

int

i4 型は int の別名です。コード中で値を解析する際には 自動的に i4int に変換されます。この実装では、int のほうを 正式名とみなしています。

base64

この型を使用すると、Base64 エンコーディングが透過的に行われます。 そのため、これはバイナリデータ型として扱うべきで、7 ビットクリーン ではないデータを渡したい場合に使用します。デコード処理もまた 透過的に行われます。

boolean

true および 1true にマップされます。それ以外のすべての値 (空文字列を含む)は false に変換されます。

string

<>" および & の各文字は、 XML-RPC での通信の際に各々と等価なエンティティ &lt;&gt;&quot; および &amp; に変換されます。現在の XML-RPC の仕様では エンコードするよう推奨されているのは < および & だけですが、この実装ではさらに一歩先を行っています。 その理由は XML 1.0 勧告 で説明されています。

現在は、文字列 "-1" を XML_RPC_Value のコンストラクタに渡すと、空の結果を作成します。"-1" は特別な値として扱われます。

TODO: &apos; エンティティは現在サポートされていません。

生成

コンストラクタは、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 ( )

値の型を表す文字列 structarray あるいは 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 ( )

$valarray の場合、その配列の要素数を返します。

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($myDispMap0);

// ... 何らかの他の処理をここで行う

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

XML_RPC パッケージの利用例 (Previous) XML_RPC2 (Next)
Last updated: Wed, 20 Aug 2014 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report or add a note.
View this page in:

User Notes:

There are no user contributed notes for this page.