wiki:WebRpc

Version 67 (modified by davea, 4 years ago) (diff)

--

  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 status of result(s)
    10. Get result list with pending credit
    11. Create team
    12. Look up teams by name
    13. Look up team by ID
    14. Get team member list
    15. Set forum preferences
    16. Get user's last posts on the forum
    17. Get list of application versions
    18. Get info for auto-attach download button

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 by account management systems and credit statistics web sites.

The file boinc/html/inc/web_rpc_api.php has PHP interfaces for a few of the RPCs (lookup_account, create_account, download_info). Use those if possible, and you can skip the details below.

These RPCs 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).

  • The output is XML.
  • If the project's get_project_config.php file includes a <web_rpc_url_base> element, its content should be used as the URL prefix; otherwise use the project's master URL.
  • Optional values are shown enclosed in square brackets.
  • 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. The EMail address or team name is already 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

-209: Attach failed. Perhaps due to invalid invitation code.

Project configuration

action
Export project or account manager configuration info.
URL
project_url/get_project_config.php
input
none.
examples

​http://setiathome.berkeley.edu/get_project_config.php

output

<project_config>
    <name>Project name</name>
    <master_url>URL</master_url>
    [ <account_creation_disabled/> ]
    [ <account_manager/> ]
    [ <client_account_creation_disabled/> ]
    [ <error_num>N</error_num> ]
    [ <local_revision>12345</local_revision> ]
    [ <min_passwd_length>N</min_passwd_length> ]
    [
      <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>
    ]
    [ <terms_of_use>TEXT</terms_of_use> ]
    [ <uses_username/> ]
    [ <web_rpc_url_base>URL</web_rpc_url_base> ]
    [ <web_stopped>0|1</web_stopped> ]
</project_config>
name
Project name
master_url
Master URL
account_creation_disabled
If present, this project is not allowing creation of new accounts
account_manager
If present, this is an account manager, not a BOINC project
client_account_creation_disabled
If present, new accounts can be created only via the web (not via the client software).
error_num
The project is currently down. A BOINC error number is returned.
local_revision
The SVN changeset number of the project's server software.
min_passwd_length
Minimum password length (for new account creation)
platforms
A list of platforms for which the project has application versions.
sched_stopped
Nonzero if the project's scheduler server is down, which means you can't get new work or report completed work.
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.
terms_of_use
If present, client GUIs should display this text and require that the user click Accept before attaching to this project.
uses_username
If present, this project uses names (rather than email addresses) as the primary account identifier.
web_rpc_url_base
prefix to use for web RPCs and statistics file downloads. Usually the same as master URL.
web_stopped
Nonzero if the project's database is down, which means the data-driven web pages are turned off.

Server status

action
Get project status. Can be used used to make web sites showing the server status of multiple BOINC projects. Do not poll more often than 10 minutes.
URL
project_url/server_status.php
input
[ xml ]
output formatting. 0=HTML (default), 1=XML.
examples
​http://lhcathome.cern.ch/lhcathome/server_status.php?xml=1
output
<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

action

Create an account. 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.

If <opaque_auth> is included in the reply, all subsequent RPCs that reference the account must supply the given string as well as the authenticator.

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 lower case form of their EMail address. The user password itself is never sent in an RPC call.
user_name
the user name.
[ invite_code ]
Invitation code if project requires invitation to create accounts.
[ team_name ]
optional name of a team to put user in.
[ consent_flag ]
optional - If true, sets the consent_flag to 1. If false the consent_flag is set to 0 and consent_not_required is set to 1. See ​UserOptInConsent for discussion.
[ source ]
optional - Set the source of who is setting consent, e.g., 'manager' or 'web'. See ​UserOptInConsent for discussion.
example
​http://ralph.bakerlab.org/create_account.php?email_addr=user@example.com&passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&user_name=CrunchAll
output
<account_out>
    <authenticator>XXX</authenticator>
</account_out>

Look up account

action
If passwd_hash is given and is correct, the user's authentication string is returned. This authentication string is required for many of the other RPCs. If no paswd_hash is given and the account exists, a success message is returned. If no account with the EMail address provided exists, an error is returned.

If ldap_auth is non-zero and ldap_uid and passwd are given, authenticate using the LDAP_HOST specified in project.inc. If no account with the EMail address of the ldap_uid exists, a new one is created and the authenticator returned.

URL
project_url/lookup_account.php
input
[ email_addr ]
email address of account (ignored when ldap_auth is non-zero)
[ passwd_hash ]
The MD5 hash of the concatenation of the user's password and the lower case form of the account's EMail address.
[ ldap_auth ]
Needs to be non-zero in order to use LDAP authentication. When enabled, ldap_uid and passwd must be supplied too.
[ ldap_uid ]
The LDAP userid that can be found on LDAP_HOST (defined in project.inc)
[ passwd ]
The password authenticating the LDAP userid.
examples
​http://ralph.bakerlab.org/lookup_account.php?email_addr=user@example.com&passwd_hash=2ab598faf3160ccfa1a2d41a95557a92&get_opaque_auth=1
output
<account_out>
    [ <authenticator>XXX</authenticator> ]
    [ <success/> ]
</account_out>

Get account info

action
returns data associated with the given account
URL
project_url/am_get_info.php
input
account_key
Authentication string for account to retrieve information about. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.
output
<am_get_info_reply>
    <success/>
    <id>ID</id>
    <name>NAME</name>
    <country>COUNTRY</country>
    <weak_auth>WEAK_AUTH</weak_auth>
    <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>

Set account info

action
Updates one or more attributes of the given account. If email address is changed, you must also change the password hash. If the project uses opaque_auth, then it will be returned on the reply.
URL
project_url/am_set_info.php
input
account_key
Authentication string of user account being changed. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.
[ 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 ]
The password hash is MD5(password+lower_case(email_addr)).
[ consent_name ]
This is the 'shortname' of the consent_type to modify.
[ consent_flag ]
Sets the consent_flag to 0 or 1.
[ consent_not_required ]
Sets the consent_not_required flag to 0 or 1.
[ consent_source ]
The source of the consent change, most likely the account manager name, e.g. 'GridRepublic'.
output
<am_set_info_reply>
    <success/>
    [ <opaque_auth>xxx</opaque_auth> ]
</am_set_info_reply>

NOTE: because the arguments of am_set_info can potentially be very long, it's also available as a HTTP POST transaction, with the same arguments.

For more information on the four consent related parameters, see ​UserOptInConsent.

Set host info

action
Updates the host's venue
URL
project_url/am_set_host_info.php
input
account_key
Authentication string of user account owning the host being changed. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.
hostid
venue
output
<am_set_host_info_reply>
    <success/>
</am_set_host_info_reply>

Get account/host credit information

action
Returns info about an account. If called with the authentication string, returns a list of hosts associated with the account.
URL
project/show_user.php
input
[ userid ]
User ID to display. Either id or auth must be specified.
[ auth ]
Authentication string of user to display. See create account RPC or lookup account RPC. Either id: or auth: must be specified.
opaque_auth
opaque authenticator, if present.
format
output formatting. 'xml' is only supported value (default is HTML formatting)
examples
​http://boinc.bakerlab.org/rosetta/show_user.php?userid=123&format=xml ​http://boinc.bakerlab.org/rosetta/show_user.php?auth=X&format=xml
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>

Get status of result(s)

URL
project/result_status.php
input
  • ids: comma-separated list of result IDs
  • or names: comma-separated list of result names
output
Descriptions of those result, including most of the DB fields such as server status, granted credit, etc.
examples
http://boinc.berkeley.edu/test/result_status.php?ids=5575279
output
<results>
    <result>
        <id>5575279</id>
        <create_time>1448056368</create_time>
        <workunitid>5527524</workunitid>
        <server_state>5</server_state>
        <outcome>1</outcome>
        <client_state>5</client_state>
        <hostid>1193</hostid>
        <userid>1</userid>
        <report_deadline>1453432427</report_deadline>
        <sent_time>1453428827</sent_time>
        <received_time>1453428866</received_time>
        <name>wu_nodelete_0</name>
        <cpu_time>19.93693</cpu_time>
        <batch>0</batch>
        <file_delete_state>2</file_delete_state>
        <validate_state>1</validate_state>
        <granted_credit>0.1138503608530816</granted_credit>
        <app_version_num>710</app_version_num>
        <appid>1</appid>
        <exit_status>0</exit_status>
        <elapsed_time>21.88125</elapsed_time>
        <flops_estimate>2247739772.112254</flops_estimate>
        <peak_working_set_size>5619712</peak_working_set_size>
        <peak_swap_size>3297280</peak_swap_size>
        <peak_disk_usage>203640</peak_disk_usage>
    </result>
</results>

Get result list with pending credit

DEPRECATED - BOINC NO LONGER HAS A NOTION OF PENDING CREDIT

URL
project/pending.php
input
format
Output formatting. 'xml' is only supported value (deafult is HTML formatting)
authenticator
Authentication string for user account to retrieve pending credit information about. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.

examples
​http://boinc.bakerlab.org/rosetta/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

REMOVED; SPAM

action
Creates a team
URL
project/create_team.php
input
account_key
Authentication string of team founder's user account. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.
name
name of team.
[ url ]
team URL.
type
one of these types.
[ name_html ]
team name, with HTML formatting.
[ description ]
text describing team.
[ country ]
team country (if present, must be one of these countries).
output
<create_team_reply>
    <success/>
    <teamid>N</teamid>
</create_team_reply>

Look up teams by name

action
Teams with names matching *string* will be returned. A maximum of 100 teams will be returned.
URL
project/team_lookup.php
input
team_name
Substring of team name
[ format ]
Output formatting. 'xml' is only supported value (deafult is HTML formatting)
examples
​http://boinc.bakerlab.org/team_lookup.php?team_name=BOINC&format=xml
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

Look up team by ID

action
Show info on team with the given ID.
URL
project/team_lookup.php
input
team_id
Team number of the team to lookup.
examples
​http://boinc.bakerlab.org/rosetta/team_lookup.php?team_id=111
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>

Get team member list

action
Show list of team members. If authentication string is that of a team administrator, show email addresses, and flag indicating whether the user opted out of getting emails.
URL
project/team_email_list.php
input
teamid
database ID of team
[ account_key ]
Authentication string of a team administrator's user account. See create account RPC or lookup account RPC
opaque_auth
opaque authenticator, if present.
xml
output formatting. 0=HTML, 1=XML. (default is 0)
[ creditonly ]
output credit related fields only and suppress users with total_credit=0 (only used with xml output).
examples
​http://boinc.bakerlab.org/rosetta/team_email_list.php?teamid=2241&account_key=Y&xml=1
output
<users>
    <user>
        <id>1</id>
        [ <email_addr>pdq@example.com</email_addr> ]
        [ <email_ok>yes|no</email_ok> ]
        <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>example.com/~pdq</url>
        <has_profile>1</has_profile>
    </user>
    [ ... ]
</users>

Set forum preferences

action
Update user's forum preferences
URL
project/edit_forum_preferences_action.php (NOTE: this uses POST, not GET)
input
account_key
Authentication string of user account to change preferences for. See create account RPC or lookup account RPC
[ opaque_auth ]
opaque authenticator, if present.
[ 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)

Get user's last posts on the forum

action
Get user's last posts from the forum, or get user's last threads from the forums.
URL
project/forum_get_data.php
input
method
"user_posts" to retrieve post details, "user_threads" to retrieve thread details.
userid
Numeric user ID you wish to see forum data about.
[ count ]
number of entries to return. Maximum 50, default 10.
[ contentlength ]
number of characters to return from post content. Default returns whole post. Only used when method=user_posts.
examples
​http://setiathome.berkeley.edu/forum_get_data.php?method=user_posts&userid=18&count=20&contentlength=256 ​http://setiathome.berkeley.edu/forum_get_data.php?method=user_threads&userid=182&count=20
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>

or 

<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>

Get list of application versions

URL
project/apps.php
input
[ xml ]
output formatting. 0=HTML, 1=XML. (default is 0)
examples
​http://setiathome.berkeley.edu/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>

Get info for auto-attach download button

This lets a "source" web site provide download buttons that auto-attach to an account on a "target" BOINC project or account manager.

URL
project/download_software.php
input
user_agent
user agent string passed by user's browser
auth
authenticator of user account
rpc_key
a security key supplied by the target project
action
must be 'get_info'
output
Error if account not found, or can't figure out user's platform, or the platform doesn't support auto-attach (only Mac and Win currently do). In that case show a link to the BOINC download page, ​https://boinc.berkeley.edu/download.php

Otherwise returns XML of the form 

<?xml version="1.0" encoding="ISO-8859-1" ?>
<download_info>
   <project_id>X</project_id>
   <token>X</token>
   <user_id>X</user_id>
   <platform>X</platform>
   <boinc>
      <filename>X</filename>
      <size_mb>X</size_mb>
      <boinc_version>X</boinc_version>
   </boinc>
   <boinc_vbox>
      <filename>X</filename>
      <size_mb>X</size_mb>
      <boinc_version>X</boinc_version>
      <vbox_version>X</vbox_version>
   </boinc_vbox>
</download_info>

This info is used to create buttons for downloading auto-attach versions of the BOINC installer. I.e. when the user downloads and installs, they'll be attached to the given account. The <boinc_vbox> element is present if there's a combined BOINC/VirtualBox installer for the platform.

See web_rpc_api.inc for example usage in PHP; this shows how to make Download buttons based on the info returned by the RPC.