Changes between Version 90 and Version 91 of XmlRpcPlugin


Ignore:
Timestamp:
Apr 19, 2012 9:28:42 AM (3 years ago)
Author:
rjollos
Comment:

Conent moved to XmlRpcPlugin/Ruby.

Legend:

Unmodified
Added
Removed
Modified
  • XmlRpcPlugin

    v90 v91  
    224224 
    225225=== Using from Ruby === 
    226 You can either use the XMLRPC functionality included in the [http://ruby-doc.org/stdlib/libdoc/xmlrpc/rdoc/index.html Ruby Standard Library] or [/attachment/wiki/XmlRpcPlugin/trac4r.tar.gz download the trac4r library] which does all the trivial stuff for you. 
    227  
    228 please refer to the '''SSL Support''' section if you need one. 
    229  
    230 ==== trac4r Example ==== 
    231 This example uses trac4r: 
    232 {{{ 
    233 #!ruby 
    234 require 'trac4r/trac' 
    235 # initialize the connection (username and password can be ommitted if not needed, but most of the time you will need them if anonymous doesn't have XMLRPC permissions) 
    236 trac = Trac.new "https://dev.example.com/trac/my_awesome_project", "myusername", "mypassword" 
    237 # get a list of all tickets (as an array of numbers) 
    238 trac.tickets.list :include_closed => true # this is the default anyway 
    239 # get all the tickets 
    240 # NOTE: the results here are cached, so you can call it as often as you want without producing traffic more than once. 
    241 # use ":cached_results => false" to get the latest version 
    242 trac.tickets.get_all :include_closed => true 
    243 # get a single ticket 
    244 ticket = trac.tickets.get 5 
    245 # print the data 
    246 puts "Title: #{ticket.summary}" 
    247 puts "Description: #{ticket.description}" 
    248 puts "Milestone: #{ticket.milestone}" 
    249 puts "Status: #{ticket.status}" 
    250 puts "Type: #{ticket.type}" 
    251 puts "Priority: #{ticket.priority}" 
    252 # get a list of all wiki pages 
    253 trac.wiki.list 
    254 # download one page 
    255 trac.wiki.get_html "SomeRandomPageName" # HTML version 
    256 trac.wiki.get_raw "AnotherRandomPageName" # trac syntax version (e.g. for editing) 
    257 # for previews use 
    258 trac.wiki.raw_to_html "content of a page in [wiki:WikiFormatting Trac syntax] as a ''String''" 
    259 # to post a page use 
    260 trac.wiki.put "NameOfThePage", "content in Trac syntax" 
    261 # list the attachments of a wiki page 
    262 trac.wiki.attachments "NameOfThePage" 
    263 # save an attachment 
    264 File.new("my_cool_document","w") do |f| 
    265   f.write trac.wiki.get_attachment "NameOfThePage", "my_cool_document.pdf" 
    266 end 
    267  
    268 # upload an attachment to the page above 
    269 page = "NameOfThePage" 
    270 fn = "my_nice_doc.pdf" 
    271 fh = File.new(fn, "rb") 
    272 sdata = fh.read 
    273 data = XMLRPC::Base64.new(sdata) 
    274 result = trac.wiki.put_attachment(page, name, "uploaded via ruby script", data) 
    275 # the correct result should be the name of the file: 
    276 puts "ERROR: uploading #{name} didn't work properly!" if result != name 
    277 }}} 
    278  
    279 Also see the included Documentation in trac4r/doc 
    280  
    281 If you need to do a custom query do 
    282 {{{ 
    283 #!ruby 
    284 trac.query("system.getAPIVersion") 
    285 }}} 
    286 The first argument is the method name, all other arguments are directly passed to XMLRPC. 
    287 For this example of cause you could do `trac.api_version` instead ;) 
    288  
    289 If you have any problems with trac4r you can email me: niklas.cathor (eat) gmail dot com 
    290  
    291 ==== xmlrpc Example ==== 
    292  
    293 An example using XML-RPC directly with Ruby to append to a wiki page: 
    294 {{{ 
    295 #!ruby 
    296 require 'xmlrpc/client' 
    297 user = "username" 
    298 password = "password" 
    299 page_name = "SandBoxRPC" 
    300 new_content = "\n\nMy new content" 
    301 new_comment = "Adding new content from ruby" 
    302  
    303 server = XMLRPC::Client.new2("https://#{user}:#{password}@trac.server.com/trac/login/xmlrpc") 
    304 content = server.call("wiki.getPage", page_name) + new_content 
    305 server.call("wiki.putPage", page_name, content, {"comment" => new_comment}) 
    306 }}} 
    307  
    308 ==== SSL Support + X509 ==== 
    309 The standard ruby xmlrpc client for some reason does not support SSL at all. 
    310 In order to be able to use the XMLRPC over SSL with both 
    311  * Client Certificate authentication 
    312  * Basic Authentication 
    313 One must do as follows. 
    314  
    315 in order to proceed, you should have: 
    316  * ca certificate in .pem format 
    317  * personal certificate + RSA key in .p12 format (and its password, of course) 
    318  * patched version of xmlrpc/client.rb 
    319  * patched version of trac4r 
    320  * username/password (for basic authentication) 
    321  
    322 Assuming you have the above, and your ca and user certificates are respectively: 
    323 {{{ 
    324 ~/.openssl/cacert.pem 
    325 ~/.openssl/certkey.p12 
    326 }}} 
    327 ===== The Instructions ===== 
    328  1. apply the patches: 
    329    1. to the [attachment:"xmlrpc-client.SSL.patch" xmlrpc client] 
    330 {{{ 
    331 sudo su - 
    332 cd /usr/lib/ruby/1.8/ 
    333 patch -p0  < /path/to/xmlrpc-client.SSL.patch 
    334 }}} 
    335    1. to the [attachment:"trac4r-1.2.3.SSL.patch" trac4r gem] 
    336 {{{ 
    337 sudo su - 
    338 cd /var/lib/gems/1.8/gems/ 
    339 patch -p0  < /path/to/trac4r-1.2.3.SSL.patch 
    340 }}} 
    341  1. create a .yml file called {{{~/.trac/creds.yml}}} of the following structure: 
    342 {{{ 
    343 ---  
    344 tracurl: https://yourserver.yourdomain/yourproject 
    345 tracuser: yourwebuser 
    346 tracpass: yourwebpassword 
    347 certkey: /home/youruser/.openssl/certkey.p12 
    348 cacert: /home/youruser/.openssl/cacert.pem 
    349 keypass: yourkeypassword 
    350 }}} 
    351    * do not forget to chmod the personal files to 600 or 400 
    352  1. use the data in the code 
    353 {{{ 
    354 #!ruby 
    355 require 'yaml' 
    356 require 'openssl' 
    357 require 'xmlrpc/client' 
    358 require 'trac4r' 
    359  
    360 ## read the data from yaml: 
    361 $ymlname= "#{ENV['HOME']}/.trac/creds.yml" 
    362 if !File.exists?($ymlname)  
    363     raise "Cannot open credentials file!" 
    364 end 
    365 begin 
    366     $vars = YAML::load_file($ymlname) 
    367 rescue Exception => e 
    368     raise "Cannot load credentials file #{$ymlname}: #{e.message}\nTrace: #{e.stacktrace}" 
    369 end 
    370  
    371 ## extract the certificate, and the key from the fles. 
    372 pkcs = OpenSSL::PKCS12.new(File.open($vars['certkey']),$vars['keypass']) 
    373 cert = pkcs.cert 
    374 key = pkcs.key 
    375 ## connect to the server 
    376 trac = Trac.new($vars['tracurl'], $vars['tracuser'], $vars['tracpass'], $vars['cacert'], cert, key) 
    377 ## from now you can refer to the connection as open (or query it) 
    378 ## use the API as explained above. 
    379 }}} 
    380  
    381 '''NOTE:''' The working environment of the code (trac4r + ssl) is: 
    382  * Debian/GNU system: {{{Linux hostname 2.6.26-2-686 #1 SMP Mon Jun 21 05:58:44 UTC 2010 i686 GNU/Linux}}} 
    383  * OpenSSL: {{{OpenSSL 0.9.8g 19 Oct 2007}}} 
    384  * Ruby: {{{ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]}}} 
    385  * The certificates have been issued by the above OpenSSL setup. 
     226 
     227See XmlRpcPlugin/Ruby. 
    386228 
    387229=== API Usage ===