pegasus/src/Pegasus/Provider/CIMProvider.h - diff

Return to CIMProvider.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Provider

Diff for /pegasus/src/Pegasus/Provider/CIMProvider.h between version 1.36 and 1.37

version 1.36, 2006/09/06 19:32:41

version 1.37, 2006/09/20 19:50:22

Line 44

PEGASUS_NAMESPACE_BEGIN

/**

Parent class for all provider interfaces.

CIMProvider is the base class for the provider interface. A provider

must implement all the interfaces of the CIMProvider class and one or

more of its subclasses (such as CIMInstanceProvider). If a provider

does not support any of the operations specified by the interfaces,

it may just throw a CIMNotSupportedException.

The CIMProvider is the parent class for all provider

Some of the parameters that are common to the provider operation

interface types. The currently supported interfaces are:

interfaces are:

<ul>

<li>{@link CIMInstanceProvider CIMInstanceProvider} - supports

<li>The OperationContext parameter contains information about the

manipulation of CIM instances and their properties</li>

context for the specified operation, including the user name of the

<li>{@link CIMMethodProvider CIMMethodProvider} - supports

client requesting the operation. It is the provider's responsibility

invocation of methods defined on CIM instances</li>

to determine whether the user is authorized to perform the operation.

<li>{@link CIMAssociationProvider CIMAssociationProvider} -

If the operation should not be permitted, the provider must throw

supports query of CIM Associaitons and their properties. This provider

a CIMAccessDeniedException.</li>

interfaces provides both reference and associatior query operations in

accordance with the DMTF Cim Operation specifications

<li>A CIMObjectPath specifies the CIM object on which the operation

</ul>

is to be performed. This parameter specifies the hostname, namespace,

classname, and key values that uniquely identify a CIM instance.</li>

A provider may inherit from any of these interface classes or all of

them. A provider MUST implement every function in the chosen

interface(s). However, it is not required that all operations be

supported. If an operation is not supported, then a minimal

implementation of the corresponding function must throw a {@link

NotSupported NotSupported} exception.

\Label{mainParams}Certain parameters are passed in several of the functions

in the provider interfaces. These are also described in their own

sections, and include:

<ul>

<li>{@link OperationContext OperationContext} - contains

information about the client's context, including the User ID.

The provider must determine whether the specified user

should be permitted to perform the operation. If the

operation should not be permitted, the provider must throw

an {@link AccessDenied AccessDenied} exception.

</li>

<li>{@link CIMObjectPath CIMObjectPath} - specifies the

CIM object on which the operation is to be performed. This

parameter specifies the hostname, namespace, classname, and key values that

uniquely identify an instance of a CIM object.

hostname - specifies the name of the system on which

the object resides. This does not need to be the system that the CIM server

is running on, but it generally will be the same system.

namespace - this {@link CIMNamespaceName CIMNamespaceName}

object specifies the namespace on the

aforementioned host in which the object resides.

classname - specifies the class on which the requested

operation is to be performed.

keybindings - this{@link CIMKeyBinding CIMKeyBinging}

object specifies the set of key properties for the aforementioned

class. The set of keys uniquely identifies a CIM instance in the

host and namespace. It is permissible for clients to specify,

and providers should accept,

empty strings for key values when this would not be ambiguous.

If the specification is ambiguous, or if a key name is invalid or

missing, the provider

should throw an {@link InvalidParameter InvalidParameter}

exception.</li>

<li>{@link CIMInstance CIMInstance} - contains a

representation of an instance of a CIM object to be used

by the requested operation. This parameter should contain

all of the key properties, as well as all properties

necessary to perform the requested operation.</li>

<li>{@link CIMPropertyList CIMPropertyList} - specifies

the properties on which this operation should be performed.

The exact use of this parameter depends on the specific

operation, and is described in the respective section.</li>

<li>{@link ResponseHandler ResponseHandler} - a

callback handle used to return results to the CIM Server

for subsequent return to the client.</li>

</ul>

Certain exceptions can be thrown by several of the functions

in the provider interfaces. These are described in their own

sections, and include:

<ul>

<li>{@link CIMNotSupportedException CIMNotSupportedException} - the operation is not

supported.</li>

<li>{@link CIMInvalidParameterException CIMInvalidParameterException} - a parameter's

value was invalid. This could be an unknown property or key name, an

invalid flag, or other.</li>

<li>{@link CIMObjectNotFoundException CIMObjectNotFoundException} - the object specified

in the {@link CIMObjectPath CIMObjectPath} parameter could not be

found or does not exist.</li>

<li>{@link CIMObjectAlreadyExistsException CIMObjectAlreadyExistsException} - the object specified in a

<tt>{@link createInstance createInstance}</tt> operation already

exists.</li>

<li>{@link CIMAccessDeniedException CIMAccessDeniedException} - the requested

operation is not permitted. This can be because the user specified in

the {@link OperationContext} parameter is not authorized to perform

the requested operation, or another reason.</li>

<li>{@link CIMOperationFailedException CIMOperationFailedException} - a failure occurred during

processing of the operation.</li>

</ul>

<!-- save this material for later

<h3>Classes Instrumented</h3>

A provider may be registered to perform

operations on elements of more than one class. This

is useful when different classes of object are related

in the system resources that they manipulate, or

the system services that they call. It is also possible

for a provider to perform operations on several levels

of the same line of descent.

-->

The CIMProvider interface contains two functions that are

inherited by all provider interfaces:

<ul>

<li><tt>{@link initialize initialize}</tt> - Called before the

first call to any client-requested operation; the provider

should perform any processing

that may be required before normal operation can begin.</li>

<li><tt>{@link terminate terminate}</tt> - Called prior to

the provider being stopped; the provider should perform any

final processing that may be required.</li>

</ul>

Providers must implement these functions. A minimal

<li>A ResponseHandler is a callback handle used by the provider to

implementation may simply return to the caller.

deliver response data to the CIM Server.</li>

</ul>

class PEGASUS_PROVIDER_LINKAGE CIMProvider

{

public:

/** Creates a CIMProvider instance with null values (default constructor).

/**

Default constructor for the abstract CIMProvider class.

CIMProvider(void);

CIMProvider();

/**CIMProvider destructor.

/**

Destructs the CIMProvider instance.

virtual ~CIMProvider(void);

virtual ~CIMProvider();

/**

Performs any setup required before normal operation of the provider.

Initializes the provider. This method is called each time the

The initialize() function allows the provider to conduct the

provider is loaded and must complete before any of the other

necessary preparations to handle requests.

provider methods (other than terminate) are called.

The initialize function is called only once during the lifetime of the provider.

Note, however, that with the Pegasus automatic unload function enabled, a

An exception thrown from this method indicates a provider

provider many be unloaded and loaded many times during one cycle of the CIMOM.

initialization failure which prevents it from processing operation

This function must complete before the CIM server invokes any other function of

requests.

the provider, other than terminate.

An exception thrown from this method indicates a provider initialization

failure which prevents it from processing operation requests.

@param cimom Reserved for future use.

virtual void initialize(CIMOMHandle & cimom) = 0;

/**

Performs any cleanup required before termination.

Performs any cleanup required before the provider is unloaded.

The terminate function allows the provider to conduct the

This method may be called by the CIM Server at any time, including

necessary preparations for termination. This function

during initialization. No other provider methods are called after

may be called by the CIM Server

this method is invoked.

at any time, including initialization. Once invoked, no other provider

functions are invoked until after a call to initialize.

Examples of cleanup a provider may perform in this method include:

The provider may, for example, do the following in the

terminate function:

<ul>

<li>close files or I/O streams</li>

<li>Closing files and/or I/O streams</li>

<li>release resources such as shared memory</li>

<li>Releasing resources such as shared memory</li>

<li>inform concurrently executing

<li>Informing concurrently executing requests to complete

requests to complete immediately (this may be done by

immediately (perhaps by setting a global flag)</li>

setting a global flag)</li>

<li>Terminating subprocesses</li>

<li>kill subprocesses</li>

<li>and others</li>

</ul>

If the provider instance was created on the heap with

new in PegasusCreateProvider, then it must

If the PegasusCreateProvider function dynamically instantiates the

be deleted in terminate:

provider with the "new" operator, then the terminate() method must

<pre>void MyProvider::terminate()

"delete" it:

<pre>

void MyProvider::terminate()

{

...

delete this;

...

}

return;

</pre>

}</pre>

An exception thrown from this method is considered to be a provider error

An exception thrown from this method is considered to be a provider

and is ignored.

error and is ignored.

virtual void terminate(void) = 0;

virtual void terminate() = 0;

};

PEGASUS_NAMESPACE_END

Legend:

Removed from v.1.36
changed lines
	Added in v.1.37

No CVS admin address has been configured