Changes between Version 20 and Version 21 of WebRpc


Ignore:
Timestamp:
Jan 18, 2009, 12:33:59 PM (16 years ago)
Author:
feet1st
Comment:

Seperate line for each input variable. Added example URL section to each RPC. Removed variables from URL section and placed in example section. Display input fields in monospaced font. Consistently use []s to denote optional values.

Legend:

Unmodified
Added
Removed
Modified

  • WebRpc

    v20 v21  
    1414}}}
    1515where param1 ... paramN are the parameter names, and val1 ... valn are the values. Parameter values must be URL-encoded (for example, using PHP's `urlencode` function).
     16 * The output is XML.
     17 * If the project's [#get_project_config get_project_config.php] file includes a `<rpc_prefix>` element, its content should be used as the URL prefix; otherwise use the project's master URL.
     18 * Optional values are shown enclosed in square brackets.
    1619 * If an RPC fails, the returned XML document is
    1720
    … …  
    4750 '''-208'''::
    4851        Account creation disabled
    49  * The output is XML.
    50  * If the project's [#get_project_config get_project_config.php] file includes a `<rpc_prefix>` element, its content should be used as the URL prefix; otherwise use the project's master URL.
    51 
    5252
    5353== Project configuration == #get_project_config
    5454
    55 Each BOINC project and account manager exports a few configuration items via a web RPC; namely, it must provide an XML document at the address
    56 {{{
    57 http://PROJECT_URL/get_project_config.php
    58 }}}
     55 '''URL'''::
     56        project_url/get_project_config.php
     57 '''input'''::
     58        none. [[BR]]
     59 '''examples'''::
     60http://setiathome.berkeley.edu/get_project_config.php
     61 '''output'''::
    5962
    6063This file is created by [MakeProject make_project], and in most cases you don't have to change it.
    … …  
    106109The elements are:
    107110
    108  '''name'''::
     111 {{{name}}}::
    109112        Project name
    110  '''master_url'''::
     113 {{{master_url}}}::
    111114        Master URL
    112  '''local_revision'''::
     115 {{{local_revision}}}::
    113116        The SVN changeset number of the project's server software.
    114  '''web_stopped'''::
     117 {{{web_stopped}}}::
    115118        Nonzero if the project's database is down, which means the data-driven web pages are turned off.
    116  '''sched_stopped'''::
     119 {{{sched_stopped}}}::
    117120        Nonzero if the project's scheduler server is down, which means you can't get new work or report completed work.
    118  '''account_creation_disabled'''::
     121 {{{account_creation_disabled}}}::
    119122        If present, this project is not allowing creation of new accounts
    120  '''min_passwd_length'''::
     123 {{{min_passwd_length}}}::
    121124        Minimum password length (for new account creation)
    122  '''account_manager'''::
     125 {{{account_manager}}}::
    123126        If present, this is an account manager, not a BOINC project
    124  '''uses_username'''::
     127 {{{uses_username}}}::
    125128        If present, this project uses names (rather than email addresses)     as the primary account identifier
    126  '''client_account_creation_disabled'''::
     129 {{{client_account_creation_disabled}}}::
    127130        If present, new accounts can be created only via the web (not via the client software).
    128  '''rpc_prefix'''::
     131 {{{rpc_prefix}}}::
    129132        Prefix to use for web RPCs, instead of the master URL.
    130  '''error_num'''::
     133 {{{error_num}}}::
    131134        The project is currently down. A BOINC error number is returned.
    132  '''platforms'''::
     135 {{{platforms}}}::
    133136        A list of platforms for which the project has application versions.
    134  '''system_requirements'''::
     137 {{{system_requirements}}}::
    135138        Hardware requirements for participating in this project. If a computer doesn't meet these requirements it may not get sent any work by the project. All requirements are 'net'; e.g. the CPU requirements are after factors like [ClientSched on-fraction, active-fraction], and resource share have been taken into consideration. NOT IMPLEMENTED YET.
    136139
     140  '''action'''::
     141        Each BOINC project and account manager exports it's configuration via the get_project_config web RPC.
     142
    137143
    138144== Server status == #server_status
    139145
    140 BOINC-based projects offer the following XML export at `URL/server_status.php`. These are generally updated every 10 minutes or so - do not poll more often than that. These can be used to make web sites showing the server status of multiple BOINC projects.
     146 '''URL'''::
     147        project_url/server_status.php
     148 '''input'''::
     149        none. [[BR]]
     150 '''examples'''::
     151        http://einstein.phys.uwm.edu/server_status.php
     152 '''output'''::
    141153
    142154{{{
    … …  
    177189}}}
    178190
     191  '''action'''::
     192        XML export generally updated every 10 minutes or so - do not poll more often than that. Status is used to make web sites showing the server status of multiple BOINC projects.
     193
    179194== Create account == #create_account
    180195
    181   '''URL'''::
     196 '''URL'''::
    182197        project_url/create_account.php
    183198 '''input'''::
    184         email_addr: email address passwd_hash: the MD5 hash of the concatenation of the user's password and the email address.
    185         user_name: the user name
     199        {{{email_addr}}}: email address. [[BR]]
     200        {{{passwd_hash}}}: the MD5 hash of the concatenation of the user's password and the email address.[[BR]]
     201        {{{user_name}}}: the user name.[[BR]]
     202 '''examples'''::
     203        http://ralph.bakerlab.org/create_account.php?email_addr=feet1st@noyaspamhoo.com&passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&user_name=CrunchAll
     204
    186205 '''output'''::
    187206       
    … …  
    192211}}}
    193212
    194  '''action'''::
     213  '''action'''::
    195214        If the project already has an account with that email address, and a different password, it returns an error. If an account with that email address exists and has the same password, it returns the authenticator.  Otherwise the project creates an account and returns the authenticator.
    196215
    … …  
    200219        project_url/lookup_account.php
    201220 '''input'''::
    202         email_addr: email address [ passwd_hash ]: the MD5 hash of the concatenation of the user's password and the email address.
     221        {{{email_addr}}}: email address [[BR]]
     222        [ {{{passwd_hash}}}: ] the MD5 hash of the concatenation of the user's password and the email address.  [[BR]]
     223 '''examples'''::
     224        http://ralph.bakerlab.org/lookup_account.php?email_addr=feet1st@noyaspamhoo.com&passwd_hash=2ab598faf3160ccfa1a2d41a95557a92
    203225 '''output'''::
    204226       
    … …  
    219241        project_url/am_get_info.php
    220242 '''input'''::
    221         account_key
     243        {{{account_key}}}:
     244 '''examples'''::
    222245 '''output'''::
    223246       
    … …  
    254277        project_url/am_set_info.php
    255278 '''input'''::
    256         account_key     [ name ]     [ country ]     [ postal_code ]     [ global_prefs ]     [ project_prefs ]     [ url ]     [ send_email ]     [ show_hosts ]     [ teamid ]  ''zero means quit current team, if any''     [ venue ]     [ email_addr ]     [ password_hash ]
     279        {{{account_key}}}:     [[BR]]
     280        [ {{{name}}}: ]     [[BR]]
     281        [ {{{country}}}: ]     [[BR]]
     282        [ {{{postal_code}}}: ]     [[BR]]
     283        [ {{{global_prefs}}}: ]     [[BR]]
     284        [ {{{project_prefs}}}: ]     [[BR]]
     285        [ {{{url}}}: ]     [[BR]]
     286        [ {{{send_email}}}: ]    [[BR]]
     287        [ {{{show_hosts}}}: ]     [[BR]]
     288        [ {{{teamid}}}: ]  ''zero means quit current team, if any''     [[BR]]
     289        [ {{{venue}}}: ]     [[BR]]
     290        [ {{{email_addr}}}: ]     [[BR]]
     291        [ {{{password_hash}}}: ]  [[BR]]
     292 '''examples'''::
    257293 '''output'''::
    258294       
    … …  
    272308        project_url/am_set_host_info.php
    273309 '''input'''::
    274         account_key     hostid     venue
     310        {{{account_key}}}:     [[BR]]
     311        {{{hostid}}}:     [[BR]]
     312        {{{venue}}}:   [[BR]]
     313 '''examples'''::
    275314 '''output'''::
    276315       
    … …  
    288327
    289328 '''URL'''::
    290         project/show_user.php?userid=X&format=xml or     project/show_user.php?auth=X&format=xml
    291  '''input'''::
    292         id (user ID) or auth (account key)
     329        project/show_user.php
     330 '''input'''::
     331        {{{id}}}: (user ID) or auth: (account key)  [[BR]]
     332        {{{format}}}: output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
     333 '''examples'''::
     334        http://boinc.bakerlab.org/rosetta/show_user.php?userid=123&format=xml
     335        http://boinc.bakerlab.org/rosetta/show_user.php?auth=X&format=xml
    293336 '''output'''::
    294337       
    … …  
    349392
    350393 '''URL'''::
    351         project/pending.php?format=xml&authenticator=X
     394        project/pending.php
     395 '''input'''::
     396        {{{format}}}:   Output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
     397        {{{authenticator}}}:  [[BR]]
     398 '''examples'''::
     399        http://boinc.bakerlab.org/rosetta/pending.php?format=xml&authenticator=X
    352400 '''output'''::
    353401{{{
    … …  
    369417        project/create_team.php
    370418 '''input'''::
    371         account_key: identifies team founder name: name of team url: team URL (optional) type: one of [/team_types.php these types]. name_html: team name, HTML (optional) description: text describing team (optional) country: team country (optional; if present, must be one of [/countries.php these countries].
     419        {{{account_key}}}: identifies team founder.  [[BR]]
     420        {{{name}}}: name of team.   [[BR]]
     421        [ {{{url}}} ]: team URL.  [[BR]]
     422        {{{type}}}: one of [/team_types.php these types].   [[BR]]
     423        [ {{{name_html}}} ]: team name, with HTML formatting.  [[BR]]
     424        [ {{{description}}} ]: text describing team.  [[BR]]
     425        [ {{{country}}} ]: team country (if present, must be one of [/countries.php these countries]).  [[BR]]
     426 '''examples'''::
    372427 '''output'''::
    373428       
    … …  
    386441
    387442 '''URL'''::
    388         project/team_lookup.php?team_name=string&format=xml
    389  '''input'''::
    390         Substring of team name
     443        project/team_lookup.php
     444 '''input'''::
     445        {{{team_name}}}: Substring of team name  [[BR]]
     446        [ {{{format}}} ]:  Output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
     447 '''examples'''::
     448        http://boinc.bakerlab.org/team_lookup.php?team_name=BOINC&format=xml
    391449 '''output'''::
    392450       
    … …  
    424482
    425483 '''URL'''::
    426         project/team_lookup.php?team_id=N
    427  '''input'''::
    428         Team ID
     484        project/team_lookup.php
     485 '''input'''::
     486        {{{team_id}}}:
     487 '''examples'''::
     488        http://boinc.bakerlab.org/rosetta/team_lookup.php?team_id=111
    429489 '''output'''::
    430490       
    … …  
    452512
    453513 '''URL'''::
    454         project/team_email_list.php?teamid=X&account_key=Y&xml=1
    455  '''input'''::
    456         teamid: database ID of team     account_key: account key of team founder (optional)
     514        project/team_email_list.php
     515 '''input'''::
     516        {{{teamid}}}: database ID of team     [[BR]]
     517        {{{account_key}}}: account key of team founder (optional)   [[BR]]
     518        {{{xml}}}: output formatting. 0=HTML, 1=XML. (default is 0)   [[BR]]
     519 '''examples'''::
     520        http://boinc.bakerlab.org/rosetta/team_email_list.php?teamid=2241&account_key=Y&xml=1
     521
    457522 '''output'''::
    458523       
    … …  
    485550
    486551 '''URL'''::
    487         project/edit_forum_preferences_action.php          NOTE: this uses POST, not GET
    488  '''input'''::
    489         account_key     avatar_url ''Note: the image will be downloaded and stored locally. Only JPG and PNG accepted.''     avatar_select     forum_images_as_links     forum_link_externally     forum_hide_avatars     forum_hide_signatures     forum_jump_to_unread     forum_ignore_sticky_posts     forum_low_rating_threshold     forum_high_rating_threshold     forum_minimum_wrap_postcount     forum_display_wrap_postcount     signature_enabled     signature     forum_sort     thread_sort     faq_sort     answer_sort     forum_filter_user     [ removeID ... ]
     552        project/edit_forum_preferences_action.php
     553        NOTE: this uses POST, not GET
     554 '''input'''::
     555        {{{account_key}}}:     [[BR]]
     556        {{{avatar_url}}}: ''Note: the image will be downloaded and stored locally. Only JPG and PNG accepted.''     [[BR]]
     557        {{{avatar_select}}}:     [[BR]]
     558        {{{forum_images_as_links}}}:   [[BR]] 
     559        {{{forum_link_externally}}}:     [[BR]]
     560        {{{forum_hide_avatars}}}:     [[BR]]
     561        {{{forum_hide_signatures}}}:     [[BR]]
     562        {{{forum_jump_to_unread}}}:     [[BR]]
     563        {{{forum_ignore_sticky_posts}}}:     [[BR]]
     564        {{{forum_low_rating_threshold}}}:     [[BR]]
     565        {{{forum_high_rating_threshold}}}:     [[BR]]
     566        {{{forum_minimum_wrap_postcount}}}:     [[BR]]
     567        {{{forum_display_wrap_postcount}}}:     [[BR]]
     568        {{{signature_enabled}}}:     [[BR]]
     569        {{{signature}}}:     [[BR]]
     570        {{{forum_sort}}}:     [[BR]]
     571        {{{thread_sort}}}:     [[BR]]
     572        {{{faq_sort}}}:     [[BR]]
     573        {{{answer_sort}}}:     [[BR]]
     574        {{{forum_filter_user}}}:  [[BR]]   
     575        [ {{{removeID}}}: ... ]   [[BR]]
     576 '''examples'''::
    490577 '''output'''::
    491578        A lot of HTML (not XML)
    … …  
    494581
    495582
    496 == Get last user's posts from the forum == #forum_get_data_user_posts
    497 
    498 
    499  '''URL'''::
    500         project/forum_get_data.php?method=user_posts&userid=N&count=N&contentlength=N
    501  '''input'''::
    502         userid: numeric user ID in the database[[BR]]
    503         count ''(optional)'': number of entries to return. Maximum 50, default 10.[[BR]]
    504         contentlength ''(optional)'': number of characters to return from post content. Default returns whole post.
     583== Get user's last posts on the forum == #forum_get_data_user_posts
     584
     585
     586 '''URL'''::
     587        project/forum_get_data.php
     588 '''input'''::
     589        {{{method}}}: [[BR]]
     590                "user_posts" to retrieve post details, [[BR]]
     591                "user_threads" to retrieve thread details.[[BR]]
     592        {{{userid}}}: numeric user ID in the database[[BR]]
     593        [ {{{count}}} ]: number of entries to return. Maximum 50, default 10.[[BR]]
     594        [ {{{contentlength}}} ]: number of characters to return from post content. Default returns whole post. Only used when method=user_posts.
     595 '''examples'''::
     596        http://setiathome.berkeley.edu/forum_get_data.php?method=user_posts&userid=18&count=20&contentlength=256
     597        http://setiathome.berkeley.edu/forum_get_data.php?method=user_threads&userid=182&count=20
     598
    505599 '''output'''::
    506600       
    … …  
    521615}}}
    522616
    523  '''action'''::
    524         Get last user's posts from the forum.
    525 
    526 
    527 == Get last user's threads from the forum == #forum_get_data_user_threads
    528 
    529 
    530  '''URL'''::
    531         project/forum_get_data.php?method=user_threads&userid=N&count=N
    532  '''input'''::
    533     * userid: numeric user ID in the database
    534     * count ''(optional)'': number of entries to return. Maximum 50, default 10.
    535  '''output'''::
    536        
     617or
     618
    537619{{{
    538620<rpc_response>
    … …  
    553635
    554636 '''action'''::
    555         Get last user's threads from the forums.
     637        Get user's last posts from the forum, or get user's last threads from the forums.
    556638
    557639
    … …  
    559641
    560642 '''URL'''::
    561         project/apps.php?xml=1
     643        project/apps.php
     644 '''input'''::
     645        [ {{{xml}}} ]: output formatting. 0=HTML, 1=XML. (default is 0)
     646 '''examples'''::
     647        http://setiathome.berkeley.edu/apps.php?xml=1
    562648 '''output'''::
    563649        List of applications and application versions. For example: