cimclient.h

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

        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
        the target namespace.  See defintion of
        \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.

        @param instanceName The <TT>instanceName</TT> input parameter defines
        the name (model path) of the Instance to be deleted.

        @return If successful, the specified Instance MUST have been removed
        by the CIM Server.

        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_INVALID_CLASS (the CIM Class does not exist in the
                specified namespace)
            <LI>CIM_ERR_NOT_FOUND (the CIM Class does exist, but the requested
                CIM Instance does not exist in the specified namespace)
            <LI>CIM_ERR_FAILED (some other unspecified error occurred)</LI>
        </UL>
    */
    void deleteInstance(
        const CIMNamespaceName& nameSpace,
        const CIMObjectPath& instanceName
    );

    /** The <TT>createClass</TT> method creates a single CIM Class in
    the target Namespace. The Class MUST NOT already exist. The NewClass input
    parameter defines the new Class.  The proposed definition MUST be a correct
    Class definition according to the CIM specification.

    In processing the creation of the new Class, the following rules MUST be
    conformed to by the CIM Server:

    Any CLASSORIGIN and PROPAGATED attributes in the NewClass MUST be ignored by
    the Server. If the new Class has no Superclass, the NewClass parameter
    defines a new base Class. The Server MUST ensure that all Properties and
    Methods of the new Class have a CLASSORIGIN attribute whose value is the
    name of the new Class. If the new Class has a Superclass, the NewClass
    parameter defines a new Subclass of that Superclass. The Superclass MUST
    exist. The Server MUST ensure that:

    <UL>
        <LI>Any Properties, Methods or Qualifiers in the Subclass not defined in
        the Superclass are created as new elements of the Subclass. In
        particular the Server MUST set the CLASSORIGIN attribute on the new
        Properties and Methods to the name of the Subclass, and ensure that all
        other Properties and Methods preserve their CLASSORIGIN attribute value
        from that defined in the Superclass

        If a CIMProperty is defined in the Superclass and in the Subclass, the
        value assigned to that property in the Subclass (including NULL) becomes
        the default value of the property for the Subclass. If a CIMProperty or
        CIMMethod of the Superclass is not specified in the Subclass, then that
        CIMProperty or CIMMethod is inherited without modification by the
        Subclass

        <LI>Any Qualifiers defined in the Superclass with a TOSUBCLASS attribute
        value of true MUST appear in the resulting Subclass. Qualifiers in the
        Superclass with a TOSUBCLASS attribute value of false MUST NOT be
        propagated to the Subclass . Any CIMQualifier propagated from the
        Superclass cannot be modified in the Subclass if the OVERRIDABLE
        attribute of that CIMQualifier was set to false in the Superclass. It is
        a
        Client error to specify such a CIMQualifier in the NewClass with a
        different definition to that in the Superclass (where definition
        encompasses the name, type and flavor attribute settings of the
        <QUALIFIER> element, and the value of the CIMQualifier).
        </LI>
    </UL>

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

    @param newClass The <TT>newClass<?TT> input parameter defines the new Class.

    @return If successful, the specified Class MUST have been created by the CIM