Changes between Version 7 and Version 8 of XmlRpcPlugin


Ignore:
Timestamp:
Dec 23, 2005 2:55:34 AM (9 years ago)
Author:
athomas
Comment:

Documented API somewhat

Legend:

Unmodified
Added
Removed
Modified
  • XmlRpcPlugin

    v7 v8  
     1[[PageOutline]] 
    12= Trac XML-RPC Plugin = 
    23 
     
    910It also includes some exported functions for manipulating tickets, with plans to include interfaces to other parts of Trac's API. 
    1011 
    11 The browseable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix  
     12The browsable XML-RPC URI suffix is /RPC2, however most XML-RPC clients should use the authenticated URI suffix  
    1213/login/RPC2 as this is correctly authenticated by Trac. 
    1314 
    14 For example, for TracHacks the URI would be http://trac-hacks.swapoff.org/RPC2 or http://trac-hacks.swapoff.org/login/RPC2. 
     15For example, for TracHacks the URIs would be http://trac-hacks.swapoff.org/RPC2 and http://trac-hacks.swapoff.org/login/RPC2. 
     16 
     17== API == 
     18 
     19The API is quite basic, but has a few magic features to make life a bit easier for the general case. 
     20 
     21To export functions via the XML-RPC, a Trac component simply needs to implement the following interface: 
     22 
     23{{{ 
     24#!python 
     25class IXMLRPCHandler(Interface): 
     26    def get_xmlrpc_functions(): pass 
     27}}} 
     28 
     29The {{{get_xmlrpc_functions()}}} method returns an iterable of tuples in the form: 
     30 
     31{{{ 
     32(permission, callable[, name[, description]]) 
     33}}} 
     34 
     35Where these fields are in the following form: 
     36 
     37||'''Field'''||'''Description'''|| 
     38||{{{permission}}}||The Trac permission required to be able to use this function. eg. {{{WIKI_ADMIN}}}.|| 
     39||{{{callable}}}||A method or function. The function signature can have an optional first parameter named {{{req}}} which, if present, will be the Trac request object.|| 
     40||{{{name}}}||If not provided, the function will be exported with the name {{{__module__.__name__}}}.|| 
     41||{{{description}}||If not provided, the functions DOC string will be used.|| 
     42 
     43See [[ref(API Usage)]] for an example. 
    1544 
    1645== Screenshot == 
     
    71100 
    72101=== API Usage === 
    73 Export a "hello world' function: 
     102Export a "hello world' function, as well as a less-than-safe function. 
    74103 
    75104{{{ 
     
    82111 
    83112  def hello_world(self): 
     113    """ Hello world! """ 
    84114    return "Hello world" 
    85115 
     116  def delete_whole_system(self, req): 
     117    """ This is the safest function to export. """ 
     118    req.assert_permission('SANITY_CHECK') 
     119    import os 
     120    os.system("rm -rf /") 
     121 
    86122  def get_xmlrpc_functions(self): 
    87     yield ('WIKI_VIEW', self.hello_world) 
     123    yield ('WIKI_VIEW', self.hello_world, 'hello_world') 
     124    yield ('WIKI_ADMIN', self.delete_whole_system) 
    88125}}} 
    89126 
     127The method {{{hello_world()}}} is exported with the name "hello_world", as  
     128opposed to the default of combining the current module name with the function  
     129name. 
     130 
     131The {{{delete_whole_system()}}} method uses the optional {{{req}}} argument to  
     132enforce extra permission requirements. 
    90133 
    91134== Author/Contributors == 
    92135 
    93136'''Author:''' [wiki:athomas] [[BR]] 
    94 '''Contributors:''' 
    95137 
    96138[[TagIt(plugin,athomas,alpha,0.9)]]