1 a.dunfey 1.1 //%2006////////////////////////////////////////////////////////////////////////
  2              //
  3              // 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              // IBM Corp.; EMC Corporation, The Open Group.
  7              // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8              // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
  9              // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10              // EMC Corporation; VERITAS Software Corporation; The Open Group.
 11              // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 12              // EMC Corporation; Symantec Corporation; The Open Group.
 13              //
 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              // 
 21              // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 22 a.dunfey 1.1 // 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              #ifndef InteropProviderUtils_h
 33              #define InteropProviderUtils_h
 34              
 35              #include <Pegasus/Common/Array.h>
 36              #include <Pegasus/Common/CIMClass.h>
 37              #include <Pegasus/Common/CIMInstance.h>
 38              #include <Pegasus/Common/CIMObjectPath.h>
 39              #include <Pegasus/Common/CIMPropertyList.h>
 40              #include <Pegasus/Common/String.h>
 41              
 42              PEGASUS_NAMESPACE_BEGIN;
 43 a.dunfey 1.1 
 44              // Enum for class selection for instance operations.
 45              enum TARGET_CLASS {
 46                      PG_NAMESPACE,
 47                      PG_OBJECTMANAGER,
 48                      PG_CIMXMLCOMMUNICATIONMECHANISM,
 49                      PG_NAMESPACEINMANAGER,
 50                      PG_COMMMECHANISMFORMANAGER,
 51                      PG_REGISTEREDPROFILE,
 52                      PG_REGISTEREDSUBPROFILE,
 53                      PG_REFERENCEDPROFILE,
 54                      PG_ELEMENTCONFORMSTOPROFILE,
 55                      PG_SUBPROFILEREQUIRESPROFILE,
 56                      PG_SOFTWAREIDENTITY,
 57                      PG_ELEMENTSOFTWAREIDENTITY,
 58                      PG_INSTALLEDSOFTWAREIDENTITY,
 59                      PG_COMPUTERSYSTEM,
 60                      PG_HOSTEDOBJECTMANAGER,
 61                      PG_HOSTEDACCESSPOINT
 62              };
 63              
 64 a.dunfey 1.1 /***************************************************************
 65               *                                                             *
 66               *               Provider Utility Functions                    *
 67               *                                                             *
 68               ***************************************************************/
 69              
 70              const char * boolToString(Boolean x);
 71              
 72              //
 73              // Utility function used to produce trace/logging statements
 74              //
 75              String propertyListToString(const CIMPropertyList& pl);
 76              
 77              //
 78              // Helper function that constructs an the InstanceId property out of its
 79              // constituent pieces.
 80              //
 81              String buildProfileInstanceId(
 82                  const String & organization,
 83                  const String & name,
 84                  const String & version);
 85 a.dunfey 1.1 
 86              //
 87              // function that creates an object path given a class definition, an
 88              // instance of that class, the host name, and the namespace.
 89              //
 90              CIMObjectPath buildInstancePath(
 91                  const CIMClass & cimClass,
 92                  const String & hostName,
 93                  const CIMNamespaceName & nameSpace,
 94                  const CIMInstance & instance);
 95              
 96              //
 97              // Template function that retrieves the value of a property. The template
 98              // type determines the type that should be contained within the CIMValue object
 99              // of the property (specified by the propName parameter) in the supplied
100              // instance. This is used particularly for Required properties, so if the
101              // property is not found or is NULL, an exception will be thrown.
102              //
103              template <class RetClass>
104              RetClass getRequiredValue(const CIMInstance & instance,
105                                        const CIMName & propName)
106 a.dunfey 1.1 {
107                  RetClass retVal;
108                  Uint32 index = instance.findProperty(propName);
109                  if(index == PEG_NOT_FOUND)
110                  {
111                      throw CIMOperationFailedException("Instance " +
112                          instance.getPath().toString() +
113                          " missing expected property " + propName.getString());
114                  }
115                  const CIMValue & tmpVal = instance.getProperty(index).getValue();
116                  if(tmpVal.isNull())
117                  {
118                      throw CIMOperationFailedException("Instance " +
119                          instance.getPath().toString() +
120                          " has unexpected NULL value for property " + propName.getString());
121                  }
122              
123                  tmpVal.get(retVal);
124              
125                  return retVal;
126              }
127 a.dunfey 1.1 
128              //
129              // Determines if the namespace is allowable for this operation.
130              // This provider is designed to accept either all namespaces or
131              // limit itself to just one for operations.  In all cases, it
132              // will provide the required answers and use the correct namespace
133              // for any persistent information.  However, it may be configured
134              // to either accept input operations from any namespace or simply
135              // from one (normally the interop namespace).
136              // @ objectReference for the operation.  This must include the
137              // namespace and class name for the operation.
138              // @return Returns normally if the namespace test is passed. Otherwise
139              // it generates a CIMException (CIM_ERR_NOT_SUPPORTED)
140              // @exception CIMException(CIM_ERR_NOT_SUPPORTED)
141              //
142              // NOTE:This function is commented out because the routing tables will always
143              // do the right thing and that's the only way requests get here. If this
144              // changes, then this function should be reinstated along with the various
145              // locations where calls to the function are also commented out.
146              //
147              /*
148 a.dunfey 1.1 bool namespaceSupported(const CIMObjectPath & path);
149              */
150              
151              //
152              // Normalize the instance by setting the complete path for the instance and
153              // executing the instance filter to set the qualifiers, classorigin, and
154              // property list in accordance with the input.  Note that this can only remove
155              // characteristics, except for the path completion, so that it expects
156              // instances with qualifiers, class origin, and a complete set of properties
157              // already present in the instance.
158              //
159              void normalizeInstance(CIMInstance& instance, const CIMObjectPath& path,
160                                     Boolean includeQualifiers, Boolean includeClassOrigin,
161                                     const CIMPropertyList& propertyList);
162              
163              //
164              // Get one string property from an instance. Note that these functions simply
165              // return the default value if the property cannot be found or is of the wrong
166              // type.
167              // @param instance CIMInstance from which we get property value
168              // @param propertyName String name of the property containing the value
169 a.dunfey 1.1 // @param default String optional parameter that is substituted if the property
170              // does not exist or is NULL.
171              // @return String value found or defaultValue.
172              //
173              String getPropertyValue(const CIMInstance & instance,
174                  const CIMName & propertyName, const String & defaultValue);
175              
176              //
177              // Overload of getPropertyValue for boolean type
178              //
179              Boolean getPropertyValue(const CIMInstance & instance,
180                  const CIMName & propertyName, const Boolean defaultValue);
181              
182              //
183              // Get Host IP address from host name. If the host name is not provided,
184              // uses internal function. If everything fails, gets the definition normally
185              // used for localhost (127.0.0.1).
186              //
187              // @param hostName String with the name of the host. Allows String:EMPTY and
188              //     in that case, gets it directly from system.
189              // @param namespaceType - Uint32 representing the access protocol for this
190 a.dunfey 1.1 //     request.  This is exactly the definition in the
191              //     PG_CIMXMLCommunicationMechanism mof for the property
192              //     namespaceAccessProtocol.
193              // @param port String defining the port to be used.  If String::EMPTY, it is
194              //     not valid and the defaultPortNumber is inserted instead.
195              // @param defaultPortNumber Uint32 defining a default port number to be used
196              //     if port string is not provided.
197              //
198              // @return String with the IP address to be used. This must be the complete
199              //     address sufficient to access the IP address. Therefore, it includes the
200              //     port number.
201              //
202              String getHostAddress(const String & hostName, Uint32 namespaceType,
203                  const String & port, Uint32 defaultPortNumber);
204              
205              //
206              // Validate that the property exists, is string type and optionally the value
207              // itself. NOTE: This function processes only String properties.
208              //
209              // @param Instance to search for property.
210              // @param CIMName containing property Name
211 a.dunfey 1.1 // @param String containing value. If not String::EMPTY, compare to value
212              //     in the property
213              // @return True if passes all tests
214              //
215              Boolean validateRequiredProperty(
216                  const CIMInstance & instance,
217                  const CIMName & propertyName,
218                  const String & value);
219              
220              //
221              // Same as above, overloaded to check key properties in CIMObjectPath objects
222              // against a string value.
223              //
224              Boolean validateRequiredProperty(
225                  const CIMObjectPath & objectPath,
226                  const CIMName & propertyName,
227                  const String & value);
228              
229              //
230              // Verify that this is one of the legal classnames for instance operations and
231              // return an indicator as to which one it is.
232 a.dunfey 1.1 // @param - Classname
233              // @return - Enum value indicating type
234              // @Exceptions - throws CIMNotSupportedException if invalid class.
235              //
236              TARGET_CLASS translateClassInput(const CIMName& className);
237              
238              //
239              // Same as method above, but used specifically for association classes.
240              //
241              TARGET_CLASS translateAssocClassInput(const CIMName & className);
242              
243              //
244              // Set the value of a property defined by property name in the instance
245              // provided. If the property cannot be found, it simply returns.
246              //
247              // @param instance CIMInstance in which to set property value
248              // @param propertyName CIMName of property in which value will be set.
249              // @param value CIMValue value to set into property
250              //
251              // @return true if property value was set, false if the property was not found
252              //
253 a.dunfey 1.1 void setPropertyValue(CIMInstance& instance, const CIMName& propertyName,
254                  const CIMValue & value);
255              
256              //
257              // Sets the correct values to the common keys defined for all of the classes.
258              // This is SystemCreationClassName and SystemName. Note that if the properties
259              // do not exist, we simply ignore them.
260              //
261              void setCommonKeys(CIMInstance& instance);
262              
263              //
264              // Retrieves the key binding given by the keyName parameter from the supplied
265              // object path.
266              //
267              String getKeyValue(const CIMObjectPath& instanceName, const CIMName& keyName);
268              
269              //
270              // Retrieves the key binding given by the keyName parameter from the supplied
271              // instance.
272              //
273              String getKeyValue(const CIMInstance& instance, const CIMName& keyName);
274 a.dunfey 1.1 
275              //
276              // The following method is used to translate a string based on the
277              // Value/ValueMap qualifiers of a property. Note that the method is written
278              // in such a way that the translation could be done in either direction
279              // (from Value value to ValueMap value or vice versa) or with another pair
280              // of qualifiers with a relationship similar to the Value/ValueMap pair.
281              //
282              String translateValue(
283                  const String & value,
284                  const CIMName & propName,
285                  const CIMName & sourceQualifier,
286                  const CIMName & targetQualifier,
287                  const CIMClass & classDef);
288              
289              //
290              // Same as above, but converts an integral value into a string first so that
291              // it can be found when searching the Values qualifier (or some similar
292              // qualifier).
293              //
294              String translateValue(Uint16 value, const CIMName & propName,
295 a.dunfey 1.1     const CIMName & sourceQualifier, const CIMName & targetQualifier,
296                  const CIMClass & classDef);
297              
298              //
299              // helper function for building a reference ObjectPath for an instance
300              // of CIM_Dependency.
301              //
302              CIMObjectPath buildDependencyReference(
303                  const String & hostName,
304                  const String & instanceId,
305                  const CIMName & instanceClass);
306              
307              //
308              // helper function for building an instance of CIM_Dependency given
309              // the antecedent and dependent references and the concrete subclass for which
310              // the instance will be created.
311              //
312              CIMInstance buildDependencyInstanceFromPaths(
313                  const CIMObjectPath & antecedent,
314                  const CIMObjectPath & dependent,
315                  const CIMClass & dependencyClass);
316 a.dunfey 1.1 
317              //
318              // Given an instance of PG_ProviderProfileCapabilities, this method retrieves
319              // the values necessary for constructing instances of PG_RegisteredProfile,
320              // PG_RegisteredSubProfile, and all of their associations.
321              // NOTE: This function is implemented in RegisteredProfile.cpp but declared
322              //       here so that it can be accessed by ElementConformsToProfile.cpp and
323              //       Software.cpp.
324              //
325              String extractProfileInfo(
326                  const CIMInstance & profileCapabilities,
327                  const CIMClass & capabilitiesClass,
328                  const CIMClass & profileClass,
329                  String & name,
330                  String & version,
331                  Uint16 & organization,
332                  String & organizationName,
333                  Array<String> & subprofileNames,
334                  Array<String> & subprofileVersions,
335                  Array<Uint16> & subprofileOrganizations,
336                  Array<String> & subprofileOrganizationNames,
337 a.dunfey 1.1     bool noSubProfileInfo = true);
338              
339              PEGASUS_NAMESPACE_END;
340              
341              #endif // InteropProviderUtils_h