The Provider Programming Interfaces

This section discusses the provider interfaces at a general level. Specific information about the functions, their interface, arguments and data types, can be found in the HP WBEM Services Software Developer’s Kit documentation in the /opt/wbem/html directory.

Relationship to Client Operations

The interfaces of the Provider API are the mechanism by which the CIM Server passes requests from clients onward to providers, which then manipulate the actual system resources modeled (represented) by CIM objects. The operations that clients can request generally correspond to the functions of the provider interfaces. However, it is important to remember that they are not identical. For example, the client operations getProperty and setProperty are converted by the CIM server to calls to the Instance Provider functions getInstance() and modifyInstance(), respectively.

General Considerations

All providers implement the CIMProvider interface (initialize() and terminate()).
A provider must implement (be declared as a C++ derived class of) one or more other interfaces: either the CIMInstanceProvider or the CIMMethodProvider interface. A single provider can implement both of these:
#include <Pegasus/Provider/CIMInstanceProvider.h> #include <Pegasus/Provider/CIMMethodProvider.h> class MyProvider : public CIMInstanceProvider, public CIMMethodProvider
All methods in an interface must be implemented; if a method is to be unsupported, it should throw a CIMNotSupportedException exception.
A provider may service more than one class, but there can be at most one instance provider for a given class, and it must "know about" all instances of the class(es) that it services.

Main Arguments

Most provider API functions take a class or an instance reference (an instance of the C++ CIMObjectPath class, sometimes called an instance name or object path) as the principle argument. A reference uniquely identifies an object (a class definition or an instance). It specifies a class name and, if an instance reference, the set of keys that uniquely identify the object.

Most functions that perform write operations (modify, delete) take a full instance (an instance of the C++ CIMInstance class) or a class definition (an instance of the C++ CIMClass class), as opposed to a reference (a CIMObjectPath), as the principle argument.

Other arguments and how they should be handled are covered in the Provider API sections in the /opt/wbem/html directory.

Returning Results

The C++ functions of the provider interfaces are of type void, and return no value. All normal (non-error) responses are returned to the CIM Server via a callback mechanism: functions receive a ResponseHandler object. The ResponseHandler class contains the following public member functions for returning data:

processing()
Informs the CIM Server that the provider is going to deliver results
deliver()
Delivers a potentially partial result to the CIM Server
complete()
All results for the operation have been delivered

Providers are encouraged to return partial results to enumerations in calls to deliver(), rather than constructing a complete result array. This aids overall system performance, as well as serving as a means for the CIM Server to know that a provider is still operating in cases where the result may be large.

Handling Error Conditions

All errors must be reported to the CIM Server by throwing an exception. The exception codes are listed in the API documentation in the Software Developers Kit, in the /opt/wbem/html directory.

PegasusCreateProvider and the Provider Class Constructor and Destructor

As previously discussed, a provider is an instance of a C++ class derived from one or more of the provider interfaces. When the CIM Server needs to invoke a provider function for the first time, after loading the appropriate shared library (if it has not already been loaded), it will call PegasusCreateProvider() with the name of the provider specified in the corresponding instance of PG_Provider. There must be exactly one PegasusCreateProvider entry point in a shared library, regardless of how many CIM classes may be served and regardless of how many C++ provider classes may be implemented.

PegasusCreateProvider() must return a pointer to an instance of the C++ provider class that will handle requests for the specified provider. The C++ provider instance can be created with new (so-called heap storage), or statically (an example is shown below). If the provider instance was created with new, it must be explicitly deallocated by a delete this; statement at the end of the provider's terminate() function. However, if it was created statically, it must not be explicitly deallocated with delete.

The provider source fragment shown in the section on “Provider Registration and Naming” illustrates how PegasusCreateProvider may be coded, creating the provider instance with new. The fragments below show static provider allocation.

Example 4-10 Code fragment showing static allocation of a provider instance

// class declaration for Example Provider
class ExampleProvider : public CIMInstanceProvider
{
...
};
...
// global static instantiation - exists in shared library
// and comes into existence when shared library is loaded.
// Note that the use of the "static" storage class
// specifier is not required for a global instance declaration,
// as shown.
ExampleProvider exp;
 
extern "C" CIMProvider*
PegasusCreateProvider(const String &providerName)
{
// return  the address of the global provider instance
if String::equalNoCase(providerName, "ExampleProvider")
return &exp;
else
return 0;
 
}

The provider constructor and destructor should do as little as possible. Any initialization should be done in the initialize() function, and cleanup in the terminate() function.

Instance Provider

The InstanceProvider interface is the most commonly implemented provider interface. An instance provider is required for any class that will have instances that can be displayed or manipulated by a client.

An instance provider must supply values for all required and key properties (required properties may be inherited from superclasses). This is required by the CIM standard for DMTF compliance, not HP WBEM Services for HP-UX. Properties not supported can be omitted by simply not adding the property when building a CIMInstance for responses to read operations (getInstance() and enumerateInstances()). However, on write operations (createInstance() and modifyInstance()), the provider must throw a CIMNotSupportedException exception if the specified instance contains properties that it does not support.

If an instance provider performs authorization, it may do so before attempting the requested operation. If the provider determines that the client is not authorized to perform the requested operation, it must throw an CIMAccessDeniedException exception.

If there are no instances to return in a request to enumerateInstanceNames() or enumerateInstances(), the provider should not throw an exception. It can simply return, or it may call the ResponseHandler processing() and complete() functions without calling deliver(). In either case, the client will receive an empty response.

If the instance named by getInstance(), modifyInstance(), or deleteInstance() does not exist, the provider must throw a CIMObjectNotFoundException exception.

Method Provider

A MethodProvider implements methods that are defined in a class. These are referred to in CIM as extrinsic methods (the operations of the Client API, such as getInstance(), are referred to as intrinsic methods). When a client wishes to invoke such a schema-specified method, it uses the invokeMethod() operation. The Method Provider must implement the provider interface function, invokeMethod(). In the implementation, it may examine the argument that contains the name of the requested extrinsic method, and thereby implement any number of extrinsic methods.