cimclient.h

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
// l10n start
    /** Sets the accept languages that will be used on the next request.
        Accept languages are the preferred languages that are to be
        returned on the response to the next request.
        @param langs - REVIEWERS: Complete this
    */	
	void setRequestAcceptLanguages(AcceptLanguages& langs);

    /** Gets the accept languages that will be used on the next request.
        Accept languages are the preferred languages that are to be
        returned on the response to the next request.
    */
	AcceptLanguages getRequestAcceptLanguages() const;
	
    /** Sets the content languages that will be used on the next request.
        These content languages are the languages of the CIM objects that will
        sent on the next request.
        @param langs REVIEWERS: Complete this
    */  	
	void setRequestContentLanguages(ContentLanguages& langs);

    /** Gets the content languages that will be used on the next request.
     * These content languages are the languages of the CIM objects that will
     * sent on the next request.
    */    
	ContentLanguages getRequestContentLanguages() const;
	
    /** Gets the content languages of the last response.
     * These content languages are the languages of the CIM objects, or 
     * CIM exceptions, that were returned on the last response..
    */    	
	ContentLanguages getResponseContentLanguages() const;
	
	/** REVIEWERS: COmplete this
	 * 
	 */
	void setRequestDefaultLanguages();
// l10n end
#endif // PEGASUS_USE_EXPERIMENTAL_INTERFACES	


    /** The <TT>getClass</TT> method executes a CIM operation that returns
        a single CIM Class from the target Namespace where the ClassName input 
        parameter defines the name of the class to be retrieved.  
    
        @param nameSpace (Required) The <TT>nameSpace</TT> parameter is a CIMName 
        object that defines the target Namespace.  See definition of 
        \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.  
    
        @param className (Required)The <TT>className</TT> input parameter is a CIMName 
        object that defines the name of the Class to be retrieved.  
    
        @param localOnly (Boolean, Optional, default = true, Input)  If the <TT>localOnly</TT> input 
        parameter is true, this specifies that only CIM Elements (properties, 
        methods and qualifiers) overridden within the definition of the Class are 
        returned.  If false, all elements are returned.  This parameter therefore 
        effects a CIM Server-side mechanism to filter certain elements of the 
        returned object based on whether or not they have been propagated from the 
        parent Class (as defined by the PROPAGATED attribute).  
    
        @param includeQualifiers (Boolean, Optional, default = true, Input) If the 
        <TT>includeQualifiers</TT> input parameter is true, this specifies that 
        all Qualifiers for that Class (including Qualifiers on the Class and on 
        any returned Properties, Methods or CIMMethod Parameters) MUST be included 
        as elements in the response.  If false no QUALIFIER elements are present 
        in the returned Class object.  
    
        @param includeClassOrigin (Boolean,Optional, default = false, Input) If 
        the <TT>includeClassOrigin</TT> input parameter is true, this specifies 
        that the CLASSORIGIN attribute MUST be present on all appropriate elements 
        in the returned Class.  If false, no CLASSORIGIN attributes are present in 
        the returned Class.  
    
        @param propertyList (optional, Input) If the <TT>propertyList</TT> 
        CIMPropertyList input parameter is not NULL, the members of the array 
        define one or more CIMProperty names.  The returned Class WILL NOT include 
        elements for any Properties missing from this list.  Note that if 
        LocalOnly is specified as true this acts as an additional filter on the 
        set of Properties returned (for example, if CIMProperty A is included in 
        the PropertyList but LocalOnly is set to true and A is not local to the 
        requested Class, then it will not be included in the response).  If the 
        PropertyList input parameter is an empty array this signifies that no 
        Properties are included in the response.  If the PropertyList input 
        parameter is NULL this specifies that all Properties (subject to the 
        conditions expressed by the other parameters) are included in the 
        response.  
        @see CIMPropertyList
    
    	If the <TT>propertyList</TT> contains duplicate elements, the Server
    	MUST ignore the duplicates but otherwise process the request normally.
    	If the PropertyList contains elements which are invalid CIMProperty
    	names for the target Class, the Server MUST ignore such entries but
    	otherwise process the request normally.
    
    	@return If successful, the return value is a single CIMClass objcet.
    
    	If unsuccessful, an exception is executed. If the error is local, this may
        be any local exception.
        If the error is in the host normally a CIMException is returned with one of the
        following CIMException codes, where the first applicable error in the list (starting with
    	the first element of the list, and working down) is the error returned.
    	Any additional method-specific interpretation of the error is given
    	in parentheses.
    	<UL>
    		<LI>CIM_ERR_ACCESS_DENIED
    		<LI>CIM_ERR_INVALID_NAMESPACE
    		<LI>CIM_ERR_INVALID_PARAMETER (including missing,
    		duplicate,unrecognized or otherwise incorrect parameters)
    		<LI>CIM_ERR_NOT_FOUND (the request CIM Class does not exist in
    		the specified namespace)
    		<LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
        @exceptions REVIEWERS: Need to complete this definition
    	</UL>
        <pre>
            ... Connect sequence.
            CIMNamespace("root/cimv2);
            Boolean localOnly = true;
            Boolean includQualifiers = true;
            Boolean includeClassOrigin = false;
            CIMPropertyList propertyList;      // empty property list
            try
            CIMException checkClassException;
            { 
            CIMClass cimClass = client.getClass(nameSpace,
                                        className,
                                        localOnly,
                                        includeQualifiers,
                                        includeClassOrigin,
                                        propertyList);
            }
            catch(CIMException& e)
            {
                if (checkClassException.getCode() = CIM_ERR_NOT_FOUND)
                    cout << "Class " << className << " not found." << endl;
                ...
            }
            catch(Exception& e)
            {
            }
            ...
        
            // An alternate call with the default parameters would be:
            // This uses the defaults localOnly = includeQualifiers = true
            // includeClassOrigin = false. propertyList = Null;
            
            CIMClass cimClass = client.getClass(nameSpace, className);
        </pre>
        @exception REVIEWERS: Complete this
        @see CIMExcetpion
    */
    CIMClass getClass(
	const CIMNamespaceName& nameSpace,
	const CIMName& className,
	Boolean localOnly = true,
	Boolean includeQualifiers = true,
	Boolean includeClassOrigin = false,
	const CIMPropertyList& propertyList = CIMPropertyList()
    );

    /** Gets the CIM instance for the specified CIM object path.
        
        @param nameSpace (Required) The <TT>nameSpace</TT> parameter is a CIMName 
        object that defines the target Namespace.  See definition of 
        \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.  
        
    	@param instanceName CIMobjectpath that identifies this CIM instance. 
    	This must include all of the keys. 
    	
        @param localOnly If true, only properties and qualifiers overridden 
    	or defined in the returned Instance are included in the response. 
    	If false, all elements of the returned Instance are returned. 
    	
        @param includeQualifiers If true, all Qualifiers for each Object 
    	(including Qualifiers on the Object and on any returned Properties) 
    	MUST be included. If false no Qualifiers are present in the returned Object. 
    	
        @param includeClassOrigin If true, CLASSORIGIN attribute MUST be 
    	present on all appropriate elements in each returned Object. If false, 
    	no CLASSORIGIN attributes are present in each returned Object. The CLASSORIGIN
        attribute is defined in the DMTF's Specification for the Representation of CIM
        in XML. CLASSORIGIN is an XML tag identifying the following text as a class name.
        It is attached to a property or method (when specified in XML), to indicate the
        class where that property or method is first defined. Where the same property
        name is locally defined in another superclass or subclass, the Server will
        return the value for the property in the lowest subclass. 
    	
        @param propertyList If the PropertyList input parameter is not NULL, the
        members of the array define one or more Property names. Each returned Object
        MUST NOT include elements for any Properties missing from this list.
        Note that if LocalOnly is specified as true this acts as an additional
        filter on the set of Properties returned (for example, if Property A is
        included in the PropertyList but LocalOnly is set to true and A is not local
        to a returned Instance, then it will not be included in that Instance).
        If the PropertyList input parameter is an empty array this signifies that
        no Properties are included in each returned Object. If the PropertyList
        input parameter is NULL this specifies that all Properties (subject to
        the conditions expressed by the other parameters) are included in each
        returned Object. If the PropertyList contains duplicate elements, the
        Server ignores the duplicates but otherwise process the request normally.
        If the PropertyList contains elements which are invalid Property names for
        any target Object, the Server ignores such entries but otherwise process
        the request normally. 
    	
        @return If successful, the CIM instance identified by the CIMObjectPath. If 
        unsuccessful, an exception is executed.
        REVIEWERS: COmplete this.
	*/
	
    CIMInstance getInstance(
	const CIMNamespaceName& nameSpace,
	const CIMObjectPath& instanceName,
	Boolean localOnly = true,
	Boolean includeQualifiers = false,
	Boolean includeClassOrigin = false,
	const CIMPropertyList& propertyList = CIMPropertyList()
    );

    /** The <TT>DeleteClass</TT> method deletes a single CIM Class from the
	target Namespace.

	@param nameSpace The nameSpace parameter is a CIMName that defines
	the target namespace. 	See defintion of
	\URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.

	@param className The <TT>className</TT> input parameter defines the name
	of the Class to be deleted.

	@return If successful, the specified Class (including any subclasses
	and any instances) MUST have been removed by the CIM Server.  The
	operation MUST fail if any one of these objects cannot be deleted.

	If unsuccessful, one of the following status codes MUST be returned by
	this method, where the first applicable error in the list (starting
	with the first element of the list, and working down) is the error
	returned. Any additional method-specific interpretation of the error
	in is given in parentheses.

	<UL>
	    <LI>CIM_ERR_ACCESS_DENIED
	    <LI>CIM_ERR_NOT_SUPPORTED
	    <LI>CIM_ERR_INVALID_NAMESPACE
	    <LI>CIM_ERR_INVALID_PARAMETER (including missing, duplicate,
		unrecognized or otherwise incorrect parameters)
	    <LI>CIM_ERR_NOT_FOUND (the CIM Class to be deleted does not exist)
	    <LI>CIM_ERR_CLASS_HAS_CHILDREN (the CIM Class has one or more
		subclasses which cannot be deleted)
	    <LI>CIM_ERR_CLASS_HAS_INSTANCES (the CIM Class has one or more
		instances which cannot be deleted)
	    <LI>CIM_ERR_FAILED (some other unspecified error occurred)
	</UL>
    */
    void deleteClass(
	const CIMNamespaceName& nameSpace,
	const CIMName& className
    );

    /** The <TT>DeleteInstance</TT> operation deletes a single CIM Instance
	from the target Namespace.

	@param nameSpace The nameSpace parameter is a string that defines