XML-RPC
محتویات |
What is XML-RPC?
[Wikipedia Article on XML-RPC]
[XML-RPC HomePage]
IBSng as an XML-RPC SERVER
IBSng Composed of two major systems. The most important and critical part is a service that runs on start of the system and remains on memory. This system called core. The other is interface that shows informations to users and get the input data. Everything outside core talks to core by using xml-rpc protocol. None of other systems access to database directly. Only core is allowed to connect to database. This is mandatory because core caches many informations in memory, and changing database directly doesn't invalidate the cache. By default, IBSng core listens on 127.0.0.1 tcp port 1235. If you want to connect from outside to IBSng, you need to receonfigure IBSng.conf and change bind_ip directive to listen on 0.0.0.0 (all interfaces)
Request Format
All requests to IBSng core has a method name and a single argument. The method name is in format HANDLER_NAME.HANDLE_METHOD (ex user.addNewUser). The single argument is an associative array that contains real arguments of handler. Associative array is represented by xml-rpc struct. Ex.
array(“count”=>1, “credit”=>10)
Authentication
IBSng Core authenticates every request that it receives before processing. So The associative array always should contain 3 authentication parameters. auth_type: Role of the requester. Can be ADMIN, NORMAL_USER, VOIP_USER or ANONYMOUS auth_name: Username of requester. Should be ANONYMOUS for ANONYMOUS auth_type. auth_pass: Password of requester.
Trusted Clients can pass another argument used to recongnize real client ip address auth_remoteaddr: Remote Address of requester.
If client is not in trusted clients list (by default only 127.0.0.1 is), the connection ip address is used for remote_address.
Ex.
method:user.addNewUser Arguement: array (“auth_name”=>”system”, “auth_pass”=>”sys”, “auth_type”=>”ADMIN”, ”count”=>1, “credit”=>20.0, “owner_name”=>”system”, “group_name”=>”test_group”, “credit_comment”=>””)
Handlers And Arguments
There are plenty of registered handlers in IBSng that used by many other systems to perform needed actions. For example handler “user” is used for user management, and handler “ias” is used by and outside accouting software. Each handler has some registered methods. For example handler user has “user.addNewUser” and “user.getUserInfo” among other methods. A list of all handlers and their methods can be found in XML-RPC API document.
Some methods need a group of specific arguments be available in request associative array. “user.addNewUser” needs “count”,”credit”,”owner_name”,”group_name”,”credit_comment” always be available in request. If request was incomplete, and xml-rpc error will be returned with message incomplete request.
Some methods has optional arguments too. “user.getUserInformation” can give client user information based on “user_id” or “normal_username” or “voip_username”. So it only needs one of these arguments to be present in request. Optional arguments are always tagged in API documentation.
