[Enterprise Extensions only]

Object::_create_request

Overview Creates a Request object suitable for invoking a specific operation using the Dynamic Invocation Interface (DII).
Original class CORBA::Object
Exceptions CORBA::SystemException


Intended Usage

The _create_request method (two forms) are used to create CORBA::Request objects tailored to a specific IDL operation. The CORBA::Request object can then be used to invoke requests using the DII. After invoking the method, an application can obtain the return result, output parameter values, and exceptions using methods on CORBA::Request.

The target of CORBA::Object::_create_request() is typically a proxy object, rather than a local object. When invoked on a proxy object, this method operates locally; the remote object to which the proxy refers is unaffected until the DII request that is created by CORBA::Object::_create_request() is invoked.

The two forms of CORBA::Object::_create_request() differ in whether a CORBA::ExceptionList_ptr and a CORBA::ContextList_ptr are provided as input. These input parameters are not needed for operations that have no raises or context clause in the IDL specification. For IDL operations that do have a raises or context clause, the second form of CORBA::Object::_create_request() can be used to avoid (potentially time-consuming) Interface Repository lookups by the ORB when the DII request is invoked.

See also Object::_request, which creates a CORBA::Request without providing the parameters for the operation.

IDL Syntax

  virtual CORBA::Status _create_request (CORBA::Context_ptr ctx,
                                         const char* operation,
                                         CORBA::NVList_ptr arg_list,
                                         CORBA::NamedValue_ptr result,
                                         CORBA::Request_ptr &request,
                                         CORBA::Flags reg_flags) = 0;
  virtual CORBA::Status _create_request (CORBA::Context_ptr ctx,
                                         const char* operation,
                                         CORBA::NVList_ptr arg_list,
                                         CORBA::NamedValue_ptr result,
                                         CORBA::ExceptionList_ptr exc_list,
                                         CORBA::ContextList_ptr ctx_list,
                                         CORBA::Request_ptr &request,
                                         CORBA::Flags reg_flags) = 0;

Input parameters

ctx
A pointer to the CORBA::Context object to be passed when the DII request is invoked. For operations having no context clause in their IDL specification, this can be NULL. The CORBA::Request object assumes ownership of this parameter.
operation
The unscoped name of the IDL operation to be invoked using the Request. This must be an operation that is implemented or inherited by the CORBA::Object on which CORBA::Object::_create_request() is invoked. The caller retains ownership of this parameter (the CORBA::Request object makes a copy).
arg_list
A pointer to a CORBA::NVList object that describes;
  • The types of all the operation parameters of the IDL.
  • The values of the in and inout parameters of the operation.
  • The variables in which the out parameter values will be stored after the DII request is invoked.
result
A pointer to a CORBA::NamedValue object that will hold the result of the DII request after it is invoked. The CORBA::Request object assumes ownership of this parameter.
request
A CORBA::Request_ptr variable, passed by reference, to be initialized by CORBA::Object::_create_request() to point to the newly-created CORBA::Request object. The caller retains ownership of this parameter.
req_flags
A bit-vector describing how the DII request will be invoked. Oneway methods (methods that do not require a response) should be created using a req_flags value of CORBA::INV_NO_RESPONSE. No other req_flags values are currently used.
exc_list
A pointer to a CORBA::ExceptionList object that describes the user-defined exceptions that the DII operation can throw (according to the operation declaration in the IDL specification). This parameter is essentially a list of TypeCodes for UserException subclasses. The CORBA::Request object assumes ownership of this parameter. This parameter is optional and NULL can be passed (even for methods that raise user-defined exceptions).
ctx_list
A pointer to a CORBA::ContextList object that lists the Context strings that must be sent with the DII operation (according to the operation declarations in the IDL specification). This parameter differs from the ctx parameter in that this parameter supplies only the context strings whose values are to be transmitted with the DII request, while the ctx parameter is the object from which those context string values are obtained. The CORBA::Request object assumes ownership of this parameter. This parameter is optional and NULL can be passed (even for methods that pass Context parameters).

Return values

CORBA::Status
A return value of zero indicates success.

Example

  /* The following IDL signature is used:
     interface testObject
     {
        string testMethod(in long input_value, out float outvalue);
     };
   */
  ...
  /* Get the OperationDef that describes testMethod */
  CORBA::ORB_var myorb = 
     CORBA::ORB_init(argc, argv, "DSOM");  /* argc, argv: input arguments */
  CORBA::Repository_var my_IR = CORBA::Repository::_narrow(generic_IR);
  CORBA::Contained_var generic_opdef = 
     my_IR -> lookup("testObject::testMethod");
  CORBA::OperationDef_var my_opdef = 
     CORBA::OperationDef::_narrow(generic_opdef);
 
  /* Create the NVList and NamedValue for the request */
  CORBA::NVList_ptr params = NULL;
  myorb -> create_operation_list(my_opdef, params);
  CORBA::NamedValue_ptr result = NULL;
  myorb -> create_named_value(result); 
 
  /* Create the Request object */
  CORBA::Object_var my_proxy =   /* Get a proxy somehow */
     my_proxy -> _create_request(NULL, "testMethod", params, result, 
        my_request, 0);