VisiBroker for C++ API Reference Guide : Introduction to VisiBroker : Dynamic interfaces and classes

Dynamic interfaces and classes
This section describes the classes that support the Dynamic Invocation Interface used by client applications and the Dynamic Skeleton Interface used by object servers.
Any
The CORBA::Any class is used to represent an IDL type so that its value may be passed in a type-safe manner. Objects of this class have a pointer to a TypeCode that defines the object's type and a pointer to the value associated with the object. Methods are provided to construct, copy, and destroy an object as well as to initialize and query the object's type and value. In addition, streaming operators are provided to read and write the object to a stream.
The code sample below provides an example of how to create and use an Any.
// create an any object
CORBA::Any anObject;
// use the typecode operator to specify that
// 'anObject' object can store long
anObject <<= CORBA::_tc_long;
Include file
Include the CORBA.h file when you use this structure.
Any methods
CORBA::Any();
This is the default constructor. It creates an empty Any object.
CORBA::Any(const CORBA::Any& val);
This is a copy constructor; it creates an Any object that is a copy of the specified target.
CORBA::Any(CORBA::TypeCode_ptr tc,
void *
value, CORBA::Boolean release = 0);
This constructor creates an Any object initialized with the specified value and TypeCode.
If set to TRUE, the memory associated with this Any object's value is released when this Any object is destroyed.
static CORBA::Any-_ptr _duplicate(CORBA::Any_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to it.
The Any to be duplicated.
static CORBA::Any_ptr _nil();
This static method returns a NULL pointer that can be used for initialization purposes.
static void _release(CORBA::Any_ptr *ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
The Any to be released.
Insertion operators
void operator<<=(CORBA::Short);
void operator<<=(CORBA::UShort);
void operator<<=(CORBA::Long);
void operator<<=(CORBA::ULong);
void operator<<=(CORBA::Float);
void operator<<=(CORBA::Double);
void operator<<=(const CORBA::Any&);
void operator<<=(const char *);
void operator<<=(CORBA::LongLong);
void operator<<=(CORBA::ULongLong);
void operator<<=(CORBA::LongDouble);
These operators initialize this object with the specified value, automatically setting the appropriate TypeCode for the value. If this Any object was constructed with the release flag set to TRUE, the value previously stored in this Any object is released before the new value is assigned.
void operator<<=(CORBA::TypeCode_ptr tc);
This method initializes this object with the specified TypeCode of the value.
Extraction operators
CORBA::Boolean operator>>=(CORBA::Short&) const;
CORBA::Boolean operator>>=(CORBA::UShort&) const;
CORBA::Boolean operator>>=(CORBA::Long&) const;
CORBA::Boolean operator>>=(CORBA::ULong&) const;
CORBA::Boolean operator>>=(CORBA::Float&) const;
CORBA::Boolean operator>>=(CORBA::Double&) const;
CORBA::Boolean operator>>=(CORBA::Any&) const;
CORBA::Boolean operator>>=(const char *&) const;
CORBA::Boolean operator>>=(CORBA::LongLong&) const;
CORBA::Boolean operator>>=(CORBA::ULongLong&) const;
CORBA::Boolean operator>>=(CORBA::LongDouble&) const;
These operators store the value from this object into the specified target. If the TypeCode of the target does not match the TypeCode of the stored value, FALSE is returned and no value is extracted. Otherwise, the stored value is assigned to the target and TRUE is returned.
Deprecated operator
The following extraction operator is deprecated:
CORBA::Boolean operator>>=(char *&) const;
It is supported for backward compatibility, but Micro Focus recommend that where possible, you use an operator in the above list instead.
CORBA::Boolean operator>>=(CORBA::TypeCode_ptr& tc) const;
This method extracts the TypeCode of the value stored in this object.
ContextList
class CORBA::ContextList
This class contains a list of contexts that may be associated with an operation request. See “Request” on page 69 for more information.
ContextList methods
CORBA::ContextList();
This method constructs an empty Context list.
~CORBA::ContextList();
This method is the default destructor.
void add(const char *ctx);
This method adds the specified context to this object's list.
void add_consume(char *ctx);
This method adds the specified context code to this object's list. ThisContextList becomes the owner of the context specified by the argument. You should not attempt to access or free this Context after you invoke this method.
CORBA::ULong count() const;
This method returns the number of items currently stored in the list.
const char *item(CORBA::ULong index);
This method returns a pointer to the context that is stored in the list at the specified index. If the index is invalid, a NULL pointer is returned. You should not attempt to free the returned context. To remove a context, use the remove method instead.
void remove(CORBA::ULong index);
This method removes the context with the specified index from the list. If the index is invalid, no removal will occur.
static CORBA::ContextList-_ptr _duplicate(CORBA::ContextList_ptr ptr);
This static method increments the reference count for the object and then returns a pointer to it.
static CORBA::ContextList_ptr _nil();
This static method returns a NULL pointer that can be used for initialization purposes.
static void _release(CORBA::ContextList *ptr);
This static method decrements the reference count for this object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
DynamicImplementation
class PortableServer::DynamicImplementation : public
PortableServer::ServantBase
This base class is used derive object implementations that use the Dynamic Skeleton Interface instead of a skeleton class generated by the IDL compiler. You must provide implementations of the invoke and _primary-interface() methods when deriving from this class.
DynamicImplementation methods
virtual void invoke(CORBA::ServerRequest_ptr request) = 0;
This method is invoked by the POA whenever client operation requests are received for your object implementation. You must provide an implementation of this method which validates the ServerRequest object's contents, performs the necessary processing to fulfill the request, and returns the results to the client. For more information on the ServerRequest class, see “ServerRequest” on page 72.
The ServerRequest object that represents the client's operation request.
virtual CORBA::RepositoryId _primary_interface(
const PortableServer::ObjectId&
oid PortableServer::POA_ptr poa) const;
This method will be invoked as a callback by the POA. The servants that inherit from the DynamicImplementation class must implement it. This method should be called directly or unpredictable behavior will result. Invoking this method under other circumstances may lead to unpredictable results. The _primary_interface method receives an ObjectId value and a POA_ptr as input parameters and returns a valid RepositoryId representing the most-derived interface for that oid.
DynAny
class DynamicAny::DynAny : public CORBA::LocalObject
A DynAny object is used by a client application or server to create and interpret data types at runtime which were not defined at compile time. A DynAny may contain a basic type (such as a boolean, int, or float) or a complex type (such as a struct or union). The type contained by a DynAny is defined when it is created and may not be changed during the lifetime of the object.
A DynAny object may represent a data type as one or more components, each with its own value. The next, seek, rewind, and current_component methods are provided to help you navigate through the components.
A DynAnyFactory is created by calling ORB::resolve_initial_references("DynAnyFactory"). The factory is then used to create basic or complex types. The DynAnyFactory belongs to the DynamicAny module.
DynAny objects for basic types are created using the DynAnyFactory::create_dyn_any_from_type_code method. A DynAny object may also be created and initialized from an Any object using the DynAnyFactory::create_dyn_any method.
The following interfaces are derived from DynAny and provide support for constructed types that are managed dynamically.
Include file
The dynany.h file should be included when you use this class.
Important usage restrictions
DynAny objects cannot be used as parameters on operation requests or DII requests, nor can they be externalized using the ORB::object_to_string method. However, you may use the DynAny::to_any method to convert a DynAny object into an Any, which can be used as a parameter.
DynAny methods
void assign(DynamicAny::DynAny_ptr dyn_any);
Initializes the value in this DynAny object from the specified DynAny.
A type mismatch exception is raised if the type contained in the Any does not match the type contained by this object.
DynamicAny::DynAny_ptr copy();
Returns a copy of this object.
virtual CORBA::ULong component_count( );
Returns the number of components for the complex type stored inside the DynAny as an unsigned long.
virtual DynamicAny::DynAny_ptr current_component();
Returns the current component in this object.
virtual void destroy();
Destroys this object.
virtual CORBA::Boolean equal(const DynamicAny::DynAny_ptr value);
Compares two DynAny values for equality. Returns TRUE if they are equal, FALSE otherwise.
virtual void from_any(const CORBA::Any& value);
Initializes the current component of this object from the specified Any object.
A type mismatch exception is raised if the TypeCode of value contained in the Any does not match the TypeCode that was defined for this object when it was created.
If the value parameter passed is not legal, the operation raises an InvalidValue exception.
An Any object containing the value to set for this object.
virtual CORBA::Boolean next();
Advances to the next component, if one exists, and returns TRUE. If there are no more components, this method returns FALSE.
virtual void rewind();
Sets the current component of this object to be the first component defined in this DynAny.
If this object contains only one component, invoking this method has no effect.
virtual CORBA::Boolean seek(CORBA::Long index);
Makes the component with the specified index the current component. If there is no component at the specified index, this method returns FALSE, otherwise it returns TRUE.
virtual CORBA::Any* to_any( );
Converts the DynAny object into an Any object and returns a pointer to the Any object.
CORBA::TypeCode_ptr type();
Returns the TypeCode of the value stored in the DynAny.
Extraction methods
The DynAny extraction methods return the type contained in this DynAny object's current component. The list below shows the name of each of the extraction methods.
A TypeMismatch exception is raised if the value contained in this DynAny does not match the expected return type for the extraction method used.
Extraction methods offered by the DynAny class are:
virtual CORBA::Any* get_any();
virtual CORBA::Boolean get_boolean();
virtual CORBA::Char get_char();
virtual CORBA::Double get_double();
virtual DynamicAny::DynAny* get_dyn_any();
virtual CORBA::Float get_float();
virtual CORBA::Long get_long();
virtual CORBA::LongLong get_longlong();
virtual CORBA::Octet get_octet();
virtual CORBA::Object_ptr get_reference();
virtual CORBA::Short get_short();
virtual char* get_string();
virtual CORBA::TypeCode_ptr get_typecode();
virtual CORBA::ULong get_ulong();
virtual CORBA::UlongLong get_ulonglong();
virtual CORBA::UShort get_ushort();
virtual CORBA::ValueBase* get_val();
virtual CORBA::WChar get_wchar();
virtual CORBA::WChar* get_wstring();

Solaris, AIX, HP-UX, and Linux 64-bit:
virtual CORBA::LongDouble get_longdouble();
Insertion methods
An insertion method copies a value of a particular type to this DynAny object's current component. Following is the list of methods provided for inserting various types.
These methods raise an InvalidValue exception if the inserted object's type does not match the DynAny object's type.
Insertion methods offered by the DynAny class are:
virtual void insert_any(const CORBA:Any& value);
virtual void insert_boolean(CORBA::Boolean value);
virtual void insert_char(CORBA::Char value);
virtual void insert_double(CORBA::Double value);
virtual void insert_dyn_any (const DynamicAny::DynAny_ptr
value);
virtual void insert_float(CORBA::Float value);
virtual void insert_long(CORBA::Long value);
virtual void insert_longlong(CORBA::LongLong value);
virtual void insert_octet(CORBA::Octet value);
virtual void insert_reference(CORBA:Object_ptr value);
virtual void insert_short(CORBA::Short value);
virtual void insert_string(const char* value);
virtual void insert_typecode(CORBA:TypeCode_ptr value);
virtual void insert_ulong(CORBA::ULong value);
virtual void insert_ulonglong(CORBA::ULongLong value);
virtual void insert_ushort(CORBA::UShort value);
virtual void insert_val(const CORBA::ValueBase& value);
virtual void insert_wchar(CORBA::WChar value);
virtual void insert_wstring(const CORBA::WChar* value);

Solaris
, AIX, HP-UX, and Linux 64-bit:
virtual void insert_longdouble(CORBA::LongDouble value); Solaris only
DynAnyFactory
class DynamicAny::DynAnyFactory : public CORBA::LocalObject
A DynAnyFactory object is used to create a new DynAny object. To obtain a reference to the DynAnyFactory object, call ORB::resolve_initial_references("DynAnyFactory").
DynAnyFactory methods
DynAny_ptr create_dyn_any (const CORBA::Any& value);
Creates a DynAny object of the specified value
A new DynAny object of a specified value.
DynAny_ptr create_dyn_any_from_type_code (CORBA::TypeCode_ptr type);
Creates a DynAny object of the specified type.
The type of the new DynAny object.
DynArray
class DynamicAny::DynArray : public VISDynComplex
Objects of this class are used by a client application or server to create and interpret array data types at runtime which were not defined at compile time. A DynArray may consist of a sequence of basic types (such as a boolean, int, or float) or constructed types (such as struct or union). The type contained by a DynArray is defined when it is created and may not be changed during the lifetime of the object.
The next, rewind, seek, and current_component methods, inherited from DynAny, may be used to navigate through the components.
The VISDynComplex class is a helper class that allows the VisiBroker ORB to manage complex DynAny types.
Important usage restrictions
DynArray objects cannot be used as parameters on operation requests or DII requests, nor can they be externalized using the ORB::object_to_string method. However, you may use the DynAny::to_any method to convert a DynArray object to a sequence of Any objects, which can be used as a parameter.
DynArray methods
virtual void destroy();
Destroys this object.
CORBA::AnySeq* get_elements();
Returns a sequence of Any objects containing the values stored in this object.
void set_elements(const CORBA::AnySeq& _value);
Assigns the elements in the DynArray to those in the sequence specified by the value parameter.
DynamicAny::DynAnySeq* get_elements_as_dyn_any();
Returns the elements contained in the DynAny as a DynAny sequence.
void set_elements_as_dyn_any (const DynamicAny::DynAnySeq& value);
Sets the elements contained in the object from the specified DynAny sequence.
An InvalidValue exception is raised if the number of elements in value is not equal to the number of elements in this DynArray. A type mismatch exception is raised if the type of the Any values do not match the TypeCode of the DynAny.
An array of Any objects whose values will be set in this DynArray.
DynEnum
class DynamicAny::DynEnum : public DynamicAny::DynAny
Objects of this class are used by a client application or server to create and interpret enumeration values at runtime which were not defined at compile time.
Since objects of this type contains a single component, the DynAn::rewind and DynAny::next methods of a DynEnum object always return FALSE.
Important usage restrictions
DynEnum objects cannot be used as parameters on operation requests or DII requests, nor can they be externalized using the ORB::object_to_string method. However, you may use the to_any method to convert a DynEnum object to an Any, which can be used as a parameter.
DynEnum methods
void from_any(const CORBA::Any& value);
Initializes the value of this object using the specified Any object.
An Invalid exception is raised if the TypeCode of value contained in the Any does not match the TypeCode defined for this object when it was created.
An Any object.
CORBA::Any* to_any();
Returns an Any object containing the value of the current component.
char* get_as_string();
Returns the DynEnum object's value as a string.
void set_as_string(const char* value_as_string);
Sets the value of this DynEnum to the specified string.
CORBA::ULong get_as_ulong()
Returns an unsigned long containing the DynEnum object's value.
void set_as_ulong(CORBA::ULong value_as_ulong)
Sets the value of this DynEnum to the specified CORBA::Ulong.
DynSequence
class DynamicAny::DynSequence : public DynamicAny::DynArray
Objects of this class are used by a client application or server to create and interpret sequence data types at runtime which were not defined at compile time. A DynSequence may contain a sequence of basic types (such as a boolean, int, or float) or constructed types (such as a struct or union). The type contained by a DynSequence is defined when it is created and may not be changed during the lifetime of the object.
The next, rewind, seek, and current_component methods may be used to navigate through the components.
Important usage restrictions
DynSequence objects cannot be used as parameters on operation requests or DII requests nor can they be externalized using the ORB::object_to_string method. However, you may use the to_any method to convert a DynSequence object to a sequence of Any objects. You can use the sequence of Any objects as a parameter.
DynSequence methods
CORBA::ULong get_length();
Returns the number of elements contained in this DynSequence.
void set_length(CORBA::ULong length);
Sets the number of elements contained in this DynSequence.
If you specify a length that is less than the current number of elements, the sequence is truncated.
CORBA::AnySeq * get_elements();
Returns a sequence of Any objects containing the value stored in this object.
void set_elements (const AnySeq& _value)
Sets the elements within this object with specified sequence of Any objects.
set _elements_as_dyn_any();
See “DynArray” on page 57 for more details.
get_elements_as_dyn_any();
See “DynArray” on page 57 for more details.
DynStruct
class DynamicAny::DynStruct :public VISDynComplex
Objects of this class are used by a client application or server to create and interpret structures at runtime which were not defined at compile time.
The next, rewind, seek, and current_component methods may be used to navigate through the structure members.
You create an DynStruct object by invoking the DynAnyFactory::create_dyn_any_from_typecode method.
Important usage restrictions
DynStruct objects cannot be used as parameters on operation requests or DII requests, nor can they be externalized using the ORB::object_to_string method. However, you may use the to_any method to convert a DynStruct object to an Any object, which can be used as a parameter.
DynStruct methods
void destroy();
Destroys this object.
CORBA::FieldName current_member_name();
Returns the member name of the current component.
CORBA::TCKind current_member_kind();
Returns the TypeCode associated with the current component.
DynamicAny::NameValuePairSeq get_members();
Returns the members of the structure as a sequence of NameValuePair objects.
void set_members(const DynamicAny::NameValuePairSeq& value);
Sets the structure members from the array of NameValuePair objects.
DynamicAny::NameDynAnyPairSeq get_members_as_dyn_any();
Returns the members of the structure as a NameDynAnyPair sequence.
void set_members_as_dyn_any(const DynamicAny::NameDynAnyPairSeq value);
Sets the structure members from NameDynAnyPair objects.
An InvalidValue exception is raised if the length of the value sequence is not equal to the number of members of DynStruct, and a TypeMismatch exception is raised when any of the element's typecode does not match that of the structure.
DynUnion
class DynamicAny::DynUnion : public VISDynComplex
This interface is used by a client application or server to create and interpret unions at runtime which were not defined at compile time. The DynUnion contains a sequence of two elements: the union discriminator and the actual member.
The next, rewind, seek, and current_component methods may be used to navigate through the components.
You create a DynUnion object by invoking the DynamicAny::DynAnyFactory::create_dyn_any_from_type_code method and passing a union type code as an argument.
Important usage restrictions
DynUnion objects cannot be used as parameters on operation requests or DII requests nor can they be externalized using the ORB::object_to_string method. However, you may use the DynAny::to_any method to convert a DynUnion object to an Any object which can be used as a parameter.
DynUnion methods
DynamicAny::DynAny_ptr get_discriminator();
Returns a DynAny object containing the discriminator for the union.
CORBA::TCKind discriminator_kind();
Returns the type code of the discriminator for the union.
DynamicAny::DynAny_ptr member();
Returns a DynAny object for the current component which represents a union member.
CORBA::TCKind member_kind();
Returns the type code for the current component, which represents a member in the union.
CORBA::FieldName member_name();
Returns the member name of the current component.
void set_discriminator (const DynamicAny::DynAny_ptr value);
Sets the discriminator of this DynUnion to the specified value.
void set_to_default_member();
Sets the discriminator to a value that is consistent with the value of the default case of a union.
void set_to_no_active_member();
Sets the discriminator to a value that does not correspond to any of the union's case labels.
CORBA::Boolean has_no_active_member();
Returns TRUE if the union has no active member (that is, the union's value consists solely of its discriminator because the discriminator has a value that is not listed as an explicit case label).
Environment
class CORBA::Environment
The Environment class is used for reporting and accessing both system and user exceptions on platforms where C++ language exceptions are not supported. When an interface specifies that user exceptions may be raised by the object's methods, the Environment class becomes an explicit parameter of that method. If an interface does not raise any exceptions, the Environment class is an implicit parameter and is only used for reporting system exceptions. If an Environment object is not passed from the client to a stub, the default of per-object Environment is used.
Multithreaded applications have a global Environment object for each thread that is created. Applications that are not multithreaded have just one global Environment object.
Include file
You should include the corba.h file when you use this class.
Environment methods
void ORB::create_environment(COBRA::Environment_out ptr);
This method can be used to create a new Environment object.
Note
This method is provided for CORBA compliance. You may find it easier to use the constructor provided for this class or the C++ new operator.
Environment();
This method creates an Environment object. This is equivalent to calling the ORB::create_environment method.
static COBRA::Environment& CORBA::current_environment();
This static method returns a reference to the global Environment object for the application process. In multithreaded applications, it returns the global Environment object for this thread.
void exception(COBRA::Exception *exp);
This method records the Exception object passed as an argument. The Exception object must be dynamically allocated because the specified object will assume ownership of the Exception object and will delete it when the Environment itself is deleted. Passing a NULL pointer to this method is equivalent to invoking the clear method on the Environment.
A pointer to a dynamically allocated Exception object to be recorded for this Environment.
CORBA::Exception *exception() const;
This method returns a pointer to the Exception currently recorded in this Environment. You must not invoke delete on the Exception pointer returned by this call. If no Exception has been recorded, a NULL pointer is returned.
void clear();
This method deletes any Exception object that it holds. If this object holds no exception, this method has no effect.
ExceptionList
class CORBA::ExceptionList
This class contains a list of type codes that represent exceptions that may be raised by an operation request. See “Request” on page 69.
ExceptionList methods
CORBA::ExceptionList();
This method constructs an empty exception list.
CORBA::ExceptionList(CORBA::ExceptionList& list);
This is a copy constructor.
~CORBA::ExceptionList();
This method is the default destructor.
void add(CORBA::TypeCode_ptr tc);
This method adds the specified exception type code to this object's list.
void add_consume(CORBA::TypeCode_ptr tc);
This method adds the specified exception type code to this object's list. Ownership of the passed argument is assumed by this ExceptionList. You should not attempt to access or free the argument after invoking this method.
CORBA::ULong count() const;
This method returns the number of items currently stored in the list.
CORBA::TypeCode_ptr item(CORBA::ULong index);
This method returns a pointer to the TypeCode stored in the list at the specified index. If the index is invalid, a NULL pointer is returned. You should not attempt to access or free the argument after invoking this method. To remove a TypeCode from the list, use the remove method.
void remove(CORBA::long index);
This method removes the TypeCode with the specified index from the list. If the index is invalid, no removal occurs.
static CORBA::ExceptionList-_ptr _duplicate(
CORBA::ExceptionList_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to that object.
static CORBA::ExceptionList_ptr _nil();
This static method returns a NULL pointer that can be used for initialization purposes.
static void _release(CORBA::ExceptionList *ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
NamedValue
class CORBA::NamedValue
The NamedValue class is used to represent a name-value pair used as a parameter or return value in a Dynamic Invocation Interface request. Objects of this class are grouped into an NVList, described in “NVList” on page 66. The value of the name-value pair is represented by using an Any object. The Request class is described in “Request” on page 69.
Include file
You should include the file corba.h when using this class.
NamedValue methods
CORBA::Flags flags() const;
This method returns the flag defining how this name-value pair is to be used. It returns one of the following:
When combined with the ARG_INOUT flag, this flag indicates that the ORB copies the output parameter. This allows the ORB to release memory associated with this parameter without impacting the client application's memory.
const char *name() const;
This method returns the name portion of this object's name-value pair. You should never release the storage pointed to by the return argument.
CORBA::Any *value() const;
This method returns the value portion of this object's name-value pair. You should never release the storage pointed to by the return argument.
static CORBA::NamedValue-_ptr _duplicate(CORBA::NamedValue_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to it.
static CORBA::NamedValue_ptr _nil();
This static method returns a NULL pointer that can be used to initialize a CORBA::NamedValue_ptr.
static void _release(CORBA::NamedValue *ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
NVList
class CORBA::NVList
The NVList class is used to contain a list of NamedValue objects, described in “NamedValue” on page 65. It is used to pass parameters associated with a Dynamic Invocation Interface request. The Request class is described in “Request” on page 69.
Several methods are provided for adding items to the list. You should never release the storage pointed to by the return argument. Always use the remove method to delete an item from the list.
Include file
You should include the file corba.h when using this class.
NVList methods
CORBA::NamedValue_ptr add(CORBA::Flags flags);
This method adds a NamedValue object to this list, initializing only the flags. Neither the name or value of the added object are initialized. A pointer is returned which can be used to initialize the name and value attributes of the NamedValue. You should never release the storage associated with the return argument.
The flag indicating the intended use of the NamedValue object. It can be one of ARG_IN, ARG_OUT, or ARG_INOUT.
CORBA::NamedValue_ptr add_item(const char *name, CORBA::Flags flag);
This method adds a NamedValue object to this list, initializing the object's flag and name attributes. A pointer is returned which can be used to initialize the value attribute of the NamedValue.
Caution
You should never release the storage associated with the return argument.
The flag indicating the intended use of the NamedValue object. It can be one of ARG_IN, ARG_OUT, or ARG_INOUT.
NamedValue_ptr add_item_consume(char *nm, CORBA::Flags flag);
This method is the same as the add_item method, except that the NVList takes over the management of the storage pointed to by nm. You will not be able to access nm after this method is called because the list may have copied and released it. When this item is removed, the storage associated with it is automatically freed.
Caution
You should never release the memory associated with this method's return value.
The flag indicating the intended use of the NamedValue object. It must be one of ARG_IN, ARG_OUT, or ARG_INOUT.
CORBA::NamedValue_ptr add_value(const char *name, const CORBA::Any *value,CORBA::Flags flag);
This method adds a NamedValue object to this list, initializing the name, value, and flag. A pointer to the NamedValue object is returned.
Caution
You should never release the storage associated with the return argument.
The flag indicating the intended use of the NamedValue object. It can be one of ARG_IN, ARG_OUT, or ARG_INOUT.
NamedValue_ptr add_value_consume(char *nm, CORBA::Any *value, CORBA::Flags flag);
This method is the same as the add_value method, except that the NVList takes over the management of the storage pointed to by nm and value. You will not be able to access nm or value after this method is called because the list may have copied and released them. When this list element is removed, the storage associated with it is automatically freed.
The flag indicating the intended use of the NamedValue object. It must be one of ARG_IN, ARG_OUT, or ARG_INOUT.
CORBA::Long count() const;
This method returns the number of NamedValue objects in this list.
static CORBA::Boolean CORBA::is_nil(NVList_ptr obj);
This method returns TRUE if the specified NamedValue pointer is NULL.
NamedValue_ptr item(CORBA::ULong index);
This method returns the NamedValue in the list with the specified index.
Caution
Never release the storage associated with the return argument.
static void CORBA::release(CORBA::NVList_ptr obj);
This static method releases the specified object.
void remove(CORBA::ULong index);
This method deletes the NamedValue object located at the specified index from this list. Storage associated with items in the list that were added using the add_item_consume or add_value_consume methods is released before the item is removed.
The index of the NamedValue object. Note that indexing is zero-based.
static CORBA::NVList_ptr _duplicate(CORBA::NVList_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to that object.
static CORBA::NVList_ptr _nil();
This static method returns a NULL pointer that can be used to initialize an NV_List pointer. For example, you might do something like this: CORBA::NV_List_ptr p = CORBA::NVList::_nil();
static void _release(CORBA::NVList *ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
Request
class CORBA::Request
The Request class is used by client applications to invoke an operation on an ORB object using the Dynamic Invocation Interface. A single ORB object is associated with a given Request object. The Request represents an operation that is to be performed on the ORB object. It includes the arguments to be passed, the Context, and an Environment object, if any. Methods are provided for invoking the request, receiving the response from the object implementation, and retrieving the result of the operation.
You can create a Request object by using the Object::_create_request. For more information, go to “Core interfaces and classes”.
Note
A Request object retains ownership of all return parameters, so you should never attempt to free them.
Include file
Include the corba.h file when you use this class.
Request methods
CORBA::Any& add_in_arg();
This method adds an unnamed input argument to this Request and returns a reference to the Any object so that you can set its name, type, and value.
CORBA::Any& add_in_arg(const char *name);
This method adds a named input argument to this Request and returns a reference to the Any object so that you can set its type and value.
Caution
You should never release the memory associated with this method's return value.
CORBA::Any& add_inout_arg();
This method adds an unnamed inout argument to this Request and returns a reference to the Any object so that you can set its name, type, and value.
CORBA::Any& add_inout_arg(const char *name);
This method adds a named inout argument to this Request and returns a reference to the Any object so that you can set its type and value.
CORBA::Any& add_out_arg();
This method adds an unnamed output argument to this Request and returns a reference to the Any object so that you can set its name, type, and value.
CORBA::Any& add_out_arg(const char *name);
This method adds a named output argument to this Request and returns a reference to the Any object so that you can set its type and value.
CORBA::NVList_ptr arguments();
This method returns a pointer to an NVList object containing the arguments for this request. The pointer can be used to set or retrieve the argument values. For more information on NVList, see “NVList” on page 66.
Caution
You should never release the memory associated with this method's return value.
CORBA::ContextList_ptr contexts();
This method returns a pointer to a list of all the Context objects that are associated with this Request. For more information on the Context class, go to “Core interfaces and classes”.
Caution
You should never release the memory associated with this method's return value.
CORBA::Context_ptr ctx() const;
This method returns a pointer to the Context associated with this request.
void ctx(CORBA::Context_ptr ctx);
This method sets the Context to be used with this request. For more information on the Context class, go to “Core interfaces and classes”.
CORBA::Environment_ptr env();
This method returns a pointer to the Environment associated with this request. For more information on the Environment class, go to “Environment” on page 62.
CORBA::ExceptionList_ptr exceptions();
This method returns a pointer to a list of all the exceptions that this request may raise.
Caution
You should never release the memory associated with this method's return value.
void get_response();
This method is used after the send_deferred method has been invoked to retrieve a response from the object implementation. If there is no response available, this method blocks the client application until a response is received.
void invoke();
This method invokes this Request on the ORB object associated with this request. This method blocks the client until a response is received from the object implementation. This Request should be initialized with the target object, operation name and arguments before this method is invoked.
const char* operation() const;
This method returns the name of the operation that this request performs.
CORBA::Boolean poll_response();
This non-blocking method is invoked after the send_deferred method to determine if a response has been received. This method returns TRUE if a response has been received, otherwise it returns FALSE.
CORBA::NamedValue_ptr result();
This method returns a pointer to a NamedValue object where the return value for the operation will be stored. The pointer can be used to retrieve the result value after the request has been processed by the object implementation. For more information on the NamedValue class, go to “NamedValue” on page 65.
CORBA::Any& return_value();
This method returns a reference to an Any object that represents the return value of this Request object.
void set_return_type(CORBA::TypeCode_ptr tc);
This method sets the TypeCode of the return value that is expected. You must set the return value's type before using the invoke method or one of the send methods.
void send_deferred();
Like the invoke method, this method sends this Request to the object implementation. Unlike the invoke method, this method does not block waiting for a response. The client application can retrieve the response using the get_response method.
void send_oneway();
This method invokes this Request as a oneway operation. Oneway operations do not block and do not result in a response being sent from the object implementation to the client application.
CORBA::Object_ptr target() const;
This method returns a reference to the target object on which this request will operate.
static CORBA::Request-_ptr _duplicate(CORBA::Request_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to that object.
static CORBA::Request_ptr _nil();
This static method returns a NULL pointer that can be used to initialize a CORBA::Request_ptr object.
static void _release(CORBA::Request_ptr ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
ServerRequest
The ServerRequest class is used to represent an operation request received by an object implementation that is using the Dynamic Skeleton Interface. When the POA receives a client operation request, it invokes the object implementation's invoke method and passes an object of this type.
This class provides the methods needed by the object implementation to determine the operation being requested and the arguments. It also provides methods for setting the return value and reflecting exceptions to the client application.
You should never attempt to free memory associated with any value returned by this class.
Include file
The corba.h file should be included when you use this class.
ServerRequest methods
void arguments(CORBA::NVList_ptr param);
This method sets the parameter list for this request.
The parameter list to be filled in. You must initialize this list with the appropriate number of Any objects and set their type and flag values prior to invoking this method.
CORBA::Context_ptr ctx()
This method returns the Context object associated with the request.
Caution
You should never release the memory associated with this method's return value.
void exception(CORBA::Any_ptr exception);
This method is used to reflect the specified exception to the client application.
The exception that was raised. If this pointer is NULL, a CORBA::UnknownUserException is reflected.
const char *operation() const;
Returns the name of the operation being requested.
const char* op_name() const
This method returns the name of the operation associated with the request. The object implementation uses this name to determine if the request is valid, to perform the appropriate processing to fulfill the request, and to return the appropriate value to the client.
void params(CORBA::NVList_ptr params);
This method accepts an NVList object initialized with the appropriate number of Any objects. The method fills the NVList in with the parameters supplied by the client.
The parameter list to be filled in. You must initialize this list with the appropriate number of Any objects and set their type and flag values prior to invoking this method.
void result(CORBA::Any_ptr result);
This method sets the result that is to be reflected to the client application.
An Any object representing the return value.
void set_exception(const CORBA::Any& a);
This method sets the exception that is to be reflected to the client application.
An Any object representing the exception.
void set_result(const CORBA::Any& a);
This method sets the result that is to be reflected to the client application.
An Any object representing the return value.
static CORBA::ServerRequest-_ptr _duplicate(CORBA::ServerRequest_ptr ptr);
This static method increments the reference count for the specified object and then returns a pointer to the object.
static CORBA::ServerRequest_ptr _nil();
This static method returns a NULL pointer that can be used for initialization purposes.
static void _release(CORBA::ServerRequest *ptr);
This static method decrements the reference count for the specified object. When the count reaches zero, all memory managed by the object is released and the object is deleted.
TCKind
enum TCKind
This enumeration describes the various types that a TypeCode object, described in “TypeCode” on page 76, may represent.
The values are shown in the following table.
TypeCode
class CORBA::TypeCode
The TypeCode class represents the various types that can be defined in IDL. Type codes are most often used to define the type of value being stored in an Any object, described in “Any” on page 49. Type codes may also be passed as parameters to method invocations.
TypeCode objects can be created using the various CORBA::ORB.create_<type>_tc methods, whose description begins in “Core interfaces and classes”. You may also use the constructors listed here.
Include file
Include the corba.h file when you use this class.
TypeCode constructors
CORBA::TypeCode(CORBA::TCKind kind, CORBA::Boolean is_constant);
This method constructs a TypeCode object for types that do not require any additional parameters. A BAD_PARAM exception is raised if kind is not a valid type for this constructor.
TypeCode methods
CORBA::TypeCode_ptr content_type() const;
This method returns the TypeCode of the elements in a sequence or array. It also will return the type of an alias. A BadKind exception is raised if this object's kind is not CORBA::tk_sequence, CORBA::tk_array, or CORBA::tk_alias.
CORBA::Long default_index() const;
This method returns the default index of a TypeCode representing a union. If this object's kind is not CORBA::tk_union, a BadKind exception is raised.
CORBA::TypeCode_ptr discriminator_type() const;
This method returns the discriminator type of a TypeCode representing a union. If this object's kind is not CORBA::tk_union, a BadKind exception is raised.
CORBA::Boolean equal(CORBA::TypeCode_ptr tc) const;
This method compares this object with the specified TypeCode. If they match in every respect, TRUE is returned. Otherwise, FALSE is returned.
const char* id() const;
This method returns the repository identifier of the type being represented by this object. If the type being represented does not have a repository identifier, a BadKind exception is raised. Types that have a repository identifier include:
CORBA::TCKind kind() const
This method returns this object's kind.
CORBA::ULong length() const;
This method returns the length of the string, sequence, or array represented by this object. The length of a string is the number of characters. The length of an array or sequence is the number of elements. A BadKind exception is raised if this object's kind is not CORBA::tk_string, CORBA::tk_sequence, or CORBA::tk_array.
CORBA::ULong member_count() const;
This method returns the member count of the type being represented by this TypeCode object. If the type being represented does not have members, a BadKind exception is raised. Types that have members include:
CORBA::Any_ptr member_label(CORBA::ULong index) const;
This method returns the label of the member with the specified index from a TypeCode object for a union. If this object's kind is not CORBA::tk_union, a BadKind exception is raised. If the index is invalid, a Bounds exception is raised.
const char *member_name(CORBA::ULong index) const;
This method returns the name of the member with the specified index from the type being represented by this object. If the type being represented does not have members, a BadKind exception is raised. If the index is invalid, a Bounds exception is raised.
Types that have members include:
CORBA::TypeCode_ptr member_type(CORBA::ULong index) const;
This method returns the type of the member with the specified index from the type being represented by this object. If the type being represented does not have members with types, a BadKind exception is raised. If the index is invalid, a Bounds exception is raised. Types that have members include:
const char *name() const;
This method returns the name of the type represented by this object. If the type does not have a name, a BadKind exception is raised. Types that have a name include:
static CORBA::TypeCode_ptr _duplicate(
CORBA::TypeCode_ptr obj);
This static method duplicates the specified TypeCode object.
static CORBA::TypeCode_ptr _nil();
This static method returns a NULL TypeCode pointer that can be used for initialization purposes.
static void _release(CORBA::TypeCode_ptr obj);
This static method decrements the reference count to the specified object. When the reference count is zero, it also frees all memory that it is managing and then deletes the object.
CORBA::Boolean equivalent (CORBA_TypeCode_ptr tc) const;
The equivalent operation is used by the ORB when determining the type equivalence for values stored in an IDL.
CORBA_TypeCode_ptr get_compact_typecode() const;
The get_compact_code operation strips out all optional name & member name fields, but it leaves all alias typecodes intact.
virtual CORBA::Visibility member_visibility(CORBA::ULong index) const;
This method returns the Visibility of the valuetype member identified by index.
Note
The member_visibility operation can only be invoked on valuetype TypeCodes, not on valueboxes (or boxed values).
virtual CORBA::ValueModifier type_modifier() const;
The type_modifier operations can only be invoked on non-boxed valuetype TypeCodes. This method returns the ValueModifier that applies to the valuetype represented by the target TypeCode.
virtual CORBA::TypeCode_ptr concrete_base_type()
The concrete_base_type operations can only be invoked on non-boxed valuetype TypeCodes. If the value represented by the target TypeCode has a concrete base valuetype, this method returns a TypeCode for the concrete base, otherwise it returns a nil TypeCode reference.