XML-RPC 與 XML-RPC 服務器類 · CodeIgniter3.0 中文用戶指南

# XML-RPC 與 XML-RPC 服務器類 CodeIgniter 的 XML-RPC 類允許你向另一個服務器發送請求，或者建立一個你自己的 XML-RPC 服務器來接受請求。 * [什么是 XML-RPC ？](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#xml-rpc) * [使用 XML-RPC 類](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id2) * [初始化類](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id3) * [發送 XML-RPC 請求](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id4) * [解釋](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id5) * [請求解析](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id6) * [創建一個 XML-RPC 服務器](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id8) * [處理服務器請求](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id9) * [注意](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id10) * [格式化響應](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id11) * [發送錯誤信息](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id13) * [創建你自己的客戶端與服務端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id14) * [客戶端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id15) * [服務端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id16) * [嘗試一下](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id17) * [在請求參數中使用關聯數組](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id18) * [數據類型](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id19) * [類參考](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id21) ## [什么是 XML-RPC ？](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id22) 這是一種在兩臺計算機之間使用 XML 通過互聯網進行通信的簡單方法。一臺計算機 , 我們稱之為客戶端 , 發送一個 XML-RPC 請求給另外一臺計算機，我們稱之為服務器，當服務器收到請求時，對其進行處理然后將結果返回給客戶端。例如，使用 MetaWeblog API 時，XML-RPC 客戶端（通常是桌面發布工具）將會發送請求到你站點上的 XML-RPC 服務器，這個請求可能是發布一篇新博客，或者編輯一篇已有的博客。當 XML-RPC 服務器收到該請求時，它會決定使用哪個類和方法來處理該請求，請求處理完成后，服務器將發送一條回復消息。關于 XML-RPC 的規范，你可以查看?[XML-RPC](http://www.xmlrpc.com/)?的網站。 ## [使用 XML-RPC 類](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id23) ### [初始化類](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id24) 跟 CodeIgniter 中的其他類一樣，可以在你的控制器中使用?$this->load->library()?方法加載 XML-RPC 類和 XML-RPC 服務器類。加載 XML-RPC 類如下: ~~~ $this->load->library('xmlrpc'); ~~~ 一旦加載，XML-RPC 類就可以像下面這樣使用: ~~~ $this->xmlrpc ~~~ 加載 XML-RPC 服務器類如下: ~~~ $this->load->library('xmlrpc'); $this->load->library('xmlrpcs'); ~~~ 一旦加載，XML-RPC 服務器類就可以像下面這樣使用: ~~~ $this->xmlrpcs ~~~ 注解當使用 XML-RPC 服務器類時，xmlrpc 和 xmlrpcs 都需要加載。 ### [發送 XML-RPC 請求](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id25) 向 XML-RPC 服務器發送一個請求，你需要指定以下信息： * 服務器的 URL * 你想要調用的服務器方法 * **請求**?數據（下面解釋）下面是個基本的例子，向?[Ping-o-Matic](http://pingomatic.com/)?發送一個簡單的 Weblogs.com ping 請求。 ~~~ $this->load->library('xmlrpc'); $this->xmlrpc->server('http://rpc.pingomatic.com/', 80); $this->xmlrpc->method('weblogUpdates.ping'); $request = array('My Photoblog', 'http://www.my-site.com/photoblog/'); $this->xmlrpc->request($request); if ( ! $this->xmlrpc->send_request()) { echo $this->xmlrpc->display_error(); } ~~~ #### [解釋](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id26) 上面的代碼初始化了一個 XML-RPC 類，并設置了服務器 URL 和要調用的方法（weblogUpdates.ping）。然后通過 request() 方法編譯請求，例子中請求是一個數組（標題和你網站的 URL）。最后，使用 send_request() 方法發送完整的請求。如果發送請求方法返回 FALSE ，我們會顯示出 XML-RPC 服務器返回的錯誤信息。 ### [請求解析](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id27) XML-RPC 請求就是你發送給 XML-RPC 服務器的數據，請求中的每一個數據也被稱為請求參數。上面的例子中有兩個參數：你網站的 URL 和標題。當 XML-RPC 服務器收到請求后，它會查找它所需要的參數。請求參數必須放在一個數組中，且數組中的每個參數都必須是 7 種數據類型中的一種（string、number、date 等），如果你的參數不是 string 類型，你必須在請求數組中指定它的數據類型。下面是三個參數的簡單例子: ~~~ $request = array('John', 'Doe', 'www.some-site.com'); $this->xmlrpc->request($request); ~~~ 如果你的數據類型不是 string ，或者你有幾個不同類型的數據，那么你需要將每個參數放到它單獨的數組中，并在數組的第二位聲明其數據類型: ~~~ $request = array( array('John', 'string'), array('Doe', 'string'), array(FALSE, 'boolean'), array(12345, 'int') ); $this->xmlrpc->request($request); ~~~ 下面的?[數據類型](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#datatypes)?一節列出了所有支持的數據類型。 ### [創建一個 XML-RPC 服務器](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id28) XML-RPC 服務器扮演著類似于交通警察的角色，等待進入的請求，并將它們轉到恰當的函數進行處理。要創建你自己的 XML-RPC 服務器，你需要先在負責處理請求的控制器中初始化 XML-RPC 服務器類，然后設置一個映射數組，用于將請求轉發到合適的類和方法，以便進行處理。下面是個例子: ~~~ $this->load->library('xmlrpc'); $this->load->library('xmlrpcs'); $config['functions']['new_post'] = array('function' => 'My_blog.new_entry'); $config['functions']['update_post'] = array('function' => 'My_blog.update_entry'); $config['object'] = $this; $this->xmlrpcs->initialize($config); $this->xmlrpcs->serve(); ~~~ 上例中包含了兩個服務器允許的請求方法，數組的左邊是允許的方法名，數組的右邊是當請求該方法時，將會映射到的類和方法。其中，'object' 是個特殊的鍵，用于傳遞一個實例對象，當映射的方法無法使用 CodeIgniter 超級對象時，它將是必須的。換句話說，如果 XML-RPC 客戶端發送一個請求到 new_post 方法，你的服務器會加載 My_blog 類并調用 new_entry 函數。如果這個請求是到update_post?方法的，那么你的服務器會加載 My_blog 類并調用?update_entry?方法。上面例子中的函數名是任意的。你可以決定這些函數在你的服務器上叫什么名字，如果你使用的是標準的 API，比如 Blogger 或者 MetaWeblog 的 API，你必須使用標準的函數名。這里還有兩個附加的配置項，可以在服務器類初始化時配置使用。debug 設為 TRUE 以便調試，?xss_clean?可被設置為 FALSE 以避免數據被安全類庫的?xss_clean?函數過濾。 ### [處理服務器請求](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id29) 當 XML-RPC 服務器收到請求并加載類與方法來處理時，它會接收一個包含客戶端發送的數據參數。在上面的例子中，如果請求的是 new_post 方法，服務器請求的類與方法會像這樣: ~~~ class My_blog extends CI_Controller { public function new_post($request) { } } ~~~ $request 變量是一個由服務端匯集的對象，包含由 XML-RPC 客戶端發送來的數據。使用該對象可以讓你訪問到請求參數以便處理請求。請求處理完成后，發送一個響應返回給客戶端。下面是一個實際的例子，使用 Blogger API 。Blogger API 中的一個方法是 getUserInfo()， XML-RPC 客戶端可以使用該方法發送用戶名和密碼到服務器，在服務器返回的數據中，會包含該用戶的信息（昵稱，用戶 ID，Email 地址等等）。下面是處理的代碼: ~~~ class My_blog extends CI_Controller { public function getUserInfo($request) { $username = 'smitty'; $password = 'secretsmittypass'; $this->load->library('xmlrpc'); $parameters = $request->output_parameters(); if ($parameters[1] != $username && $parameters[2] != $password) { return $this->xmlrpc->send_error_message('100', 'Invalid Access'); } $response = array( array( 'nickname' => array('Smitty', 'string'), 'userid' => array('99', 'string'), 'url' => array('http://yoursite.com', 'string'), 'email' => array('jsmith@yoursite.com', 'string'), 'lastname' => array('Smith', 'string'), 'firstname' => array('John', 'string') ), 'struct' ); return $this->xmlrpc->send_response($response); } } ~~~ #### [注意](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id30) output_parameters()?函數獲取一個由客戶端發送的請求參數數組。上面的例子中輸出參數將會是用戶名和密碼。如果客戶端發送的用戶名和密碼無效的話，將使用?send_error_message()?函數返回錯誤信息。如果操作成功，客戶端會收到包含用戶信息的響應數組。 ### [格式化響應](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id31) 和請求一樣，響應也必須被格式化為數組。然而不同于請求信息，響應數組?**只包含一項**?。該項可以是一個包含其他數組的數組，但是只能有一個主數組，換句話說，響應的結果大概是下面這個樣子: ~~~ $response = array('Response data', 'array'); ~~~ 但是，響應通常會包含多個信息。要做到這樣，我們必須把各個信息放到他們自己的數組中，這樣主數組就始終只有一個數據項。下面是一個例子展示如何實現這樣的效果: ~~~ $response = array( array( 'first_name' => array('John', 'string'), 'last_name' => array('Doe', 'string'), 'member_id' => array(123435, 'int'), 'todo_list' => array(array('clean house', 'call mom', 'water plants'), 'array'), ), 'struct' ); ~~~ 注意：上面的數組被格式化為 struct，這是響應最常見的數據類型。如同請求一樣，響應可以是七種數據類型中的一種，參見?[數據類型](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#datatypes)?一節。 ### [發送錯誤信息](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id32) 如果你需要發送錯誤信息給客戶端，可以使用下面的代碼: ~~~ return $this->xmlrpc->send_error_message('123', 'Requested data not available'); ~~~ 第一個參數為錯誤編號，第二個參數為錯誤信息。 ### [創建你自己的客戶端與服務端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id33) 為了幫助你理解目前為止講的這些內容，讓我們來創建兩個控制器，演示下 XML-RPC 的客戶端和服務端。你將用客戶端來發送一個請求到服務端并從服務端收到一個響應。 #### [客戶端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id34) 使用文本編輯器創建一個控制器 Xmlrpc_client.php ，在這個控制器中，粘貼以下的代碼并保存到 applications/controllers/ 目錄: ~~~ <?php class Xmlrpc_client extends CI_Controller { public function index() { $this->load->helper('url'); $server_url = site_url('xmlrpc_server'); $this->load->library('xmlrpc'); $this->xmlrpc->server($server_url, 80); $this->xmlrpc->method('Greetings'); $request = array('How is it going?'); $this->xmlrpc->request($request); if ( ! $this->xmlrpc->send_request()) { echo $this->xmlrpc->display_error(); } else { echo '<pre>'; print_r($this->xmlrpc->display_response()); echo '</pre>'; } } } ?> ~~~ 注解上面的代碼中我們使用了一個 URL 輔助函數，更多關于輔助函數的信息，你可以閱讀?[這里](http://codeigniter.org.cn/user_guide/general/helpers.html)?。 #### [服務端](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id35) 使用文本編輯器創建一個控制器 Xmlrpc_server.php ，在這個控制器中，粘貼以下的代碼并保存到 applications/controllers/ 目錄: ~~~ <?php class Xmlrpc_server extends CI_Controller { public function index() { $this->load->library('xmlrpc'); $this->load->library('xmlrpcs'); $config['functions']['Greetings'] = array('function' => 'Xmlrpc_server.process'); $this->xmlrpcs->initialize($config); $this->xmlrpcs->serve(); } public function process($request) { $parameters = $request->output_parameters(); $response = array( array( 'you_said' => $parameters[0], 'i_respond' => 'Not bad at all.' ), 'struct' ); return $this->xmlrpc->send_response($response); } } ~~~ #### [嘗試一下](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id36) 現在使用類似于下面這樣的鏈接訪問你的站點: ~~~ example.com/index.php/xmlrpc_client/ ~~~ 你應該能看到你發送到服務端的信息，以及服務器返回的響應信息。在客戶端，你發送了一條消息（"How's is going?"）到服務端，隨著一個請求發送到 "Greetings" 方法。服務端收到這個請求并映射到 "process" 函數，然后返回響應信息。 ### [在請求參數中使用關聯數組](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id37) 如果你希望在你的方法參數中使用關聯數組，那么你需要使用 struct 數據類型: ~~~ $request = array( array( // Param 0 array('name' => 'John'), 'struct' ), array( // Param 1 array( 'size' => 'large', 'shape'=>'round' ), 'struct' ) ); $this->xmlrpc->request($request); ~~~ 你可以在服務端處理請求信息時獲取該關聯數組。 ~~~ $parameters = $request->output_parameters(); $name = $parameters[0]['name']; $size = $parameters[1]['size']; $shape = $parameters[1]['shape']; ~~~ ### [數據類型](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id38) 根據?[XML-RPC 規范](http://www.xmlrpc.com/spec)?一共有七種不同的數據類型可以在 XML-RPC 中使用： * int?or?i4 * boolean * string * double * dateTime.iso8601 * base64 * struct?(contains array of values) * array?(contains array of values) ## [類參考](http://codeigniter.org.cn/user_guide/libraries/xmlrpc.html#id39) classCI_Xmlrpc initialize([$config = array()]) 參數: * **$config**?(array) -- Configuration data 返回類型: void 初始化 XML-RPC 類，接受一個包含你設置的參數的關聯數組。 server($url[,?$port = 80[,?$proxy = FALSE[,?$proxy_port = 8080]]]) 參數: * **$url**?(string) -- XML-RPC server URL * **$port**?(int) -- Server port * **$proxy**?(string) -- Optional proxy * **$proxy_port**?(int) -- Proxy listening port 返回類型: void 用于設置 XML-RPC 服務器端的 URL 和端口: ~~~ $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); ~~~ 支持基本的 HTTP 身份認證，只需簡單的將其添加到 URL中: ~~~ $this->xmlrpc->server('http://user:pass@localhost/', 80); ~~~ timeout($seconds = 5) 參數: * **$seconds**?(int) -- Timeout in seconds 返回類型: void 設置一個超時時間（單位為秒），超過該時間，請求將被取消: ~~~ $this->xmlrpc->timeout(6); ~~~ method($function) 參數: * **$function**?(string) -- Method name 返回類型: void 設置 XML-RPC 服務器接受的請求方法: ~~~ $this->xmlrpc->method('method'); ~~~ 其中 method 參數為請求方法名。 request($incoming) 參數: * **$incoming**?(array) -- Request data 返回類型: void 接受一個數組參數，并創建一個發送到 XML-RPC 服務器的請求: ~~~ $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); $this->xmlrpc->request($request); ~~~ send_request() 返回: TRUE on success, FALSE on failure 返回類型: bool 發送請求的方法，成功返回 TRUE，失敗返回 FALSE ，可以用在條件判斷里。 display_error() 返回: Error message string 返回類型: string 當請求失敗后，返回錯誤信息。 ~~~ echo $this->xmlrpc->display_error(); ~~~ display_response() 返回: Response 返回類型: mixed 遠程服務器接收請求后返回的響應，返回的數據通常是一個關聯數組。 ~~~ $this->xmlrpc->display_response(); ~~~ send_error_message($number,?$message) 參數: * **$number**?(int) -- Error number * **$message**?(string) -- Error message 返回: XML_RPC_Response instance 返回類型: XML_RPC_Response 這個方法允許你從服務器發送一個錯誤消息到客戶端。第一個參數是錯誤編號，第二個參數是錯誤信息。 ~~~ return $this->xmlrpc->send_error_message(123, 'Requested data not available'); ~~~