Proposed OILv2 XML Schema

General

OILv2 transactions are ordered as a single query followed by a single response. A login query must be the first transaction of an OILv2 session, as it identifies the target user. Use of a session ID allows an OILv2 session to persist across connections for a limited amount of time, however its use is optional.

A query consists of an XML block containing a header with protocol version, and operation information, and an optional data section containing the specific arguments.

A response consists of an XML block containing a header with protocol version, operation, and success information. The success value may be either true or false, and if false error information may also be included in the header. An optional data section follows, containing the result attributes.

Login

Query

A login query is required to start an OILv2 session or to continue an OILv2 session from a previous connection. Two attributes must be passed:

authmethod: This may be either wind or oilsession.
authtoken: This may be either a ticket ID for authmethod wind or a session ID for authmethod oilsession.

Login Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>login</operation>
     </header>
     <payload>
       <authmethod>wind</authmethod>
       <authtoken>nM8m234neEU23euH7TH239T</authtoken>
     </payload>
   </cheneyRequest>
 </XML>

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>login</operation>
     </header>
     <payload>
       <authmethod>oilsession</authmethod>
       <authtoken>4572104563476596</authtoken>
     </payload>
   </cheneyRequest>
 </XML>

Response

A login response will return true if the provided authmethod and authtoken are valid. The following attributes may be returned:

username: On successful login, this will contain the name of the user authenticated.
sessionid: On successful login using authmethod wind, this will be a session ID that may be used for repeated login auth queries until the session ID expires.

Login Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>login</operation>
       <success>true</success>
     </header>
     <payload>
       <username>joeuser</username>
       <sessionid>4572104563476596</sessionid>
     </payload>
   </cheneyResponse>
 </XML>
 
 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>login</operation>
       <success>false</success>
       <error>Permission denied</error>
     </header>
   </cheneyResponse>
 </XML>

GetTransactionToken

Query

A gettranscationtoken query retrieves an opaque token that may be used to prevent the resubmission of a request. No attributes are expected.

GetTransactionToken Query Example

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>gettransactiontoken</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A gettransactiontoken response will return true if a transaction token has been successfully allocated. The following attribute may be returned:

transactiontoken: The token that may be used one time only.

GetTransactionToken Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>gettransactiontoken</operation>
       <success>true</success>
     </header>
     <payload>
       <transactiontoken>9462957306720173</transactiontoken>
     </payload>
   </cheneyResponse>
 </XML>

Validation

There is no explicit query to validate a transaction token. Instead, the token is passed to any other Get or Set operation. If the token is valid, the request will be processed. It the token is invalid, an appropriate error will be returned. If no token is provided, no validation will occur.

Validation Example (using SetForward)

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>setforward</operation>
       <transactiontoken>9462957306720173</transactiontoken>
     </header>
     <payload>
       <destination>joeuser@nowhere.org</destination>
     </payload>
   </cheneyRequest>
 </XML>

Logout

Query

A logout query expires an OILv2 session. Use of this query is required to expire a session ID. Two attributes must be passed:

authmethod: This must be oilsession.
authtoken: This must be the session ID returned by a login auth query.

Logout Query Example

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>logout</operation>
     </header>
     <payload>
       <authmethod>oilsession</authmethod>
       <authtoken>4572104563476596</authtoken>
     </payload>
   </cheneyRequest>
 </XML>

Response

A logout response will return true if the provided session ID has been successfully expired. No attributes are returned.

Logout Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>logout</operation>
       <success>true</success>
     </header>
   </cheneyResponse>
 </XML>

GetForward

Query

A getforward query obtains the forwarding information for the current user. No arguments are accepted.

GetForward Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>getforward</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A getforward response will return true if the forward status for the user was successfully obtained. The following attribute may be returned:

destination: The destination of the forward address. All characters between the open and close tags are significant.

GetForward Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>getforward</operation>
       <success>true</success>
     </header>
     <payload>
       <destination>joeuser@nowhere.org</destination>
     </payload>
   </cheneyResponse>
 </XML>

SetForward

Query

A setforward query sets the forwarding information for the current user. The following argument is accepted:

destination: The destination of the forward address. All characters between the open and close tags are significant. The server will perform validation of the address before accepting it. Omitting this argument indicates that forwarding should be disabled.

SetForward Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>setforward</operation>
     </header>
     <payload>
       <destination>joeuser@nowhere.org</destination>
     </payload>
   </cheneyRequest>
 </XML>

Response

A setforward response will return true if the destination address provided was accepted and stored successfully. No attributes are returned.

SetForward Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>setforward</operation>
       <success>false</success>
       <error>Invalid destination address</error>
     </header>
   </cheneyResponse>
 </XML>

GetVacation

Query

A getvacation query determines if the current user has vacation enabled. No arguments are accepted.

GetVacation Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>getvacation</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A getvacation response will return true if the current vacation status has been obtained. The following attributes may be returned:

message: The contents of the vacation message. All characters between the open and close tags are significant.
status: true if vacation is enabled, false otherwise.

GetVacation Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>getvacation</operation>
       <success>true</success>
     </header>
     <payload>
       <status>true</status>
       <message>From: No Body <nobody@columbia.edu>
Subject: Out of the office.

I am currently out of the office.  I will return on December 5th
and will respond to your message when I return.
</message>
     </payload>
   </cheneyResponse>
 </XML>

SetVacation

A setvacation query sets the vacation status for the current user. The following arguments are accepted:

message: The destination contents of the vacation message. All characters between the open and close tags are significant. If this argument is omitted, any existing vacation message will remain. If this argument is omitted, no previous message exists, and status is set to true, the request will fail.
status: true to enable vacation, false to disable vacation.

SetVacation Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>setvacation</operation>
     </header>
     <payload>
       <status>true<status>
       <message>From: No Body <nobody@columbia.edu>
Subject: Out of the office.

I am currently out of the office.  I will return on December 5th
and will respond to your message when I return.
</message>
     </payload>
   </cheneyRequest>
 </XML>

Response

A setvacation response will return true if the vacation update was processed successfully. No attributes are returned.

SetVacation Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>setvacation</operation>
       <success>true</success>
     </header>
   </cheneyResponse>
 </XML>

GetQuota

Query

A getquota query obtains the quota information for the current user. No arguments are accepted.

GetQuota Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>getquota</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A getquota response will return true if the quota information for the user was successfully obtained. Multiple quota attributes may be returned, each of which may contain the following subattributes:

filesystem: The name of the filesystem.
hardquota: The hard quota, in bytes.
usage: The usage, in bytes.

GetQuota Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>getquota</operation>
       <success>true</success>
     </header>
     <payload>
       <quota>
         <filesystem>/home1</filesystem>
	 <hardquota>20000000</hardquota>
	 <usage>4544120</usage>
       </quota>
       <quota>
         <filesystem>/home2</filesystem>
	 <hardquota>20000000</hardquota>
	 <usage>0</usage>
       </quota>
       <quota>
         <filesystem>/mail</filesystem>
	 <hardquota>10000000</hardquota>
	 <usage>673308</usage>
       </quota>
     </payload>
   </cheneyResponse>
 </XML>

MailFrom

Query

A mailfrom query obtains the header information from any messages in the current user's incoming mail spool. No arguments are accepted.

MailFrom Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>mailfrom</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A mailfrom response will return true if the user's incoming mail spool was successfully parsed. Multiple message attributes may be returned, each of which may contain the following subattributes:

date: The date of the message.
from: The from address of the message.
size: The size of the message in bytes.
subject: The subject of the message.

MailFrom Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>mailfrom</operation>
       <success>true</success>
     </header>
     <payload>
       <message>
         <date>Sun Nov  3 16:02:41 2002</date>
	 <from>J User <juser@columbia.edu></from>
	 <size>1297</size>
	 <subject>Dinner?</subject>
       </message>
     </payload>
   </cheneyResponse>
 </XML>

MailFolders

Query

A mailfolders query obtains the names and sizes of mail folders in the current user's ~/mail directory. No arguments are accepted. The special mailbox INBOX refers to ~/mbox. The special mailbox SPOOL refers to $MAIL.

MailFolders Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>mailfolders</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A mailfolders response will return true if the user's mail directory was successfully read. Multiple folder attributes may be returned, each of which may contain the following subattributes:

relpath: The relative path to the folder, under ~/mail.
size: The size of the folder in bytes.

MailFolders Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>mailfolders</operation>
       <success>true</success>
     </header>
     <payload>
       <folder>
         <relpath>INBOX</relpath>
         <size>1045423</size>
       </folder>
       <folder>
         <relpath>saved-mail</relpath>
         <size>526098</size>
       </folder>
       <folder>
         <relpath>sent-mail</relpath>
         <size>453022</size>
       </folder>
     </payload>
   </cheneyResponse>
 </XML>

MailMessages

Query

A mailmessags query obtains the header information from any messages in the requested mail folder. The following argument is accepted:

relpath: The relative path under ~/mail to the requested folder, or INBOX to denote ~/mbox, or SPOOL to denote $MAIL.

MailMessages Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>mailmessages</operation>
     </header>
     <payload>
       <relpath>saved-mail</relpath>
     </payload>
   </cheneyRequest>
 </XML>

Response

A mailmessages response will return true if the requested mail folder was successfully parsed. Multiple message attributes may be returned, each of which may contain the following subattributes:

date: The date of the message.
from: The from address of the message.
size: The size of the message in bytes.
spamscore: The SpamAssassin score for the message.
subject: The subject of the message.

MailMessages Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>mailmessages</operation>
       <success>true</success>
     </header>
     <payload>
       <message>
         <date>Sun Nov  3 16:02:41 2002</date>
	 <from>J User <juser@columbia.edu></from>
	 <size>1297</size>
	 <spamscore>1.5</spamscore>
	 <subject>Dinner?</subject>
       </message>
     </payload>
   </cheneyResponse>
 </XML>

GetMailFilters

Separate queries may subsequently be introduced for activating system-wide spam filtration.

Query

A getmailfilters query obtains the current set of mail filters for the current user, if any. No arguments are accepted.

GetMailFilters Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>getmailfilters</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A getmailfilters response will return true if the mail filters for the current user were successfully obtained. Multiple filter attributes may be returned, each of which may contain the following subattributes:

header: Any valid mail header. The special header TO automatically implies Cc, etc.
criteria: contains, equals
regexp: Regular expression to compare against.
operation: delete, move, forward.
folder: For move operation, relative path under ~ to file the message under. (Explicit reference to the mail directory, eg mail/inbox-2, must be made.)
destination: For forward operation, address to resend the message to.

GetMailFilters Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>getmailfilters</operation>
       <success>true</success>
     </header>
     <payload>
       <filter>
         <header>From</header>
         <criteria>contains</criteria>
         <regexp>myex@hotmail.com</regexp>
         <operation>forward</operation>
         <destination>news@cnn.com</destination>
       </filter>
       <filter>
         <header>Subject</header>
         <criteria>contains</criteria>
         <regexp>meeting</regexp>
         <operation>delete</operation>
       </filter>
     </payload>
   </cheneyResponse>
 </XML>

setmailfilters

Query

A setmailfilters query sets the mail filters for the current user. Multiple filter arguments are accepted, each of which may contain the following subarguments:

header: Any valid mail header. The special header TO automatically implies Cc, etc.
criteria: contains, equalso,
regexp: Regular expression to compare against.
operation: delete, move, forward.
folder: For move operation, relative path under ~ to file the message under. (Explicit reference to the mail directory, eg mail/inbox-2, must be made.)
destination: For forward operation, address to resend the message to.

SetMailFilter Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>setmailfilters</operation>
       <success>true</success>
     </header>
     <payload>
       <filter>
         <header>From</header>
         <criteria>contains</criteria>
         <regexp>myex@hotmail.com</regexp>
         <operation>forward</operation>
         <destination>news@cnn.com</destination>
       </filter>
       <filter>
         <header>Subject</header>
         <criteria>contains</criteria>
         <regexp>meeting</regexp>
         <operation>delete</operation>
       </filter>
     </payload>
   </cheneyRequest>
 </XML>

Response

A setmailfilters response will return true if the mail filter update was processed successfully. No attributes are returned.

SetMailFilters Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>setmailfilters</operation>
       <success>true</success>
     </header>
   </cheneyResponse>
 </XML>

SnapshotCandidates

Query

A snapshotcandidates query determines what backup copies of a file, if any, are available for the current user. The following argument is accepted:

relpath: The relative path of the file, under ~.

SnapshotCandidates Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>snapshotcandidates</operation>
     </header>
     <payload>
       <relpath>mail/sent-mail</relpath>
     </payload>
   </cheneyRequest>
 </XML>

Response

A snapshotcandidates response will return true if the candidate snapshots for the requested file were successfully obtained. Multiple snapshot attributes may be returned, each of which may contain the following subattributes:

id: The ID of the snapshot.
date: The last modified time of the snapshot file.
size: The size of the snapshot file, in bytes.

SnapshotCandidates Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>snapshotcandidates</operation>
       <success>true</success>
     </header>
     <payload>
       <snapshot>
         <id>hourly.0</id>
	 <date>Sun Nov  3 16:50:00 2002</date>
	 <size>16384</size>
       </snapshot>
       <snapshot>
         <id>hourly.1</id>
	 <date>Sun Nov  3 14:50:00 2002</date>
	 <size>288</size>
       </snapshot>
     </payload>
   </cheneyResponse>
 </XML>

SnapshotRestore

Query

A snapshotrestore query attempts to retrieve a backup copy of the requested file. The following arguments are accepted:

relpath: The relative path of the file, under ~.
snapshot: The ID of the snapshot to retrieve from.

SnapshotRestore Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>snapshotrestore</operation>
     </header>
     <payload>
       <relpath>mail/sent-mail</relpath>
       <id>hourly.1</id>
     </payload>
   </cheneyRequest>
 </XML>

Response

A snapshotrestore response will return true if the requested restoral was successful. The following attribute may be returned:

relpath: The relative path of the restored file.

SnapshotRestore Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>snapshotrestore</operation>
       <success>true</success>
     </header>
     <payload>
       <relpath>mail/sent-mail.restored-1</relpath>
     </payload>
   </cheneyResponse>
 </XML>

GetPages

Query

A getpages query obtains the page quota information for the current user. No arguments are accepted.

GetPages Query Examples

 <XML>
   <cheneyRequest>
     <header>
       <version>2</version>
       <operation>getpages</operation>
     </header>
   </cheneyRequest>
 </XML>

Response

A getpages response will return true if the page quota information for the current user was successfully obtained. The following attributes may be returned:

quota: Weekly page quota.
paid: Paid pages.
total: Total pages.

GetPages Response Examples

 <XML>
   <cheneyResponse>
     <header>
       <version>2</version>
       <operation>getpages</operation>
       <success>true</success>
     </header>
     <payload>
       <quota>100</quota>
       <paid>20</paid>
       <total>120</total>
     </payload>
   </cheneyResponse>
 </XML>