Expand SecurityStyleChanged interfaces to include explanations

content/public/common/security_style.h

 // Copyright (c) 2012 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 CONTENT_PUBLIC_COMMON_SECURITY_STYLE_H_
 #define CONTENT_PUBLIC_COMMON_SECURITY_STYLE_H_
 
+#include <string>
+#include <vector>
+
 namespace content {
 
 // Various aspects of the UI change their appearance according to the security
 // context in which they are displayed.  For example, the location bar displays
 // a lock icon when it is displayed during a valid SSL connection.
 // SecuritySyle enumerates these styles, but it is up to the UI elements to
 // adjust their display appropriately.
 enum SecurityStyle {
   // SECURITY_STYLE_UNKNOWN indicates that we do not know the proper security
   // style for this object.
@@ skipping 14 matching lines @@
   // authenticated manner, but there were security issues with the retrieval or
   // the object interacted with less secure objects.
   SECURITY_STYLE_WARNING,
 
   // SECURITY_STYLE_AUTHENTICATED indicates that we successfully retrieved this
   // object over an authenticated protocol, such as HTTPS.
   SECURITY_STYLE_AUTHENTICATED,
   SECURITY_STYLE_LAST = SECURITY_STYLE_AUTHENTICATED
 };
 
+// A human-readable summary phrase and more detailed description of a
+// security property that was used to compute the SecurityStyle of a
+// resource. An example summary phrase would be "Expired Certificate",
+// with a description along the lines of "This site's certificate chain
+// contains errors (net::CERT_DATE_INVALID)".
+struct SecurityStyleExplanation {
+  SecurityStyleExplanation();
+  SecurityStyleExplanation(const std::string& summary_input,
+                           const std::string& description_input);

[Peter Kasting, 2015/06/16 22:11:31]

Nit: Name these |summary| and |description|.  You can still write the
initializer list this way:

  SecurityStyleExplanation(const std::string& summary,
                           const std::string& description)
      : summary(summary), description(description) {
  }

...and the compiler will get it right.

[estark, 2015/06/16 23:42:20]

Done.

+  ~SecurityStyleExplanation();
+
+  std::string summary;
+  std::string description;
+};
+
+// A SecurityStyleExplanations contains human-readable explanations for

[Peter Kasting, 2015/06/16 22:11:31]

Nit: Remove initial "A" (it just makes the sentence less grammatically clear)

[estark, 2015/06/16 23:42:20]

Done.

+// why a particular SecurityStyle was chosen. Each
+// SecurityStyleExplanation is a single security property of a page (for
+// example, an expired certificate or the presence of active mixed
+// content). An explanation can have multiple |warning_explanations| and
+// multiple |broken_explanations|, and both can be non-empty if a site
+// has multiple issues.

[Peter Kasting, 2015/06/16 22:11:31]

Nit: This last sentence is now unclear because "An explanation" no longer
clearly refers to this class.  How about:

A single site may have multiple different explanations of both "warning" and
"broken" severity levels.

[estark, 2015/06/16 23:42:20]

Done.

+struct SecurityStyleExplanations {
+  SecurityStyleExplanations();
+  ~SecurityStyleExplanations();
+
+  std::vector<SecurityStyleExplanation> warning_explanations;
+  std::vector<SecurityStyleExplanation> broken_explanations;
+};
+
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_COMMON_SECURITY_STYLE_H_