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

Return to CIMProvider.h CVS log

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

1 karl 1.35 //%2006////////////////////////////////////////////////////////////////////////
2 mike 1.14 //
3 karl 1.33 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development 4 // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems. 5 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
6 karl 1.27 // IBM Corp.; EMC Corporation, The Open Group.
7 karl 1.33 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.; 8 // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
9 karl 1.34 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.; 10 // EMC Corporation; VERITAS Software Corporation; The Open Group.
11 karl 1.35 // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.; 12 // EMC Corporation; Symantec Corporation; The Open Group.
13 mike 1.14 // 14 // Permission is hereby granted, free of charge, to any person obtaining a copy 15 // of this software and associated documentation files (the "Software"), to 16 // deal in the Software without restriction, including without limitation the 17 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 18 // sell copies of the Software, and to permit persons to whom the Software is 19 // furnished to do so, subject to the following conditions:
20 karl 1.27 //
21 mike 1.14 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN 22 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED 23 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 24 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 25 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 26 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 27 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 28 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 29 // 30 //============================================================================== 31 // 32 //%///////////////////////////////////////////////////////////////////////////// 33
34 kumpf 1.22 #ifndef Pegasus_CIMProvider_h 35 #define Pegasus_CIMProvider_h
36 mike 1.14 37 #include <Pegasus/Common/Config.h>
38 kumpf 1.22 #include <Pegasus/Common/OperationContext.h> 39 #include <Pegasus/Provider/CIMOMHandle.h> 40 #include <Pegasus/Provider/ProviderException.h> 41 #include <Pegasus/Common/ResponseHandler.h> 42 #include <Pegasus/Provider/Linkage.h>
43 mike 1.14 44 PEGASUS_NAMESPACE_BEGIN 45
46 kumpf 1.22 /** 47 Parent class for all provider interfaces.
48 mike 1.14
49 kumpf 1.22 <p>The <i>CIMProvider</i> is the parent class for all provider 50 interface types. The currently supported interfaces are:</p> 51 52 <ul> 53 <li><b>{@link CIMInstanceProvider CIMInstanceProvider}</b> - supports 54 manipulation of CIM instances and their properties</li> 55 <li><b>{@link CIMMethodProvider CIMMethodProvider}</b> - supports 56 invocation of methods defined on CIM instances</li>
57 karl 1.30 <li><b>{@link CIMAssociationProvider CIMAssociationProvider}</b> - 58 supports query of CIM Associaitons and their properties. This provider 59 interfaces provides both reference and associatior query operations in 60 accordance with the DMTF Cim Operation specifications
61 kumpf 1.22 </ul> 62
63 karl 1.30 <p>A provider may inherit from any of these interface classes or all of 64 them. A provider <i>MUST</i> implement every function in the chosen 65 interface(s). However, it is not required that all operations be 66 supported. If an operation is not supported, then a minimal 67 implementation of the corresponding function must throw a {@link 68 NotSupported NotSupported} exception.</p>
69 kumpf 1.22 70 <p>\Label{mainParams}Certain parameters are passed in several of the functions 71 in the provider interfaces. These are also described in their own 72 sections, and include:</p> 73 74 <p><ul> 75 <li><b>{@link OperationContext OperationContext}</b> - contains 76 information about the client's context, including the User ID. 77 The provider must determine whether the specified user 78 should be permitted to perform the operation. If the 79 operation should not be permitted, the provider must throw 80 an {@link AccessDenied AccessDenied} exception. 81 </li> 82 83 <li><b>{@link CIMObjectPath CIMObjectPath}</b> - specifies the 84 CIM object on which the operation is to be performed. This 85 parameter specifies the hostname, namespace, classname, and key values that 86 uniquely identify an instance of a CIM object. 87 <p><b>hostname</b> - specifies the name of the system on which
88 karl 1.28 the object resides. This does not need to be the system that the CIM server 89 is running on, but it generally will be the same system.</p>
90 kumpf 1.22
91 karl 1.30 <p><b>namespace</b> - this <b>{@link CIMNamespaceName CIMNamespaceName}</b> 92 object specifies the <i>namespace</i> on the 93 aforementioned host in which the object resides.</p>
94 kumpf 1.22 95 <p><b>classname</b> - specifies the class on which the requested 96 operation is to be performed.</p> 97
98 karl 1.30 <p><b>keybindings</b> - this<b>{@link CIMKeyBinding CIMKeyBinging}</b> 99 object specifies the set of key properties for the aforementioned
100 kumpf 1.22 class. The set of keys uniquely identifies a CIM instance in the 101 host and namespace. It is permissible for clients to specify, 102 and providers should accept, 103 empty strings for key values when this would not be ambiguous. 104 If the specification is ambiguous, or if a key name is invalid or 105 missing, the provider 106 should throw an {@link InvalidParameter InvalidParameter} 107 exception.</li> 108 109 <li><b>{@link CIMInstance CIMInstance}</b> - contains a 110 representation of an instance of a CIM object to be used 111 by the requested operation. This parameter should contain 112 all of the key properties, as well as all properties 113 necessary to perform the requested operation.</li> 114 115 <li><b>{@link CIMPropertyList CIMPropertyList}</b> - specifies 116 the properties on which this operation should be performed. 117 The exact use of this parameter depends on the specific 118 operation, and is described in the respective section.</li> 119 120 <li><b>{@link ResponseHandler ResponseHandler}</b> - a
121 kumpf 1.23 <i>callback</i> handle used to return results to the CIM Server
122 kumpf 1.22 for subsequent return to the client.</li> 123 </ul></p> 124 125 <p>Certain exceptions can be thrown by several of the functions 126 in the provider interfaces. These are described in their own 127 sections, and include:</p> 128 <p><ul> 129 <li><b>{@link CIMNotSupportedException CIMNotSupportedException}</b> - the operation is not 130 supported.</li> 131 <li><b>{@link CIMInvalidParameterException CIMInvalidParameterException}</b> - a parameter's 132 value was invalid. This could be an unknown property or key name, an 133 invalid flag, or other.</li> 134 <li><b>{@link CIMObjectNotFoundException CIMObjectNotFoundException}</b> - the object specified 135 in the {@link CIMObjectPath CIMObjectPath} parameter could not be 136 found or does not exist.</li> 137 <li><b>{@link CIMObjectAlreadyExistsException CIMObjectAlreadyExistsException}</b> - the object specified in a 138 <tt>{@link createInstance createInstance}</tt> operation already 139 exists.</li> 140 <li><b>{@link CIMAccessDeniedException CIMAccessDeniedException}</b> - the requested 141 operation is not permitted. This can be because the user specified in 142 the {@link OperationContext} parameter is not authorized to perform 143 kumpf 1.22 the requested operation, or another reason.</li> 144 <li><b>{@link CIMOperationFailedException CIMOperationFailedException}</b> - a failure occurred during 145 processing of the operation.</li> 146 </ul></p> 147 148 <!-- save this material for later 149 <h3>Classes Instrumented</h3> 150 151 <p>A provider may be registered to perform 152 operations on elements of more than one class. This 153 is useful when different classes of object are related 154 in the system resources that they manipulate, or 155 the system services that they call. It is also possible 156 for a provider to perform operations on several levels 157 of the same line of descent.</p> 158 --> 159 160 <p>The CIMProvider interface contains two functions that are 161 inherited by all provider interfaces:</p> 162 163 <p><ul> 164 kumpf 1.22 <li><tt>{@link initialize initialize}</tt> - Called before the 165 first call to any client-requested operation; the provider 166 should perform any processing 167 that may be required before normal operation can begin.</li> 168 <li><tt>{@link terminate terminate}</tt> - Called prior to 169 the provider being stopped; the provider should perform any 170 final processing that may be required.</li> 171 </ul></p> 172 173 <p>Providers <i>must</i> implement these functions. A minimal 174 implementation may simply return to the caller.</p> 175 */
176 mike 1.18 class PEGASUS_PROVIDER_LINKAGE CIMProvider
177 mike 1.14 { 178 public:
179 karl 1.28 /** Creates a CIMProvider instance with null values (default constructor). 180 */
181 kumpf 1.22 CIMProvider(void);
182 kumpf 1.23
183 karl 1.28 /*CIMProvider destructor. 184 /
185 kumpf 1.22 virtual ~CIMProvider(void);
186 mike 1.14
187 kumpf 1.22 /**
188 karl 1.30 Performs any setup required before normal operation of the provider. 189 <p>The initialize() function allows the provider to conduct the
190 kumpf 1.22 necessary preparations to handle requests.
191 karl 1.30 The initialize function is called only once during the lifetime of the provider. 192 Note, however, that with the Pegasus automatic unload function enabled, a 193 provider many be unloaded and loaded many times during one cycle of the CIMOM.
194 karl 1.28 This function must complete before the CIM server invokes any other function of
195 kumpf 1.22 the provider, other than terminate.</p>
196 mike 1.14
197 kumpf 1.22 @param cimom Reserved for future use. 198 */ 199 virtual void initialize(CIMOMHandle & cimom) = 0;
200 mike 1.14 201 /**
202 karl 1.28 Performs any cleanup required before termination.
203 karl 1.30 <p>The terminate function allows the provider to conduct the
204 kumpf 1.23 necessary preparations for termination. This function 205 may be called by the CIM Server
206 kumpf 1.22 at any time, including initialization. Once invoked, no other provider
207 karl 1.30 functions are invoked until after a call to initialize.</p>
208 kumpf 1.22 <p>The provider may, for example, do the following in the
209 karl 1.30 terminate function:</p>
210 kumpf 1.22 <ul>
211 kumpf 1.23 <li>close files or I/O streams</li>
212 kumpf 1.22 <li>release resources such as shared memory</li> 213 <li>inform concurrently executing 214 requests to complete immediately (this may be done by 215 setting a global flag)</li> 216 <li>kill subprocesses</li>
217 karl 1.28 <li>and others</li>
218 kumpf 1.22 </ul> 219 <p>If the provider instance was created on the heap with
220 karl 1.30 <i>new</i> in PegasusCreateProvider, then it must 221 be deleted in terminate:
222 kumpf 1.22 <pre>void MyProvider::terminate() 223 { 224 ... 225 delete this; 226 ... 227 return; 228 }</pre>
229 mike 1.14 */
230 kumpf 1.22 virtual void terminate(void) = 0;
231 mike 1.14
232 kumpf 1.26 #ifdef PEGASUS_PRESERVE_TRYTERMINATE
233 mday 1.25 /**
234 karl 1.30 Allows a provider to decline a terminate call. If the provider
235 mday 1.25 is unable to terminate, it should return false. Otherwise,
236 karl 1.30 it calls its terminate() function and then
237 karl 1.28 returns true, as in the default implementation.
238 karl 1.30 @return False If the provider is unable to terminate; Otherwise, return true.
239 mday 1.25 */ 240 virtual Boolean tryTerminate(void) 241 { 242 terminate(); 243 return true; 244 }
245 kumpf 1.26 #endif
246 mday 1.25
247 mike 1.14 }; 248 249 PEGASUS_NAMESPACE_END 250
251 kumpf 1.22 #endif

No CVS admin address has been configured