Oops, I screwed stuff up and that last idl didn't attach so well. (I'm also using an open source beta version mailer with lots o' bugs, so maybe I can pretend to blame it on that :-) How about if I just paste it on in? Hope this is better :) Brad // dl2bl.idl // // IDL for dealing with communication between the GUI (buffered by a small // middle) and the data processing engine. // // Changelog: // 23 Mar 2000 : Brad, creation // 25 Mar 2000 : Jarl, added gms naming // 26 Mar 2000 : Renamed again :) added\remove some functions // Actually compiled this :) // 27 Mar 2000 : Brad, case changes, moved a few functions around // Added a struct for returning more info about a // node/process. /** * Acronyms * vsh: The overall module (the name can change when we decide on a formal * name). * dl2bl: idl for communication between the scripting/XML layer and the * data processing engine. * dl : definition layer, involved in the creation of an XML script to define * structures. * bl: Brokering Layer, layer that does the distribution\authentication\etc * pl: Processing Layer, layer that does the 'real' dataflow work. * */ module vsh { /** * Communication between the definition layer (XML script generator) and * the brokering layer, which distributes the XML info to the processing * layer. */ module dl2bl { // ##### exceptions // ---------------- /** * Requested Id is already being used for another gui. */ exception DLIdInUse {}; /** * Id number used for requested operation was not found in the list of * current gui ids being served by the data processor. */ exception DLIdNotFound{}; /** * The information for a node is not yet available because the process * has not completed. */ exception DLInfoNotAvailable{}; /** * The definition layer couldn't accept the XML document and so didn't * allocate an uri. */ exception URIUndefined{}; /** * The uri is already defined. */ exception URIInUse{}; /** * The uri cant be found, it does not excist or is not accessable. */ exception URINotFound{}; /** * Requested information was not found. */ exception InfoNotAvailable{}; // ##### structs, enums and typedefs // --------------------------------- /** * DL identification number, or 'account name'. */ typedef long DLIdT; /** * Passwords. */ typedef string passwordT; /** * Connection type: * -1 = Unconnected * 0 = Unknown * 1 = Plain connection * 2 = Encrypted connection, based on {TODO:type} encryption */ enum connectionE { UNKNOWN, UNCONNECTED, PLAIN, ENCRYPTED1 }; /** * Current state of a node or process: * -1 = Error (TODO: Other negative values to define various errors) * 0 = Unknown * 1 = Passing * 2 = Blocking * 4 = Temporary * 8 = Isolated */ typedef long stateT; /** * A value between zero and one indicating the process towards completion * for a process, subnet or node. This is useful if you have really long * programs and want to check on their status. * 1 -> finished (100% done) * intermediate -> % towards completion * 0 -> not started (0% done) */ typedef double progressT; /** * Struct for returning the status of a particular node or process. * @mem state - The current state of the node or process. * @mem progress - The progress towards completion of the node or * process. */ struct statusT{ stateT state; progressT progress; }; /** * URI type, a 128bits locating id: * bits 0-31 : instance id * bits 32-63 : brokering id, or subnet id * bits 64-127 : node i * uriT is in a IP (Internet protocol) style * uriT = 2.0.0 -> All subnets and nodes local in instance 2 * uriT = 74.35.0 -> All nodes in subnet 35 of instance 74. * uriT = 1.2.3 -> Node 3 in subnet 2 of instance 1. */ struct uriT { long instanceID; long subnetID; long nodeID; }; /** * A sequence/list of uriTs. Useful for returning info like a list of * program ids for available programs. * */ typedef sequence <string> uriListT; // ##### interfaces // ---------------- /** * Functions for establishing a connection between the definition layer * and brokering layer (which controls access to the processing layer). */ interface Connection { // TODO: introduce a 'access level', so ADM's can be limited /** setup * Initialize a connection from the dl to the brokering/processing * layer. * @parm dlid- An unique id to represent the connection. * @parm password - The password associated with this id. * @parm connecttype - requested connection type. * @returns A boolean indicating the success of the initialization. * @raises DLIdInUse - The passed dlid is already in use by another * gui. * TODO: Add more exceptions to raise as we see what problems come up. */ boolean setup(in DLIdT dlid, in passwordT password, in connectionE connecttype) raises (DLIdInUse); /** release * Close the connection between the definition layer and the brokering * processing layer * @parm dlid - An unique id to represent the connection. * @parm password - The password associated with this id. * @returns A boolean indicating the success of the initialization * @raises DLIdNotFound - The passed id was not found in the list of * ids registerd with the data processing engine. */ boolean release(in DLIdT dlid, in passwordT password) raises (DLIdNotFound); /** checkConnection * Checks if the DL with id 'dlid' has been connected. * @parm dlid - An unique id represting the connection. * @returns type of connection * @raises DLInfoNotAvailable - this connection isn't setup correctly */ connectionE checkConnection(in DLIdT dlid) raises (DLInfoNotAvailable); }; /** * Functions for passing XML information to the data processing engine * and synchronizing the document. */ interface XmlRepresentation { /** upload * Uploads a XML document to the DL, which will pass most of it to the * PL. * @parm xmldocument: A big string of xml describing the nodes/loci * to be processed and the relationship between them. * @parm dlid - The ID of the DL that uploads the document * @parm password - The password associated with this id. * @returns the URI the uploaded structure got assigned by the DL. * @raises URIUndefined, the DL/PL couldn't accept the XML document. * Use RetrieveInfo::check to see what is wrong. */ uriT upload(in string xmldocument, in DLIdT dlid, in passwordT password) raises (URIUndefined); /** update * Updates an excisting structure. * @parm xmldocument - The XML document * @parm uri - the uri id of the structure to be overwritten. * @parm dlid - The ID of the DL that uploads the document * @parm password - The password associated with this id. * @returns boolean success status. * @raises URIInUse, the uri is currently running or the DDL is not * authorized to overwrite it. */ boolean update(in string xmldocument, in uriT uri, in DLIdT dlid, in passwordT password) raises (URIInUse); /** download * Downloads a XML document from the BL to the DL. * @parm uri - uri of the structure to be downloaded. * @parm dld - The ID of the DL that uploaded the document * @parm password - The password associated with this id. * @returns An XML document. * @raises URINotFound when uri doesn't exist or is not reachable. */ string download(in uriT uri, in DLIdT dlid, in passwordT password) raises (URINotFound); }; /** * Functions to provide status information for the core (brokering and * processing layers), and for getting information about programs and * libraries registered with the processing engine. */ interface RetrieveInfo { /** checkStatus * Used for checking the status of an URI * @parm uri - uri of the structure to be checked. * @parm dlid - The ID of the DL that uploads the document * @parm password - The password associated with this id. * @returns Status of the structure uri. * @raises URINotFound when uri doesn't excist or is not reachable. */ statusT checkStatus(in uriT uri, in DLIdT dlid, in passwordT password) raises (URINotFound); /** * Get the information for a node so that is can be displayed in * the visual user interface. * @parm processid - the unique id associated with a process. * @parm uri - uri of the node to be checked. * @returns A string with the info from the node. * TODO: Need a structured and generalized way to return info * and pass it to a visual so it can be seen in the GUI * Strings aren't going to cut it for everything, * I don't think. * @raises InfoNotAvailable - If the node currently doesn't have any * information to send (ie. process is not complete). */ string getNodeInfo(in passwordT processid, in uriT uri) raises (InfoNotAvailable); /** * Get a list of all the program ids of programs registered functional * (ie. loaded) with the processing engine. * @returns A sequence of uri's with ids of available * nodes/subnets/programs. These will be returned with leading * zeros. For instance you could get back a list like the * following: * ['0.0.27', '0.0.345', '0.0.123'...] * It will be up to the definition layer to keep a dictionary * to translate between these uri's and the actual program * names. */ uriListT getProgramIds(); /** * Query a specific node to see if it is available. * @parm node_id - the unique id of a node (program/function). * @returns 1 if the program is loaded, 0 if it is not. * @raises URINotFound - If the requested URI can not be located. */ boolean isAvailable(in uriT uri) raises (URINotFound); }; }; };