PersonalDB - SOAP API

Home
Users
Developers
Viewer

Introduction

A grammer describing this SOAP service is fully described in the WSDL file and the schema file.

createUser

Summary: This method is used to create a new user account on the PersonalDB server.

Remarks: When called, this method checks that the username is unique. If the username is unique, then a database is created and the username and password are entered in a separate database that the server maintains for storing user account information.

Note that a server's administrator can configure this method. This may mean that creating new users on the server is completely unsupported. For example, the PersonalDB may disallow local user creation and instead tie user identification to the operating system, LDAP, or some other method.

Return: None.

Parameters:

username	xsd::string	The name that will identify the new user account. By default, usernames consist of only alphanumeric characters plus the underscore, and are limited to 63 characters in length. However, particular PersonalDB servers may enforce additional conditions. For example, to make usernames compatible with usernames used by the operating system, LDAP, or other configuration system.
password	xsd::string	The password for the user account. By default, the only requirement is that the password contain at least one character. However, like the username, particular PersonalDB servers may impose additional requirements.

deleteUser

Summary: This method is used to delete an existing user account on the PersonalDB server.

Remarks: When called, this method checks that the password is valid, and if so deletes the user's data and removes the user account.

Note that a server's administrator can configure this method. This may mean that deleting user accounts on the server is completely unsupported. For example, the PersonalDB may disallow local user management and instead tie user identification is tied to the operating system, LDAP, or other method.

Parameters:

username	xsd::string	The name that identifies the new user account.
password	xsd::string	The password for the user account.

login

Summary: This method validates the password and returns a token that can be used to access the database.

Remarks: When called, this method verifies the username and then validates the password. If valid, the user's database is opened, and a token is returned. The token is necessary to access most PersonalDB methods.

Return: A string (xsd::string) containing a token that can be used to access most PersonalDB methods. The token string contains only hexadecimal characters.

Parameters:

username	xsd::string	The name that identifies the new user account.
password	xsd::string	The password for the user account.

logout

Summary: This method invalidates the token so that it can no longer be used to access PersonalDB methods.

Remarks: When called, the token is verified by PersonalDB, and the user's session is accessed. The database and the session are then closed, invalidating the token.

Return: None.

Parameters:

token

xsd::string

The token to be invalidated.

logoutAsync

Summary: This method invalidates the token so that it can no longer be used to access PersonalDB methods.

Remarks: This method performs the exact sequence of operations that the method 'logout' performs. The only difference is the SOAP convention for this method specifies an asynchronous call. By convention, the SOAP client does not wait for a response from the PersonalDB server.

This function can be used when one is not concerned about possible failure. Since the client does not wait for a response from the PersonalDB server, it should execute significantly faster then a synchronous call.

Return: None.

Parameters:

token

xsd::string

The token to be invalidated.

execute

Summary: This method executes an SQL statement against the user's database.

Remarks: The first parameter to this method, a token, is validated and then used to look-up the user's database, which should have been opened using a call to the method login.

Once the SQL database has been retrieved, the method start parsing and executing the SQL statements. Each SQL statement is execute in turn. If any statement contains an error, parsing and execution of the SQL statements stops.

The rows from the last SQL statement in the list of statements passed to the method is returned from the method, provided no prior SQL statement in the same call to execute resulted in an error.

Return: personaldb::executeResponse

lastInsertRowid	xsd::int	The ID of the last row inserted into the database. This applies to the last INSERT SQL statement.
rowsChanged	xsd::int	The number rows that were inserted, deleted, or modified on the last SQL statement. Note that due to the implementation of SQLite, this value may not be accurate. Refer to the SQLite documentation.
fieldName	xsd::string[]	This is an array of strings containing the names of the fields for the rowset that resulted from the last SQL statement passed to execute.
row	personaldb::rowResponse	An array of of rowResponse structures representing the rowset that resulted from the last SQL statement passed to execute. Each rowReponse contains an array of string (xsd::string) that contain the field values.

Parameters:

token	xsd::string	A valid token obtained from a call to the method `login`.
sql	xsd::string	A list of SQL statements separated by semicolons;

executeAsync

Summary: This method executes an SQL statement against the user's database.

Remarks: The method executeAsync behaves very similarly to the method execute. The main difference is this funciton is meant to be called asynchronously. As such, any rowsets that might be returned by the SQL statements cannot be retrieved. However, this function does have the advantage of being quicker then a synchronous call to excute, as the client does not need to wait for a response from the PersonalDB server.

Return: None.

Parameters:

token	xsd::string	A valid token obtained from a call to the method `login`.
sql	xsd::string	A list of sql statements separated by semicolons.

executeBackup

Summary:

Remarks:

Return: A string (xsd::string) containing an XML document that stores the results of the database.

Parameters:

token

xsd::string

A valid token obtained from a call to login.

createSchema

Summary:

Remarks:

Return: None.

Parameters:

token	xsd::string	A valid token obtained from a call to login.
name	xsd::string	The name of a schema. Standard schema are identified by UUIDs, which are described in the standard schema documentation. Custom implementations may add additional schema, which are not necessarily identified by UUIDs.

deleteProperty

Summary:

Remarks:

Return: None.

Parameters:

token	xsd::string	A valid token obtained from a call to login.
name	xsd::string	A name indicating a property stored in the table database_properties.

getProperty

Summary:

Remarks:

Return: A string (xsd::string) with the property's value.

Parameters:

token	xsd::string	A valid token obtained from a call to login.
name	xsd::string	A name indicating a property stored in the table database_properties.

getProperties

Summary:

Remarks:

Return: A personaldb::executeResponse containing the property values. Please refer to the documentation for execute for more information.

Parameters:

token	xsd::string	A valid token obtained from a call to login.
name	xsd::string	A list of property names.

setProperty

Summary:

Remarks:

Return: A personaldb::executeResponse containing the property values. Please refer to the documentation for execute for more information.

Parameters:

token	xsd::string	A valid token obtained from a call to login.
name	xsd::string	A property name.
value	xsd::string	The property value..

A web services application that provides an SQL database for each user. Users thus have a datastore that can be located similar to an e-mail address (user@mycompany.com).

This data store can be used to store contact lists, memos, and to-do lists in a manner accessible throughout the internet. The format for standard data is specified, so that multiple viewers are possible.

Webmaster: Robert W. Johnstone