/* $Id: queues.x 258 2004-05-25 16:49:11Z gerd $ * ---------------------------------------------------------------------- * */ /**********************************************************************/ /* Data structures */ /**********************************************************************/ typedef string netname<255>; /* A network-wide user name */ typedef string queuename<30>; /* The name of a queue is a string of up to 30 bytes */ typedef opaque qid<>; /* The queue identifier is an opaque string */ struct queueparam { int qmaxlen; /* Maximum length of the queue. Negative means infinite. * Currently picked entries count. */ bool qactive; /* Whether the queue is active */ bool qaccepting; /* The queue accepts new entries */ bool qdelivering; /* The queue delivers entries */ /* Difference qactive/qaccepting/qdelivering: * - An inactive queue indicates the error INACTIVE if somebody tries to * pick an entry or tries to upload an entry. The other operations * (list entries, delete entries) are possible. * - Active queues can be stopped. The operations "pick" and "upload" * do not fail, but they wait until the queue is started again. * By setting qaccepting to false the operation "upload" is stopped, * and by setting qdelivering to false the operation "pick" is stopped. * You cannot stop uploads and downloads that have already begun. */ }; struct queue { qid qid; queuename qname; netname qowner; unsigned hyper qcreation; /* When the queue was created. Seconds since * epoch. */ unsigned hyper qmodified; /* When the queue was modified. */ int qlength; /* The current length of the queue (no picked) */ int qpicked; /* The number of picked entries */ int quploads; /* The number of upload handles */ queueparam qparams; /* The parameters (mutable) */ }; /* The struct queue contains global information about a queue. */ typedef queue qlist<>; /* qlist is the list of all queues */ struct property { string pname<>; string pvalue<>; }; /* A property is a pair of a name and a value that can be stored in * entries */ typedef property properties<>; /* properties: A list of properties of arbitrary length */ typedef opaque eid<>; /* The entry identifier is an opaque string */ struct entry { eid eid; /* The entry identifier */ qid eqid; /* The identifier of the containing queue */ unsigned hyper ecreation; /* The creation date of the entry */ unsigned hyper esize; /* The size of the file in bytes */ properties eprops; /* The properties */ }; typedef entry elist<>; /* The elist is the list of entries of a queue. The first member of the * elist is the next entry to pick */ typedef opaque dhandle<>; /* A download handle is an opaque string */ typedef opaque uhandle<>; /* An upload handle is an opaque string */ struct chunk { unsigned hyper serial; /* The serial number of the chunk */ bool last; /* Is this the last chunk? */ string data<>; /* The data of the chunk */ }; /* Upload and download chunks */ typedef int timeout; /* Timeout values in seconds. Negative values mean infinite timeout, 0 means * immediate timeout. */ /**********************************************************************/ /* Error codes */ /**********************************************************************/ enum errorcode { SUCCESSFUL = 0, NOT_FOUND = 1, /* The queuename, qid, eid, dhandle, or uhandle could not be found */ PICKED = 2, /* The entry is currently "picked" and not accessible */ EXISTS = 3, /* A queue with this queuename already exists */ NOT_PICKED = 4, /* The entry must be picked first in order to do this function. This code * is also returned if the picked entry is lost because of a timeout or * broken network connections. */ CHUNKS_TOO_LARGE = 5, /* The requested chunksize is too large. */ TIMEOUT = 6, /* The upload/download handle has been dropped (timeout). */ EMPTY = 7, /* The queue is empty, and there is no entry to pick */ QUEUE_DELETED = 8, /* While uploading/downloading someone deleted the queue */ FULL = 9, /* The queue is full */ BAD_NAME = 10, /* The queue name contains bad characters */ BAD_VALUE = 11, /* One of the passed values is out of the valid range */ INACTIVE = 12, /* The queue is inactive */ PERMISSION_DENIED = 13, /* No permission for this operation */ SYS_ERROR = 20 /* The operating system reports an error. */ }; /**********************************************************************/ /* Result structures */ /**********************************************************************/ union errorcond switch (errorcode e) { case SUCCESSFUL: void; default: void; }; union qlist_or_errorcode switch (errorcode e) { case SUCCESSFUL: qlist list; default: void; }; union queue_or_errorcode switch (errorcode e) { case SUCCESSFUL: queue queue; default: void; }; union elist_or_errorcode switch (errorcode e) { case SUCCESSFUL: elist list; default: void; }; union entry_or_errorcode switch (errorcode e) { case SUCCESSFUL: entry entry; default: void; }; union dhandle_or_errorcode switch (errorcode e) { case SUCCESSFUL: dhandle dhandle; default: void; }; union uhandle_or_errorcode switch (errorcode e) { case SUCCESSFUL: uhandle uhandle; default: void; }; union chunk_or_errorcode switch (errorcode e) { case SUCCESSFUL: chunk chunk; default: void; }; /**********************************************************************/ /* Program */ /**********************************************************************/ program QUEUESPROG { version QUEUESVERS1 { /* Ping */ void ping(void) = 0; /* Management of queues */ errorcond create_queue(queuename) = 10; errorcond delete_queue(queuename) = 11; qlist_or_errorcode list_queues(void) = 12; queue_or_errorcode get_queue(queuename) = 13; errorcond set_queue(queuename, queueparam) = 14; /* Queue entries */ elist_or_errorcode list_queue_entries(qid) = 20; entry_or_errorcode pick_queue_entry(qid,timeout) = 21; errorcond return_picked_queue_entry(qid,eid) = 22; errorcond remove_picked_queue_entry(qid,eid) = 23; errorcond remove_queue_entry(qid,eid) = 24; /* A "picked" entry is temporarily removed from the queue. It can * be downloaded, but is invisible to others. By removing the * picked entry it is really removed from the queue. By returning * the entry it is visible again. * If the queue is empty, the timeout value specifies how long to * wait for new entries. 0 means not to wait. A negative value means * to wait endless. If there is still no entry after this time * the error EMPTY is returned. * If the TCP connection is closed, the picked entry will be * automatically returned to the queue. */ /* Download queue entries */ dhandle_or_errorcode download_entry(qid,eid,int) = 30; chunk_or_errorcode download_chunk(dhandle) = 31; /* You can only download picked entries. If the entry is * removed or returned while the download is in progress, the * download functions will indicate an error condition. * * download_entry(qid,eid,chunksize): The function requests a download * in chunks of [chunksize] bytes. * download_chunk(dhandle): Downloads the next chunk. The dhandle * is automatically deallocated when the last chunk is downloaded, * or when the picked entry is removed or returned. */ /* Upload queue entries */ uhandle_or_errorcode upload_entry(qid,properties, timeout) = 40; errorcond upload_chunk(uhandle, chunk) = 41; /* Only if the entry is completely uploaded, it will be visible * to the others. * If the upload is not finished until timeout, the upload will * be canceled. The same happens if the TCP connection breaks. * * upload_entry(qid,properties, timeout): Begins an upload. The entry * will have the passed property list. * upload_chunk(uhandle, chunk): Uploads the next chunk. The chunks * must have proper serial numbers, and the last chunk must be * flagged as last. */ } = 1; } = 0x2000EEEE;