wifi_sync: add ability to convert WifiCredential to onc properties

components/wifi_sync/wifi_credential.h

 // Copyright 2014 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_WIFI_SYNC_WIFI_CREDENTIAL_H_
 #define COMPONENTS_WIFI_SYNC_WIFI_CREDENTIAL_H_
 
 #include <stdint.h>
 
 #include <set>
 #include <string>
 #include <vector>
 
+#include "base/memory/scoped_ptr.h"
 #include "components/wifi_sync/wifi_security_class.h"
 
+namespace base {
+class DictionaryValue;
+}
+
 namespace wifi_sync {
 
 // A container to hold the information required to locate and connect
 // to a WiFi network.
 class WifiCredential final {  // final because the class is copyable
  public:
+  // Per IEEE 802.11-2012 (Sec 8.4.2.2), the only requirement on SSIDs
+  // is that they are between 0 and 32 bytes in length
+  // (inclusive). There are no restrictions on the values of those
+  // bytes. The SSID is not, e.g., required to be encoded as UTF-8.
   using SsidBytes = std::vector<uint8_t>;
   using CredentialSet = std::set<
       WifiCredential,
       bool(*)(const WifiCredential&a, const WifiCredential& b)>;
 
-  // Constructs a credential with the given |ssid|, |security_class|,
+  ~WifiCredential();
+
+  // Creates a WifiCredential with the given |ssid|, |security_class|,
   // and |passphrase|. No assumptions are made about the input
-  // encoding of |ssid|. The passphrase must be valid UTF-8.
-  WifiCredential(const SsidBytes& ssid,
-                 WifiSecurityClass security_class,
-                 const std::string& passphrase);
-  ~WifiCredential();
+  // encoding of |ssid|. |passphrase|, however, must be valid
+  // UTF-8. Returns NULL if the parameters are invalid.
+  static scoped_ptr<WifiCredential> Create(
+      const SsidBytes& ssid,
+      WifiSecurityClass security_class,
+      const std::string& passphrase);
 
   const SsidBytes& ssid() const { return ssid_; }
   WifiSecurityClass security_class() const { return security_class_; }
   const std::string& passphrase() const { return passphrase_; }
 
+  // Returns a dictionary which represents this WifiCredential as ONC
+  // properties. The resulting dictionary can be used, e.g, to
+  // configure a new network using
+  // chromeos::NetworkConfigurationHandler::CreateConfiguration. Due
+  // to limitations in ONC, this operation fails if ssid() is not
+  // valid UTF-8. In case of failure, returns a scoped_ptr with value
+  // nullptr.
+  scoped_ptr<base::DictionaryValue> ToOncProperties() const;
+
   // Returns a string representation of the credential, for debugging
   // purposes. The string will not include the credential's passphrase.
   std::string ToString() const;
 
   // Returns true if credential |a| comes before credential |b|.
   static bool IsLessThan(const WifiCredential& a, const WifiCredential& b);
 
   // Returns an empty set of WifiCredentials, with the IsLessThan
   // ordering function plumbed in.
   static CredentialSet MakeSet();
 
+  // Returns |ssid| as an SsidBytes instance. This convenience
+  // function simplifies some tests, which need to instantiate
+  // SsidBytes from string literals.
+  static SsidBytes MakeSsidBytesForTest(const std::string& ssid);
+
  private:
+  // Constructs a credential with the given |ssid|, |security_class|,
+  // and |passphrase|.
+  WifiCredential(const SsidBytes& ssid,
+                 WifiSecurityClass security_class,
+                 const std::string& passphrase);
+
   // The WiFi network's SSID.
   const SsidBytes ssid_;
   // The WiFi network's security class (e.g. WEP, PSK).
   const WifiSecurityClass security_class_;
   // The passphrase for connecting to the network.
   const std::string passphrase_;
 };
 
 }  // namespace wifi_sync
 
 #endif  // COMPONENTS_WIFI_SYNC_WIFI_CREDENTIAL_H_