From d8afb982f10e259142f33f882f6d6032a3ca9b1c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 16:01:46 +0300 Subject: [ci skip] Update XML-RPC library docs --- user_guide_src/source/libraries/xmlrpc.rst | 182 +++++++++++++++++------------ 1 file changed, 106 insertions(+), 76 deletions(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index a43c48837..c79f8bed9 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -5,6 +5,13 @@ XML-RPC and XML-RPC Server Classes CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up your own XML-RPC server to receive requests. +.. contents:: + :local: + +.. raw:: html + +
+ **************** What is XML-RPC? **************** @@ -24,8 +31,11 @@ it to determine which class/method should be called to process the request. Once processed, the server will then send back a response message. -For detailed specifications, you can visit the -`XML-RPC `_ site. +For detailed specifications, you can visit the `XML-RPC `_ site. + +*********************** +Using the XML-RPC Class +*********************** Initializing the Class ====================== @@ -123,6 +133,7 @@ with the data type in the second position:: The `Data Types <#datatypes>`_ section below has a full list of data types. + Creating an XML-RPC Server ========================== @@ -425,114 +436,133 @@ the Server. $size = $parameters[1]['size']; $shape = $parameters[1]['shape']; -************************** -XML-RPC Function Reference -************************** +Data Types +========== -$this->xmlrpc->server() -======================= +According to the `XML-RPC spec `_ there are +seven types of values that you can send via XML-RPC: -Sets the URL and port number of the server to which a request is to be -sent:: +- *int* or *i4* +- *boolean* +- *string* +- *double* +- *dateTime.iso8601* +- *base64* +- *struct* (contains array of values) +- *array* (contains array of values) - $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); +*************** +Class Reference +*************** -$this->xmlrpc->timeout() -======================== +.. class:: CI_Xmlrpc -Set a time out period (in seconds) after which the request will be -canceled:: + .. method:: initialize([$config = array()]) - $this->xmlrpc->timeout(6); + :param array $config: configuration data + :returns: void -$this->xmlrpc->method() -======================= + Initializes the XML-RPC library. Accepts an associative array containing your settings. -Sets the method that will be requested from the XML-RPC server:: + .. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]]) - $this->xmlrpc->method('method'); + :param string $url: XML-RPC server URL + :param int $port: server port + :param string $proxy: optional proxy + :param int $proxy_port: proxy listening port + :returns: void -Where method is the name of the method. + Sets the URL and port number of the server to which a request is to be sent:: -$this->xmlrpc->request() -======================== + $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); -Takes an array of data and builds request to be sent to XML-RPC server:: + .. method:: timeout($seconds = 5) - $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); - $this->xmlrpc->request($request); + :param int $seconds: timeout in seconds + :returns: void -$this->xmlrpc->send_request() -============================== + Set a time out period (in seconds) after which the request will be canceled:: -The request sending function. Returns boolean TRUE or FALSE based on -success for failure, enabling it to be used conditionally. + $this->xmlrpc->timeout(6); -$this->xmlrpc->set_debug(TRUE); -================================ + .. method:: method($function) -Enables debugging, which will display a variety of information and error -data helpful during development. + :param string $function: method name + :returns: void -$this->xmlrpc->display_error() -=============================== + Sets the method that will be requested from the XML-RPC server:: -Returns an error message as a string if your request failed for some -reason. + $this->xmlrpc->method('method'); -:: + Where method is the name of the method. - echo $this->xmlrpc->display_error(); + .. method:: request($incoming) -$this->xmlrpc->display_response() -================================== + :param array $incoming: request data + :returns: void -Returns the response from the remote server once request is received. -The response will typically be an associative array. + Takes an array of data and builds request to be sent to XML-RPC server:: -:: + $request = array(array('My Photoblog', 'string'), 'http://www.yoursite.com/photoblog/'); + $this->xmlrpc->request($request); - $this->xmlrpc->display_response(); + .. method:: send_request() -$this->xmlrpc->send_error_message() -===================================== + :returns: bool -This function lets you send an error message from your server to the -client. First parameter is the error number while the second parameter -is the error message. + The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally. -:: + .. method set_debug($flag = TRUE) - return $this->xmlrpc->send_error_message('123', 'Requested data not available'); + :param bool $flag: debug status flag + :returns: void -$this->xmlrpc->send_response() -=============================== + Enables or disables debugging, which will display a variety of information and error data helpful during development. -Lets you send the response from your server to the client. An array of -valid data values must be sent with this method. + .. method:: display_error() -:: + :returns: string - $response = array( - array( - 'flerror' => array(FALSE, 'boolean'), - 'message' => "Thanks for the ping!" - ) - 'struct'); - return $this->xmlrpc->send_response($response); + Returns an error message as a string if your request failed for some reason. + :: -Data Types -========== + echo $this->xmlrpc->display_error(); -According to the `XML-RPC spec `_ there are -seven types of values that you can send via XML-RPC: + .. method:: display_response() -- *int* or *i4* -- *boolean* -- *string* -- *double* -- *dateTime.iso8601* -- *base64* -- *struct* (contains array of values) -- *array* (contains array of values) + :returns: mixed + + Returns the response from the remote server once request is received. The response will typically be an associative array. + :: + + $this->xmlrpc->display_response(); + + .. method:: send_error_message($number, $message) + + :param int $number: error number + :param string $message: error message + :returns: object + This method lets you send an error message from your server to the client. + First parameter is the error number while the second parameter is the error message. + :: + + return $this->xmlrpc->send_error_message(123, 'Requested data not available'); + + .. method send_response($response) + + :param array $response: response data + :returns: object + + Lets you send the response from your server to the client. An array of valid data values must be sent with this method. + :: + + $response = array( + array( + 'flerror' => array(FALSE, 'boolean'), + 'message' => "Thanks for the ping!" + ), + 'struct' + ); + + return $this->xmlrpc->send_response($response); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc042095bcce9856402cc04997f44310074716e0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:08:27 +0200 Subject: [ci skip] Some more generic user guide cleanup --- user_guide_src/source/libraries/xmlrpc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index c79f8bed9..c89c69c46 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -6,11 +6,11 @@ CodeIgniter's XML-RPC classes permit you to send requests to another server, or set up your own XML-RPC server to receive requests. .. contents:: - :local: + :local: .. raw:: html -
+
**************** What is XML-RPC? -- cgit v1.2.3-24-g4f1b From d192953eb39845623811486a28b777b3dda93b5c Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 7 Jan 2014 12:16:16 +0200 Subject: Add basic HTTP auth info to the XML-RPC docs --- user_guide_src/source/libraries/xmlrpc.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index c89c69c46..91d832ff6 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -476,6 +476,10 @@ Class Reference $this->xmlrpc->server('http://www.sometimes.com/pings.php', 80); + Basic HTTP authentication is also supported, simply add it to the server URL:: + + $this->xmlrpc->server('http://user:pass@localhost/', 80); + .. method:: timeout($seconds = 5) :param int $seconds: timeout in seconds -- cgit v1.2.3-24-g4f1b From 75b3fb26a324c71ff18fa19b2a3caa357f8133ec Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Sat, 11 Jan 2014 06:58:43 -0600 Subject: cleanup warnings Signed-off-by: Connor Tumbleson --- user_guide_src/source/libraries/xmlrpc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index 91d832ff6..53fe965d7 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -551,7 +551,7 @@ Class Reference First parameter is the error number while the second parameter is the error message. :: - return $this->xmlrpc->send_error_message(123, 'Requested data not available'); + return $this->xmlrpc->send_error_message(123, 'Requested data not available'); .. method send_response($response) -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/xmlrpc.rst | 53 ++++++++++++++++-------------- 1 file changed, 29 insertions(+), 24 deletions(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index d9b2dfb1a..2cf548750 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -459,18 +459,18 @@ Class Reference .. method:: initialize([$config = array()]) - :param array $config: configuration data - :returns: void + :param array $config: Configuration data + :rtype: void Initializes the XML-RPC library. Accepts an associative array containing your settings. .. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]]) - :param string $url: XML-RPC server URL - :param int $port: server port - :param string $proxy: optional proxy - :param int $proxy_port: proxy listening port - :returns: void + :param string $url: XML-RPC server URL + :param int $port: Server port + :param string $proxy: Optional proxy + :param int $proxy_port: Proxy listening port + :rtype: void Sets the URL and port number of the server to which a request is to be sent:: @@ -482,8 +482,8 @@ Class Reference .. method:: timeout($seconds = 5) - :param int $seconds: timeout in seconds - :returns: void + :param int $seconds: Timeout in seconds + :rtype: void Set a time out period (in seconds) after which the request will be canceled:: @@ -491,8 +491,8 @@ Class Reference .. method:: method($function) - :param string $function: method name - :returns: void + :param string $function: Method name + :rtype: void Sets the method that will be requested from the XML-RPC server:: @@ -502,8 +502,8 @@ Class Reference .. method:: request($incoming) - :param array $incoming: request data - :returns: void + :param array $incoming: Request data + :rtype: void Takes an array of data and builds request to be sent to XML-RPC server:: @@ -512,20 +512,22 @@ Class Reference .. method:: send_request() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally. .. method set_debug($flag = TRUE) - :param bool $flag: debug status flag - :returns: void + :param bool $flag: Debug status flag + :rtype: void Enables or disables debugging, which will display a variety of information and error data helpful during development. .. method:: display_error() - :returns: string + :returns: Error message string + :rtype: string Returns an error message as a string if your request failed for some reason. :: @@ -534,7 +536,8 @@ Class Reference .. method:: display_response() - :returns: mixed + :returns: Response + :rtype: mixed Returns the response from the remote server once request is received. The response will typically be an associative array. :: @@ -543,9 +546,10 @@ Class Reference .. method:: send_error_message($number, $message) - :param int $number: error number - :param string $message: error message - :returns: object + :param int $number: Error number + :param string $message: Error message + :returns: XML_RPC_Response instance + :rtype: XML_RPC_Response This method lets you send an error message from your server to the client. First parameter is the error number while the second parameter is the error message. @@ -555,8 +559,9 @@ Class Reference .. method send_response($response) - :param array $response: response data - :returns: object + :param array $response: Response data + :returns: XML_RPC_Response instance + :rtype: XML_RPC_Response Lets you send the response from your server to the client. An array of valid data values must be sent with this method. :: @@ -569,4 +574,4 @@ Class Reference 'struct' ); - return $this->xmlrpc->send_response($response); + return $this->xmlrpc->send_response($response); \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 25f119cef588a01651cec7c59d3b03924b2dd81c Mon Sep 17 00:00:00 2001 From: darwinel Date: Tue, 11 Feb 2014 18:29:58 +0100 Subject: Writing style fix based on style guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit „Use of || is discouraged as its clarity on some output devices is low (looking like the number 11 for instance). && is preferred over AND but either are acceptable, and a space should always precede and follow !.” --- user_guide_src/source/libraries/xmlrpc.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index 2cf548750..115b4e680 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -223,17 +223,17 @@ email address, etc.). Here is how the processing function might look:: $parameters = $request->output_parameters(); - if ($parameters['1'] != $username AND $parameters['2'] != $password) + 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') + $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'); -- cgit v1.2.3-24-g4f1b From 053d5d6e8dff0f1af9c33330960a1085628b3930 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Tue, 11 Feb 2014 21:45:39 +0200 Subject: [ci skip] Update the XML-RPC lib docs --- user_guide_src/source/libraries/xmlrpc.rst | 131 +++++++++++++++-------------- 1 file changed, 66 insertions(+), 65 deletions(-) (limited to 'user_guide_src/source/libraries/xmlrpc.rst') diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index 115b4e680..c2e9a1113 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -123,12 +123,12 @@ If you use data types other than strings, or if you have several different data types, you will place each parameter into its own array, with the data type in the second position:: - $request = array ( - array('John', 'string'), - array('Doe', 'string'), - array(FALSE, 'boolean'), - array(12345, 'int') - ); + $request = array( + array('John', 'string'), + array('Doe', 'string'), + array(FALSE, 'boolean'), + array(12345, 'int') + ); $this->xmlrpc->request($request); The `Data Types <#datatypes>`_ section below has a full list of data @@ -171,7 +171,7 @@ not part of the CodeIgniter super object. In other words, if an XML-RPC Client sends a request for the new_post method, your server will load the My_blog class and call the new_entry function. If the request is for the update_post method, your server -will load the My_blog class and call the update_entry function. +will load the My_blog class and call the ``update_entry()`` method. The function names in the above example are arbitrary. You'll decide what they should be called on your server, or if you are using @@ -181,7 +181,7 @@ function names. There are two additional configuration keys you may make use of when initializing the server class: debug can be set to TRUE in order to enable debugging, and xss_clean may be set to FALSE to prevent sending -data through the Security library's xss_clean function. +data through the Security library's ``xss_clean()`` method. Processing Server Requests ========================== @@ -207,49 +207,52 @@ have access to the *request parameters* enabling you to process the request. When you are done you will send a Response back to the Client. Below is a real-world example, using the Blogger API. One of the methods -in the Blogger API is getUserInfo(). Using this method, an XML-RPC +in the Blogger API is ``getUserInfo()``. Using this method, an XML-RPC Client can send the Server a username and password, in return the Server sends back information about that particular user (nickname, user ID, email address, etc.). Here is how the processing function might look:: class My_blog extends CI_Controller { - function getUserInfo($request) - { - $username = 'smitty'; - $password = 'secretsmittypass'; + public function getUserInfo($request) + { + $username = 'smitty'; + $password = 'secretsmittypass'; - $this->load->library('xmlrpc'); + $this->load->library('xmlrpc'); - $parameters = $request->output_parameters(); + $parameters = $request->output_parameters(); - if ($parameters['1'] != $username && $parameters['2'] != $password) - { - return $this->xmlrpc->send_error_message('100', 'Invalid Access'); - } + 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'); + $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); - } + return $this->xmlrpc->send_response($response); + } } Notes: ------ -The output_parameters() function retrieves an indexed array +The ``output_parameters()`` method retrieves an indexed array corresponding to the request parameters sent by the client. In the above example, the output parameters will be the username and password. If the username and password sent by the client were not valid, and -error message is returned using send_error_message(). +error message is returned using ``send_error_message()``. If the operation was successful, the client will be sent back a response array containing the user's info. @@ -263,22 +266,22 @@ single item**. This item can be an array with several additional arrays, but there can be only one primary array index. In other words, the basic prototype is this:: - $response = array('Response data', 'array'); + $response = array('Response data', 'array'); Responses, however, usually contain multiple pieces of information. In order to accomplish this we must put the response into its own array so that the primary array continues to contain a single piece of data. Here's an example showing how this might be accomplished:: - $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' - ); + $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' + ); Notice that the above array is formatted as a struct. This is the most common data type for responses. @@ -373,17 +376,16 @@ folder:: $parameters = $request->output_parameters(); $response = array( - array( - 'you_said' => $parameters[0], - 'i_respond' => 'Not bad at all.' - ), - 'struct' - ); + array( + 'you_said' => $parameters[0], + 'i_respond' => 'Not bad at all.' + ), + 'struct' + ); return $this->xmlrpc->send_response($response); } } - ?> Try it! @@ -398,7 +400,7 @@ back to you. The client you created sends a message ("How's is going?") to the server, along with a request for the "Greetings" method. The Server -receives the request and maps it to the "process" function, where a +receives the request and maps it to the ``process()`` method, where a response is sent back. Using Associative Arrays In a Request Parameter @@ -408,22 +410,21 @@ If you wish to use an associative array in your method parameters you will need to use a struct datatype:: $request = array( - array( - // Param 0 - array( - 'name'=>'John' - ), - 'struct' - ), - array( - // Param 1 - array( - 'size'=>'large', - 'shape'=>'round' - ), - 'struct' - ) - ); + array( + // Param 0 + array('name' => 'John'), + 'struct' + ), + array( + // Param 1 + array( + 'size' => 'large', + 'shape'=>'round' + ), + 'struct' + ) + ); + $this->xmlrpc->request($request); You can retrieve the associative array when processing the request in -- cgit v1.2.3-24-g4f1b