ciminstanceprovider.h

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

    <tt>{@link complete complete}</tt> functions without calling
    <tt>{@link deliver deliver}</tt>.

    @exception CIMAccessDeniedException
    @exception CIMOperationFailedException

    */
    virtual void enumerateInstances(
        const OperationContext & context,
        const CIMObjectPath & classReference,
        const Boolean includeQualifiers,
        const Boolean includeClassOrigin,
        const CIMPropertyList & propertyList,
        InstanceResponseHandler & handler) = 0;

    /**
    \Label{enumerateInstanceNames}
    Return all instance names of a single class.

    <p>Like <tt>enumerateInstances</tt>, a typical implementation
    of <tt>enumerateInstanceNames</tt> will call the
    <tt>{@link processing processing}</tt> function in the
    <tt>{@link ResponseHandler handler}</tt> object, then
    iterate over the system resources representing instances of
    the CIM object, calling <tt>{@link deliver deliver}</tt> on
    each iteration. It must call {@link deliver deliver} with an
    argument of type <tt>{@link CIMObjectPath CIMObjectPath}</tt>
    containing the information that uniquely identifies each
    instance.
    Finally, it will call <tt>{@link complete complete}</tt> to
    inform the CIM Server that it has delivered all known instances.</p>

    <p>A provider can be implemented and registered to perform
    operations for several levels of the same line of descent (e.g.,
    CIM_ComputerSystem and CIM_UnitaryComputerSystem). When this
    is done, the provider must return instance names <i>only</i>
    for the deepest class for which it is registered, since
    the CIM Server will invoke <tt>enumerateInstanceNames</tt> for all
    classes at and beneath that specified in the
    {@link CIMObjectPath classReference}.</p>

    @param context specifies the client user's context for this operation,
    including the User ID.

    @param classReference specifies the fully qualified object path to
    the class of interest.

    @param handler {@link ResponseHandler ResponseHandler} object for
    delivery of results.

    @exception CIMNotSupportedException
    @exception CIMInvalidParameterException
    @exception CIMObjectNotFoundException
    @exception CIMAccessDeniedException
    @exception CIMOperationFailedException
    */
    virtual void enumerateInstanceNames(
        const OperationContext & context,
        const CIMObjectPath & classReference,
        ObjectPathResponseHandler & handler) = 0;

    /**
    \Label{modifyInstance}
    Replace the current instance specified in the
    instanceReference parameter.

    <p><tt>modifyInstance</tt> sets the values of properties of
    the instance specified by the <tt>instanceReference</tt> parameter
    to those specified in the <tt>instanceObject</tt> parameter, as
    controlled by the <tt>propertyList</tt> parameter. If the
    <tt>propertyList</tt>
    is NULL, then the operation sets all properties. Otherwise,
    it sets only those specified in the <tt>propertyList</tt>.
    Properties specified in the <tt>propertyList</tt> but not present in
    the <tt>instanceObject</tt> are replaced by
    the class default values or left null.</p>

    <p>Ideally, <tt>modifyInstance</tt> is intended to be
    an <i>atomic</i> operation on values of the instance. That is,
    concurrent accesses to the instance by other threads should be
    blocked during the operation, so that all of the affected property
    values can be
    changed without intervening accesses by concurrent requests.
    Otherwise, other requests could obtain intermediate, and
    possibly inconsistent, results.</p>

    <p>If the specified instance does not exist, the provider
    should throw an {@link CIMObjectNotFoundException ObjectNotFound}
    exception.

    @param context specifies the client user's context for this operation,
    including the User ID.

    @param instanceReference specifies the fully qualified object path of the instance of interest.

    @param instanceObject contains the partial or complete set of
    properties whose values should be changed.

    @param includeQualifiers indicates whether the instance qualifiers must
    be updated as specified in the modified instance.  If false, no
    qualifiers are explicitly modified by this operation.

    @param propertyList If not null, this parameter
    specifies the set of properties required to be updated in the instance. Support
    for this parameter is NOT optional.  Providers that do not support this
    feature must throw a {@link CIMNotSupportedException CIMNotSupportedException} exception.

    @param handler {@link ResponseHandler ResponseHandler} object for
    delivery of results.

    @exception CIMNotSupportedException
    @exception CIMInvalidParameterException
    @exception CIMObjectNotFoundException
    @exception CIMAccessDeniedException
    @exception CIMOperationFailedException
    */
    virtual void modifyInstance(
        const OperationContext & context,
        const CIMObjectPath & instanceReference,
        const CIMInstance & instanceObject,
        const Boolean includeQualifiers,
        const CIMPropertyList & propertyList,
        ResponseHandler & handler) = 0;

    /**
    \Label{createInstance}
    Create a new instance.

    <p>Create a new instance of the specified class as specified
    by the <tt>instanceReference</tt> and <tt>instanceObject</tt>
    parameters.</p>

    @param context specifies the client user's context for this operation,
    including the User ID.

    @param instanceReference specifies the fully qualified object
    path of the instance to create.
    It is possible that the values for some properties are
    null, and that these null
    properties may be keys, when this would not be ambiguous. When
    a non-key property value is null, the provider may insert
    the default value for the class, or null. When a key property
    value is null, the provider <i>must</i> use a valid value
    for the property. If a key property value is null, and the set
    of keys does not uniquely define an instance name, or any
    other parameter is invalid, then the
    provider should throw an {@link CIMInvalidParameterException CIMInvalidParameterException}
    exception.

    @param instanceObject contains the partial or complete instance to create.

    @param handler {@link ResponseHandler ResponseHandler} object for
    delivery of results.

    @exception CIMNotSupportedException
    @exception CIMInvalidParameterException
    @exception ObjectAlreadyExists
    @exception CIMAccessDeniedException
    @exception CIMOperationFailedException
    */
    virtual void createInstance(
        const OperationContext & context,
        const CIMObjectPath & instanceReference,
        const CIMInstance & instanceObject,
        ObjectPathResponseHandler & handler) = 0;

    /**
    \Label{deleteInstance}
    Delete the instance specified by the instanceReference parameter.

    @param context specifies the client user's context for this operation,
    including the User ID.

    @param instanceReference specifies the fully qualified object
    path of the instance to delete. If the specified object does
    not exist, the provider should throw an
    {@link CIMObjectNotFoundException ObjectNotFound} exception.

    @param handler {@link ResponseHandler ResponseHandler} object for
    delivery of results.

    @exception CIMNotSupportedException
    @exception CIMInvalidParameterException
    @exception CIMObjectNotFoundException
    @exception CIMAccessDeniedException
    @exception CIMOperationFailedException
    */
    virtual void deleteInstance(
        const OperationContext & context,
        const CIMObjectPath & instanceReference,
        ResponseHandler & handler) = 0;
};

PEGASUS_NAMESPACE_END

#endif