/* ---------------------------------------------------------------------- */ /* DLInterchange.idl /* last update: 9/19/95 hassan */ #include "CosPropertyService.idl" module IDLInterchange { /* ------------------------------------------------------------ */ /* some simple types */ typedef string TString; typedef long TOptionalSize; /* a value of -1 means NULL */ /* this typedef breaks the generated C++ code */ /* typedef CosPropertyService::Any Any; */ /* Forward references */ interface CItem; interface CServicePreferences; interface CQuery; interface CCollection; interface CConstrainCollection; /* ------------------------------------------------------------ */ /* define a cookie. */ typedef CosPropertyService::Any TCookie; typedef sequence TCookies; /* ------------------------------------------------------------ */ /* TMessageID is a client-side identifier for all the responses to a particular request. */ typedef TCookie TMessageID; typedef TString TItemClass; /* ------------------------------------------------------------ */ /* define Status - for use with CItem::GetStatus call. */ /* swh 9/19/95 */ enum EStatus { IN_PROGRESS, /* the request is being worked on. */ UNKNOWN_MESSAGE_ID, /* never heard of it. */ COMPLETED /* that request has completed. */ }; /* ------------------------------------------------------------ */ /* define Access Capability */ struct TAccessOption { CItem aTarget; TCookie aCookie; TItemClass anItemClass; CosPropertyService::Properties aHints; }; typedef sequence TAccessCapability; typedef sequence TAccessCapabilities; /* ItemState */ /* ------------------------------------------------------------ */ /* define item state */ /* Three types for transferring state for multiple items: 1. Simplest case: only the state information is transmitted. 2. Service provides access capabilities and associated state for multiple items. Typical use: Initial response to a query. 3. Client asked for more properties of items via their access capabilities, providing a set of associated client cookies. The service now returns the requested properties, each with the associated client cookie. Note: this trades off interface beauty for minimizing information transfer. :) */ /* This is what a CosPropertyService::PropertyValuesList would be */ typedef sequence TPropertyValues; typedef sequence TPropertyValuesList; /* swh 9/19/95 */ typedef sequence PropertyNamesList; struct TItemsState { CosPropertyService::PropertyNames aNames; TPropertyValuesList anItemsState; }; /* note: aNames and anItemsStates[i] must be of the same length. */ /* ItemsCookieState */ struct TItemsCookieState { TCookies aClientCookies; TItemsState aStates; }; /* note: aClientCookies and aStates.anItemsState must be of the same length. */ /* ItemsACState */ struct TItemsACState { TAccessCapabilities aACs; TItemsState aState; }; /* note: aACs and aStates.anItemsState must be of the same length. */ /* ------------------------------------------------------------ */ /* Exceptions - some possible exceptions. Needs work. */ exception InvalidRequest{TString aReason;}; /* swh 9/19/95 */ exception InvalidQuery{TString aReason;}; /* swh 9/19/95 */ exception InvalidAuthenication{TString aReason;}; /* swh 9/19/95 */ exception InvalidPayment{TString aReason;}; /* swh 9/19/95 */ exception UnableToCompleteRequest{TString aReason;}; /* swh 9/29/95 */ exception InvalidProperties{CosPropertyService::PropertyNames aPropertyNames;}; exception InvalidMoreCookie{}; exception InvalidCookies{TCookies aCookies;}; exception InvalidMessageID{TString aReason;}; /* swh 3/21/96 */ enum EExceptionReason { kInvalidRequest, kInvalidQuery, kInvalidAuthenication, /* swh 9/19/95 */ kInvalidPayment, /* swh 9/19/95 */ kInvalidProperties, kInvalidMoreCookie, kInvalidCookies, kUnableToCompleteRequest, /* swh 9/29/95 */ kInvalidMessageID }; union TException switch (EExceptionReason) { case kInvalidRequest : TString aRequestReason; /* swh 9/19/95 */ case kInvalidQuery : TString aQueryReason; /* swh 9/19/95 */ case kInvalidAuthenication : TString aAuthenicationReason; /* swh 9/19/95 */ case kInvalidPayment : TString aPaymentReason; /* swh 9/19/95 */ case kInvalidProperties : CosPropertyService::PropertyNames aProperties; case kInvalidCookies : TCookies aCookies; case kUnableToCompleteRequest : TString aUnableReason; /* swh 3.21.96 */ case kInvalidMessageID : TString aMessageIDReason; /* swh 9/19/95 */ }; typedef sequence TExceptions; exception MultipleExceptions{TExceptions aExceptions;}; /* ------------------------------------------------------------ */ /* ############################################################ */ /* CItem */ /* ############################################################ */ /* ------------------------------------------------------------ */ /* ------------------------------------------------------------ */ /* CItem holds all or part of the state of an information object. */ interface CItem : CosPropertyService::PropertySet { /* return all of the item handles related to this item. */ TAccessCapability GetAccessCapability(); /* add a list of item handles to this item */ void AddAccessOptions(in TAccessCapability pOptions); /* remove this list of item handles from this item. */ void RemoveAccessOptions(in TAccessCapability pOptions); /* ------------------------------------------------------------ */ /* RequestItemProperties() Request to be sent certain properties for this item. Sometime later, one or more SetItemProperties messages will be sent to pResultTarget and finally a CompletedRequest() or RaiseException() will be sent to signal the end of the request. o pMessageID is the client-side data to pass back in order to identify the resulting callback messages. o pPropertyNames are the list of fields desired. o pResultTarget is the target result CItem. Note: this simply adds a asynchronous option to the ICosProperty interface: get properties from a single item. */ oneway void RequestItemProperties(in TMessageID pMessageID, in CosPropertyService::PropertyNames pPropertyNames, in CItem pResultTarget); /* ------------------------------------------------------------ */ /* SetItemProperties() Sets properties of this item. o pMessageID is the client-side data that matches the pMessageID of the initial request (a RequestItemProperties call) o pItem contains the state information requested. */ oneway void SetItemProperties(in TMessageID pMessageID, in CosPropertyService::Properties pItem); /* ------------------------------------------------------------ */ /* GetStatus() returns the status of a particular message request. */ EStatus GetStatus(in TMessageID pMessageID); /* ------------------------------------------------------------ */ /* CompletedRequest() Signals to the client that the request with pMessageID has completed successfully. No other messages with pMessageID shall be sent. */ oneway void CompletedRequest(in TMessageID pMessageID); /* ------------------------------------------------------------ */ /* RaiseException() Signals to the client that the request with pMessageID has encountered an exception. No other messages with pMessageID shall be sent. */ oneway void RaiseException(in TMessageID pMessageID, in TException pException); /* ------------------------------------------------------------ */ /* CancelRequest() Signals to a requestee that the pending request with pMessageID shall be cancel. No other messages with pMessageID shall be sent to the requestor. */ void CancelRequest(in TMessageID pMessageID) /* swh 3.21.96 */ raises(InvalidMessageID); }; /* ------------------------------------------------------------ */ /* ############################################################ */ /* CCollection */ /* ############################################################ */ /* ------------------------------------------------------------ */ /* CCollection contains a set of items (maybe documents) and efficently allows for the retrieval and setting of the items' properties in bulk. All of the Request methods are asynchronous in nature. The results should come back sometime later with the SetItems or SetItemsProperties methods. The cookies are generated by the server collection and given to the client to hand back when more items are needed. They may be used as an index into an array on the server side. Other schemes are allowed. This protocol does not require items to be stored in a sequencial manner. */ interface CCollection : CItem { /* ------------------------------------------------------------ */ /* GetTotalItems() Returns the total expected size of this collection. If -1, then the expected size is unknown. */ TOptionalSize GetTotalItems(); /* ------------------------------------------------------------ */ /* SetTotalItems() Sets the total expected size of this collection. o pTotalSize is the expected total size of the collection. If -1, then the expected size is unknown. */ oneway void SetTotalItems(in TOptionalSize pTotalSize); /* ------------------------------------------------------------ */ /* GetItems() Get 'pNumberOfMoreItems' more Items. o pPropertyNames are the list of fields desired. o pNumberItems represents the maximum number of Items to send back. If -1, then return all of the items in this collection. o pMoreCookie was returned by AddItems that represents how to get more Items in the collection. A value of NIL means to start from the beginning of the collection. o pNewMoreCookie is a new handle to get more Items. */ TItemsACState GetItems(in CosPropertyService::PropertyNames pPropertyNames, in TCookie pMoreCookie, in TOptionalSize pNumberOfItems, out TAccessCapability pNewMoreCookie) raises(InvalidRequest, InvalidProperties, InvalidAuthenication, InvalidPayment, InvalidMoreCookie, MultipleExceptions); /* ------------------------------------------------------------ */ /* RequestItems() Request to be sent pNumberItems more Items to pTarget. Sometime later, one or more AddItems messages will be sent to pResultTarget and finally a CompletedRequest() or RaiseException() will be sent to signal the end of the request. o pPropertyNames are the list of fields desired. o pMoreCookie was returned by AddItems that represents how to get more Items in the collection. A value of NIL means to start from the beginning of the collection. o pNumberItems represents the maximum number of Items to send back. If -1, then return all of the items in this collection. o pTarget is the result collection to send the Items to. */ oneway void RequestItems( in TMessageID pMessageID, in CosPropertyService::PropertyNames pPropertyNames, in TCookie pMoreCookie, in TOptionalSize pNumberItems, in CCollection pResultTarget); /* ------------------------------------------------------------ */ /* AddItems() Add additional Items to this collection. o pMessageID is the client-side data that matches the pMessageID of the initial request (a RequestConstrain or RequestItems call.) o pItems contains the state information requested. o pNewMoreCookie should be passed to collection to request more Items. A NIL value means there are no more Items. */ oneway void AddItems(in TMessageID pMessageID, in TItemsACState pItems, in TAccessCapability pNewMoreCookie); /* ------------------------------------------------------------ */ /* GetItemsProperties() Get properties of items given their service-side cookies. o pPropertyNames are the list of fields desired. o pServerCookies is a list of server-side cookies of the items requested. Note: order and size of result TItemsState must match the order and size of the pServerCookies parameter. */ TItemsState GetItemsProperties( in CosPropertyService::PropertyNames pPropertyNames, in TCookies pServerCookies) raises(InvalidRequest, InvalidAuthenication, InvalidPayment, InvalidCookies, InvalidProperties, MultipleExceptions); /* ------------------------------------------------------------ */ /* RequestItemsProperties() Request to be sent properties of items given their server-side cookies. Sometime later, one or more SetItemsProperties messages will be sent to pResultTarget and finally a CompletedRequest() or RaiseException() will be sent to signal the end of the request. o pMessageID is the client-side data to pass back in order to identify the resulting callback messages. o pPropertyNames are the list of fields desired. o pServerCookies is a list of server-side cookies of the items requested. o pClientCookies is a list of client-side cookies to be returned in conjuction with the items' state information. The client can place anything in these cookies and is guarateed to be matched up with the resulting items. o pResultTarget is the target result collection to send the Items to. */ oneway void RequestItemsProperties( in TMessageID pMessageID, in CosPropertyService::PropertyNames pPropertyNames, in TCookies pServerCookies, in TCookies pClientCookies, in CCollection pResultTarget); /* ------------------------------------------------------------ */ /* SetItemsProperties() Set properties of existing Items in this collection. If a item does not exist in this collection, raise an exception. o pMessageID is the client-side data that matches the pMessageID of the initial request (a RequestItemsProperties call) o pItems contains the state information requested. */ oneway void SetItemsProperties(in TMessageID pMessageID, in TItemsCookieState pItems); /* ------------------------------------------------------------ */ /* GetItemsPropertyNames() For a list of items, return a list of valid property names. */ PropertyNamesList GetItemsPropertyNames(in TCookies pCookies) raises(InvalidRequest, InvalidCookies, InvalidAuthenication, InvalidPayment, MultipleExceptions); /* ------------------------------------------------------------ */ /* RequestItemsPropertyNames() Cause this collection to call SetItemsPropertyNames on pResultTarget) */ oneway void RequestItemsPropertyNames(in TMessageID pMessageID, in TCookies pCookies, in CCollection pResultTarget); /* ------------------------------------------------------------ */ /* SetItemsPropertyNames() */ oneway void SetItemsPropertyNames(in TMessageID pMessageID, in PropertyNamesList pNamesList); /* ------------------------------------------------------------ */ /* RaiseExceptions() Signals to the client that the request with pMessageID has encountered multiple exceptions. No other messages with pMessageID should be sent. */ oneway void RaiseExceptions(in TMessageID pMessageID, in TExceptions pExceptions); /* ------------------------------------------------------------ */ /* RemoveItems() Remove the following items from the collection. */ void RemoveItems(in TCookies pCookies) raises(InvalidRequest, InvalidAuthenication, MultipleExceptions); }; /* ------------------------------------------------------------ */ /* ############################################################ */ /* CServicePreferences */ /* ############################################################ */ /* ------------------------------------------------------------ */ struct TServicePrefSummary { CServicePreferences aServicePreferences; TOptionalSize aNumberOfItems; CosPropertyService::Properties aMoreSummary; }; interface CServicePreferences : CosPropertyService::PropertySet { TServicePrefSummary GetSummary(); TOptionalSize GetNumberOfItems(); void SetNumberOfItems(in TOptionalSize pNumberOfItems); }; /* ---------------------------------------------------------------------- */ /* proximity */ enum RPNNumericRelationType {kRPN_PROX_LESSTHAN, kRPN_PROX_LESSTHANOREQUAL, kRPN_PROX_EQUAL, kRPN_PROX_GREATERTHANOREQUAL, kRPN_PROX_GREATERTHAN, kRPN_PROX_NOTEQUAL}; enum RPNProximityUnitCode {kRPN_CHARACTER, kRPN_WORD, kRPN_SENTENCE, kRPN_PARAGRAPH, kRPN_SECTION, kRPN_CHAPTER, kRPN_DOCUMENT, kRPN_ELEMENT, kELEMENT, kRPN_SUBELEMENT, kRPN_ELEMENTTYPE, kRPN_BYTE}; struct RPNProximityOperator { boolean exclusion; /* not within x words. */ short distance; boolean ordered; RPNNumericRelationType relationType; RPNProximityUnitCode unitcode; }; /* attributes */ struct RPNAttributeElement { unsigned long aAttributeSet; unsigned long aType; unsigned long aValue; }; typedef sequence RPNAttributeList; /* operators */ enum RPNRelationOperator {kRPN_LESSTHAN, kRPN_LESSTHANOREQUAL, kRPN_EQUAL, kRPN_GREATERTHANOREQUAL, kRPN_GREATERTHAN, kRPN_NOTEQUAL, kRPN_PHONETIC, kRPN_STEM, kRPN_RELEVANCE, kRPN_ALWAYSMATCHES, kRPN_CONTAINS}; enum RPNBooleanOperator {kRPN_AND, kRPN_OR, kRPN_NOT}; enum RPNOperatorKey {kRPN_BOOLEAN, kRPN_PROXIMITY, kRPN_RELATION}; union RPNOperator switch (RPNOperatorKey) { case kRPN_BOOLEAN : RPNBooleanOperator bool_oper; case kRPN_PROXIMITY : RPNProximityOperator prox; case kRPN_RELATION : RPNRelationOperator rel_oper; }; /* term */ enum RPNTermValueKey { kRPN_STRING, kRPN_NUMERIC, kRPN_REAL }; /* swh 3.21.96 */ union RPNTermValue switch (RPNTermValueKey) { /* swh 3.21.96 */ case kRPN_STRING : TString string_term; case kRPN_NUMERIC : long int_term; case kRPN_REAL : double real_term; }; struct RPNTerm { /* swh 3.21.96 */ RPNTermValue term; RPNAttributeList attributes; }; /* operand */ enum RPNOperandKey {kRPNTERM, kRPNCOLLECTION, kRPNATTRIBUTE}; union RPNOperand switch (RPNOperandKey){ case kRPNTERM : RPNTerm term; case kRPNCOLLECTION : CCollection coll; case kRPNATTRIBUTE : RPNAttributeList attrs; }; /* rpn structure */ enum RPNStructureKey {kRPNTREE, kRPNLEAF}; union RPNStructure switch (RPNStructureKey) { case kRPNLEAF : RPNOperand op; case kRPNTREE : struct RPNNode { RPNOperator op; sequence operands; } rpnRpnOp; }; /* rpn query 101 */ struct RPNQuery101 { unsigned long attributeSetId; RPNStructure rpn; }; /* rpn query 10 */ struct RPNQuery0 { long querytype; CosPropertyService::Any query; }; enum QueryType {kQTYPE0, kQTYPE101}; union TQueryDescription switch (QueryType) { case kQTYPE0 : RPNQuery0 QueryType0; case kQTYPE101 : RPNQuery101 QueryType101; }; /* ---------------------------------------------------------------------- */ /* Query */ struct TQuerySummary { CQuery aQueryObject; TQueryDescription aQueryDescription; CosPropertyService::PropertyNames aItemPropertyNames; CosPropertyService::Properties aMoreSummary; }; /* ------------------------------------------------------------ */ /* CQuery represents the type, keywords, and other data needed to perform a constraint on a collection. */ interface CQuery : CosPropertyService::PropertySet { TQuerySummary GetSummary(); TQueryDescription GetQueryDescription(); void SetQueryDescription(in TQueryDescription pQueryDescription); /* if this inherits from PropertySet, are these two necessary? --dlk*/ CosPropertyService::PropertyNames GetItemPropertyNames(); void SetItemPropertyNames(in CosPropertyService::PropertyNames pItemPropertyNames); }; /* ------------------------------------------------------------ */ /* ############################################################ */ /* CConstrainCollection */ /* ############################################################ */ /* ------------------------------------------------------------ */ /* ------------------------------------------------------------ */ /* CConstrainCollection is a constrainable collection meaning that constraints can be placed on it (like a query or search.) It is up to the implementation whether it wants to create a new collection to constrain or constrain this collection even further. The pMoreCookie is returned to allow for both of these implementations. */ interface CConstrainCollection : CCollection { /* ------------------------------------------------------------ */ /* Constrain() Constrain Collection with pDesignator and return pNumberOfItems Items back with properties of pPropertyNames. o pQuerySummary is the constraints to place on this collection. o pServicePrefSummary are miscellaneous preferences like quality of service, passwords, flow control, number of items to send now. o pTotalSize is the total expected size of this collection. If -1, then the total size is unknown at this time. o pMoreCookie should be passed to collection to request more Items. A NIL value means there are no more Items. */ TItemsACState Constrain(in TQuerySummary pQuerySummary, in TServicePrefSummary pServicePrefSummary, out TOptionalSize pTotalSize, out TAccessCapability pMoreCookie) raises ( InvalidRequest, InvalidQuery, InvalidAuthenication, InvalidPayment, MultipleExceptions); /* ------------------------------------------------------------ */ /* RequestConstrain() Request to constrain Collection with pDesignator and send results to pTarget. Sometime later, one or more AddItems messages will be sent to pResultTarget and finally a CompletedRequest() or RaiseException() will be sent to signal the end of the request. o pMessageID is the client-side data to pass back in order to identify the resulting callback messages. o pQuerySummary is the constraints to place on this collection. o pServicePrefSummary are miscellaneous preferences like quality of service, passwords, flow control, number of itmes to send now. o pPropertyNames are the list of fields desired. o pTarget is the result collection to send the Items to. */ oneway void RequestConstrain( in TMessageID pMessageID, in TQuerySummary pQuerySummary, in TServicePrefSummary pServicePrefSummary, in CCollection pResultTarget); }; };