// -*- IDL -*- $Id$

// This file contains the interface definitions for "Portable"
// Interceptor support.

// **********************************************************
//   Notice that the Portable Interceptor specification
//   is still under discussion in OMG and both the IDL
//   and the implementation details in TAO will eventually
//   change to conform with the PI spec in the future.
//
//   @@ Now that a working draft of the Portable Interceptors
//      is available, we will provide a compliant implementation
//      shortly.
//
//      Please see the annotation marked with "@@" in this file
//      for hints on transitting from the temporary
//      implementation to new APIs.
//
//      See $TAO_ROOT/docs/interceptors.html for more info.
// **********************************************************

// Author (currently): Nanbor Wang <nanbor@cs.wustl.edu>
// @@ I will no longer be the author of this IDL file. ;-)

#include <corba.pidl>
#include <IOP.pidl>

#pragma prefix "TAO"
// The prefix should be changed to "omg.org" once the spec. gets
// finallized.
// @@ The prefix will be changed to "omg.org".

module PortableInterceptor
{
  interface Cookie
    {
      // Cookie's are used to pass information among interceptors
      // within a invocation or an upcall.
      //
      // @@ Cookie will no longer be available.
      string myname ();
    };

  typedef sequence<Cookie>  Cookies;
  // Collections of Cookie's become Cookies'es.
  //
  // @@ Cookies will no longer be available.

  interface Interceptor
    {
      // Base interface for Interceptors.
      //
      // @@ This interface will not change.
      readonly attribute string name;
    };

  interface ServerRequestInterceptor : Interceptor
    {
      // Server side request interceptor definition.
      //
      // @@ The name of the interface will not change.

      void preinvoke (in unsigned long request_id,
                      in boolean response_expected,
                      in CORBA::Object objref,
                      in string operation_name,
                      inout IOP::ServiceContextList sc,
                      inout NVList arguments,
                      inout Cookies ck);
      // Interception pointer before invoking the servant method.
      // Currently, we don't pass NVList into the interceptor because
      // I haven't figured out how to best optimize this stuff.
      // In the future, NVList will contain all in and inout arguments
      // of the operation.
      //
      // @@ This operation will map to either
      // <receive_request_service_contexts> or <receive_request> of
      // the standard APIs.  If you are not sure, use
      // <receive_request>.
      //
      // void receive_request_service_contexts (in ServerRequestInfo ri) raises (ForwardRequest);
      // void receive_request (in ServerRequestInfo ri) raises (ForwardRequest);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ServerRequestInfo> interface.

      void postinvoke (in unsigned long request_id,
                       in boolean response_expected,
                       in CORBA::Object objref,
                       in string operation_name,
                       inout IOP::ServiceContextList sc,
                       inout NVList arguments,
                       inout Cookies ck);
      // Interception pointer after invoking the servant method.
      // Currently, we don't pass NVList into the interceptor because
      // I haven't figured out how to best optimize this stuff.
      // In the future, NVList will contain all out, inout arguments
      // and the return value of the operation.
      //
      // @@ This operation will map to <send_reply>.
      // It is not clear whether oneway call will invoke <send_other>
      // operation or not.
      //
      // void send_reply (in ServerRequestInfo ri);
      // void send_other (in ServerRequestInfo ri) raises (ForwardRequest);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ServerRequestInfo> interface.

      void exception_occurred (in unsigned long request_id,
                               in boolean response_expected,
                               in CORBA::Object objref,
                               in string operation_name,
                               inout Cookies ck);
      // Exception interception point.
      //
      // @@ This method will map to <send_exception> method.
      //
      // void send_exception (in ServerRequestInfo ri) raises (ForwardRequest);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ServerRequestInfo> interface.
    };

  interface ClientRequestInterceptor : Interceptor
    {
      // Client side interceptor.
      //
      // @@ The name of the interface will not change.

      void preinvoke (in unsigned long request_id,
                      in boolean response_expected,
                      in CORBA::Object objref,
                      in string operation_name,
                      inout IOP::ServiceContextList sc,
                      inout NVList arguments,
                      inout Cookies ck);
      // Before remote invocation.
      // Currently, we don't pass NVList into the interceptor because
      // I haven't figured out how to best optimize this stuff.
      // In the future, NVList will contain all in and inout arguments
      // of the operation.
      //
      // @@ This operation will map to <send_request> of the standard
      // APIs.
      //
      // void send_request (in ClientRequestInfo) raises (ForwardRequest);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ClientRequestInfo> interface.

      void postinvoke (in unsigned long request_id,
                       in boolean response_expected,
                       in CORBA::Object objref,
                       in string operation_name,
                       inout IOP::ServiceContextList sc,
                       inout NVList arguments,
                       inout Cookies ck);
      // After returned from remote invocation.
      // Currently, we don't pass NVList into the interceptor because
      // I haven't figured out how to best optimize this stuff.
      // In the future, NVList will contain all out, inout arguments
      // and the return value of the operation.
      //
      // @@ This operation will map to either <receive_reply> or
      // <receive_other> in the standard APIs depending on whether the
      // operation is oneway or not.
      //
      // void receive_reply (in ClientRequestInfo ri);
      // void receive_other (in ClientRequestInfo ri);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ClientRequestInfo> interface.

      void exception_occurred (in unsigned long request_id,
                               in boolean response_expected,
                               in CORBA::Object objref,
                               in string operation_name,
                               inout Cookies ck);
      // Exception occurred.
      //
      // @@ This method will map to <receive_exception> method as:
      //
      //    void receive_exception (in ClientRequestInfo ri) raises (ForwardRequest);
      //
      // @@ Note that all arguments will be accessed thru
      // <PortableInterceptor::ClientRequestInfo> interface.
    };
};

#pragma prefix ""