/* ---------------------------------------------------------------------- */
/* DLInterchange.idl
/* last update: 9/19/95 hassan */
#include "CosPropertyService.idl"
module IDLInterchange
{
/* ------------------------------------------------------------ */
/* some simple types */
typedef string TString;
typedef unsigned long TOptionalSize;
/* 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<TCookie> 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 <TAccessOption> TAccessCapability;
typedef sequence <TAccessCapability> 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 <CosPropertyService::Any> TPropertyValues;
typedef sequence <TPropertyValues> TPropertyValuesList;
/* swh 9/19/95 */
typedef sequence<CosPropertyService::PropertyNames> 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<TException> 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 NULL,
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 NULL, 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 NULL, 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 NULL, 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()
*/
oneway void RequestItemsPropertyNames(in TMessageID pMessageID,
in TCookies pCookies);
/* ------------------------------------------------------------ */
/* 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<RPNAttributeElement> 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<RPNStructure> 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
NULL, 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);
};
};