version 1.36, 2006/09/06 19:32:41
|
version 1.37, 2006/09/20 19:50:22
|
|
|
PEGASUS_NAMESPACE_BEGIN | 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. |
| |
<p>The <i>CIMProvider</i> is the parent class for all provider |
<p>Some of the parameters that are common to the provider operation |
interface types. The currently supported interfaces are:</p> |
interfaces are: |
| |
<ul> | <ul> |
<li><b>{@link CIMInstanceProvider CIMInstanceProvider}</b> - 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><b>{@link CIMMethodProvider CIMMethodProvider}</b> - 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><b>{@link CIMAssociationProvider CIMAssociationProvider}</b> - |
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> |
<p>A provider may inherit from any of these interface classes or all of |
|
them. A provider <i>MUST</i> 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.</p> |
|
|
|
<p>\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:</p> |
|
|
|
<p><ul> |
|
<li><b>{@link OperationContext OperationContext}</b> - 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><b>{@link CIMObjectPath CIMObjectPath}</b> - 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. |
|
<p><b>hostname</b> - 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.</p> |
|
|
|
<p><b>namespace</b> - this <b>{@link CIMNamespaceName CIMNamespaceName}</b> |
|
object specifies the <i>namespace</i> on the |
|
aforementioned host in which the object resides.</p> |
|
|
|
<p><b>classname</b> - specifies the class on which the requested |
|
operation is to be performed.</p> |
|
|
|
<p><b>keybindings</b> - this<b>{@link CIMKeyBinding CIMKeyBinging}</b> |
|
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><b>{@link CIMInstance CIMInstance}</b> - 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><b>{@link CIMPropertyList CIMPropertyList}</b> - 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><b>{@link ResponseHandler ResponseHandler}</b> - a |
|
<i>callback</i> handle used to return results to the CIM Server |
|
for subsequent return to the client.</li> |
|
</ul></p> |
|
|
|
<p>Certain exceptions can be thrown by several of the functions |
|
in the provider interfaces. These are described in their own |
|
sections, and include:</p> |
|
<p><ul> |
|
<li><b>{@link CIMNotSupportedException CIMNotSupportedException}</b> - the operation is not |
|
supported.</li> |
|
<li><b>{@link CIMInvalidParameterException CIMInvalidParameterException}</b> - a parameter's |
|
value was invalid. This could be an unknown property or key name, an |
|
invalid flag, or other.</li> |
|
<li><b>{@link CIMObjectNotFoundException CIMObjectNotFoundException}</b> - the object specified |
|
in the {@link CIMObjectPath CIMObjectPath} parameter could not be |
|
found or does not exist.</li> |
|
<li><b>{@link CIMObjectAlreadyExistsException CIMObjectAlreadyExistsException}</b> - the object specified in a |
|
<tt>{@link createInstance createInstance}</tt> operation already |
|
exists.</li> |
|
<li><b>{@link CIMAccessDeniedException CIMAccessDeniedException}</b> - 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><b>{@link CIMOperationFailedException CIMOperationFailedException}</b> - a failure occurred during |
|
processing of the operation.</li> |
|
</ul></p> |
|
|
|
<!-- save this material for later |
|
<h3>Classes Instrumented</h3> |
|
|
|
<p>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.</p> |
|
--> |
|
|
|
<p>The CIMProvider interface contains two functions that are |
|
inherited by all provider interfaces:</p> |
|
|
|
<p><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></p> |
|
| |
<p>Providers <i>must</i> implement these functions. A minimal |
<li>A ResponseHandler is a callback handle used by the provider to |
implementation may simply return to the caller.</p> |
deliver response data to the CIM Server.</li> |
|
</ul> |
*/ | */ |
class PEGASUS_PROVIDER_LINKAGE CIMProvider | class PEGASUS_PROVIDER_LINKAGE CIMProvider |
{ | { |
public: | 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 |
<p>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.</p> |
|
|
|
An exception thrown from this method indicates a provider initialization |
|
failure which prevents it from processing operation requests. |
|
| |
@param cimom Reserved for future use. | @param cimom Reserved for future use. |
*/ | */ |
virtual void initialize(CIMOMHandle & cimom) = 0; | virtual void initialize(CIMOMHandle & cimom) = 0; |
| |
/** | /** |
Performs any cleanup required before termination. |
Performs any cleanup required before the provider is unloaded. |
<p>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.</p> |
<p>Examples of cleanup a provider may perform in this method include: |
<p>The provider may, for example, do the following in the |
|
terminate function:</p> |
|
<ul> | <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> | </ul> |
<p>If the provider instance was created on the heap with |
|
<i>new</i> in PegasusCreateProvider, then it must |
<p>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; | delete this; |
... |
} |
return; |
</pre> |
}</pre> |
|
| |
An exception thrown from this method is considered to be a provider error |
<p>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 | PEGASUS_NAMESPACE_END |