/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2010 Raritan Inc. All rights reserved.
 */

#include <UserEvent.idl>

/** Bulk Configuration */
module bulkcfg {

    /** Bulk Configuration Interface */
    interface BulkConfiguration_1_0_2 {

        /** Status of the last bulk configuration restore operation */
        enumeration Status {
            UNKNOWN,            ///< No bulk configuration was done yet
            UPLOAD_FAILED,      ///< Uploading a bulk configuration failed
            RESTORE_PENDING,    ///< Restore is pending
            RESTORE_OK,         ///< Restoring bulk configuration successful
            RESTORE_FAILED      ///< Restoring bulk configuration failed
        };

        /**
         * Retrieve the status of the last bulk configuration restore
         * operation.
         *
         * @param status     Result: Bulk configuration restore status
         * @param timeStamp  Result: Time of last restore operation (UNIX timestamp, UTC)
         */
        void getStatus(out Status status, out time timeStamp);

        /**
         * These are the supported supported filter types.
         */
        enumeration FilterType {
            WHITELIST,                  ///< Whitelist filter (value is part of the bulk configuration)
            BLACKLIST                   ///< Blacklist filter (value is not part of the bulk configuration)
        };

        /**
         * This structure defines a filter.
         */
        structure Filter {
            string name;                ///< internal name of the filter
            string displayName;         ///< name of the filter in the user interface
            boolean noOverride;         ///< true if filter is always active and has a fixed type
            boolean bulkOnly;           ///< true if filter is not for backup
            vector<string> ruleSpecs;   ///< filter rule specifications (used only internally)
        };

        /**
         * Filter profiles are named collections of filters.
         *
         * Custom filter profiles inherit all filters from the builtin profile, i.e. if the filter profile
         * is empty it is identical to the builtin profile. The type for most of the inherited filters can
         * be changed in the derived profile. Only filters with the noOverride flag set are unchangable.
         */
        structure FilterProfile {
            string name;                                ///< name of the filter profile
            string description;                         ///< description of the filter profile
            map<string,FilterType> filterNameToTypeMap; ///< map filter name to type
        };

        /**
        * Settings
        */
        structure Settings {
            vector<FilterProfile> filterProfiles;       ///< Defined filter profiles
            string defaultProfileName;                  ///< Name of the default profile
        };

        /** Event: Bulk configuration settings changed */
        valueobject SettingsChangedEvent extends event.UserEvent {
        };

        /** Event: Bulk configuration saved (also used for saving config backup) */
        valueobject SavedEvent extends event.UserEvent {
            boolean isBackup; ///< true if the event is caused by saving a full configuration backup
        };

        /** Event: Bulk configuration restored (also used for restoring config backup) */
        valueobject RestoredEvent extends event.UserEvent {
            boolean isBackup; ///< true if the event is caused by restoring a full configuration backup
        };

        /**
         * Error codes
         */
        constant int SUCCESS                    = 0;    ///< The operation was successful
        constant int ERR_FILTER_NAME_UNKNOWN    = 1;    ///< A referenced filter name is unknown
        constant int ERR_FILTER_TYPE_READONLY   = 2;    ///< A referenced filter can't be overridden
        constant int ERR_PROFILE_ALREADY_EXISTS = 3;    ///< A profile with the given name already exists
        constant int ERR_PROFILE_DOES_NOT_EXIST = 4;    ///< A profile with the given name does not exist
        constant int ERR_PROFILE_IS_DEFAULT     = 5;    ///< The selected profile is the current default profile
        constant int ERR_PROFILE_IS_BUILTIN     = 6;    ///< The selected profile is the builtin profile
        constant int ERR_PROFILE_NAME_TOO_LONG  = 7;    ///< The profile name is too long
        constant int ERR_PROFILE_NAME_INVALID   = 8;    ///< The profile name contains invalid characters
        constant int ERR_PROFILE_TOO_MANY       = 9;    ///< The maximum number of profiles already exist.

        /**
         * Retrieve the list of supported filters.
         *
         * @return List of supported filters
         */
        vector<Filter> getFilters();

        /**
         * Retrieve the configured filter profiles.
         *
         * @return List of filter profiles
         */
        vector<FilterProfile> getFilterProfiles();

        /**
         * Add a new filter profile.
         *
         * @param profile  The new filter profile
         *
         * @return SUCCESS                    if OK
         * @return ERR_FILTER_NAME_UNKNOWN    if a referenced filter name is unknown
         * @return ERR_FILTER_TYPE_READONLY   if a referenced filter can't be overridden
         * @return ERR_PROFILE_ALREADY_EXISTS if a profile with the given name already exists
         * @return ERR_PROFILE_IS_BUILTIN     if the selected profile is the builtin profile
         * @return ERR_PROFILE_NAME_TOO_LONG  if the profile name is too long
         * @return ERR_PROFILE_NAME_INVALID   if the profile name contains invalid characters
         * @return ERR_PROFILE_TOO_MANY       if the maximum number of profiles already exist
         */
        int addFilterProfile(in FilterProfile profile);

        /**
         * Modify an existing filter profile.
         *
         * @param profile  The updated filter profile
         *
         * @return SUCCESS                    if OK
         * @return ERR_FILTER_NAME_UNKNOWN    if a referenced filter name is unknown
         * @return ERR_FILTER_TYPE_READONLY   if a referenced filter can't be overridden
         * @return ERR_PROFILE_DOES_NOT_EXIST if a profile with the given name does not exist
         * @return ERR_PROFILE_IS_BUILTIN     if the selected profile is the builtin profile
         */
        int modifyFilterProfile(in FilterProfile profile);

        /**
         * Delete an existing filter profile.
         *
         * @param profileName  The name of the profile to be deleted
         *
         * @return SUCCESS                    if OK
         * @return ERR_PROFILE_DOES_NOT_EXIST if a profile with the given name does not exist
         * @return ERR_PROFILE_IS_DEFAULT     if the selected profile is the current default profile
         * @return ERR_PROFILE_IS_BUILTIN     if the selected profile is the builtin profile
         */
        int deleteFilterProfile(in string profileName);

        /**
         * Retrieve the name of the currently selected default profile.
         *
         * @return  The name of the current default profile
         */
        string getDefaultFilterProfileName();

        /**
         * Select a new default filter profile.
         *
         * @param profileName  The name of the new default profile
         *
         * @return SUCCESS                    if OK
         * @return ERR_PROFILE_DOES_NOT_EXIST if a profile with the given name does not exist
         */
        int selectDefaultFilterProfile(in string profileName);

        /**
         * Get settings
         *
         * @return Settings
         */
        Settings getSettings();

        /**
         * Set settings
         *
         * NOTE: The builtin profile will be ignored when present in the list of filter profiles.
         *
         * @param settings  The settings to set
         *
         * @return SUCCESS                    if OK
         * @return ERR_FILTER_NAME_UNKNOWN    if a referenced filter name is unknown
         * @return ERR_FILTER_TYPE_READONLY   if a referenced filter can't be overridden
         * @return ERR_PROFILE_ALREADY_EXISTS if the settings contain multiple profiles with the same name
         * @return ERR_PROFILE_NAME_TOO_LONG  if the profile name is too long
         * @return ERR_PROFILE_NAME_INVALID   if the profile name contains invalid characters
         * @return ERR_PROFILE_TOO_MANY       if the settings contain too many profiles
         * @return ERR_PROFILE_DOES_NOT_EXIST if a profile with the given name does not exist
         */
        int setSettings(in Settings settings);

    };

}
