= Web Remote Procedure Calls (RPCs) = == Contents == * [WebRpc#Overview Overview] * [WebRpc#Projectconfiguration Project configuration] * [WebRpc#Createaccount Create account] * [WebRpc#Lookupaccount Lookup account] * [WebRpc#Getaccountinfo Get account info] * [WebRpc#Setaccountinfo Set account info] * [WebRpc#Sethostinfo Set host info] * [WebRpc#Getaccounthostcreditinformation Get account/host credit info] * [WebRpc#Createteam Create team] * [WebRpc#Lookupteamsbyname Lookup teams by name] * [WebRpc#LookupteambyID Lookup team by ID] * [WebRpc#Getteammemberlist Get team member list] * [WebRpc#Setforumpreferences Set forum preferences] * [WebRpc#Getlastuserspostsfromtheforum Get last user's posts from the forum] * [WebRpc#Getlastusersthreadsfromtheforum Get last user's threads from the forum] * [WebRpc#Getlistofapplicationversions Get list of applications and versions] == Overview == 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¶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). * 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 (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 * The output is XML. * If the project's [ProjectConfigRpc get_project_config.php] file includes a `` element, its content should be used as the URL prefix; otherwise use the project's master URL. == Project configuration == Each BOINC project exports some configuration items relevant to attaching and creating accounts. This RPC is documented [ProjectConfigRpc here]. == Create account == '''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 email address. user_name: the user name '''output''':: {{{ XXX }}} '''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 email address. '''output''':: {{{ [ XXX ] }}} '''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 == '''URL''':: project_url/am_get_info.php '''input''':: account_key '''output''':: {{{ ID NAME COUNTRY POSTAL_CODE GLOBAL_PREFS PROJECT_PREFS URL SEND_EMAIL SHOW_HOSTS N [ ] X }}} '''action''':: returns data associated with the given account == Set account info == '''URL''':: project_url/am_set_info.php '''input''':: account_key [ 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 ] '''output''':: {{{ }}} '''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 hostid venue '''output''':: {{{ }}} '''action''':: Updates the host's venue == Get account/host credit information == '''URL''':: project/show_user.php?userid=X&format=xml or project/show_user.php?auth=X&format=xml '''input''':: id (user ID) or auth (account key) '''output''':: {{{ 123 fe0b2753a355b17864ec061eb1b9e8de 918948493 Joe Smith United States 3806.869739 200 1110833427.64028 114322 example.com 1 or 123 fe0b2753a355b17864ec061eb1b9e8de 1101918807 David United States 0.293197 0.000883 1116963330.83107 0 example.com 1 123 1287339128 123 fe0b2753a355b17864ec061eb1b9e8de 0 0 0 Sorabji 1 Mobile Intel(R) Pentium(R) 4 - M CPU 2.20GHz Pentium 330806175.78458 409200165.535107 Microsoft Windows XP Professional Edition, Service Pack 2, (05.01.2600.00) ... }}} '''action''':: Returns info about an account. If called with the account key, returns a list of hosts associated with the account. == Create team == '''URL''':: project/create_team.php '''input''':: account_key: identifies team founder name: name of team url: team URL (optional) type: one of the types listed [http://boinc.berkeley.edu/team_types.php here]. name_html: team name, HTML (optional) description: text describing team (optional) country: team country (optional; if present, must be one of the countries listed [http://boinc.berkeley.edu/countries.php here]. '''output''':: {{{ N }}} '''action''':: Creates a team == Look up teams by name == '''URL''':: project/team_lookup.php?team_name=string&format=xml '''input''':: Substring of team name '''output''':: {{{ 5 BOINC@AUSTRALIA Australia 9 BOINC Synergy International 16 BOINC.BE Belgium 23 HispaSeti & BOINC International 5 BOINC@AUSTRALIA Australia }}} '''action''':: Show info on team with the given ID. == Get team member list == '''URL''':: project/team_email_list.php?teamid=X&account_key=Y&xml=1 '''input''':: teamid: database ID of team account_key: account key of team founder (optional) '''output''':: {{{ 1 pdq@usndathoople.edu 232f381c79336f0bd8df02bbce2f2217 1076897105 David United States 9.907264 0.023264 1142628426.48937 usndathoople.edu/~pdq 1 [ ... ] }}} '''action''':: Show list of team members. If account key is that of team founder, show email addresses. == Set forum preferences == '''URL''':: project/edit_forum_preferences_action.php NOTE: this uses POST, not GET '''input''':: account_key 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) '''action''':: Update user's forum preferences == Get last user's posts from the forum == '''URL''':: project/forum_get_data.php?method=user_posts&userid=N&count=N '''input''':: userid: numeric user ID in the database count ''(optional)'': number of entries to return. Maximum 50, default 10. '''output''':: {{{ 1 4157 76 1162847905 [ ... ] }}} '''action''':: Get last user's posts from the forum. == Get last user's threads from the forum == '''URL''':: project/forum_get_data.php?method=user_threads&userid=N&count=N '''input''':: userid: numeric user ID in the database count ''(optional)'': number of entries to return. Maximum 50, default 10. '''output''':: {{{ 1 356 2 11 612 1159062318 <![CDATA[Example forum thread title]]> [...] }}} '''action''':: Get last user's threads from the forums. == Get list of application versions == '''URL''':: project/apps.php '''output''':: List of applications and application versions; this shows what platforms are supported by the project.