-- IDL module extracted from ITU-T Q.816 (01/2001)
/* This IDL code is intended to be stored in a file named "itut_q816.idl"
located in the search path used by IDL compilers on your system. */
#ifndef ITUT_Q816_IDL
#define ITUT_Q816_IDL
#include <CosTime.idl>
#include <itut_x780.idl>
#pragma prefix "itu.int"
module itut_q816 {
// Types imported from CosTime
typedef TimeBase::UtcT UtcT;
// Types imported from itut_x780
typedef itut_x780::AttributeSetType AttributeSetType;
typedef itut_x780::GeneralizedTimeType GeneralizedTimeType;
typedef itut_x780::NameType NameType;
typedef itut_x780::NameSetType NameSetType;
typedef itut_x780::ObjectClassType ObjectClassType;
typedef itut_x780::ObjectClassSetType ObjectClassSetType;
typedef itut_x780::ScopedNameType ScopedNameType;
typedef itut_x780::ScopedNameSetType ScopedNameSetType;
typedef itut_x780::StringSetType StringSetType;
typedef itut_x780::SystemLabelType SystemLabelType;
// Interfaces imported from itut_x780 (interfaces are not typedeffed
// for efficiency and clarity reasons)
// itut_x780::ManagedObject
// itut_x780::ManagedObjectFactory
// Exceptions imported from itut_x780 (exceptions can't be typedeffed)
// itut_x780::ApplicationError
// itut_x780::DeleteError
// Data Types and Structures
/** ScopeChoice enumerates four possible choices for a scope. A
scope may include just the named base object, the entire subtree
of object below and including the base object, the objects at a certain
level below the base object (level 1 objects are directly contained by
the base object), or all of the objects down to a level, including the
base object and the level.
*/
enum ScopeChoiceType {baseObjectOnly, wholeSubtree, individualLevel,
baseToLevel};
/** Scope is used to convey which objects contained under the base
object, if any, are to be included in the scope of a scoped and
filtered operation. A level does not make sense for the baseObjectOnly
and wholeSubtree choices, but does for the other two. To illustrate
the difference between the two options that include a level, a
scope choice of individualLevel with level = 1 would include all
of the objects directly contained by the base object. A scope choice
of baseToLevel with level = 1 would include all of the objects
directly contained by the base object, and the base object.
*/
union ScopeType switch (ScopeChoiceType)
{
/* The baseObjectOnly and wholeSubtree cases carry no value. */
case individualLevel: /* fall through */
case baseToLevel: short level;
};
/** BaseAndScopeType combines the name of a base managed object with
a "scope" of objects contained below it. */
struct BaseAndScopeType {
NameType base;
ScopeType scope;
};
/** BaseAndScopeSetType is a set of BaseAndScopeTypes. */
typedef sequence <BaseAndScopeType> BaseAndScopeSetType;
/** ChannelIDType is a string used to contain a channel ID. */
typedef string ChannelIDType;
/** EventSetType is a list of event types. It is actually just a list
of strings. The values of the strings are the names of the event types
(the strings that go in the "type_name" field of the structured event),
which are the same as the scoped names of the operation defined on the
Notifications interfaces to send the events. For example:
itut_x780::Notifications::objectCreation */
typedef sequence <ScopedNameType> EventSetType;
/** A channelInfo structure contains information about an event
channel.
@member channelID A string identifier for the channel.
@member channelClass the channel's scoped class name.
@member baseAndScopes The objects and the scopes of managed objects
below them sending events to this channel.
A null list indicates that all base managed
objects on the system are covered by this
channel.
@member eventTypes The list of event types handled by this
channel. A null list indicates all event types
are handled by this channel.
@member excludedEventTypes If the eventTypes parameter is null, this
can be used to exclude event types. If
eventTypes is not null, this should be null
and is ignored.
@member sourceClasses The list of types of objects that send events
to this channel. A null list indicates all
types of managed objects send events to this
channel.
@member excludedSourceClasses If the sourceClasses parameter is null,
this can be used to exclude source classes.
If sourceClasses is not null, this should be
null and is ignored.
@member channel a reference to the channel.
*/
struct ChannelInfoType {
ChannelIDType channelID;
ObjectClassType channelClass;
BaseAndScopeSetType baseAndScopes;
EventSetType eventTypes;
EventSetType excludedEventTypes;
ObjectClassSetType sourceClasses;
ObjectClassSetType excludedSourceClasses;
Object channel;
};
/** A channel info set contains a list of channel references and the
data associated with them. */
typedef sequence <ChannelInfoType> ChannelInfoSetType;
/** ChannelModification indicates the type of event channel
modification. */
enum ChannelModificationType {ChannelCreate, ChannelDelete,
ChannelUpdate};
/** The DeleteResultsType holds, for a single object, the results
of a scoped delete operation. If both boolean flags in the result
are false, the object was deleted.
@member name The name of the object to which these results
apply.
@member notFilterable This flag will be true if the service could not
interact with the object to see if it even
passed the filter.
@member notDeletable This flag will be true if the object could not
be deleted due to its delete policy or because
it raised an exception.
*/
struct DeleteResultsType {
NameType name;
boolean notFilterable;
boolean notDeletable;
};
/** The DeleteResultsSetType is a set of results returned by the
scoped delete operation. */
typedef sequence <DeleteResultsType> DeleteResultsSetType;
/** A factory info structure contains information about a managed
object factory.
@member factoryClass the factory's scoped class name
@member factoryRef a reference to the factory
*/
struct FactoryInfoType {
ObjectClassType factoryClass;
itut_x780::ManagedObjectFactory factoryRef;
};
/** A factory info set contains a list of factory references and
their class names. */
typedef sequence <FactoryInfoType> FactoryInfoSetType;
/** A FilterType parameter conveys the filter expression used in a
scoped and filtered operation.
*/
typedef string FilterType;
/** GetResults structures hold a list of attribute values per object.
@member name The CORBA name of the object
@member notFilterable This flag will be true if the service could not
interact with the object to see if it even
passed the filter. If true, the attributes and
failedAttributes members will be empty.
@member attributes The list of attributes retrieved from the
object.
@member failedAttributes The list of attributes whose values could
not be retrieved from the object.
*/
struct GetResultsType {
NameType name;
boolean notFilterable;
AttributeSetType attributes;
StringSetType failedAttributes;
};
/** The GetResultsSet is a set of results returned by a scoped get
operation. */
typedef sequence <GetResultsType> GetResultsSetType;
/** HeartbeatPeriodType contains the length of the interval between
heartbeats emitted by the Heartbeat Service. Using an unsigned short
to contain this interval limits the longest possible interval to
a little over 18 hours. */
typedef unsigned short HeartbeatPeriodType;
/** A LanguageType parameter conveys the filter expression language
used in a scoped and filtered operation.
*/
typedef string LanguageType;
/** A LanguageSetType parameter contains a sequence of Languages. */
typedef sequence <LanguageType> LanguageSetType;
/** ModificationOp is used to indicate the type of update to be made to
an attribute. */
enum ModificationOpType {set, add, remove};
/** Modification structures identify an attribute and a modification to
be made to it. Multiple updates may be made to a single attribute by
including multiple structures with the same attribute name in the
modification Set.
@member attrib The name of the attribute to update.
@member op The operation to be performed on the attribute.
@member val The value to be used for the update operation.
It's type will depend on the attribute.
*/
struct ModificationType {
string attrib; // the name of the attribute
ModificationOpType op; // operation to be performed
any value; // value used to update attrib.
};
/** The Modification Sequence contains a sequence of modifications to
be made (in order) to each object in a scoped update operation. */
typedef sequence <ModificationType> ModificationSeqType;
/** Update Results structures hold the name of an object, a boolean
flag indicating if all modifications to that object were successful,
and a list of the attributes that could not be updated on that object.
The list will be null if the success flag is true.
@member name the CORBA name of the object
@member notFilterable This flag will be true if the service could not
interact with the object to see if it even
passed the filter. If true, the client will
know no attributes could be set, so
the failedAttributes member will be empty.
@member failedAttributes the list of attributes that were not
correctly updated.
*/
struct UpdateResultsType {
NameType name;
boolean notFilterable;
StringSetType failedAttributes;
};
/** An Update Results Set is returned in response to a scoped update
operation (one that sets, adds to, or removes from the value of an
attribute). */
typedef sequence <UpdateResultsType> UpdateResultsSetType;
// Constants
/** Default filter is to allow everything through the filter*/
const FilterType defaultFilter = "TRUE";
/** Default language is the grammar described in this document */
const LanguageType defaultLanguage = "MOO 1.0";
// Exceptions
/** A channel already registered exception is returned when an attempt
is made to register a channel with multiple channel IDs. */
exception ChannelAlreadyRegistered {};
/** A channel not found exception is returned when an event channel
cannot be found. */
exception ChannelNotFound {};
/** A FactoryNotFound exception is raised when a requested factory
can't be found. */
exception FactoryNotFound {};
/** A Filter Complexity Limit is raised when a filter expression in a
scoped operation is valid, but too complex to be processed. */
exception FilterComplexityLimit {};
/** An invalid filter exception is raised when a client includes a
filter expression that cannot be parsed. The text surrounding the
syntax error should be returned for trouble-shooting purposes. */
exception InvalidFilter {string badText;};
/** An Invalid Parameter exception is raised when the value of a
parameter is not valid for the operation.
@param parameter the name of the bad parameter
*/
exception InvalidParameter {string parameter;};
// Interfaces
// Factory Finder Interface
/**
This interface defines a simple service for locating a managed object
factory.
*/
interface FactoryFinder {
/** This method is used to find a managed object factory.
@param factoryClass The scoped class name of the factory,
NOT the managed object to be created.
*/
itut_x780::ManagedObjectFactory find (
in ObjectClassType factoryClass)
raises (FactoryNotFound, itut_x780::ApplicationError);
/** This method returns the list of factories registered
with the factory finder. */
FactoryInfoSetType list()
raises (itut_x780::ApplicationError);
}; // end of FactoryFinder interface
/**
This interface extends the FactoryFinder interface to add methods
to support the registration and unregistration of factories.
*/
interface FactoryFinderComponent : FactoryFinder {
/** This method is used by factories to register themselves.
It should not be used by managing systems.
@param factoryClass The scoped class name of the factory,
NOT the managed object to be created.
@param factoryRef A reference to the factory.
*/
void register (in ObjectClassType factoryClass,
in itut_x780::ManagedObjectFactory factoryRef)
raises (itut_x780::ApplicationError);
/** This method is used by factories to unregister themselves,
if necessary. It should not be used by managing systems.
@param factoryClass The scoped class name of the factory,
NOT the managed object to be created.
@param factoryRef A reference to the factory.
*/
void unregister (in ObjectClassType factoryClass,
in itut_x780::ManagedObjectFactory factoryRef)
raises (FactoryNotFound, itut_x780::ApplicationError);
}; // end of FactoryFinderComponent interface
// Channel Finder Interface
/**
This interface defines a simple service for locating event channels.
*/
interface ChannelFinder {
/** This method returns the list of channels registered
with the channel finder. */
ChannelInfoSetType list()
raises (itut_x780::ApplicationError);
}; // end of ChannelFinder interface
/**
This interface extends the ChannelFinder interface to add methods
to support the registration and unregistration of channels.
*/
interface ChannelFinderComponent : ChannelFinder {
/** This method is used by channels to register themselves.
It should not be used by managing systems. Re-registering
a channel (re-using an existing channelID) results in
updating that entry. The other information previously
associated with that entry is overwritten. A
ChannelAlreadyRegistered exception may be raised when an
attempt is made to register a channel with multiple channelIDs.
This should not be done. (The service cannot guarantee that
because two object references differ, they do not reference
the same object. It is therefore required that the managed
system ensure that the same channel is not registered twice.)
A channel change notification is sent whenever calling this
method results in a change.
@param channelID A string identifier for the channel.
@param channelClass The scoped class name of the event
channel.
@param baseAndScopes The objects and the scopes of managed
objects below them sending events to
this channel. A null list indicates
that all base managed objects on the
system are covered by this channel.
@param eventTypes The list of event types handled by
this channel. A null list indicates one
of the following:
- for event channel interfaces that do not provide an explicit query for the events types handled by the channel (e.g. the OMG Notification channel),it implies all event types are handled by this channel
- for event channel interfaces that do provide an explicit query for the event types handled by the channel (e.g. 3GPP NotificationIRPOperations interface), it implies that the explicit query must be used to determime the types of events handled.
@param excludedEventTypes If the eventTypes parameter is null,
this can be used to exclude event
types. If eventTypes is not null, this
should be null and is ignored.
@param sourceClasses The list of types of objects that send
events to this channel. A null list
indicates all types of managed objects
send events to this channel.
@param excludedSourceClasses If the sourceClasses parameter is
null, this can be used to exclude
source classes. If sourceClasses is
not null, this should be null and is
ignored.
@param channel A reference to the channel.
*/
void register (in ChannelIDType channelID,
in ObjectClassType channelClass,
in BaseAndScopeSetType baseAndScopes,
in EventSetType eventTypes,
in EventSetType excludedEventTypes,
in ScopedNameSetType sourceClasses,
in ScopedNameSetType excludedSourceClasses,
in Object channel)
raises (ChannelAlreadyRegistered,
itut_x780::ApplicationError);
/** This method is used by managed systems to unregister
channels, if necessary. It should not be used by managing
systems.
@param channelID A string identifier for the channel.
*/
void unregister (in ChannelIDType channelID)
raises (ChannelNotFound, itut_x780::ApplicationError);
}; // end of ChannelFinderComponent interface
// Heartbeat Service Interface
/**
This interface defines a service used to periodically test the
operation of the notification channels on a system. The service
supporting this interface periodically emits a short "heartbeat"
notification on each channel on the system.
*/
interface Heartbeat {
/** The systemLabel attribute is sent in heartbeat
notifications. It is used to identify the heartbeat service
instance from which the notification came. Resetting this does
not cause the service to immediately emit a notification, but
the new value will be sent with the next notification. */
attribute SystemLabelType systemLabel;
/** The period is the interval, in seconds, at which the
heartbeat service emits the heartbeat notification. If it is
zero, the service does not emit notifications. */
HeartbeatPeriodType periodGet()
raises (itut_x780::ApplicationError);
/** Updating of the period shall cause the service to deliver a
notification to all channels with the new period value and then
begin a new period. Setting the period to zero shall cause the
service to emit one final notification with a period value of
zero, then no more (until the period is reset).
Implementations may limit the range of values supported by this
operation, particularly on the low end as excessive heartbeats
would present a drain on the managed system. An attempt to
set the period to a value outside the range supported will
result in an ApplicationError with the error code set to
invalidParameter. */
void periodSet(in HeartbeatPeriodType period)
raises(itut_x780::ApplicationError);
}; // end of Heartbeat interface
// Terminator Service Interface
/**
This interface defines a service that supports the deletion of managed
objects by clients. A goal of the framework is to enable
implementations in which the managed objects do not have to maintain
the naming tree information. The factories are one place to implement
the functions needed to create name bindings, and this service can be
used to clean up the naming tree after object deletion. <p>
Also, this service can implement the rules for deleting objects based
on the delete policy of the managed objects.
*/
interface TerminatorService {
/** This method is used to delete a managed object by
specifying its name. */
void deleteByName (in NameType name)
raises (itut_x780::ApplicationError,
itut_x780::DeleteError);
/** This method is used to delete a managed object by
reference. */
void deleteByRef (in itut_x780::ManagedObject mo)
raises (itut_x780::ApplicationError,
itut_x780::DeleteError);
}; // end of TerminatorService interface
// DeleteResultsIterator Interface
/** The Delete Results Iterator interface is used to retrieve the
results from a scoped delete operation using the iterator design
pattern. */
interface DeleteResultsIterator {
/** This method is used to retrieve the next "howMany" results
in the result set.
@param howMany The maximum number of items to be returned in
the results.
@param results The next batch of results.
@return True if there are more results after those
being returned. The return value should not
be true if the results set is empty, as this
forces the client to poll for results.
Instead the call should block.
*/
boolean getNext(in unsigned short howMany,
out DeleteResultsSetType results)
raises (itut_x780::ApplicationError);
/** This method is used to destroy the iterator and release its
resources. */
void destroy();
}; // end of Delete Results Iterator interface
// GetResultsIterator Interface
/** The Get Results Iterator interface is used to retrieve the results
from a scoped get operation using the iterator design pattern. */
interface GetResultsIterator {
/** This method is used to retrieve the next "howMany" results
in the result set.
@param howMany The maximum number of items to be returned in
the results.
@param results The next batch of results.
@return True if there are more results after those
being returned. The return value should not
be true if the results set is empty, as this
forces the client to poll for results.
Instead the call should block.
*/
boolean getNext(in unsigned short howMany,
out GetResultsSetType results)
raises (itut_x780::ApplicationError);
/** This method is used to destroy the iterator and release its
resources. */
void destroy();
}; // end of Get Results Iterator interface
// UpdateResultsIterator Interface
/** The Update Results Iterator interface is used to retrieve the
results from a scoped update (set, add, remove) operation using the
iterator design pattern.
*/
interface UpdateResultsIterator {
/** This method is used to retrieve the next "howMany" results
in the result set.
@param howMany The maximum number of items to be returned in
the results.
@param results The next batch of results.
@return True if there are more results after those
being returned. The return value should not
be true if the results set is empty, as this
forces the client to poll for results.
Instead the call should block.
*/
boolean getNext(in unsigned short howMany,
out UpdateResultsSetType results)
raises (itut_x780::ApplicationError);
/** This method is used to destroy the iterator and release its
resources. */
void destroy();
}; // end of Update Results Iterator interface
// BasicMooService Interface
/** The basic scoping and filtering interface provides a common service
for performing attribute retrieval operations on multiple objects.
*/
interface BasicMooService {
/** This operation is used to retrieve the list of filter
languages supported by the service. At the least, the
list must include the value of the defaultLanguage constant
defined above. */
LanguageSetType getFilterLanguages()
raises (itut_x780::ApplicationError);
/** This operation is used to retrieve attributes from multiple
objects using a small number of method invocations. The method
returns the first batch of results, one per object. Each
result has the name of the object and a list of name-value
pairs indicating the attributes that could be retrieved with
their values.
@param baseName The name of the object at the base of the scope
tree.
@param scope A value indicating the contained objects to
include in the scope of the operations. See
ScopeType for details.
@param filter A string containing an expression to be
evaluated with attribute values from each
object in the scope. Attribute values are
returned only for those objects for which the
expression evaluates to true.
@param language A string identifying the language in which the
filter expression is written.
@param attributes The names of the attributes for which values
should be returned. If this list is null, all
attributes are to be returned.
@param howMany The maximum number of objects for which results
should be returned in the first batch.
@param resultsIterator A reference to an iterator that can be
used to retrieve the rest of the results. This
reference will be null if all results were
returned in the first batch.
*/
GetResultsSetType scopedGet (
in NameType baseName,
in ScopeType scope,
in FilterType filter,
in LanguageType language,
in StringSetType attributes,
in unsigned short howMany,
out GetResultsIterator resultsIterator)
raises (InvalidParameter,
InvalidFilter,
FilterComplexityLimit,
itut_x780::ApplicationError);
}; // end of BasicMooService interface
// AdvancedMooService Interface
/** The advanced scoping and filtering interface provides a common
service for performing multiple-attribute updates on multiple objects,
and for deleting multiple objects.
*/
interface AdvancedMooService : BasicMooService {
/** This operation is used to modify multiple attributes in
multiple objects using a small number of method invocations.
The method returns the first batch of results, a list of
objects for which one or more modifications failed. Each
result indicates the attribute(s) on that object that could not
be updated.
@param baseName The name of the object at the base of the scope
tree.
@param scope A value indicating the contained objects to
include in the scope of the operations. See
ScopeType for details.
@param filter A string containing an expression to be
evaluated with attribute values from each
object in the scope. Updates are performed
only on those objects for which the expression
evaluates to true.
@param language A string identifying the language in which the
filter expression is written.
@param modifications The list of modifications to be made to
each object.
@param failuresOnly If true only results for failed objects
will be returned.
@param howMany The maximum number of objects for which results
should be returned in the first batch.
@param resultsIterator A reference to an iterator that can be
used to retrieve the rest of the results. This
reference will be null if all results were
returned in the first batch.
*/
UpdateResultsSetType scopedUpdate (
in NameType baseName,
in ScopeType scope,
in FilterType filter,
in LanguageType language,
in ModificationSeqType modifications,
in boolean failuresOnly,
in unsigned short howMany,
out UpdateResultsIterator resultsIterator)
raises (InvalidParameter,
InvalidFilter,
FilterComplexityLimit,
itut_x780::ApplicationError);
/** This operation is used to delete multiple objects using a
small number of method invocations. The method returns the
first batch of results, a list of the objects that could not be
deleted.
@param baseName The name of the object at the base of the scope
tree.
@param scope A value indicating the contained objects to
include in the scope of the operations. See
ScopeType for details.
@param filter A string containing an expression to be
evaluated with attribute values from each
object in the scope. Only those objects for
which the expression evaluates to true are
deleted.
@param language A string identifying the language in which the
filter expression is written.
@param failuresOnly If true only results for failed objects
will be returned.
@param howMany The maximum number of objects for which results
should be returned in the first batch.
@param resultsIterator A reference to an iterator that can be
used to retrieve the rest of the results. This
reference will be null if all results were
returned in the first batch.
*/
DeleteResultsSetType scopedDelete (
in NameType baseName,
in ScopeType scope,
in FilterType filter,
in LanguageType language,
in boolean failuresOnly,
in unsigned short howMany,
out DeleteResultsIterator resultsIterator)
raises (InvalidParameter,
InvalidFilter,
FilterComplexityLimit,
itut_x780::ApplicationError);
}; // end of AdvancedMooService interface
// Notifications Interface
/** The notifications interface defines the notifications emitted by
the framework services, not the managed objects themselves.
*/
interface Notifications {
/** The Channel Change notification is a special notification
because it is emitted by the framework (the Channel Finder) and
not a managed object. It reports the addition, deletion, or
change of a registered event channel.
@param channelModification indicates if a channel has been
added, removed, or updated.
@param channelInfo provides the information about
the affected channel.
*/
void channelChange (
in ChannelModificationType channelModification,
in ChannelInfoType channelInfo
);
/** This operation signature defines the notification emitted
by the heartbeat service.
@param systemLabel the current value of the Heartbeat
service systemLabel attribute.
@param channelID the ID of the channel through which the
notification was sent.
@param period the current value of the Heartbeat
service period attribute.
@param timeStamp the current time when the notification
is emitted.
*/
void heartbeat (
in SystemLabelType systemLabel,
in ChannelIDType channelID,
in HeartbeatPeriodType period,
in GeneralizedTimeType timeStamp
);
/** These constants defines the names of the notification
declared above and are provided to help reduce errors. */
const string channelChangeTypeName =
"itut_q816::Notifications::channelChange";
const string heartbeatTypeName =
"itut_q816::Notifications::heartbeat";
/** These constants define the names of the parameters used in
the notifications declared above and are provided to help
reduce errors. */
const string channelIDName = "channelID";
const string channelModificationName = "channelModification";
const string channelInfoName = "channelInfo";
const string periodName = "period";
const string systemLabelName = "systemLabel";
const string timeStampName = "timeStamp";
}; // end of Notifications interface
}; // end of module itut_q816
#endif // end of #ifndef ITUT_Q816_IDL