[[PageOutline]]

= 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 [AccountManagement 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 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 [source:trunk/boinc/lib/error_numbers.h 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

== Project configuration == #get_project_config

 '''URL'''::
	project_url/get_project_config.php
 '''input'''::
	none. [[BR]]
 '''examples'''::
http://setiathome.berkeley.edu/get_project_config.php
 '''output'''::

This file is created by [MakeProject 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:

{{{
#!html
<font color=darkgreen face="monospace">
}}}
 name::
{{{
#!html
</font>
}}}
	Project name
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 master_url::
{{{
#!html
</font>
}}} 
        Master URL
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 local_revision::
{{{
#!html
</font>
}}}
        The SVN changeset number of the project's server software.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 web_stopped::
{{{
#!html
</font>
}}} 
        Nonzero if the project's database is down, which means the data-driven web pages are turned off.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 local_revision::
{{{
#!html
</font>
}}}
        Nonzero if the project's scheduler server is down, which means you can't get new work or report completed work.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 account_creation_disabled::
{{{
#!html
</font>
}}} 
	If present, this project is not allowing creation of new accounts
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 min_passwd_length::
{{{
#!html
</font>
}}}
	Minimum password length (for new account creation)
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 account_manager::
{{{
#!html
</font>
}}}
	If present, this is an account manager, not a BOINC project
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 uses_username::
{{{
#!html
</font>
}}}
	If present, this project uses names (rather than email addresses)     as the primary account identifier
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 client_account_creation_disabled::
{{{
#!html
</font>
}}}
	If present, new accounts can be created only via the web (not via the client software).
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 rpc_prefix::
{{{
#!html
</font>
}}}
	Prefix to use for web RPCs, instead of the master URL.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 error_num::
{{{
#!html
</font>
}}}
	The project is currently down. A BOINC error number is returned.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 platforms::
{{{
#!html
</font>
}}}
	A list of platforms for which the project has application versions.
{{{
#!html
<font color=darkgreen face="monospace">
}}}
 system_requirements::
{{{
#!html
</font>
}}}
	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 [ClientSched 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 == #server_status

 '''URL'''::
	project_url/server_status.php
 '''input'''::
	none. [[BR]]
 '''examples'''::
	http://einstein.phys.uwm.edu/server_status.php
 '''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 == #create_account

 '''URL'''::
	project_url/create_account.php
 '''input'''::
	{{{email_addr}}}: email address. [[BR]]
	{{{passwd_hash}}}: the MD5 hash of the concatenation of the user's password and the email address.[[BR]]
	{{{user_name}}}: the user name.[[BR]]
 '''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 == #lookup_account

 '''URL'''::
	project_url/lookup_account.php
 '''input'''::
	{{{email_addr}}}: email address [[BR]]
	[ {{{passwd_hash}}}: ] the MD5 hash of the concatenation of the user's password and the email address.  [[BR]]
 '''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 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 == #am_get_info


 '''URL'''::
	project_url/am_get_info.php
 '''input'''::
	{{{account_key}}}:
 '''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 == #am_set_info


 '''URL'''::
	project_url/am_set_info.php
 '''input'''::
	{{{account_key}}}:     [[BR]]
	[ {{{name}}}: ]     [[BR]]
	[ {{{country}}}: ]     [[BR]]
	[ {{{postal_code}}}: ]     [[BR]]
	[ {{{global_prefs}}}: ]     [[BR]]
	[ {{{project_prefs}}}: ]     [[BR]]
	[ {{{url}}}: ]     [[BR]]
	[ {{{send_email}}}: ]    [[BR]] 
	[ {{{show_hosts}}}: ]     [[BR]]
	[ {{{teamid}}}: ]  ''zero means quit current team, if any''     [[BR]]
	[ {{{venue}}}: ]     [[BR]]
	[ {{{email_addr}}}: ]     [[BR]]
	[ {{{password_hash}}}: ]  [[BR]]
 '''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 == #am_set_host_info


 '''URL'''::
	project_url/am_set_host_info.php
 '''input'''::
	{{{account_key}}}:     [[BR]]
	{{{hostid}}}:     [[BR]]
	{{{venue}}}:   [[BR]]
 '''examples'''::
 '''output'''::
	
{{{
<am_set_host_info_reply>
    <success/>
</am_set_host_info_reply>
}}}

 '''action'''::
	Updates the host's venue

== Get account/host credit information == #show_user


 '''URL'''::
	project/show_user.php
 '''input'''::
	{{{id}}}: (user ID) or auth: (account key)  [[BR]]
	{{{format}}}: output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
 '''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 account key, returns a list of hosts associated with the account.

== Get result list with pending credit == #pending

 '''URL'''::
	project/pending.php
 '''input'''::
	{{{format}}}:   Output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
	{{{authenticator}}}:  [[BR]]
 '''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

 '''URL'''::
	project/create_team.php
 '''input'''::
	{{{account_key}}}: identifies team founder.  [[BR]]
	{{{name}}}: name of team.   [[BR]]
	[ {{{url}}} ]: team URL.  [[BR]]
	{{{type}}}: one of [/team_types.php these types].   [[BR]]
	[ {{{name_html}}} ]: team name, with HTML formatting.  [[BR]]
	[ {{{description}}} ]: text describing team.  [[BR]]
	[ {{{country}}} ]: team country (if present, must be one of [/countries.php these countries]).  [[BR]]
 '''examples'''::
 '''output'''::
	
{{{
<create_team_reply>
    <success/>
    <teamid>N</teamid>
</create_team_reply>
}}}

 '''action'''::
	Creates a team

== Look up teams by name == #team_lookup_name


 '''URL'''::
	project/team_lookup.php
 '''input'''::
	{{{team_name}}}: Substring of team name  [[BR]]
	[ {{{format}}} ]:  Output formatting. 'xml' is only supported value (deafult is HTML formatting)  [[BR]]
 '''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 == #team_lookup_id


 '''URL'''::
	project/team_lookup.php
 '''input'''::
	{{{team_id}}}:
 '''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 == #team_email_list


 '''URL'''::
	project/team_email_list.php
 '''input'''::
	{{{teamid}}}: database ID of team     [[BR]]
	{{{account_key}}}: account key of team founder (optional)   [[BR]]
	{{{xml}}}: output formatting. 0=HTML, 1=XML. (default is 0)   [[BR]]
 '''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 account key is that of a team admin, show email addresses, and flags indicating whether the user opted out of getting emails.


== Set forum preferences == #edit_forum_preferences


 '''URL'''::
	project/edit_forum_preferences_action.php  [[BR]]
	(NOTE: this uses POST, not GET)
 '''input'''::
	{{{account_key}}}:     [[BR]]
	{{{avatar_url}}}: ''Note: the image will be downloaded and stored locally. Only JPG and PNG accepted.''     [[BR]]
	{{{avatar_select}}}:     [[BR]]
	{{{forum_images_as_links}}}:   [[BR]]  
	{{{forum_link_externally}}}:     [[BR]]
	{{{forum_hide_avatars}}}:     [[BR]]
	{{{forum_hide_signatures}}}:     [[BR]]
	{{{forum_jump_to_unread}}}:     [[BR]]
	{{{forum_ignore_sticky_posts}}}:     [[BR]]
	{{{forum_low_rating_threshold}}}:     [[BR]]
	{{{forum_high_rating_threshold}}}:     [[BR]]
	{{{forum_minimum_wrap_postcount}}}:     [[BR]]
	{{{forum_display_wrap_postcount}}}:     [[BR]]
	{{{signature_enabled}}}:     [[BR]]
	{{{signature}}}:     [[BR]]
	{{{forum_sort}}}:     [[BR]]
	{{{thread_sort}}}:     [[BR]]
	{{{faq_sort}}}:     [[BR]]
	{{{answer_sort}}}:     [[BR]]
	{{{forum_filter_user}}}:  [[BR]]   
	[ {{{removeID}}}: ... ]   [[BR]]
 '''examples'''::
 '''output'''::
	A lot of HTML (not XML)
 '''action'''::
	Update user's forum preferences


== Get user's last posts on the forum == #forum_get_data_user_posts


 '''URL'''::
	project/forum_get_data.php
 '''input'''::
	{{{method}}}: [[BR]]
		"user_posts" to retrieve post details, [[BR]]
		"user_threads" to retrieve thread details.[[BR]]
	{{{userid}}}: numeric user ID in the database[[BR]]
	[ {{{count}}} ]: number of entries to return. Maximum 50, default 10.[[BR]]
	[ {{{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>
}}}

 '''action'''::
	Get user's last posts from the forum, or get user's last threads from the forums.


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

}}}