Reland of: Adding error output param to SetConfiguration, using new RTCError type.

webrtc/api/peerconnectioninterface.h

 /*
  *  Copyright 2012 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 132 matching lines @@
   virtual void AddHistogramSample(PeerConnectionMetricsName type,
                                   int value) = 0;
 
  protected:
   virtual ~MetricsObserverInterface() {}
 };
 
 typedef MetricsObserverInterface UMAObserver;
 
 // Enumeration to represent distinct classes of errors that an application
-// may wish to act upon differently. These roughly map to DOMExceptions in
-// the web API, as described in the comments below.
-enum class RtcError {
+// may wish to act upon differently. These roughly map to DOMExceptions or
+// RTCError "errorDetailEnum" values in the web API, as described in the
+// comments below.
+enum class RTCErrorType {
   // No error.
   NONE,
   // A supplied parameter is valid, but currently unsupported.
   // Maps to InvalidAccessError DOMException.
   UNSUPPORTED_PARAMETER,
   // General error indicating that a supplied parameter is invalid.
   // Maps to InvalidAccessError or TypeError DOMException depending on context.
   INVALID_PARAMETER,
   // Slightly more specific than INVALID_PARAMETER; a parameter's value was
   // outside the allowed range.
@@ skipping 10 matching lines @@
   // Maps to InvalidModificationError DOMException.
   INVALID_MODIFICATION,
   // An error occurred within an underlying network protocol.
   // Maps to NetworkError DOMException.
   NETWORK_ERROR,
   // The operation failed due to an internal error.
   // Maps to OperationError DOMException.
   INTERNAL_ERROR,
 };
 
+// Roughly corresponds to RTCError in the web api. Holds an error type and
+// possibly additional information specific to that error.
+//
+// Doesn't contain anything beyond a type now, but will in the future as more
+// errors are implemented.
+class RTCError {
+ public:
+  RTCError() : type_(RTCErrorType::NONE) {}
+  explicit RTCError(RTCErrorType type) : type_(type) {}
+
+  RTCErrorType type() const { return type_; }
+  void set_type(RTCErrorType type) { type_ = type; }
+
+ private:
+  RTCErrorType type_;
+};
+
 // Outputs the error as a friendly string.
 // Update this method when adding a new error type.
-std::ostream& operator<<(std::ostream& stream, RtcError error);
+std::ostream& operator<<(std::ostream& stream, RTCErrorType error);
 
 class PeerConnectionInterface : public rtc::RefCountInterface {
  public:
   // See http://dev.w3.org/2011/webrtc/editor/webrtc.html#state-definitions .
   enum SignalingState {
     kStable,
     kHaveLocalOffer,
     kHaveLocalPrAnswer,
     kHaveRemoteOffer,
     kHaveRemotePrAnswer,
@@ skipping 113 matching lines @@
         ice_connection_receiving_timeout =
             kAggressiveIceConnectionReceivingTimeout;
 
         // These parameters are not defined in Java or IOS configuration,
         // so their values will not be overwritten.
         enable_ice_renomination = true;
         redetermine_role_on_ice_restart = false;
       }
     }
 
+    bool operator==(const RTCConfiguration& o) const;
+    bool operator!=(const RTCConfiguration& o) const;
+
     bool dscp() { return media_config.enable_dscp; }
     void set_dscp(bool enable) { media_config.enable_dscp = enable; }
 
     // TODO(nisse): The corresponding flag in MediaConfig and
     // elsewhere should be renamed enable_cpu_adaptation.
     bool cpu_adaptation() {
       return media_config.video.enable_cpu_overuse_detection;
     }
     void set_cpu_adaptation(bool enable) {
       media_config.video.enable_cpu_overuse_detection = enable;
@@ skipping 53 matching lines @@
     bool prune_turn_ports = false;
     // If set to true, this means the ICE transport should presume TURN-to-TURN
     // candidate pairs will succeed, even before a binding response is received.
     bool presume_writable_when_fully_relayed = false;
     // If true, "renomination" will be added to the ice options in the transport
     // description.
     bool enable_ice_renomination = false;
     // If true, ICE role is redetermined when peerconnection sets a local
     // transport description that indicates an ICE restart.
     bool redetermine_role_on_ice_restart = true;
+    //
+    // Don't forget to update operator== if adding something.
+    //
   };
 
   struct RTCOfferAnswerOptions {
     static const int kUndefined = -1;
     static const int kMaxOfferToReceiveMedia = 1;
 
     // The default value for constraint offerToReceiveX:true.
     static const int kOfferToReceiveMediaTrue = 1;
 
     int offer_to_receive_video = kUndefined;
@@ skipping 157 matching lines @@
   virtual bool UpdateIce(const IceServers& configuration,
                          const MediaConstraintsInterface* constraints) {
     return false;
   }
   virtual bool UpdateIce(const IceServers& configuration) { return false; }
   // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
   // PeerConnectionInterface implement it.
   virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() {
     return PeerConnectionInterface::RTCConfiguration();
   }
+
   // Sets the PeerConnection's global configuration to |config|.
+  //
+  // The members of |config| that may be changed are |type|, |servers|,
+  // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate
+  // pool size can't be changed after the first call to SetLocalDescription).
+  // Note that this means the BUNDLE and RTCP-multiplexing policies cannot be
+  // changed with this method.
+  //
   // Any changes to STUN/TURN servers or ICE candidate policy will affect the
   // next gathering phase, and cause the next call to createOffer to generate
-  // new ICE credentials. Note that the BUNDLE and RTCP-multiplexing policies
-  // cannot be changed with this method.
+  // new ICE credentials, as described in JSEP. This also occurs when
+  // |prune_turn_ports| changes, for the same reasoning.
+  //
+  // If an error occurs, returns false and populates |error| if non-null:
+  // - INVALID_MODIFICATION if |config| contains a modified parameter other
+  //   than one of the parameters listed above.
+  // - INVALID_RANGE if |ice_candidate_pool_size| is out of range.
+  // - SYNTAX_ERROR if parsing an ICE server URL failed.
+  // - INVALID_PARAMETER if a TURN server is missing |username| or |password|.
+  // - INTERNAL_ERROR if an unexpected error occurred.
+  //
   // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
   // PeerConnectionInterface implement it.
   virtual bool SetConfiguration(
+      const PeerConnectionInterface::RTCConfiguration& config,
+      RTCError* error) {
+    return false;
+  }
+  // Version without error output param for backwards compatibility.
+  // TODO(deadbeef): Remove once chromium is updated.
+  virtual bool SetConfiguration(
       const PeerConnectionInterface::RTCConfiguration& config) {
     return false;
   }
   // Provides a remote candidate to the ICE Agent.
   // A copy of the |candidate| will be created and added to the remote
   // description. So the caller of this method still has the ownership of the
   // |candidate|.
   // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
   // take the ownership of the |candidate|.
   virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
@@ skipping 277 matching lines @@
     cricket::WebRtcVideoEncoderFactory* encoder_factory,
     cricket::WebRtcVideoDecoderFactory* decoder_factory) {
   return CreatePeerConnectionFactory(
       worker_and_network_thread, worker_and_network_thread, signaling_thread,
       default_adm, encoder_factory, decoder_factory);
 }
 
 }  // namespace webrtc
 
 #endif  // WEBRTC_API_PEERCONNECTIONINTERFACE_H_