cmpift.h

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.
//
//==============================================================================
//
//%/////////////////////////////////////////////////////////////////////////////

#ifndef _CMPIFT_H_
#   define _CMPIFT_H_

#   include "cmpidt.h"
#   include "cmpios.h"

#   ifdef __cplusplus
extern "C"
{
#   endif


  //---------------------------------------------------
  //--
  //   _CMPIBrokerEncFT Function Table
  //--
  //---------------------------------------------------


   /** This structure is a table of pointers to broker and factory services
       of encapsulated CMPIObjects. This table is made available
       by the Management Broker, aka CIMOM, whenever a provider
       is loaded and initialized.
   */
  struct _CMPIBrokerEncFT
  {

     /** Function table version
     */
    int ftVersion;

     /** Instance factory service.
         @param mb Pointer to the broker.
	     @param op ObjectPath containing namespace and classname.
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created Instance.
     */
    CMPIInstance *(*newInstance)
      (const CMPIBroker * mb, const CMPIObjectPath * op, CMPIStatus * rc);

     /** ObjectPath factory service.
         @param mb Pointer to the broker.
	     @param ns Namespace
	     @param cn Classname.
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created ObjectPath.
     */
    CMPIObjectPath *(*newObjectPath)
      (const CMPIBroker * mb, const char *ns, const char *cn,
       CMPIStatus * rc);

     /** Args container factory service.
         @param mb Pointer to the broker.
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created Args container.
     */
    CMPIArgs *(*newArgs) (const CMPIBroker * mb, CMPIStatus * rc);

     /** String container factory service.
         @param mb Pointer to the broker.
	     @param data String data
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created String.
     */
    CMPIString *(*newString)
      (const CMPIBroker * mb, const char *data, CMPIStatus * rc);

     /** Array container factory service.
         @param mb Pointer to the broker.
	     @param max Maximum number of elements
	     @param type Element type
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created Array.
     */
    CMPIArray *(*newArray)
      (const CMPIBroker * mb, CMPICount max, CMPIType type, CMPIStatus * rc);

     /** DateTime factory service. Initialized with the time of day.
         @param mb Pointer to the broker.
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created DateTime.
     */
    CMPIDateTime *(*newDateTime) (const CMPIBroker * mb, CMPIStatus * rc);

     /** DateTime factory service. Initialized from <binTime>.
         @param mb Pointer to the broker.
	     @param binTime Date/Time definition in binary format in microsecods
	       starting since 00:00:00 GMT, Jan 1,1970.
 	     @param interval Wenn true, defines Date/Time definition to be an interval value
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created DateTime.
     */
    CMPIDateTime *(*newDateTimeFromBinary)
      (const CMPIBroker * mb, CMPIUint64 binTime, CMPIBoolean interval,
       CMPIStatus * rc);

     /** DateTime factory service. Is initialized from <utcTime>.
         @param mb Pointer to the broker.
	     @param utcTime Date/Time definition in UTC format
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created DateTime.
     */
    CMPIDateTime *(*newDateTimeFromChars)
      (const CMPIBroker * mb, const char *utcTime, CMPIStatus * rc);

     /** SelectExp factory service. 
         @param mb Pointer to the broker.
	     @param query The select expression.
	     @param lang The query language.
	     @param projection Output: Projection specification (suppressed when NULL).
	     @param rc Output: Service return status (suppressed when NULL).
         @return The newly created SelectExp.
     */
    CMPISelectExp *(*newSelectExp)
      (const CMPIBroker * mb, const char *query, const char *lang,
       CMPIArray ** projection, CMPIStatus * st);

     /** Function to determine whether a CIM class is of <type> or any of
         <type> subclasses.
         @param mb Pointer to the broker.
	     @param op The class path (namespace and classname components).
	     @param type The type to tested for.
	     @param rc Output: Service return status (suppressed when NULL).
         @return True if test successful.
     */
      CMPIBoolean (*classPathIsA)
      (const CMPIBroker * mb, const CMPIObjectPath * op, const char *type,
       CMPIStatus * rc);

     /** Attempts to transforms an CMPI object to a broker specific string format.
         Intended for debugging purposes only.
         @param mb Pointer to the broker.
	     @param object A valid CMPI object.
	     @param rc Output: Service return status (suppressed when NULL).
         @return String from representation of <object>.
     */
    CMPIString *(*toString)
      (const CMPIBroker * mb, const void *object, CMPIStatus * rc);

     /** Verifies whether <object> is of CMPI type <type>.
         Intended for debugging purposes only.
         @param mb Pointer to the broker.
	     @param object A valid CMPI object.
	     @param type A string specifying a valid CMPI Object type
	         ("CMPIInstance", "CMPIObjectPath", etc).
	     @param rc Output: Service return status (suppressed when NULL).
         @return True if test successful.
     */
      CMPIBoolean (*isOfType)
      (const CMPIBroker * mb, const void *object, const char *type,
       CMPIStatus * rc);

     /** Retrieves the CMPI type of <object>.
         Intended for debugging purposes only.
         @param mb Pointer to the broker.
	     @param object A valid CMPI object.
	     @param rc Output: Service return status (suppressed when NULL).
         @return CMPI object type.
     */
    CMPIString *(*getType)
      (const CMPIBroker * mb, const void *object, CMPIStatus * rc);

     /** Retrieves translated message.
         @param mb Pointer to the broker.
	     @param msgId The message identifier.
	     @param defMsg The default message.
	     @param rc Output: Service return status (suppressed when NULL).
	     @param count The number of message substitution values.
         @return the trabslated message.
     */
#   ifdef CMPI_VER_85
    CMPIString *(*getMessage)
      (const CMPIBroker * mb, const char *msgId, const char *defMsg,
       CMPIStatus * rc, CMPICount count, ...);
#   endif // CMPI_VER_85	
        /** Logs a diagnostic message.
		@param mb The mb argument points to a CMPIBroker structure.
		@param severity  The level argument describes the level of log message. Levels are defined in Section 4.9.
		@param id The component argument, if not NULL, is the component ID.
		@param text  The text argument, if not NULL, is the message text to be logged.
		@param string The string argument, if not NULL, is the message text to be logged. string will be
			 ignored when text is not NULL.
	    @return Service return status.
      */
#   ifdef CMPI_VER_100
      CMPIStatus (*logMessage)
      (const CMPIBroker *, int severity, const char *id,
       const char *text, const CMPIString * string);

        /** Logs a trace entry. Intended for debugging purposes.
		@param mb The mb argument points to a CMPIBroker structure.
		@param level  The level argument describes the level of log message. Levels are defined in Section 4.9.
		@param component The component argument, if not NULL, is the component ID.
		@param text  The text argument, if not NULL, is the message text to be logged.
		@param string The string argument, if not NULL, is the message text to be logged. string will be
			 ignored when text is not NULL.
	    @return Service return status.
      */
      CMPIStatus (*trace)
      (const CMPIBroker *, int level, const char *component,
       const char *text, const CMPIString * string);
#   else // pre-1.0 versions supported getKeyList()
      CMPIArray *(*getKeyList)
      (CMPIBroker *mb, CMPIContext *ctx, CMPIObjectPath *op, CMPIStatus *rc);
#   endif /* CMPI_VER_100 */

#   ifdef CMPI_VER_200
     /** Error factory service.
         @param mb Pointer to the broker.
	     @param msgID A string which uniquely identifies, within the scope of the 'owner' argument, the format of the message.
		 @param msg A string which represenst the formatted message.
		 @parem sev The percieved severity of the error.
		 @param pc The probably cause of this error
	     @param status Service return status.
         @return The newly created Error.
     */
	  CMPIError* (*newCMPIError)
	  (const CMPIBroker*, const char*, const char*, const char*,
	   const CMPIErrorSeverity, const CMPIErrorProbableCause,const CMPIrc,
           CMPIStatus *rc);

     /** Opens a message file.
         @param mb Broker this pointer
         @param msgFile The message file identifier.
         @param msgFileHandle Output: The handle representing the open message file.
         @return Service return status.
     */
     CMPIStatus (*openMessageFile)
      (const CMPIBroker* mb, const char *msgFile, 
       CMPIMsgFileHandle* msgFileHandle);

     /** Closes a message file.
         @param mb Broker this pointer
         @param msgFileHandle The handle representing the open message file.
         @return Service return status.
     */
     CMPIStatus (*closeMessageFile)
      (const CMPIBroker* mb, const CMPIMsgFileHandle msgFileHandle);

     /** Retrieves translated message.
         @param mb Broker this pointer
         @param msgId The message identifier.
         @param msgFileHandle The handle representing the open message file.
         @param defMsg The default message.
         @param rc Output: Service return status (suppressed when NULL).
         @param count The number of message substitution values.
         @return the translated message.
     */
     CMPIString* (*getMessage2)
      (const CMPIBroker* mb, const char *msgId, 
       const CMPIMsgFileHandle msgFileHandle, const char *defMsg, 
       CMPIStatus* rc, CMPICount count, ...);

#   endif /* CMPI_VER_200 */

  };



  //---------------------------------------------------
  //--
  //   _CMPIBrokerFT Function Table
  //--
  //---------------------------------------------------


   /** This structure is a table of pointers to broker CIMOM services
       (up-calls). This table is made available by the Management Broker,
       whenever a provider is loaded and initialized.
   */
  struct _CMPIBrokerFT
  {

     /** 32 bits describing CMPI features supported by this CIMOM.
         See CMPI_MB_Class_x and CMPI_MB_Supports_xxx flags.
     */
    unsigned int brokerCapabilities;
     /** CIMOM version as defined by CIMOM
     */
    unsigned int brokerVersion;
     /** CIMOM name
     */
    const char *brokerName;

     /** This function prepares the CMPI run time system to accept
         a thread that will be using CMPI services. The returned
	 CMPIContext object must be used by the subsequent attachThread()
	 and detachThread() invocations.
	 @param mb Pointer to the broker.
	 @param ctx Old Context object
	 @return New Context object to be used by thread to be attached.
     */
    CMPIContext *(*prepareAttachThread)
      (const CMPIBroker * mb, const CMPIContext * ctx);

      /** This function informs the CMPI run time system that the current
         thread with Context will begin using CMPI services.
	 @param mb Pointer to the broker.
	 @param ctx Context object
	 @return Service return status.
     */
      CMPIStatus (*attachThread) (const CMPIBroker *, const CMPIContext *);

      /** This function informs the CMPI run time system that the current thread
         will not be using CMPI services anymore. The Context object will be
	 freed during this operation.
	 @param mb Pointer to the broker.
	 @param ctx Context object