Add touch flag to output of Schema::Normalize()

components/policy/core/common/schema.h

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef COMPONENTS_POLICY_CORE_COMMON_SCHEMA_H_
 #define COMPONENTS_POLICY_CORE_COMMON_SCHEMA_H_
 
 #include <string>
 
 #include "base/basictypes.h"
 #include "base/memory/ref_counted.h"
 #include "base/values.h"
 #include "components/policy/policy_export.h"
 
 namespace policy {
 namespace internal {
 
 struct POLICY_EXPORT SchemaData;
 struct POLICY_EXPORT SchemaNode;
 struct POLICY_EXPORT PropertyNode;
 struct POLICY_EXPORT PropertiesNode;
 
 }  // namespace internal
 
 // Option flags passed to Schema::Validate() and Schema::Normalize(), describing
 // the strategy to handle unknown properties or invalid values for dict type.
 // Note that in Schema::Normalize() allowed errors will be dropped and thus
 // ignored.
+// Unknown error indicates that some value in a dictionary (may or may not be
+// the one in root) have unknown property name according to schema.
+// Invalid error indicates a validation failure against the schema. As
+// validation is done recursively, a validation failure of dict properties or
+// list items might be ignored (or dropped in Normalize()) or trigger whole
+// dictionary/list validation failure.
 enum SchemaOnErrorStrategy {
   // No errors will be allowed.
   SCHEMA_STRICT = 0,
   // Unknown properties in the top-level dictionary will be ignored.
   SCHEMA_ALLOW_UNKNOWN_TOPLEVEL,
   // Unknown properties in any dictionary will be ignored.
   SCHEMA_ALLOW_UNKNOWN,
   // Mismatched values will be ignored at the toplevel.
   SCHEMA_ALLOW_INVALID_TOPLEVEL,
   // Mismatched values will be ignored at the top-level value.
@@ skipping 44 matching lines @@
   // detailed message if |value| doesn't strictly conform to the schema. If
   // |value| doesn't conform to the schema even within the allowance of
   // |strategy|, false will be returned and |error_path| and |error| will
   // contain the corresponding error that caused the failure. |error_path| can
   // be NULL and in that case no error path will be returned.
   bool Validate(const base::Value& value,
                 SchemaOnErrorStrategy strategy,
                 std::string* error_path,
                 std::string* error) const;
 
-  // Same as Validate() but drop values with errors instead of ignoring them.
+  // Similar to Validate() but drop values with errors instead of ignoring them.
+  // |changed| is a pointer to a boolean value, and indicate whether |value|
+  // is changed or not (probably dropped properties or items). Be sure to set
+  // the bool that |changed| pointed to to false before calling Normalize().
+  // |changed| can be NULL and in that case no boolean will be set.
+  // This function will also take the ownership of dropped base::Value and
+  // destroy them.
   bool Normalize(base::Value* value,
                  SchemaOnErrorStrategy strategy,
                  std::string* error_path,
-                 std::string* error) const;
+                 std::string* error,
+                 bool* changed) const;
 
   // Used to iterate over the known properties of TYPE_DICTIONARY schemas.
   class POLICY_EXPORT Iterator {
    public:
     Iterator(const scoped_refptr<const InternalStorage>& storage,
              const internal::PropertiesNode* node);
     Iterator(const Iterator& iterator);
     ~Iterator();
 
     Iterator& operator=(const Iterator& iterator);
@@ skipping 49 matching lines @@
   bool ValidateIntegerRestriction(int index, int value) const;
   bool ValidateStringRestriction(int index, const char* str) const;
 
   scoped_refptr<const InternalStorage> storage_;
   const internal::SchemaNode* node_;
 };
 
 }  // namespace policy
 
 #endif  // COMPONENTS_POLICY_CORE_COMMON_SCHEMA_H_