Difference between revisions of "Linden Lab Official:Reg API Examples"
Rand Linden (talk | contribs) |
(RegAPI 2.1 update) |
||
(11 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{: | {{Supported API}} | ||
{{:API Portal/navigation|reg}} | |||
The following examples illustrate using the Reg API to register a new user with a specified Second Life first name and last name. The example code first checks to determine the availability of the selected first and last name, and either registers the user or returns an error message if the name is already taken. | The following examples illustrate using the Reg API to register a new user with a specified Second Life first name and last name. The example code first checks to determine the availability of the selected first and last name, and either registers the user or returns an error message if the name is already taken. | ||
<br | __TOC__ | ||
<br clear="all"/> | |||
== LLSD library downloads == | == LLSD library downloads == | ||
Line 16: | Line 18: | ||
NOTE: The PHP scripts only work with PHP4. | NOTE: The PHP scripts only work with PHP4. | ||
An externally developed Java implementation of LLSD and RegAPI is available at http://mimuve.cs.st-andrews.ac.uk/llsd-java/src/llsd-java-0.2.1.zip . Code written by Xugu Madison, copyright held by University of St Andrews, and made available under the BSD license. Tested with Java 1.5. | |||
Question: what version of each language is required? | Question: what version of each language is required? | ||
Line 23: | Line 27: | ||
=== Ruby === | === Ruby === | ||
This ruby example shows how to use the Registration API. | |||
<nowiki>require 'llsd' | |||
# 0 - get capability urls | # 0 - get capability urls | ||
Line 42: | Line 45: | ||
password = ARGV[2] | password = ARGV[2] | ||
else | else | ||
puts "Please pass in your second life first name, last name, and password as arguments. | puts "Please pass in your second life first name, last name, and password as arguments." | ||
puts "ruby registration_api.rb joe linden 1234" | puts "For example: ruby registration_api.rb joe linden 1234" | ||
exit | exit | ||
end | end | ||
# 0 - Get Capability URLS | # 0 - Get Capability URLS ############################################## | ||
puts "========== Getting capabilities ===========\n" | puts "========== Getting capabilities ===========\n" | ||
post_body = "first_name=#{first_name}&last_name=#{last_name}&password=#{password}" # create a url-encoded string to POST | post_body = "first_name=#{first_name}&last_name=#{last_name}&password=#{password}" | ||
response_xml = LLSD.post_urlencoded_data get_capabilities_url, post_body # POST the capability url to get capabilities | # create a url-encoded string to POST | ||
response_xml = LLSD.post_urlencoded_data get_capabilities_url, post_body | |||
# POST the capability url to get capabilities | |||
puts "xml response:" # Print out response xml | puts "xml response:" # Print out response xml | ||
Line 63: | Line 68: | ||
capability_urls.each { |k,v| puts "#{k} => #{v}"} # print out capabilities | capability_urls.each { |k,v| puts "#{k} => #{v}"} # print out capabilities | ||
# 1 - Print out error codes | # 1 - Print out error codes ############################################## | ||
puts "\n\n========== Get Error Codes Example ===========\n" | puts "\n\n========== Get Error Codes Example ===========\n" | ||
if capability_urls['get_error_codes'] | if capability_urls['get_error_codes'] | ||
response_xml = LLSD.http_raw capability_urls['get_error_codes'] # GET the capability url for getting error codes | response_xml = LLSD.http_raw capability_urls['get_error_codes'] | ||
# GET the capability url for getting error codes | |||
puts "xml response:" # Print out response xml | puts "xml response:" # Print out response xml | ||
Line 74: | Line 80: | ||
error_codes = LLSD.parse(response_xml) # Parse the xml | error_codes = LLSD.parse(response_xml) # Parse the xml | ||
error_codes.each {|error| puts "#{error[0]} => #{error[1]}"} # print out all error codes | error_codes.each {|error| puts "#{error[0]} => #{error[1]}"} | ||
# print out all error codes | |||
else | else | ||
puts "Get_error_codes capability not granted to #{first_name} #{last_name}. | puts "Get_error_codes capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." | ||
end | end | ||
# 2 - Get Last Names Example ############################################## | |||
# 2 - Get Last Names Example | |||
puts "\n\n========== Get Last Names Example ===========\n" | puts "\n\n========== Get Last Names Example ===========\n" | ||
if capability_urls['get_last_names'] | if capability_urls['get_last_names'] | ||
response_xml = LLSD.http_raw capability_urls['get_last_names'] # GET the capability url for getting last names and ids | response_xml = LLSD.http_raw capability_urls['get_last_names'] | ||
# GET the capability url for getting last names and ids | |||
puts "xml response:" # Print out response xml | puts "xml response:" # Print out response xml | ||
Line 94: | Line 100: | ||
# 3 - Check Name Example | # 3 - Check Name Example ############################################## | ||
print "\n\n========== Check Name Example ===========\n" | print "\n\n========== Check Name Example ===========\n" | ||
if capability_urls['check_name'] | if capability_urls['check_name'] | ||
random_username = 'tester' + Kernel.rand(10000).to_s # Generate a random username | random_username = 'tester' + Kernel.rand(10000).to_s # Generate a random username | ||
valid_last_name_id = last_names.keys.first # Get the first valid last name id | valid_last_name_id = last_names.keys.first # Get the first valid last name id | ||
params_hash = {"username" => random_username, "last_name_id" => valid_last_name_id } # put it in a hash | params_hash = {"username" => random_username, "last_name_id" => valid_last_name_id } | ||
# put it in a hash | |||
xml_to_post = LLSD.to_xml(params_hash) # convert it to llsd xml | xml_to_post = LLSD.to_xml(params_hash) # convert it to llsd xml | ||
Line 115: | Line 122: | ||
puts "Result (is name available?): #{is_name_available}" # Print the result | puts "Result (is name available?): #{is_name_available}" # Print the result | ||
# 4 - Create User Example ############################################## | |||
# 4 - Create User Example | |||
puts "\n\n========== Create User Example ===========\n" | puts "\n\n========== Create User Example ===========\n" | ||
if is_name_available and capability_urls['create_user']: | if is_name_available and capability_urls['create_user']: | ||
Line 141: | Line 146: | ||
# ALL DONE!! | # ALL DONE!! | ||
else | else | ||
puts "Create_user capability not granted to #{first_name} #{last_name}. | puts "Create_user capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." | ||
end | end | ||
else | else | ||
puts "Check_name capability not granted to #{first_name} #{last_name}. | puts "Check_name capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." | ||
end | end | ||
else | else | ||
puts "Get_last_names capability not granted to #{first_name} #{last_name}. | puts "Get_last_names capability not granted to #{first_name} #{last_name}. Exiting Prematurely..." | ||
end | end</nowiki> | ||
</ | |||
=== Python === | === Python === | ||
< | <nowiki>import llsd | ||
import llsd | |||
import urllib2, random, sys | import urllib2, random, sys | ||
Line 174: | Line 177: | ||
else: | else: | ||
print "Please pass in your second life first name, last name, and password as arguments. For example:" | print "Please pass in your second life first name, last name, and password as arguments. For example:" | ||
print " | print "python registration_api.py registration mackay 1234" | ||
sys.exit() | sys.exit() | ||
Line 193: | Line 196: | ||
print "%s => %s" % (id, name) | print "%s => %s" % (id, name) | ||
# 1 - Print out error codes ############################################################### | # 1 - Print out error codes ############################################################### | ||
if | if 'get_error_codes' in capability_urls: | ||
print "\n\n========== Get Error Codes Example ===========\n" | print "\n\n========== Get Error Codes Example ===========\n" | ||
Line 213: | Line 214: | ||
# 2 - Get Last Names Example ############################################################## | # 2 - Get Last Names Example ############################################################## | ||
if | if 'get_last_names' in capability_urls: | ||
print "\n\n========== Get Last Names Example ===========" | print "\n\n========== Get Last Names Example ===========" | ||
Line 225: | Line 226: | ||
for id, name in last_names.items(): # Print out last names | for id, name in last_names.items(): # Print out last names | ||
print "%s => %s" % (id, name) | print "%s => %s" % (id, name) | ||
# 3 - Check Name Example ################################################################## | # 3 - Check Name Example ################################################################## | ||
if | if 'check_name' in capability_urls: | ||
print "\n\n========== Check Name Example ===========" | print "\n\n========== Check Name Example ===========" | ||
Line 251: | Line 250: | ||
print "Result (is name available?): %s" % (is_name_available) # Print the result | print "Result (is name available?): %s" % (is_name_available) # Print the result | ||
# 4 - Create User Example ################################################################# | # 4 - Create User Example ################################################################# | ||
if is_name_available and | if is_name_available and 'create_user' in capability_urls: | ||
print "\n\n========== Create User Example ===========" | print "\n\n========== Create User Example ===========" | ||
xml_to_post = llsd.toXML(params_hash) # convert it to llsd xml | xml_to_post = llsd.toXML(params_hash) # convert it to llsd xml | ||
Line 275: | Line 267: | ||
result_hash = llsd.parse(response_xml) # Parse the xml | result_hash = llsd.parse(response_xml) # Parse the xml | ||
print "New agent id: %s" % (result_hash["agent_id"]) | print "New agent id: %s" % (result_hash["agent_id"]) | ||
print "Finalize this user at: %s" % (result_hash["complete_reg_url"]) | |||
Line 286: | Line 279: | ||
else: | else: | ||
print "get_last_names capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name) | print "get_last_names capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name)</nowiki> | ||
</ | |||
=== PHP === | === PHP === | ||
NOTE: This uses PHP4. See also [[Registration_API#Guidelines_and_tips|Guidelines and tips]]. | |||
< | <nowiki><?php | ||
<?php | |||
require_once('llsd.php'); | require_once('llsd.php'); | ||
Line 309: | Line 300: | ||
'username' => $_POST['username'], | 'username' => $_POST['username'], | ||
'last_name_id' => (int)$_POST['last_name_id'], | 'last_name_id' => (int)$_POST['last_name_id'], | ||
); | ); | ||
$result = llsd_post(URI_CREATE_USER, $user); | $result = llsd_post(URI_CREATE_USER, $user); | ||
header( "Location: " . $result['complete_reg_url'] ); | |||
} | } | ||
else | else | ||
Line 346: | Line 334: | ||
</select> | </select> | ||
</td> | </td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
Line 433: | Line 388: | ||
return false; | return false; | ||
} | } | ||
?> | ?></nowiki> | ||
</ | |||
[[Category:RegAPI|Sample Code]] | [[Category:RegAPI|Sample Code]] | ||
[[Category:Web Service APIs]] | [[Category:Web Service APIs]] |
Latest revision as of 10:57, 26 October 2016
The following examples illustrate using the Reg API to register a new user with a specified Second Life first name and last name. The example code first checks to determine the availability of the selected first and last name, and either registers the user or returns an error message if the name is already taken.
LLSD library downloads
To use a library:
- Remove the -lib suffix from the file name.
- Put the file in the same directory as the application code, such as the examples below.
- Ruby LLSD library (version 1.3)
- PHP LLSD library (version 1.0)
- Python LLSD library (version 1.2)
- Perl LLSD library (version 1.0)
NOTE: The PHP scripts only work with PHP4.
An externally developed Java implementation of LLSD and RegAPI is available at http://mimuve.cs.st-andrews.ac.uk/llsd-java/src/llsd-java-0.2.1.zip . Code written by Xugu Madison, copyright held by University of St Andrews, and made available under the BSD license. Tested with Java 1.5.
Question: what version of each language is required?
Example code
Ruby
This ruby example shows how to use the Registration API.
require 'llsd' # 0 - get capability urls # 1 - get error codes # 2 - get the available last names # 3 - check to see of a username + last name combo is taken # 4 - register the user with this username + last name combo get_capabilities_url = "https://cap.secondlife.com/get_reg_capabilities" # grab command line args if ARGV.length == 3 first_name = ARGV[0] last_name = ARGV[1] password = ARGV[2] else puts "Please pass in your second life first name, last name, and password as arguments." puts "For example: ruby registration_api.rb joe linden 1234" exit end # 0 - Get Capability URLS ############################################## puts "========== Getting capabilities ===========\n" post_body = "first_name=#{first_name}&last_name=#{last_name}&password=#{password}" # create a url-encoded string to POST response_xml = LLSD.post_urlencoded_data get_capabilities_url, post_body # POST the capability url to get capabilities puts "xml response:" # Print out response xml puts response_xml puts "\n" capability_urls = LLSD.parse(response_xml) # Parse the xml capability_urls.each { |k,v| puts "#{k} => #{v}"} # print out capabilities # 1 - Print out error codes ############################################## puts "\n\n========== Get Error Codes Example ===========\n" if capability_urls['get_error_codes'] response_xml = LLSD.http_raw capability_urls['get_error_codes'] # GET the capability url for getting error codes puts "xml response:" # Print out response xml puts response_xml error_codes = LLSD.parse(response_xml) # Parse the xml error_codes.each {|error| puts "#{error[0]} => #{error[1]}"} # print out all error codes else puts "Get_error_codes capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." end # 2 - Get Last Names Example ############################################## puts "\n\n========== Get Last Names Example ===========\n" if capability_urls['get_last_names'] response_xml = LLSD.http_raw capability_urls['get_last_names'] # GET the capability url for getting last names and ids puts "xml response:" # Print out response xml puts response_xml last_names = LLSD.parse(response_xml) # Parse the xml last_names.each {|k,v| puts "#{k} => #{v}"} # print out last names # 3 - Check Name Example ############################################## print "\n\n========== Check Name Example ===========\n" if capability_urls['check_name'] random_username = 'tester' + Kernel.rand(10000).to_s # Generate a random username valid_last_name_id = last_names.keys.first # Get the first valid last name id params_hash = {"username" => random_username, "last_name_id" => valid_last_name_id } # put it in a hash xml_to_post = LLSD.to_xml(params_hash) # convert it to llsd xml response_xml = LLSD.post_xml(capability_urls['check_name'], xml_to_post) puts "posted xml:" # Print out response xml puts xml_to_post puts "xml response:" # Print out response xml puts response_xml is_name_available = LLSD.parse(response_xml) # Parse the xml puts "Result (is name available?): #{is_name_available}" # Print the result # 4 - Create User Example ############################################## puts "\n\n========== Create User Example ===========\n" if is_name_available and capability_urls['create_user']: # fill in the rest of the hash we started in example 2 with valid data params_hash["email"] = random_username + "@ben.com" params_hash["password"] = "123123abc" params_hash["dob"] = "1980-01-01" xml_to_post = LLSD.to_xml(params_hash) # convert it to llsd xml response_xml = LLSD.post_xml(capability_urls['create_user'], xml_to_post) puts "posted xml:" # Print out response xml puts xml_to_post puts "xml response:" # Print out response xml puts response_xml result_hash = LLSD.parse(response_xml) # Parse the xml puts "New agent id: #{result_hash['agent_id']}" # Print the result # ALL DONE!! else puts "Create_user capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." end else puts "Check_name capability not granted to #{first_name} #{last_name}. Exiting Prematurely ..." end else puts "Get_last_names capability not granted to #{first_name} #{last_name}. Exiting Prematurely..." end
Python
import llsd import urllib2, random, sys # This python example shows how to use the Registration API. The example goes as follows: # 0 - get capability urls # 1 - get error codes # 2 - get the available last names # 3 - check to see of a username + last name combo is taken # 4 - register the user with this username + last name combo get_capabilities_url = "https://cap.secondlife.com/get_reg_capabilities" # grab command line args if len(sys.argv) == 4: first_name = sys.argv[1] last_name = sys.argv[2] password = sys.argv[3] else: print "Please pass in your second life first name, last name, and password as arguments. For example:" print "python registration_api.py registration mackay 1234" sys.exit() # 0 - Get Capability URLS ################################################################# print "========== Getting capabilities ===========" post_body = "first_name=%s&last_name=%s&password=%s" % (first_name, last_name, password) # create a url-encoded string to POST response_xml = urllib2.urlopen(get_capabilities_url, post_body).read() # POST the capability url to get capabilities print "xml response:" # Print out response xml print response_xml capability_urls = llsd.parse(response_xml) # Parse the xml for id, name in capability_urls.items(): # Print out capabilities print "%s => %s" % (id, name) # 1 - Print out error codes ############################################################### if 'get_error_codes' in capability_urls: print "\n\n========== Get Error Codes Example ===========\n" response_xml = urllib2.urlopen(capability_urls['get_error_codes']).read() # GET the capability url for getting error codes print "xml response:" # Print out response xml print response_xml error_codes = llsd.parse(response_xml) # Parse the xml for error in error_codes: # Print out capabilities print "%s => %s" % (error[0], error[1]) else: print "Get_error_codes capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name) # 2 - Get Last Names Example ############################################################## if 'get_last_names' in capability_urls: print "\n\n========== Get Last Names Example ===========" response_xml = urllib2.urlopen(capability_urls['get_last_names']).read() # GET the capability url for getting last names and ids print "xml response:" # Print out response xml print response_xml last_names = llsd.parse(response_xml) # Parse the xml for id, name in last_names.items(): # Print out last names print "%s => %s" % (id, name) # 3 - Check Name Example ################################################################## if 'check_name' in capability_urls: print "\n\n========== Check Name Example ===========" random_username = 'benny' + str(random.randrange(100,10000)) # Generate a random username valid_last_name_id = last_names.keys()[0] # Get the first valid last name id params_hash = {"username": random_username, "last_name_id": valid_last_name_id } # put it in a hash xml_to_post = llsd.toXML(params_hash) # convert it to llsd xml response_xml = urllib2.urlopen(capability_urls['check_name'], xml_to_post).read() print "posted xml " # Print out response xml print xml_to_post print "xml response:" # Print out response xml print response_xml is_name_available = llsd.parse(response_xml) # Parse the xml print "Result (is name available?): %s" % (is_name_available) # Print the result # 4 - Create User Example ################################################################# if is_name_available and 'create_user' in capability_urls: print "\n\n========== Create User Example ===========" xml_to_post = llsd.toXML(params_hash) # convert it to llsd xml response_xml = urllib2.urlopen(capability_urls['create_user'], xml_to_post).read() print "posted xml " # Print out response xml print xml_to_post print "xml response:" # Print out response xml print response_xml result_hash = llsd.parse(response_xml) # Parse the xml print "New agent id: %s" % (result_hash["agent_id"]) print "Finalize this user at: %s" % (result_hash["complete_reg_url"]) # ALL DONE!! else: print "create_user capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name) else: print "check_name capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name) else: print "get_last_names capability not granted to %s %s. Now Exiting Prematurely ..." % (first_name, last_name)
PHP
NOTE: This uses PHP4. See also Guidelines and tips.
<?php require_once('llsd.php'); // FILL THESE IN WITH YOUR OWN CAPABILITY URLS define('URI_CREATE_USER', '?????????'); define('URI_GET_LAST_NAMES', '?????????'); define('URI_CHECK_NAME', '?????????'); if ($_SERVER['REQUEST_METHOD'] == 'POST') { if (is_name_available($_POST['username'], $_POST['last_name_id'])) { $user = array ( 'username' => $_POST['username'], 'last_name_id' => (int)$_POST['last_name_id'], ); $result = llsd_post(URI_CREATE_USER, $user); header( "Location: " . $result['complete_reg_url'] ); } else { print 'SL name not available.'; } } ?> <h3>Create Second Life Account</h3> <form action="<?php print $_SERVER['PHP_SELF']; ?>" method="post"> <table border="0" cellpadding="3" cellspacing="0"> <tr> <td>First name:</td> <td><input type="text" name="username" size="25" maxlength="31" value="" /></td> </tr> <tr> <td>Last name:</td> <td> <select name="last_name_id"> <?php $last_names = llsd_get(URI_GET_LAST_NAMES); foreach ($last_names as $last_name_id => $name) { print '<option value="'.$last_name_id.'">'.$name.'</option>'; } ?> </select> </td> </tr> <tr> <td></td> <td><input type="submit" value="Create SL Account" /></td> </table> </form> <?php function get_months() { $months = array(); for ($i = 1; $i <= 12; $i++) { $key = date('n', mktime(0, 0, 0, $i, 1, 2000)); $value = date('M.', mktime(0, 0, 0, $i, 1, 2000)); $months[sprintf("%02d", $key)] = $value; } return $months; } function get_years() { $today = getdate(); $max_year = $today['year'] - 90; $min_year = $today['year'] - 13; $years = array(); for ($i = $min_year; $i >= $max_year; $i--) { $years[$i] = $i; } return $years; } function get_days() { $days = array(); for ($i = 1; $i <= 31; $i++) { $days[sprintf("%02d", $i)] = sprintf("%02d", $i); } return $days; } function is_name_available($username, $last_name_id) { $params = array('username' => $username, 'last_name_id' => (int)$last_name_id); if (llsd_post(URI_CHECK_NAME, $params) == 'true') { return true; } return false; } ?>