// types.idl // $Id: types.idl,v 1.24 2003/03/12 15:56:54 lars Exp $ #ifndef ECTF_TYPES_INCLUDED #define ECTF_TYPES_INCLUDED #pragma prefix "ectf.org" #include "constants.idl" /** @defgroup types Basic Types @anchor basic_types The basic types of S.300 and M.300. ECTF specifications, such as S.100, S.410, and S.300, define basic data types in order to have a completely specified data type for the Key-Value Set (KVSet) data structure. KVSets are used to represent attributes, parameters, and other data elements within a system, and are encoded into message payloads for transfer between components, so a complete specification is necessary. While the semantics of the basic types are identical between S.100, S.410 and S.300, the exact basic data type definitions may be different. As an example, @c CTbool is an int in S.100, but ::S3bool is not mapped to an @c int in the C++ language binding. Both definitions have the same semantics, however - they can hold a value for @c true or @c false. Because the server has to translate between S.100/S.410 and S.300 KVSets, S.300 defines the shared basic types with a different prefix, @c S3 instead of @c CT. More details of this mapping can be found in S.300 Volume 2, Chapter 6. */ module ECTF { /** @ingroup types @brief A boolean. */ typedef boolean S3bool; /** @ingroup types @brief A sequence of boolean values. */ typedef sequence S3boolSeq; /** @ingroup types @brief Also known as a byte - an 8-bit quantity. */ typedef octet S3byte; /** @ingroup types @brief A sequence of bytes. */ typedef sequence S3byteSeq; /** @ingroup types @brief A signed, 32bit integer. */ typedef long S3int; /** @ingroup types @brief A sequence of signed, 32bit integers. */ typedef sequence S3intSeq; /** @ingroup types @brief An integer range with lower and upper bounds. */ struct S3irange { /// lower bound of integer range. S3int lower; /// upper bound of integer range. S3int upper; }; /** @ingroup types @brief A sequence of integer ranges. */ typedef sequence S3irangeSeq; /** @ingroup types @brief A single precision IEEE floating point number. */ typedef float S3float; /** @ingroup types @brief A sequence of single precision IEEE floating point numbers. */ typedef sequence S3floatSeq; /** @ingroup types @brief A single precision floating point range with lower and upper bounds. */ struct S3frange { /// lower bound of float range S3float lower; /// upper bound of float range S3float upper; }; /** @ingroup types @brief A sequence of single precision floating point ranges. */ typedef sequence S3frangeSeq; /** @ingroup types @brief A double precision IEEE floating point number. */ typedef double S3double; /** @ingroup types @brief A sequence of double precision IEEE floating point numbers. */ typedef sequence S3doubleSeq; /** @ingroup types @brief A double precision floating point range with lower and upper bounds. */ struct S3drange { /// lower bound of float range. S3double lower; /// upper bound of float range. S3double upper; }; /** @ingroup types @brief A sequence of double precision floating point ranges. */ typedef sequence S3drangeSeq; /** @ingroup types @brief The S.300 string type. By default, S.300 strings are encoded in UTF-8, which can represent any Unicode/ISO10646 character. */ typedef string S3string; /** @ingroup types @brief A sequence of strings. */ typedef sequence S3stringSeq; /** @ingroup types @brief Defines the various type of result that an operation can return. This shares the values from the @c CTstatus enumeration from S.100. */ enum S3status { /// Indicates that an operation has succeeded. statusOK, /** Indicates that an operation has succeeded and there is further information in the error fields. */ statusWarning, /// Not used in S.300. statusStarted, /** Indicates that an operation failed. The error fields will indicate the reason for this failure */ statusFail, /** Indicates that an operation failed in a manner that may not be recoverable. The error fields will indicate the reason for this failure. */ statusFatal, /** Not used in S.300 */ statusDestroy }; /** @ingroup types @brief A sequence of status values. @note This definition exists because of @c CTkvs_[Put|Get]StatusArray. */ typedef sequence S3statusSeq; /** @ingroup types @brief A namespace controlled unique id. ::S3symbol is a namespace controlled bit field, 32 bits wide. The specifics of the namespace control are documented in S.100 revision 2, volume 3, section 3. */ typedef unsigned long S3symbol; /** @ingroup types @brief A sequence of symbols. */ typedef sequence S3symbolSeq; /** @ingroup types @brief This type is used for file date/times Most times in S.100/S.410 use intervals, which is expressed as millisecond offsets. */ #ifdef HAVE_CORBA_LONG_LONG typedef unsigned long long S3fileTime; #else typedef unsigned long S3fileTime; #endif /** @ingroup types @brief A sequence of file times. */ typedef sequence S3fileTimeSeq; /** @ingroup types @brief A sequence of (CORBA) object references. */ typedef sequence S3objectSeq; /** @ingroup types @brief Transaction identifier. ::S3tranID is an example of a 'Asynchronous Completion Token' pattern. It is used to: - correlate completion operations with asynchronous operations - stop asynchronous operations */ typedef long S3tranID; /** @ingroup types @brief This special Transaction ID matches all pending operations. */ const S3tranID anyTranID = CTses_intAllTransactions; /** @ingroup types @brief This transaction ID is reserved for internal use. */ const S3tranID noTranID = CTses_intNoTransaction; /** @defgroup kvset Key Value Sets A Key Value Set (KVS) is a generic and extensible data structure. Key Value Sets are used to contain most data structures that are passed from client applications (written to S.100 or S.410) to S.300. The use of Key Value Sets allows for future extension of the standard with minimal impact and also enables vendor extensions to the standard. Key Value Sets are explained in S100 rev. 2, volume 2, sections 1.2 and 1.3 The S.300 version of Key Value Sets is a representation of KVS data in IDL. Some types that are available in S.100 and S.410 are not available, because they do not contain entities visible at the S.300 level. These are mainly the handle types. This definition does not (and can not) provide the functionality of the S.100 @c CTkvs family of functions or the functionality of the Java @c Dictionary class. In particular, the uniqueness of keys is not enforced automatically. Users of the S.300 Key Value Sets need to enforce uniqueness of keys themselves or use a wrapper class. A C++ example of a KVS wrapper class can be found in the S.300 examples section. The values for types are shared between all %ECTF specifications using Key Value Sets. */ /** @ingroup kvset @brief Contains a single data item in a ::S3kvs. The @a key of a S3kvPair names the data item, while the @a value contains the actual data. The types which may be used in the @a value part of a S3kvPair are restricted to those corresponding to the @link kvset_constants here @endlink - they are prefixed with @c CTkvs_valtyp. The type values are shared between S.100, S.410 and S.300. The ::S3kvPair does not enforce this restriction: it is up to the user (or a wrapper class) to do so. */ struct S3kvPair { /** @brief The key of a KVPair. */ S3symbol key; /** @brief The value of a KVPair. */ any value; }; /** @ingroup kvset @brief An ::S3kvs is a sequence of S3kvPair. The ::S3kvs does not implicitly enforce uniqueness of the keys. It is up to the user (respectively a wrapper class) to enforce this property. */ typedef sequence S3kvs; /** @ingroup kvset @brief A sequence of ::S3kvs. */ typedef sequence S3kvsSeq; /** @ingroup resource @brief Information relevant to the start of asynchronous commands, in particular all resource specific commands. */ struct S3InfoIn { /** @brief The object requesting the operation. The completion operation must be invoked on this object reference. */ Object requestor; /** @brief The transaction ID of the command. This transaction id must be returned in S3InfoOut when the command has completed. */ S3tranID tid; /** @brief Optional parameters for the command. This KVSet may contain optional parameters valid only for the duration of the command. This KVSet may also contain vendor-defined parameters. */ S3kvs optArgs; }; /** @ingroup types @brief A utility type for return values. */ struct S3result { /** @brief The status of the command. */ S3status status; /** @brief The error of the command. Errors are symbols. Errors defined by the %ECTF are in the @c Error_ECTF symbol namespace. Vendor defined errors should be defined in the @c Error_ namespace. If the value is ::CT_statusOK, the #error and #suberror values must be ignored by the receiver, but it is recommended to set them to ::Error_ECTF_OK and @c 0 nonetheless. */ S3symbol error; /** @brief An implementation specific additional error value. This value is intended for diagnostic purposes; its use is highly recommended, but not mandatory. */ S3int suberror; }; /** @ingroup types @brief Information relevant to the completion of any command. This struct is returned with the completion function from any command. */ struct S3InfoOut { /** @brief The transaction ID of the command. This must be the same transaction ID that was passed to the command. */ S3tranID tid; /** @brief The qualifier of the operation. The qualifier is only used in conjunction with Resource-specific commands (like PlayerClient::PlayDone). For operations that are not resource specific, set the qualifier to Any_ECTF_Standard. The qualifier is always ignored if result.status is not equal #CT_statusOK. */ S3symbol qualifier; /** @brief The result of the command including status, error and suberror. */ S3result result; /// Optional data. This may be used for vendor extensions. S3kvs optArgs; }; /** @ingroup types @brief A handle type that is returned by various registration functions. */ typedef unsigned long S3handle; /** @ingroup types @brief This handle value is guaranteed to be invalid. */ const S3handle invalidHandle = 0; /** @ingroup types @brief A sequence of handles. */ typedef sequence S3handleSeq; /** @ingroup types @brief Invalid Argument exception. This exception corresponds to the S.100/S.410 symbol Error_ECTF_BadArg. */ exception InvalidArgument { /** @brief An implementation defined qualifier for diagnostic purposes. */ S3int suberror; }; /** @ingroup types @brief Object not found exception. */ exception ObjectNotFound { /** @brief An implementation defined qualifier for diagnostic purposes. */ S3int suberror; }; /** @ingroup types @brief No resources exception. This exception corresponds to the S.100/S.410 symbol Error_ECTF_ResourceUnavailable. */ exception NoResources { /** @brief An implementation defined qualifier for diagnostic purposes. */ S3int suberror; }; /** @ingroup types @brief System error exception. This exception corresponds to the S.100/S.410 symbol Error_ECTF_System. */ exception SystemError { /** @brief An implementation defined qualifier for diagnostic purposes. */ S3int suberror; }; /** @ingroup types @brief Invalid Argument exception. */ exception DuplicateEntry { /** @brief An implementation defined qualifier for diagnostic purposes. */ S3int suberror; }; }; #endif