-
Notifications
You must be signed in to change notification settings - Fork 449
WebRpc
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¶m2=val2&...¶mn=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.
Export project or account manager configuration info.
project_url/get_project_config.php
none.
http://setiathome.berkeley.edu/get_project_config.php
<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>Project name
Master URL
If present, this project is not allowing creation of new accounts
If present, this is an account manager, not a BOINC project
If present, new accounts can be created only via the web (not via the client software).
The project is currently down. A BOINC error number is returned.
The SVN changeset number of the project's server software.
Minimum password length (for new account creation)
A list of platforms for which the project has application versions.
Nonzero if the project's scheduler server is down, which means you can't get new work or report completed work.
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.
If present, client GUIs should display this text and require that the user click Accept before attaching to this project.
If present, this project uses names (rather than email addresses) as the primary account identifier.
prefix to use for web RPCs and statistics file downloads. Usually the same as master URL.
Nonzero if the project's database is down, which means the data-driven web pages are turned off.
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.
project_url/server_status.php
output formatting. 0=HTML (default), 1=XML.
http://lhcathome.cern.ch/lhcathome/server_status.php?xml=1
<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 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.
project_url/create_account.php
email address.
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.
the user name.
Invitation code if project requires invitation to create accounts.
optional name of a team to put user in.
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#RPC|UserOptInConsent for discussion.
optional - Set the source of who is setting consent, e.g., 'manager' or 'web'. See UserOptInConsent#RPC|UserOptInConsent for discussion.
<account_out>
<authenticator>XXX</authenticator>
</account_out>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.
project_url/lookup_account.php
email address of account (ignored when ldap_auth is non-zero)
The MD5 hash of the concatenation of the user's password and the lower case form of the account's EMail address.
Needs to be non-zero in order to use LDAP authentication. When enabled, ldap_uid and passwd must be supplied too.
The LDAP userid that can be found on LDAP_HOST (defined in project.inc)
The password authenticating the LDAP userid.
<account_out>
[ <authenticator>XXX</authenticator> ]
[ <success/> ]
</account_out>returns data associated with the given account
project_url/am_get_info.php
Authentication string for account to retrieve information about. See create account RPC or lookup account RPC
opaque authenticator, if present.
<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>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.
project_url/am_set_info.php
Authentication string of user account being changed. See create account RPC or lookup account RPC
opaque authenticator, if present.
zero means quit current team, if any
The password hash is MD5(password+lower_case(email_addr)).
This is the 'shortname' of the consent_type to modify.
Sets the consent_flag to 0 or 1.
Sets the consent_not_required flag to 0 or 1.
The source of the consent change, most likely the account manager name, e.g. 'GridRepublic'.
<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#RPC|UserOptInConsent.
Updates the host's venue
project_url/am_set_host_info.php
Authentication string of user account owning the host being changed. See create account RPC or lookup account RPC
opaque authenticator, if present.
<am_set_host_info_reply>
<success/>
</am_set_host_info_reply>Returns info about an account. If called with the authentication string, returns a list of hosts associated with the account.
project/show_user.php
User ID to display. Either id or auth must be specified.
Authentication string of user to display. See create account RPC or lookup account RPC. Either id: or auth: must be specified.
opaque authenticator, if present.
output formatting. 'xml' is only supported value (default is HTML formatting)
http://boinc.bakerlab.org/rosetta/show_user.php?userid=123&format=xml http://boinc.bakerlab.org/rosetta/show_user.php?auth=X&format=xml
<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>expavg_credit is exponentially-smoothed average credit per day.
expavg_time is the Unix time when this was last computed.
project/result_status.php
- ids: comma-separated list of result IDs
- or names: comma-separated list of result names
Descriptions of those result, including most of the DB fields such as server status, granted credit, etc.
https://boinc.berkeley.edu/test/result_status.php?ids=5575279
<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>DEPRECATED - BOINC NO LONGER HAS A NOTION OF PENDING CREDIT
project/pending.php
Output formatting. 'xml' is only supported value (deafult is HTML formatting)
Authentication string for user account to retrieve pending credit information about. See create account RPC or lookup account RPC
opaque authenticator, if present.
http://boinc.bakerlab.org/rosetta/pending.php?format=xml&authenticator=X
<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>REMOVED; SPAM
Creates a team
project/create_team.php
Authentication string of team founder's user account. See create account RPC or lookup account RPC
opaque authenticator, if present.
name of team.
team URL.
one of these types.
team name, with HTML formatting.
text describing team.
team country (if present, must be one of these countries).
<create_team_reply>
<success/>
<teamid>N</teamid>
</create_team_reply>Teams with names matching string will be returned. A maximum of 100 teams will be returned.
project/team_lookup.php
Substring of team name
Output formatting. 'xml' is only supported value (deafult is HTML formatting)
http://boinc.bakerlab.org/team_lookup.php?team_name=BOINC&format=xml
<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>
</teamsShow info on team with the given ID.
project/team_lookup.php
Team number of the team to lookup.
http://boinc.bakerlab.org/rosetta/team_lookup.php?team_id=111
<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>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.
project/team_email_list.php
database ID of team
Authentication string of a team administrator's user account. See create account RPC or lookup account RPC
opaque authenticator, if present.
output formatting. 0=HTML, 1=XML. (default is 0)
output credit related fields only and suppress users with total_credit=0 (only used with xml output).
http://boinc.bakerlab.org/rosetta/team_email_list.php?teamid=2241&account_key=Y&xml=1
<users>
<user>
<id>1</id>
[ <email_addr>[email protected]</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>Update user's forum preferences
project/edit_forum_preferences_action.php (NOTE: this uses POST, not GET)
Authentication string of user account to change preferences for. See create account RPC or lookup account RPC
opaque authenticator, if present.
Note: the image will be downloaded and stored locally. Only JPG and PNG accepted.
A lot of HTML (not XML)
Get user's last posts from the forum, or get user's last threads from the forums.
project/forum_get_data.php
"user_posts" to retrieve post details, "user_threads" to retrieve thread details.
Numeric user ID you wish to see forum data about.
number of entries to return. Maximum 50, default 10.
number of characters to return from post content. Default returns whole post. Only used when method=user_posts.
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
<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>project/apps.php
output formatting. 0=HTML, 1=XML. (default is 0)
http://setiathome.berkeley.edu/apps.php?xml=1
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>This lets a "source" web site provide download buttons that auto-attach to an account on a "target" BOINC project or account manager.
project/download_software.php
user agent string passed by user's browser
authenticator of user account
a security key supplied by the target project
must be 'get_info'
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.