Overview | Represents a value having an arbitrary data type. |
File name | any.h |
Supported methods | Any::_nil |
Any::operator<< | |
Any::operator>> | |
Any::replace | |
Any::type |
Intended Usage
The Any class constitutes the C++ mapping of the IDL data type "any". An Any object can be used by a client or server application to represent application data whose type is not known at compile time. The Any contains both a data structure and a TypeCode that describes the data structure.
The Any class provides a non-default constructor whose parameters are: a CORBA::TypeCode_ptr (describing the type of data held by the Any), a void* pointer (the value to be contained by the Any) and a CORBA::Boolean indicating whether the Any is to assume ownership of the data. (The Any always duplicates the TypeCode rather than assuming ownership of the original.) After the Any assumes ownership of a value, the application should make no assumptions about the continued lifetime of the value. The default value for the Boolean flag is zero (indicating that the Any does not assume ownership of the value). The void* pointer given to the Any non-default constructor can be NULL.
The default constructor creates an Any with a tk_null TypeCode and no value. The copy constructor and assignment operator for Any perform deep copies of both the TypeCode and the value contained by the Any being copied.
The Any class provides insertion (<<=) and extraction (>>=) operators that allow it to hold data of simple IDL types, while maintaining type safety (preventing one from creating an Any whose TypeCode and value do not match). The operators are also convenient because they alleviate the programmer from manipulating TypeCodes; the programmer simply streams data structures into or out of the Any, and the TypeCode is implied by the C++ type of the value being inserted or extracted.
Since the IDL boolean, octet, and char types do not map to distinct C++ types, the Any class introduces helper types for each, to allow each IDL type to have distinct insertion and extration operators. These types (from_boolean, to_boolean, from_octet, to_octet, from_char, and to_char) are shown in the Types section below. To insert a boolean, octet, or char into an Any, or to extract one from an Any, construct a helper object (by passing the data to be inserted/extracted to the helper's constructor), then use the helper object with the corresponding Any insertion/extraction operator.
Similarly, because both bounded and unbounded strings in IDL map to char* in C++, the to_string and from_string helper types are introduced (see below) for inserting/extracting both bounded and unbounded strings to/from an Any. (Unbounded strings are signified by constructing the to_string or from_string helper with a bound of zero.) The nocopy_flag of the from_string helper is used for non-copying insertion of a string into an Any (in which the Any assumes ownership of the string). Unbounded strings can also be inserted into or extracted from an Any without the use of the from_string helper type by using the char* insertion and deletion operators.
The to_object helper type (see below) is used to extract an object reference from an Any as a generic CORBA::Object type. The Any extraction operator corresponding to the to_object helper type widens its contained object reference to CORBA::Object (if it contains one). No duplication of the object reference is performed by the to_object extraction operator.
In addition to the insertion/extraction operators defined in the Any class, corresponding to the basic IDL data types, the emitters generate global insertion/extraction operators for all types defined in IDL. This allows any type that can be defined in IDL to be inserted into or extracted from an Any in a type-safe manner.
In cases where the type-safe Any operators cannot be used, the Any non-default constructor (described above), the replace method, the type method, and the value method can be used to explicitly set or get the TypeCode and value contained by the Any.
Types
struct from_boolean { from_boolean(Boolean b) : val(b) {} Boolean val; }; struct from_octet { from_octet(Octet o) : val(o) {} Octet val; }; struct from_char { from_char(Char c) : val(c) {} Char val; }; struct from_string { from_string(char *s, ULong b, Boolean nocopy = 0); char *val; ULong bound; Boolean nocopy_flag; }; struct to_boolean { to_boolean(Boolean &b) : ref(b) {} Boolean &ref; }; struct to_char { to_char(Char &c) : ref(c) {} Char &ref; }; struct to_octet { to_octet(Octet &o) : ref(o) {} Octet &ref; }; struct to_object { to_object(Object_ptr &obj) : ref(obj) {} Object_ptr &ref; }; struct to_string { to_string(char * &s, ULong b) : val(s), bound(b) {} char *&val; ULong bound; };