wiki:WebRpc

Context Navigation

Version 42 (modified by davea, 15 years ago) (diff)
--

Web Remote Procedure Calls (RPCs)

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

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

URL: project_url/get_project_config.php
input: none.
examples

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

output

The output comes from several sources. Must of it from the config.xml file, which is created by make_project, and in most cases you don't have to change it. Values are also obtained from the project database, and the trigger files that indicate when web and scheduler activity has been stopped.

The document returned 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.

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.

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.

action: Each BOINC project and account manager exports it's configuration via the get_project_config web RPC.

Server status

URL: project_url/server_status.php
input: [ xml: ] output formatting. 0=HTML, 1=XML. (default is 0 if not specified)
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>

action: 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.

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 lower case form of their EMail address. The user password itself is never sent on an RPC call for privacy.

user_name: the user name.

[ invite_code: ] Invitation code if project requires invitation to create accounts.
examples: http://ralph.bakerlab.org/create_account.php?email_addr=feet1st@noyaspamhoo.com&passwd_hash=2ab548fae3162ccfa1a2d41a55557a92&user_name=CrunchAll

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 lower case form of the account's EMail address.

examples

http://ralph.bakerlab.org/lookup_account.php?email_addr=feet1st@noyaspamhoo.com&passwd_hash=2ab598faf3160ccfa1a2d41a95557a92

output

<account_out>
    [ <authenticator>XXX</authenticator> ]
</account_out>

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.

The authentication string may also be obtained using the boinccmd --lookup_account tool from an attached BOINC client; or, if the client is attached to the project and not using a weak authentication key, it is also stored in the project's account file, in the <authenticator> tag. This file is located in the BOINC data directory of the BOINC client, and called account_*.xml (where * is replaced by the project URL, with the "http://" removed and any slashes replaced by underscores; ex: account_boinc.bakerlab.org_rosetta.xml).

Get account info

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

action: returns data associated with the given account

Set account info

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

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

examples

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: Authentication string of user account owning the host being changed. See create account RPC or lookup account RPC

hostid:

venue:

examples

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

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.

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>

action: Returns info about an account. If called with the authentication string, returns a list of hosts associated with the account.

Get result list with 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

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

URL

project/create_team.php

input

account_key: Authentication string of team founder's user account. See create account RPC or lookup account RPC

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

examples

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

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

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

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>

action: Show info on team with the given ID.

Get team member list

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

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@usndathoople.edu</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>usndathoople.edu/~pdq</url>
        <has_profile>1</has_profile>
    </user>
    [ ... ]
</users>

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.

Set 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

[ 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: ... ]
examples
output: A lot of HTML (not XML)
action: Update user's forum preferences

Get user's last posts on the forum

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>

<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 user's last posts from the forum, or get user's last threads from the forums.

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>

Download in other formats:

Plain Text