remote_broker.c

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

//%2006////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================
//
//%/////////////////////////////////////////////////////////////////////////////

/*!
  \file remote_broker.c
  \brief Common Remote Broker functionality.

  This file contains common functionality to be used by communication
  layers on the remote side, i.e. at the actual provider location.
  It provides the look-up of providers, their activation and deactivation
  respectively, and filter tracking for indication providers.

  Remote providers are each attached to a unique remote broker handle,
  which is being identified by the following criteria:
  - the communication layer identifier
  - the broker response address used for broker service requests
  - the provider name (as used to find fixed entry points)
  - the provider module/library containing the provider
  - the communication ticket issued by the remote proxy

  If a handle cannot be found for these items, a new one is being created
  and added to a static linked list, thus providers can be reidentified
  for future MI requests. The activation of the underlying provider, based
  on the type, is done dynamically, whenever it is requested by the
  communication layer. Activated providers are kept alive for a certain
  period of time after their last usage (i.e. when their use-count is
  decreased to zero), before they get unloaded together with the MI
  library. Deactivation can be prevented by communication layers using
  the acquire() call, and implicitly by activateFilter() calls issued
  against indication providers.

  \author Frank Scheffler
*/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#ifndef PEGASUS_PLATFORM_ZOS_ZSERIES_IBM
#include <dlfcn.h>
#include <error.h>
#else
  #include <dll.h>
  #include <pthread.h> /*timespec structure define in z/OS */
#endif
#include <sys/time.h>
#include <errno.h>

#include "tool.h"
#include "mm.h"
#include "native.h"
#include "remote.h"
#include "ticket.h"
#include "debug.h"

extern CMPIBrokerExtFT *CMPI_BrokerExt_Ftab;
#define INIT_LOCK(l) if (l==NULL) l=CMPI_BrokerExt_Ftab->newMutex(0);


//! CMPIIndicationMI extension to track filter de-/activations.
/*!
  This structure extends a regular CMPIIndicationMI and holds a reference
  to the provider's original MI. Furthermore, it has a reference to the
  remote broker contained within. This reference is used to modify its
  use_count to keep track of active filters, and to avoid preliminary
  deactivation. In other words, activating an indication filter is equal
  to acquiring the MI, and deactivating is equal to releasing it respectively.

  \sa __track_indicationMI()
  \sa remote_broker
*/
struct tracked_indication {
	CMPIIndicationMI mi;	       /*!< indication MI to be extended  */
	CMPIIndicationMI * saved_mi;   /*!< pointer to the provider's MI */
	remote_broker * rb;            /*!< reference to the remote broker  */
};


//! Data container for remote brokers.
/*!
  This remote broker structure is the counterpart of remote providers; they
  are one-to-one related. Therefore, it holds all the necessary information
  to identify and access the latter one. Once created, this handle is put
  into a linked list and is never removed. However, the MI module, i.e. the
  provider, associated with this handle may be deactivated and activated
  on a timely basis, depending on its usage.
 */
struct __remote_broker {
	remote_broker rb;	/*!< holds the actual broker and FTs  */

	char * comm_layer_id;	/*!< the comm-layer associated with the MI */
	char * broker_address;	/*!< the broker address used for up-calls */
	char * provider;	/*!< the name of the associated provider */
	char * provider_module;	/*!< the name of the MI library/module */
	comm_ticket ticket;	/*!< the comm. ticket used for up-calls */
	void * library;		/*!< the library handle */

	unsigned int use_count;	           /*!< number of comm-layer and
					     filters currently using this
					     provider */
	struct timeval last_used;          /*!< time of last usage  */
        CMPI_MUTEX_TYPE lock;	           /*!< lock to provide clean access
					     to use_count  */

	CMPIInstanceMI * instanceMI;       /*!< instance MI handle */
	CMPIAssociationMI * associationMI; /*!< association MI handle */
	CMPIMethodMI * methodMI;           /*!< method MI handle */
	CMPIPropertyMI * propertyMI;       /*!< property MI handle */
	CMPIIndicationMI * indicationMI;   /*!< indication MI handle */

	struct __remote_broker * next;     /*!< pointer to next element  */
};



/****************************************************************************/

//! List of all remote_broker handles currently maintained.
static struct __remote_broker * __remote_brokers   = NULL;

//! Lock to assure exclusive access to __remote_brokers.
static CMPI_MUTEX_TYPE __remote_brokers_lock = NULL;

//! CMPIContext used for activation and deactivation of providers.
/*!
  This context is passed to providers upon their activation and
  deactivation respectively. It has to be separately initialized.

  \sa init_activation_context()
 */
static CMPIContext * __remote_brokers_context = NULL;


/****************************************************************************/
/*          indication tracking functions                                   */
/****************************************************************************/


//! Cleans up a tracked indication MI.
/*!
  The function calls the provider's cleanup() method, wrapped within the
  CMPIIndicationMI, and then frees the tracked_indication structure
  mapping to it.

  \return the status of the provider's cleanup() call.
*/
#ifdef CMPI_VER_100

static CMPIStatus __indication_cleanup ( CMPIIndicationMI * mi,
					 CONST CMPIContext * ctx,
					 CMPIBoolean term)
#else
static CMPIStatus __indication_cleanup ( CMPIIndicationMI * mi,
					 CMPIContext * ctx)
					 
#endif
					 
{
	struct tracked_indication * __mi =
		(struct tracked_indication *) mi;
	CMPIStatus rc;

	TRACE_INFO(("relaying call to real provider."));
#ifdef CMPI_VER_100
	rc = __mi->saved_mi->ft->cleanup ( __mi->saved_mi, ctx, term);
#else
	rc = __mi->saved_mi->ft->cleanup ( __mi->saved_mi, ctx );
#endif

	TRACE_INFO(("freeing wrapper CMPIIndicationMIFT."));
	free ( __mi );
	return rc;
}


//! Relays the request to the actual provider.
/*!
  This request is simply forwarded to the MI saved within the
  tracked_indication struct passed in as CMPIIndicationMI.

  \return the status of the provider's authorizeFilter() call.
 */
static CMPIStatus __indication_authorizeFilter ( CMPIIndicationMI * mi,
						 CONST CMPIContext * ctx,
#ifndef CMPI_VER_100
						 CMPIResult * result,
#endif
						 CONST CMPISelectExp * sexp,
						 const char * ns,
						 CONST CMPIObjectPath * cop,
						 const char * user )
{
	struct tracked_indication * __mi =
		(struct tracked_indication *) mi;

	TRACE_INFO(("relaying call to real provider."));
	return __mi->saved_mi->ft->authorizeFilter ( __mi->saved_mi, ctx,
#ifndef CMPI_VER_100
						     result, 
#endif
						     sexp,
						     ns, cop, user );


}


//! Relays the request to the actual provider.
/*!
  This request is simply forwarded to the MI saved within the
  tracked_indication struct passed in as CMPIIndicationMI.

  \return the status of the provider's mustPoll() call.
 */
static CMPIStatus __indication_mustPoll ( CMPIIndicationMI * mi,
					  CONST CMPIContext * ctx,
#ifndef CMPI_VER_100					  
					  CMPIResult * result,
#endif
					  CONST CMPISelectExp * sexp,
					  const char * ns,
					  CONST CMPIObjectPath * cop )
{
	struct tracked_indication * __mi =
		(struct tracked_indication *) mi;

	TRACE_INFO(("relaying call to real provider."));
	return __mi->saved_mi->ft->mustPoll ( __mi->saved_mi, ctx, 
#ifndef CMPI_VER_100
					      result,
#endif
					      sexp, ns, cop );
}



//! Relays the request to the actual provider and increases the use count.
/*!
  This request is simply forwarded to the MI saved within the
  tracked_indication struct passed in as CMPIIndicationMI. Furthermore,
  the use count for the associated remote broker is increased by one, using
  the acquireMI() call from its function table.

  \return the status of the provider's activateFilter() call.
 */
static CMPIStatus __indication_activateFilter ( CMPIIndicationMI * mi,
						CONST CMPIContext * ctx,
#ifndef CMPI_VER_100
						CMPIResult * result,
#endif
						CONST CMPISelectExp * sexp,
						const char * ns,
						CONST CMPIObjectPath * cop,
						CMPIBoolean first )
{
	struct tracked_indication * __mi =
		(struct tracked_indication *) mi;

	TRACE_VERBOSE(("entered function."));

	RBAcquireMI ( __mi->rb );

	TRACE_INFO(("relaying call to real provider."));
	return __mi->saved_mi->ft->activateFilter (__mi->saved_mi, ctx,
#ifndef CMPI_VER_100						   
						    result, 
#endif
						    sexp,
						    ns, cop, first );
}


//! Relays the request to the actual provider and decreases the use count.
/*!
  This request is simply forwarded to the MI saved within the
  tracked_indication struct passed in as CMPIIndicationMI. Furthermore,
  the use count for the associated remote broker is decreased by one, using
  the releaseMI() call from its function table.

  \return the status of the provider's deActivateFilter() call.
 */
static CMPIStatus __indication_deactivateFilter ( CMPIIndicationMI * mi,
						  CONST CMPIContext * ctx,
#ifndef CMPI_VER_100
						  CMPIResult * result,
#endif
						  CONST CMPISelectExp * sexp,
						  const char * ns,
						  CONST CMPIObjectPath * cop,
						  CMPIBoolean last )
{
	struct tracked_indication * __mi =
		(struct tracked_indication *) mi;

	TRACE_VERBOSE(("entered function."));

	RBReleaseMI ( __mi->rb );

	TRACE_INFO(("relaying call to real provider."));
	return __mi->saved_mi->ft->deActivateFilter ( __mi->saved_mi, ctx,
#ifndef CMPI_VER_100
						      result,
#endif
						      sexp,
						      ns, cop, last );
}

static CMPIStatus __indication_enableIndications (CMPIIndicationMI* mi
#ifdef CMPI_VER_100
      , const CMPIContext *ctx
#endif
     )
{
    struct tracked_indication * __mi =
        (struct tracked_indication *) mi;

    TRACE_VERBOSE(("entered function."));

    TRACE_INFO(("relaying call to real provider."));
    return __mi->saved_mi->ft->enableIndications (__mi->saved_mi
#ifdef CMPI_VER_100
    ,ctx
#endif
    );
}

static CMPIStatus __indication_disableIndications (CMPIIndicationMI* mi
#ifdef CMPI_VER_100
      , const CMPIContext *ctx
#endif
     )
{
    struct tracked_indication * __mi =
         (struct tracked_indication *) mi;

    TRACE_VERBOSE(("entered function."));

    TRACE_INFO(("relaying call to real provider."));
    return __mi->saved_mi->ft->disableIndications ( __mi->saved_mi
#ifdef CMPI_VER_100
    ,ctx
#endif
    );
}


//! Builds a wrapper tracked_indication struct from the given CMPIIndicationMI.
/*!
  The function allocates a wrapper CMPIIndicationMI intercepting MI requests
  from the communication layer. Thus, de-/activateFilter() calls can be tracked
  and use counts be modified properly, preventing indication providers from
  being unloaded in advance.

  \param mi the original CMPIIndicationMI.
  \param rb the remote broker to be linked with the MI.

  \return the wrapper CMPIIndicationMI.

  \sa __indication_activateFilter, __indication_deactivateFilter
 */
static CMPIIndicationMI * __track_indicationMI ( CMPIIndicationMI * mi,
						 remote_broker * rb)
{
	static CMPIIndicationMIFT __indicationMIFT = {
		0, 0, NULL,
		__indication_cleanup,
		__indication_authorizeFilter,
		__indication_mustPoll,
		__indication_activateFilter,
		__indication_deactivateFilter,
		__indication_enableIndications,
		__indication_disableIndications,
	};

	struct tracked_indication * __mi =
		(struct tracked_indication *)
		malloc ( sizeof ( struct tracked_indication ) );

	TRACE_NORMAL(("building wrapper CMPIIndicationMIFT."));

	__mi->mi.ft    = &__indicationMIFT;
	__mi->saved_mi =  mi;
	__mi->rb     = rb;

	return (CMPIIndicationMI *) __mi;
}


/*****************************************************************************/
/*            encapsulated remote broker functions                           */
/*****************************************************************************/

static char * __get_broker_address ( remote_broker * rb )
{
	struct __remote_broker * __rb =
		(struct __remote_broker *) rb;

	TRACE_NORMAL(("returning broker address: %s", __rb->broker_address));
	return __rb->broker_address;
}


static char * __get_provider ( remote_broker * rb )
{
	struct __remote_broker * __rb =
		(struct __remote_broker *) rb;

	TRACE_NORMAL(("returning provider name: %s", __rb->provider));
	return __rb->provider;
}


static comm_ticket * __get_ticket ( remote_broker * rb )
{
	struct __remote_broker * __rb =
		(struct __remote_broker *) rb;

	TRACE_NORMAL(("returning broker ticket."));
	return &__rb->ticket;
}


static void __acquireMI ( remote_broker * rb )
{
	struct __remote_broker * __rb =
		(struct __remote_broker *) rb;

	TRACE_NORMAL(("Acquiring remote broker handle."));

        CMPI_BrokerExt_Ftab->lockMutex(__rb->lock);