indicationservice.h

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

        This function is called by the _canCreate function, and is used to
        validate the Creation Class Name, System Name and System Creation Class
        Name properties in Filter and Handler instances.

        Note: currently all properties validated by this function are of type
        String.  To use this function in the future with properties of other
        types, a type parameter would need to be added, and the default value
        would need to be passed as a CIMValue instead of a String.

        Note: currently all properties validated by this function are non-array
        properties.  To use this function in the future with both array and
        non-array properties, a Boolean isArray parameter would need to be
        added.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   defaultValue          default value for property

        @return  the value of the property
     */
    String _initOrValidateStringProperty (
        CIMInstance & instance,
        const CIMName & propertyName,
        const String & defaultValue);

    /**
        Validates the specified property in the instance.
        If the property exists and its value is not NULL, but it is not of
        the correct type, an exception is thrown.
        This function is called by the _canCreate function.  It is used to
        validate the FailureTriggerTimeInterval, TimeOfLastStateChange,
        SubscriptionDuration, SubscriptionStartTime, SubscriptionTimeRemaining,
        RepeatNotificationInterval, RepeatNotificationGap, and
        RepeatNotificationCount properties in Subscription instances, the Owner
        property in Handler instances, and the PortNumber, SNMPSecurityName,
        and SNMPEngineID properties in SNMP Mapper Handler instances.

        Note: currently all properties validated by this function are non-array
        properties.  To use this function in the future with both array and
        non-array properties, a Boolean isArray parameter would need to be
        added.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   expectedType          expected CIMType for property
        @param   isArray               indicates whether the validated
                                       property is array

        @exception   CIM_ERR_INVALID_PARAMETER  if property exists and is not
                                                null but is not of the correct
                                                type
     */
    void _checkProperty (
        CIMInstance & instance,
        const CIMName & propertyName,
        const CIMType expectedType,
        const Boolean isArray = false);

    /**
        Validates that all properties in the instance are supported properties,
        and throws an exception if an unknown, unsupported property is found.

        @param   instance              instance to be validated

        @exception   CIM_ERR_NOT_SUPPORTED      if instance includes an unknown,
                                                unsupported property
     */
    void _checkSupportedProperties (
        const CIMInstance & instance);

    /**
        Validates value of the specified Uint16 property in the instance. 
        If the value of the property is not a valid value, or is not a 
        supported value, an exception is thrown.

        @param   instance              instance to be validated
        @param   propertyName          name of property to be validated
        @param   validValues           set of valid values for property
        @param   supportedValues       set of supported values for property
                                                                              
        @exception   CIM_ERR_NOT_SUPPORTED      if the property value is not 
                                                supported
                     CIM_ERR_INVALID_PARAMETER  if the property value is not 
                                                valid
     */
    void _checkValue (
        const CIMInstance & instance,
        const CIMName & propertyName,
        const Array <Uint16> & validValues,
        const Array <Uint16> & supportedValues);

    /**
        Determines if the user is authorized to modify the instance, and if the
        specified modification is supported.  Currently, the only modification
        supported is of the Subscription State property of the Subscription
        class.

        @param   request               modification request
        @param   instance              instance to be modified
        @param   modifiedInstance      modified instance

        @exception   CIM_ERR_NOT_SUPPORTED      if the specified modification is
                                                not supported
        @exception   CIM_ERR_ACCESS_DENIED      if the user is not authorized to
                                                modify the instance
        @exception   CIM_ERR_INVALID_PARAMETER  if the modifiedInstance is
                                                invalid

        @return  True, if the instance can be modified;
                 Otherwise throws an exception
     */
    Boolean _canModify (
        const CIMModifyInstanceRequestMessage * request,
        const CIMObjectPath & instanceReference,
        const CIMInstance & instance,
        CIMInstance & modifiedInstance);

    /**
        Determines if the user is authorized to delete the instance, and if it
        is legal to delete the instance.  If authorized, Subscription instances
        may always be deleted.  Filter and non-transient Handler instances may
        only be deleted if they are not being referenced by any Subscription
        instances. If the instance to be deleted is a transient Handler, any
        referencing Subscriptions are also deleted.

        @param   instanceReference     reference for instance to be deleted
        @param   nameSpace             namespace for instance to be deleted
        @param   currentUser           current user

        @exception   CIM_ERR_ACCESS_DENIED      if the user is not authorized to
                                                delete the instance
        @exception   CIM_ERR_FAILED             if the instance to be deleted is
                                                referenced by a subscription

        @return  True, if the instance can be deleted;
                 Otherwise throws an exception
     */
    Boolean _canDelete (
        const CIMObjectPath & instanceReference,
        const CIMNamespaceName & nameSpace,
        const String & currentUser);

    /**
        Retrieves list of enabled subscription instances in all namespaces,
        where the subscription indication class matches or is a superclass
        of the supported class, and the properties required to process the
        subscription are all contained in the list of supported properties.
        If the checkProvider parameter value is True, a subscription is only
        included in the list returned if the specified provider accepted the
        subscription.  If the checkProvider parameter value is False, the
        provider parameter is not used (ignored).

        @param   supportedClass       the supported class
        @param   nameSpaces           the list of supported namespaces
        @param   supportedProperties  the list of supported properties
        @param   checkProvider        indicates whether provider acceptance is
                                          checked
        @param   provider             the provider (used if checkProvider True)

        @return   list of CIMInstance subscriptions
     */
    Array <CIMInstance> _getMatchingSubscriptions (
        const CIMName & supportedClass,
        const Array <CIMNamespaceName> nameSpaces,
        const CIMPropertyList & supportedProperties,
        const Boolean checkProvider = false,
        const CIMInstance & provider = CIMInstance ());

    /**
        Retrieves lists of enabled subscription instances in all namespaces
        that are either newly supported or previously supported, based on the
        supported class, the supported namespaces before and after modification,
        and the supported properties before and after modification.  For
        subscriptions based on the supported class, the newSubscriptions list
        returned contains the subscriptions for which the properties required
        to process the subscription are all contained in the new list of
        supported properties, but are not all contained in the old list of
        supported properties, and/or the filter source namespace is contained in
        the new list if supported namespaces, but is not contained in the old
        list of supported namespaces.  The formerSubscriptions list returned
        contains the subscriptions for which the properties required to process
        the subscription are not all contained in the new list of supported
        properties, but are all contained in the old list of supported
        properties, and/or the filter source namespace is not contained in the
        new list if supported namespaces, but is contained in the old list of
        supported namespaces.

        @param   supportedClass       the supported class
        @param   newNameSpaces        namespaces supported after modification
        @param   oldNameSpaces        namespaces supported before modification
        @param   newProperties        properties supported after modification
        @param   oldProperties        properties supported before modification
        @param   newSubscriptions     the list of newly supported subscriptions
        @param   formerSubscriptions  the list of previously supported
                                          subscriptions
     */
    void _getModifiedSubscriptions (
        const CIMName & supportedClass,
        const Array <CIMNamespaceName> & newNameSpaces,
        const Array <CIMNamespaceName> & oldNameSpaces,
        const CIMPropertyList & newProperties,
        const CIMPropertyList & oldProperties,
        Array <CIMInstance> & newSubscriptions,
        Array <CIMInstance> & formerSubscriptions);

    /**
        Determines if all of the required properties in the specified list
        are contained in the specified list of supported properties.

        @param   requiredProperties  the required properties
        @param   supportedProperties the supported properties

        @return   true, if all required properties are supported;
                  false otherwise
     */
    Boolean _inPropertyList (
        const CIMPropertyList & requiredProperties,
        const CIMPropertyList & supportedProperties);

    /**
        Builds a QueryExpression from the filter query string,
        the query language name, and the namespace in which the query
        is to be run.

        @param   filterQuery           the filter query string
        @param   queryLanguage         the query language name
        @param   ns                    query namespace

        @return  QueryExpression representing the filter query
     */
    QueryExpression _getQueryExpression (const String& filterQuery,
                                         const String& queryLanguage,
                                         const CIMNamespaceName ns) const;

    /**
        Extracts the indication class name from the specified query expression
        (WQL or CQL), and validates that the name represents a subclass of the
        Indication class.

        @param   queryExpression       the query expression
        @param   nameSpaceName         the namespace

        @return  String containing the indication class name
     */
    CIMName _getIndicationClassName (
        const QueryExpression & queryExpression,
        const CIMNamespaceName & nameSpaceName) const;

    /**
        Retrieves the list of indication providers that serve the specified
        indication subclasses.

        @param   queryExpression       the query expression
        @param   nameSpace             the namespace name
        @param   indicationClassName   the indication class name
        @param   indicationSubclasses  the list of indication subclass names

        @return  list of ProviderClassList structs
     */
    Array <ProviderClassList> _getIndicationProviders (
        const QueryExpression & queryExpression,
        const CIMNamespaceName & nameSpace,
        const CIMName & indicationClassName,
        const Array <CIMName> & indicationSubclasses) const;

    /**
        Retrieves the list of required properties (all the properties
        referenced in the WHERE clause) for the specified filter query
        expression.

        @param   queryExpression       the query expression
        @param   nameSpaceName         the namespace
        @param   indicationClassName   the indication class name

        @return  CIMPropertyList of required properties for the filter query
                 expression
     */
    CIMPropertyList _getPropertyList (
        const QueryExpression & queryExpression,
        const CIMNamespaceName & nameSpaceName,
        const CIMName & indicationClassName) const;

    /**
        Checks if the property list includes all properties in the specified
        class.  If so, a NULL CIMPropertyList is returned.  Otherwise, a
        CIMPropertyList containing the properties is returned.  The list of
        property names in the specified indication class is also returned in
        the indicationClassProperties parameter.

        @param   propertyList                the list of property names
        @param   nameSpaceName               the namespace
        @param   indicationClassName         the indication class name
        @param   indicationClassProperties   the list of property names in the
                                               specified indication class

        @return  CIMPropertyList of properties referenced by the filter query
                 select statement
     */
    CIMPropertyList _checkPropertyList (
        const Array <CIMName> & propertyList,
        const CIMNamespaceName & nameSpaceName,
        const CIMName & indicationClassName,
        Array <CIMName> & indicationClassProperties) const;

    /**
        Extracts the condition (WHERE Clause) from the specified filter query
        string.

        @param   filterQuery       the filter query

        @return  String containing the filter query condition
     */
    String _getCondition (
        const String & filterQuery) const;