Skip to content

WebRpc

Jump to bottom
Rom Walton edited this page Feb 5, 2015 · 9 revisions

PageOutline

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.

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

  • 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

    N xxx

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

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. BR 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 #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 #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.

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 #lookup_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 account with the EMail address provided exists, an error is returned.

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/lookup_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 the account's EMail address. [ get_opaque_auth ]:: Return the opaque authenticator for the user if the project provides one.

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> ]
    [ <opaque_auth>xxx</opaque_auth> ]
</account_out>

Get account info #am_get_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 #am_set_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)). 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.

Set host info #am_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 #show_user

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 result list with pending credit #pending

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

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 #team_lookup_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 #team_lookup_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 #team_email_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) 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 #edit_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 #forum_get_data_user_posts

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[thread title](Example)]></threadtitle>
        <timestamp>1162847905</timestamp>
        <content><![CDATA[post content](Example)]></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[forum thread title](Example)]></title>
        </thread>
        [...]
    </threads>
</rpc_response>

Get list of application versions #apps

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>

Home

Clone this wiki locally