/**********************************************************************
// @@@ START COPYRIGHT @@@
//
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
//
// @@@ END COPYRIGHT @@@
**********************************************************************/
// MODULE: ASSOCSVC.IDL
//
// PURPOSE: Describes the ODBC ASsociation services (AS).
//

#ifndef ASSOCSVC_H_
#define ASSOCSVC_H_

#include "common.idl"
#include "odbc.idl"
#include "odbccfg.idl"

typedef odbc::SQLSvc		SQLSvc_ObjRef;
typedef odbccfg::CfgSvc		CfgSvc_ObjRef;

module odbcas {

#define AS_uuid ((UUID_def) "9101c0ac-e07a-11d0-a543-0060b01ad6ae")
#define AS_version ((VERSION_def) 16777217)

// note clusterNm is unused but defined in the hopes that the
// cluster will have its own identity 


interface AS 
	{                  
	exception ASParamError {string ErrorText;};
	exception ASTimeout {string ErrorText;};
	exception ASInvalidUserDesc {string ErrorText;};
    exception ASNoSvcHdl  {string ErrorText;};
	exception ASInvalidHandle{};
	exception ASRejectRegistry{short RejectReason; string ErrorText;};
    exception ASRegistryFailed{};

    // the following is the keepalive call that is not responded to
    // until its time to disconnect client from server.
    // the call goes from client to server, e.g., ODBC Driver to
    // ASiation Service, ODBC Server to ASiation Service.
    void RegProcess (
		 in  CLIENT_TYPE_def	    processType,
		 in  VERSION_def			intfVersion,
         in  PROCESS_ID_def	        processDesc,
	     in  CONNECTION_CONTEXT_def inContext)
	raises (ASTimeout,
			ASRegistryFailed,
			ASRejectRegistry,
			ASParamError);

	void CompleteRegProcess (
		 in  CLIENT_TYPE_def	    processType,
         in  PROCESS_ID_def	        processDesc)
	 raises (ASTimeout,
			 ASRegistryFailed,
			 ASParamError);

    // this is to signal the client is ready to complete the
    // the original registry call and then destroy the proxy
    void DeRegProcess (
	     in  PROCESS_ID_def	        processDesc)
	raises (ASRegistryFailed, 
	        ASParamError);

	// TODO: this would be extensible if the returned Object Reference
	//	handles were in a typed sequence.  this will be very important
	//      when addressing stored procedures. 

	// changed to a context which is only the Datasource name, and
	// the last object reference handle.

    //void GetSQLObjRefHdl(
	//    in  CONNECTION_CONTEXT_def  inContext,
	//	out CONNECTION_CONTEXT_def  newContext,
	//    out SQLSvc_ObjRef			aSQLSvcObjRef)
	//raises( ASParamError, 
	//		ASInvalidUserDesc,
	//		ASTimeout,
	//		ASNoSvcHdl, 
	//		ASInvalidHandle  );

	void GetSQLObjRefHdl(
	    in  CONNECTION_CONTEXT_def  inContext,
		out CONNECTION_CONTEXT_def  newContext,
	    out SQLSvc_ObjRef			aSQLSvcObjRef)
	raises( ASParamError, 
			ASInvalidUserDesc,
			ASTimeout,
			ASNoSvcHdl, 
			ASInvalidHandle  );

	void GetCfgObjRefHdl(
	    in  CONNECTION_CONTEXT_def  inContext,
		out CONNECTION_CONTEXT_def  newContext,
	    out CfgSvc_ObjRef			aCfgSvcObjRef)
	raises( ASParamError, 
			ASInvalidUserDesc,
			ASNoSvcHdl, 
			ASInvalidHandle  );

// changed to a context which is only the Datasource name, and
	// the last object reference handle.

    void RegSQLObjRefHdl (
	    in  SQLSvc_ObjRef			aSQLSvcObjRef,
		in  PROCESS_ID_def			pidDesc,
	    in  CONNECTION_CONTEXT_def  lastContext,
	    out CONNECTION_CONTEXT_def  newContext)
	raises (ASParamError, 
			ASNoSvcHdl, 
			ASInvalidHandle, 
			ASRejectRegistry);

	void RegCfgObjRefHdl (
	    in  CfgSvc_ObjRef			aCfgSvcObjRef,
	    in  PROCESS_ID_def			pidDesc,
		in  CONNECTION_CONTEXT_def  lastContext,
	    out CONNECTION_CONTEXT_def  newContext)
	raises (ASParamError, 
			ASNoSvcHdl, 
			ASInvalidHandle, 
			ASRejectRegistry);

    // call is used by a server instance acting on behalf
    // of an administrator configuration session (Broadway GUI)
    // that has commanded that the running configuratino is to
    // be updated with the latest configuration values.
    // the call originates from the server instance as a client
    // call to ASSvcs.  Only does one Datasource at a time,
    // sending a sequence doesn't appear to have any performance
    // benefits.  the calls are async so more than one can be
    // stacked up at a time, but only one at a time should be
    // making changes to the runtime system.  consider a change
    // to a list of DS Configs, and a list of DSNms, unsure of payoff	

    void RefreshDSCfg (
	    in   DATASOURCE_CFG_def		   DSCfg )
	raises (ASParamError);

    void ResetDSStats (
	    in   SQL_IDENTIFIER_def		   DSNm )
	raises (ASParamError);

    };  // end of interface ASSvc

};  // end of module odbcas

#endif