chromium/components/policy/core/browser/configuration_policy_handler.h

// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef COMPONENTS_POLICY_CORE_BROWSER_CONFIGURATION_POLICY_HANDLER_H_
#define COMPONENTS_POLICY_CORE_BROWSER_CONFIGURATION_POLICY_HANDLER_H_

#include <memory>
#include <optional>
#include <string>
#include <vector>

#include "base/compiler_specific.h"
#include "base/containers/enum_set.h"
#include "base/functional/callback.h"
#include "base/values.h"
#include "components/policy/core/common/policy_map.h"
#include "components/policy/core/common/schema.h"
#include "components/policy/policy_export.h"

class PrefValueMap;

namespace policy {

class PolicyErrorMap;
struct PolicyHandlerParameters;
class PolicyMap;

extern POLICY_EXPORT const size_t kMaxUrlFiltersPerPolicy;

// Maps a policy type to a preference path, and to the expected value type.
struct POLICY_EXPORT PolicyToPreferenceMapEntry { … };

// An abstract super class that subclasses should implement to map policies to
// their corresponding preferences, and to check whether the policies are valid.
class POLICY_EXPORT ConfigurationPolicyHandler { … };

// Abstract class derived from ConfigurationPolicyHandler that should be
// subclassed to handle policies that have a name.
class POLICY_EXPORT NamedPolicyHandler : public ConfigurationPolicyHandler { … };

// Abstract class derived from ConfigurationPolicyHandler that should be
// subclassed to handle a single policy (not a combination of policies).
class POLICY_EXPORT TypeCheckingPolicyHandler : public NamedPolicyHandler { … };

// Policy handler that makes sure the policy value is a list and filters out any
// list entries that are not of type |list_entry_type|. Derived methods may
// apply additional filters on list entries and transform the filtered list.
class POLICY_EXPORT ListPolicyHandler : public TypeCheckingPolicyHandler { … };

// Abstract class derived from TypeCheckingPolicyHandler that ensures an int
// policy's value lies in an allowed range. Either clamps or rejects values
// outside the range.
class POLICY_EXPORT IntRangePolicyHandlerBase
    : public TypeCheckingPolicyHandler { … };

// ConfigurationPolicyHandler for policies that map directly to a preference.
class POLICY_EXPORT SimplePolicyHandler : public TypeCheckingPolicyHandler { … };

// ConfigurationPolicyHandler for policies that rely on another policy to take
// effect.
class POLICY_EXPORT PolicyWithDependencyHandler : public NamedPolicyHandler { … };

// Base class that encapsulates logic for mapping from a string enum list
// to a separate matching type value.
class POLICY_EXPORT StringMappingListPolicyHandler
    : public TypeCheckingPolicyHandler { … };

// A policy handler implementation that ensures an int policy's value lies in an
// allowed range.
class POLICY_EXPORT IntRangePolicyHandler : public IntRangePolicyHandlerBase { … };

// A policy handler implementation that maps an int percentage value to a
// double.
class POLICY_EXPORT IntPercentageToDoublePolicyHandler
    : public IntRangePolicyHandlerBase { … };

// Like TypeCheckingPolicyHandler, but validates against a schema instead of a
// single type. |schema| is the schema used for this policy, and |strategy| is
// the strategy used for schema validation errors.
class POLICY_EXPORT SchemaValidatingPolicyHandler : public NamedPolicyHandler { … };

// Maps policy to pref like SimplePolicyHandler while ensuring that the value
// set matches the schema. |schema| is the schema used for policies, and
// |strategy| is the strategy used for schema validation errors.
// The |recommended_permission| and |mandatory_permission| flags indicate the
// levels at which the policy can be set. A value set at an unsupported level
// will be ignored.
class POLICY_EXPORT SimpleSchemaValidatingPolicyHandler
    : public SchemaValidatingPolicyHandler { … };

// Maps policy to pref like SimplePolicyHandler. Ensures that the root value
// of the policy is of the correct type (that is, a string, or a list, depending
// on the policy). Apart from that, all policy values are accepted without
// modification, but the |PolicyErrorMap| will be updated for every error
// encountered - for instance, if the embedded JSON is unparsable or if it does
// not match the validation schema.
// NOTE: Do not store new policies using JSON strings! If your policy has a
// complex schema, store it as a dict of that schema. This has some advantages:
// - You don't have to parse JSON every time you read it from the pref store.
// - Nested dicts are simple, but nested JSON strings are complicated.
class POLICY_EXPORT SimpleJsonStringSchemaValidatingPolicyHandler
    : public NamedPolicyHandler { … };

// A policy handler to deprecate multiple legacy policies with a new one.
// This handler will completely ignore any of legacy policy values if the new
// one is set.
class POLICY_EXPORT LegacyPoliciesDeprecatingPolicyHandler
    : public ConfigurationPolicyHandler { … };

// A policy handler to deprecate a single policy with a new one. It will attempt
// to use the new value if present and then try to use the legacy value instead.
class POLICY_EXPORT SimpleDeprecatingPolicyHandler
    : public ConfigurationPolicyHandler { … };

// A schema policy handler for complex policies that only accept cloud sources.
class POLICY_EXPORT CloudOnlyPolicyHandler
    : public SchemaValidatingPolicyHandler { … };

// A schema policy handler for complex policies that only accept user scoped
// sources.
class POLICY_EXPORT CloudUserOnlyPolicyHandler : public NamedPolicyHandler { … };

// A schema policy handler string policies expecting a URL.
class POLICY_EXPORT URLPolicyHandler : public SimplePolicyHandler { … };

}  // namespace policy

#endif  // COMPONENTS_POLICY_CORE_BROWSER_CONFIGURATION_POLICY_HANDLER_H_