LoCI logo
Home
About Us
Projects
Publications
Software
Documents
Screencasts
Related Projects
Related Pubs

People
FAQs
News Archive
Contact Us


Links

IBPvo
Record your favorite show on TV!
Linux ISOs
Download the latest version of Linux!
 
 



 
Overview Publications Software

L-Bone API


This page outlines the usage of the L-Bone client api. It describes the data structures, functions and where to find L-Bone servers.

Data Structures

L-Bone re-uses the ibp_depot struct (char host[256] and int port) and defines Depot to be equivalent to the IBP_depot pointer for simpler code.

The L-Bone user's primary data structure is the LBONE_request:

typedef struct {

int numDepots;
unsigned long stableSize;
unsigned long volatileSize;
double duration;
char *location;

} LBONE_request;

The LBONE_request struct holds the info passed to the server outlining the client's search criteria.

numDepots is the maximum number of depots to return. It may return fewer depots if not enough depots matched the request. If you want to receive all the listed depots, you may specify ALL_DEPOTS.

stableSize and volatileSize indicate the minimum amount in megabytes of each needed to be included in the returned array. If both are non-zero numbers, then the search is an AND. If either is a zero value, it searches for the non-zero class of storage only.

duration is the minimum number of days that the user will need the space. This must be >= zero. It is a double so that you can specify partial day amounts. For example, if you only need storage for six hours, then you would specify a duration of 0.25.

location allows the user to enter keyword and value pairs to determine where they want storage and minimum environmental criteria. The user may specify as many or as few keyword/value pairs as the user wants. The keyword/value pairs can be in any order. They may even leave the pointer equal to NULL if location and environment are unimportant. If any location keywords are used, the server will then use an algorithm to determine latitude and longitude.

For US searches, the user can specify one or more of the following:

hostname= [AAA...AAA.]AAA...AAA.AAA

The hostname= keyword accepts any valid hostname.

zip= 00000

The zip= keyword requires a valid 5-digit US zipcode only.

state= AA

The state= keyword requires a valid 2-letter state code (postal code)

city= AAAAA [AAAA ....] (requires state=)

The city= keyword accepts space delimited words and must be used with state=.

country= US

The country= US location is very vague and will give poor results.

airport= AAA

The airport= keyword requires a 3-letter airport (IATA) code

For international searches, the user can specify one or more of the following:

city= AAAAA [AAAA ....] (requires country=)

The city= keyword accepts space delimited words.

country= AA

The country= keyword requires a valid 2-letter iso country code.

airport= AAA

The airport= keyword requires a 3-letter airport (IATA) code.

Location Search Algorithm

The server has access to a database of 30,000 US zipcode/city/state entries, 2,000 US airports and 6,000 international airports. Currently, international city and country lookups are done with the airport list. All entries specify lat/lon coordinates.

If multiple keyword/value pairs are given, the server uses the following algorithm to try to determine the best location:

For US searches:

1. Search for zipcode - it is the most accurate

Is it a valid number? Must be between 01001 and 99999.
If not found, decrement by 1. Repeat until found.
When found, get lat/lon.
No other searches are performed.

2. Search for airport - not as accurate as city, but more reliable results (airport codes are unique while many cities share the same name)

Is it 3 characters?
Search airports database.
If found, get lat/lon.
If not found, go to city/state search.

3. Search for city and state

Is the state 2 letters?
Search US zipcode database.
If found, get lat/lon.
If not found, go to state search.

4. Search for state only

Is the state 2 letters?
Search US zipcode database.
If found, get lat/lon.
If not found, return depots closest to UT.

For non-US searches:

1. Search for airport - not as accurate as city, but more reliable results

Is it 3 characters?
Search airports database.
If found, get lat/lon.
If not found, go to city/country search.

2. Search for city and country

Is the country 2 letters?
Search airports database.
If found, get lat/lon.
If not found, go to country search.

3. Search for country only

Is the country 2 letters?
Search airports database.
If found, get lat/lon.
If not found, return depots closest to UT.

Once the location's latitude and longitude are determined, the server then caluclates the distance based on the Haversine Formula.

dlon = lon2 - lon1
dlat = lat2 - lat1
a = (sin(dlat/2))^2 + cos(lat1) * cos(lat2) * (sin(dlon/2))^2
c = 2 * arcsin(min(1,sqrt(a)))
d = R * c where R is 3956 miles, and lat and lon are first converted from decimal values to radians.

To convert decimal degrees to radians, multiply the number of degrees by pi/180 = 0.017453293 radians/degree.

The environmental keywords allow you specify the minimum class of service for the depots that you want to use.

The keywords and their options are:

connection= What type of connection to the Internet?

connection= [ ISDN/56K | Cable/DSL | T1 | T3 ]

monitoring= When is someone available to monitor this machine?

monitoring= [ Occasional | 9-5 | 24-7 ]

power= How long can this machine run if the primary power fails?

power= [ Minutes | Hours | Generator ]

backup= What is the backup policy for depot data stored on this machine?

backup= [ Occasional | Daily-Single Copy | Daily-Multiple Copies ]

firewall= Does it have one?

firewall= [ no | yes ]

The options increase in "value" from left to right. The options match their own value and all values to their right. For example, if you specify "power= Minutes" then all depots with power equal to Minutes, Hours and Generator will be returned. If you specify "power= Hours", then only depots with a power option of Hours or Generator will be returned.

The default values return all depots (each option assumes the lowest value).

Please note that all searches are currently case sensitive.

Functions

Depot *lbone_getDepots(Depot lboneServer, LBONE_request req, int timeout);

This is the primary function. It passes the lbone server info and the search criteria. It returns NULL on failure or a null-terminated array of Depots (IBP_depots) on success. It accepts a timeout value of seconds to wait before returning NULL. A timeout of 0 seconds will block indefinitely.

The server checks the request against cached data about the IBP depots. The depot array returned by this call meets the request according to the cached data. These depots, however, may not be currently active or their capacities may have dropped since the last update.

Depot *lbone_checkDepots(Depot *depots, LBONE_request, int timeout);

This function accepts the list returned by the lbone_getDepots() call. It then spawns a thread for each depot in the array and makes an IBP_status() call. It determines which depots are currently reachable and which ones still meet the request criteria.

Depot *lbone_sortByBandwidth(Depot *depots, int timeout);

This function accepts the list returned by the lbone_checkDepots() call. It then spawns a thread for each depot in the array and makes a nws_ping() call. It measures the bandwidth to each depot and sorts them from highest to lowest. If the depot's nws sensor is not available or no measurment is taken, it is assigned a bandwidth of zero and put at the end of the list.

int lbone_depotCount(ulong_t *totalDepots, ulong_t *liveDepots, Depot lboneServer, int timeout);

This function takes pointers to totalDepots and liveDepots and fills them in with the number of listed depots in the LBone and how many replied to the last IBP_status() call. It returns a 0 on success, a negative error number otherwise. Find error values in lbone_base.h.

int lbone_getProximity(Depot lbone_server, char *location, char *filename, int timeout);

This function sends a location string to the server. The server returns an alpha sorted list of depots and their proximity measures where the higher the value is "closer". The list is then stored in the file specified by filename. It returns 0 on success, a negative error number otherwise. Find error values in lbone_base.h.

L-Bone Servers

Currently, the L-Bone server is running on vertex.cs.utk.edu on port 6767.

UTK home        DOE NSF
 
corner
Home   About Us   Projects   Publications   Software   Docs   Screencasts   Related Projects   Related Pubs   People   FAQs   News  Contact Us
corner