wiki:WebRpc

Version 18 (modified by Nicolas, 17 years ago) (diff)

Reword web_stopped and sched_stopped

  1. Web Remote Procedure Calls (RPCs)
    1. Project configuration
    2. Server status
    3. Create account
    4. Look up account
    5. Get account info
    6. Set account info
    7. Set host info
    8. Get account/host credit information
    9. Get result list with pending credit
    10. Create team
    11. Look up teams by name
    12. Look up team by ID
    13. Get team member list
    14. Set forum preferences
    15. Get last user's posts from the forum
    16. Get last user's threads from the forum
    17. Get list of application versions

Web Remote Procedure Calls (RPCs)

BOINC projects export a number of Web RPCs for creating, querying and updating accounts and host records, and miscellaneous other purposes. These can be used for account management systems and credit statistics web sites.

BOINC's RPC mechanisms have the following conventions:

  • Each RPC is an HTTP GET transaction.
  • The input is the GET arguments, i.e. a string of the form 
param1=val1&param2=val2&...&paramn=valn

where 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).

  • If an RPC fails, the returned XML document is 
<error>
    <error_num>N</error_num>
    <error_string>xxx</error_string>
</error>

where N is a BOINC error number and xxx is a textual description. BOINC error numbers are in lib/error_numbers.h; common errors are:

-1
Generic error (error_string may have more info)
-112
Invalid XML (e.g., the preferences passed to am_set_info.php are invalid)
-136
Item not found in database (bad ID of any sort, or ID refers to an item not owned by the caller)
-137
Name is not unique (Can't create account because email address already in use, or can't create team because name is in use)
-138
Can't access database (treat same as -183)
-161
Item not found (deprecated; treat same as -136)
-183
Project is temporarily down
-205
Email address has invalid syntax
-206
Wrong password
-207
Non-unique email address (treat same as -137)
-208
Account creation disabled
  • The output is XML.
  • If the project's 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.

Project configuration

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 

http://PROJECT_URL/get_project_config.php

This file is created by make_project, and in most cases you don't have to change it.

This document has this structure: 

<project_config>
    <name>Project name</name>
    <master_url>URL</master_url>
    [ <local_revision>12345</local_revision> ]
    [ <web_stopped>0|1</web_stopped> ]
    [ <account_creation_disabled/> ]
    [ <client_account_creation_disabled/> ]
    [ <min_passwd_length>N</min_passwd_length> ]
    [ <account_manager/> ]
    [ <uses_username/> ]
    [ <rpc_prefix>URL</rpc_prefix> ]
    [ <error_num>N</error_num> ]
    [
      <platforms>
        <platform>
          <platform_name>i686-apple-darwin</platform_name>
          <user_friendly_name>Mac OS X (Intel)</user_friendly_name>
        </platform>
        <platform>
          <platform_name>i686-pc-linux-gnu</platform_name>
          <user_friendly_name>Linux/x86</user_friendly_name>
        </platform>
        ...
      </platforms>
    ]
    [ <sched_stopped>0|1</sched_stopped> ]
    [
      <system_requirements>
        [ <p_fpops>N</p_fpops> ]
        [ <p_iops>N</p_iops> ]
        [ <p_membw>N</p_membw> ]
        [ <m_nbytes>N</m_nbytes> ]
        [ <m_swap>N</m_swap> ]
        [ <d_free>N</d_free> ]
        [ <bwup>N</bwup> ]
        [ <bwdown>N</bwdown> ]
      </system_requirements>
    ]
</project_config>

The elements are:

name
Project name
master_url
Master URL
local_revision
The SVN changeset number of the project's server software.
web_stopped
Nonzero if the project's database is down, which means the data-driven web pages are turned off.
sched_stopped
Nonzero if the project's scheduler server is down, which means you can't get new work or report completed work.
account_creation_disabled
If present, this project is not allowing creation of new accounts
min_passwd_length
Minimum password length (for new account creation)
account_manager
If present, this is an account manager, not a BOINC project
uses_username
If present, this project uses names (rather than email addresses) as the primary account identifier
client_account_creation_disabled
If present, new accounts can be created only via the web (not via the client software).
rpc_prefix
Prefix to use for web RPCs, instead of the master URL.
error_num
The project is currently down. A BOINC error number is returned.
platforms
A list of platforms for which the project has application versions.
system_requirements
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 on-fraction, active-fraction, and resource share have been taken into consideration. NOT IMPLEMENTED YET.

Server status

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. 

<server_status>
    <update_time>1128535206</update_time>
    <daemon_status>
        <daemon>
            <host>jocelyn</host>
            <command>BOINC database</command>
            <status>running</status>
        </daemon>
        <daemon>
            <host>castelli</host>
            <command>master science database</command>
            <status>running</status>
        </daemon>
        <daemon>
            <host>klaatu</host>
            <command>data-driven web pages</command>
            <status>disabled</status>
        </daemon>
        <daemon>
            <host>galileo</host>
            <command>feeder</command>
            <status>not running</status>
        </daemon>
    </daemon_status>
	<database_file_states>
        <results_ready_to_send>614830</results_ready_to_send>
        <results_in_progress>1208959</results_in_progress>
        <workunits_waiting_for_validation>8</workunits_waiting_for_validation>
        <workunits_waiting_for_assimilation>2</workunits_waiting_for_assimilation>
        <workunits_waiting_for_deletion>4</workunits_waiting_for_deletion>
        <results_waiting_for_deletion>15</results_waiting_for_deletion>
        <transitioner_backlog_hours>0.00083333334</transitioner_backlog_hours>
    </database_file_states>
</server_status>

Create account

URL
project_url/create_account.php
input
email_addr: email address passwd_hash: the MD5 hash of the concatenation of the user's password and the email address. user_name: the user name
output
<account_out>
    <authenticator>XXX</authenticator>
</account_out>
action
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.

Look up account

URL
project_url/lookup_account.php
input
email_addr: email address [ passwd_hash ]: the MD5 hash of the concatenation of the user's password and the email address.
output
<account_out>
    [ <authenticator>XXX</authenticator> ]
</account_out>
action
If an account with the given email address doesn't exist, return an error. If passwd_hash is given and is correct, return the account key.

Get account info

URL
project_url/am_get_info.php
input
account_key
output
<am_get_info_reply>
    <success/>
    <id>ID</id>
    <name>NAME</name>
    <country>COUNTRY</country>
    <postal_code>POSTAL_CODE</postal_code>
    <global_prefs>
        GLOBAL_PREFS
    </global_prefs>
    <project_prefs>
        PROJECT_PREFS
    </project_prefs>
    <url>URL</url>
    <send_email>SEND_EMAIL</send_email>
    <show_hosts>SHOW_HOSTS</show_hosts>
    <teamid>N</teamid>
    [ <teamfounder/> ]
    <venue>X</venue>
</am_get_info_reply>
action
returns data associated with the given account

Set account info

URL
project_url/am_set_info.php
input
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 ]
output
<am_set_info_reply>
    <success/>
</am_set_info_reply>
action
Updates one or more attributes of the given account. The password hash is MD5(password+lower_case(email_addr)). If email address is changed, you must also change the password hash.

Set host info

URL
project_url/am_set_host_info.php
input
account_key hostid venue
output
<am_set_host_info_reply>
    <success/>
</am_set_host_info_reply>
action
Updates the host's venue

Get account/host credit information

URL
project/show_user.php?userid=X&format=xml or project/show_user.php?auth=X&format=xml
input
id (user ID) or auth (account key)
output
<user>
    <id>123</id>
    <cpid>fe0b2753a355b17864ec061eb1b9e8de</cpid>
    <create_time>918948493</create_time>
    <name>Joe Smith</name>
    <country>United States</country>
    <total_credit>3806.869739</total_credit>
    <expavg_credit>200</expavg_credit>
    <expavg_time>1110833427.64028</expavg_time>
    <teamid>114322</teamid>
    <url>example.com</url>
    <has_profile>1</has_profile>
</user>

or

<user>
    <id>123</id>
    <cpid>fe0b2753a355b17864ec061eb1b9e8de</cpid>
    <create_time>1101918807</create_time>
    <name>David</name>
    <country>United States</country>
    <total_credit>0.293197</total_credit>
    <expavg_credit>0.000883</expavg_credit>
    <expavg_time>1116963330.83107</expavg_time>
    <teamid>0</teamid>
    <url>example.com</url>
    <has_profile>1</has_profile>
    <host>
        <id>123</id>
        <create_time>1287339128</create_time>
        <rpc_seqno>123</rpc_seqno>
        <host_cpid>fe0b2753a355b17864ec061eb1b9e8de</host_cpid>
        <total_credit>0</total_credit>
        <expavg_credit>0</expavg_credit>
        <expavg_time>0</expavg_time>
        <domain_name>Sorabji</domain_name>
        <p_ncpus>1</p_ncpus>
        <p_vendor>Mobile Intel(R) Pentium(R) 4 - M CPU 2.20GHz</p_vendor>
        <p_model>Pentium</p_model>
        <p_fpops>330806175.78458</p_fpops>
        <p_iops>409200165.535107</p_iops>
        <os_name>Microsoft Windows XP</os_name>
        <os_version>Professional Edition, Service Pack 2, (05.01.2600.00)</os_version>
    </host>
    ...
</user>
action
Returns info about an account. If called with the account key, returns a list of hosts associated with the account.

Get result list with pending credit

URL
project/pending.php?format=xml&authenticator=X
output
<pending_credit>
    <result>
        <resultid> N </resultid>
        <workunitid> N </workunitid>
        <claimed_credit> N </claimed_credit>
        <received_time> N </received_time>
    </result>
    [...]
    <total_claimed_credit> N </total_claimed_credit>
</pending_credit>

Create team

URL
project/create_team.php
input
account_key: identifies team founder name: name of team url: team URL (optional) type: one of these types. name_html: team name, HTML (optional) description: text describing team (optional) country: team country (optional; if present, must be one of these countries.
output
<create_team_reply>
    <success/>
    <teamid>N</teamid>
</create_team_reply>
action
Creates a team

Look up teams by name

URL
project/team_lookup.php?team_name=string&format=xml
input
Substring of team name
output
<teams>
    <team>
        <id>5</id>
        <name>BOINC@AUSTRALIA</name>
        <country>Australia</country>
    </team>
    <team>
        <id>9</id>
        <name>BOINC Synergy</name>
        <country>International</country>
    </team>
    <team>
        <id>16</id>
        <name>BOINC.BE</name>
        <country>Belgium</country>
    </team>
    <team>
        <id>23</id>
        <name>HispaSeti & BOINC</name>
        <country>International</country>
    </team>
</teams
action
Teams with names matching *string* will be returned. A maximum of 100 teams will be returned.

Look up team by ID

URL
project/team_lookup.php?team_id=N
input
Team ID
output
<team>
  <id>9</id>
  <create_time>1109465921</create_time>
  <userid>77</userid>
  <name>BOINC Synergy</name>
  <url>www.boincsynergy.com</url>
  <type>1</type>
  <country>International</country>
  <total_credit>226527.840602</total_credit>
  <expavg_credit>12.798762</expavg_credit>
  <expavg_time>1178908429.9883</expavg_time>
</team>
action
Show info on team with the given ID.

Get team member list

URL
project/team_email_list.php?teamid=X&account_key=Y&xml=1
input
teamid: database ID of team account_key: account key of team founder (optional)
output
<users>
    <user>
        <id>1</id>
        <email_addr>pdq@usndathoople.edu</email_addr>
        <cpid>232f381c79336f0bd8df02bbce2f2217</cpid>
        <create_time>1076897105</create_time>
        <name>David</name>
        <country>United States</country>
        <total_credit>9.907264</total_credit>
        <expavg_credit>0.023264</expavg_credit>
        <expavg_time>1142628426.48937</expavg_time>
        <url>usndathoople.edu/~pdq</url>
        <has_profile>1</has_profile>
    </user>
    [ ... ]
</users>
action
Show list of team members. If account key is that of team founder, show email addresses.

Set forum preferences

URL
project/edit_forum_preferences_action.php NOTE: this uses POST, not GET
input
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 ... ]
output
A lot of HTML (not XML)
action
Update user's forum preferences

Get last user's posts from the forum

URL
project/forum_get_data.php?method=user_posts&userid=N&count=N&contentlength=N
input
userid: numeric user ID in the database
count (optional): number of entries to return. Maximum 50, default 10.
contentlength (optional): number of characters to return from post content. Default returns whole post.
output
<rpc_response>
    <count>1</count>
    <posts>
        <post>
        <id>4157</id>
        <threadid>76</threadid>
        <threadtitle><![CDATA[Example thread title]]></threadtitle>
        <timestamp>1162847905</timestamp>
        <content><![CDATA[Example post content]]></content>
        </post>
        [ ... ]
    </posts>
</rpc_response>
action
Get last user's posts from the forum.

Get last user's threads from the forum

URL
project/forum_get_data.php?method=user_threads&userid=N&count=N
input
  • userid: numeric user ID in the database
  • count (optional): number of entries to return. Maximum 50, default 10.
output
<rpc_response>
    <count>1</count>
    <threads>
        <thread>
            <id>356</id>
            <forumid>2</forumid>
            <replies>11</replies>
            <views>612</views>
            <timestamp>1159062318</timestamp>
            <title><![CDATA[Example forum thread title]]></title>
        </thread>
        [...]
    </threads>
</rpc_response>
action
Get last user's threads from the forums.

Get list of application versions

URL
project/apps.php?xml=1
output
List of applications and application versions. For example: 
<?xml version="1.0" encoding="ISO-8859-1" ?>
<app_versions>
<application>
    <name>Upper Case</name>
    <version>
        <platform_short>i686-pc-linux-gnu</platform_short>
        <platform_long>Linux/x86</platform_long>
        <version_num>511</version_num>

        <date>21 Apr 2006 19:38:26 UTC</date>
        <date_unix>1145648306</date_unix>
    </version>
    <version>
        <platform_short>windows_intelx86</platform_short>
        <platform_long>Windows/x86</platform_long>
        <version_num>515</version_num>

        <date>8 May 2007 21:15:42 UTC</date>
        <date_unix>1178658942</date_unix>
    </version>
    ...
    </application>
</app_versions>