Bug 932183: Part 1: Rename function and add comments in TCPSocket implementation to make it more readable. r=honzab

dom/network/interfaces/nsITCPSocketChild.idl

@@ -8,22 +8,26 @@ interface nsITCPSocketInternal;
 interface nsIDOMWindow;
 
 // Interface to allow the content process socket to reach the IPC bridge.
-[scriptable, uuid(ada5342d-6d45-4ff1-a7d3-6a4b150d0385)]
+// Implemented in C++ as TCPSocketChild, referenced as _socketBridge in TCPSocket.js
+[scriptable, uuid(292ebb3a-beac-4e06-88b0-b5b4e88ebd1c)]
 interface nsITCPSocketChild : nsISupports
 {
   // Tell the chrome process to open a corresponding connection with the given parameters
   [implicit_jscontext]
-  void open(in nsITCPSocketInternal socket, in DOMString host,
+  void sendOpen(in nsITCPSocketInternal socket, in DOMString host,
                 in unsigned short port, in boolean ssl, in DOMString binaryType,
                 in nsIDOMWindow window, in jsval windowVal);
 
-  // Tell the chrome process to perform equivalent operations to all following methods
+  // Tell the chrome process to perform send and update the tracking number.
   [implicit_jscontext] 
-  void send(in jsval data, in unsigned long byteOffset, in unsigned long byteLength);
-  void resume();
-  void suspend();
-  void close();
-  void startTLS();
+  void sendSend(in jsval data, in unsigned long byteOffset,
+                in unsigned long byteLength, in unsigned long trackingNumber);
+
+  // Tell the chrome process to perform equivalent operations to all following methods
+  void sendResume();
+  void sendSuspend();
+  void sendClose();
+  void sendStartTLS();
 
   /**
    * Initialize the TCP socket on the child side for IPC. It is called from the child side,

dom/network/interfaces/nsITCPSocketParent.idl

@@ -9,17 +9,26 @@ interface nsIDOMTCPServerSocket;
 interface nsITCPServerSocketParent;
 interface nsITCPSocketIntermediary;
 
-// Interface required to allow the TCP socket object in the parent process
-// to talk to the parent IPC actor
-[scriptable, uuid(123f654b-4435-43c8-8447-db1b5420a1c2)]
+// Interface required to allow the TCP socket object (TCPSocket.js) in the
+// parent process to talk to the parent IPC actor, TCPSocketParent, which
+// is written in C++.
+[scriptable, uuid(868662a4-681c-4b89-9f02-6fe5b7ace265)]
 interface nsITCPSocketParent : nsISupports
 {
   [implicit_jscontext] void initJS(in jsval intermediary);
 
   // Trigger a callback in the content process for |type|, providing a serialized
-  // argument of |data|, and update the child's readyState and bufferedAmount values
-  // with the given values.
-  [implicit_jscontext] void sendCallback(in DOMString type,
+  // argument of |data|, and update the child's readyState value with the given
+  // values.
+  //
+  // @param type
+  //        Event type: 'onopen', 'ondata', 'onerror' or 'onclose'. 'odrain' is
+  //        controlled by child.
+  // @param data
+  //        Serialized data that is passed to event handler.
+  // @param readyState
+  //        Current ready state.
+  [implicit_jscontext] void sendEvent(in DOMString type,
                                       in jsval data,
                                       in DOMString readyState,
                                       in uint32_t bufferedAmount);
@@ -38,7 +47,10 @@ interface nsITCPSocketParent : nsISupports
 
 // Intermediate class to handle sending multiple possible data types
 // and kicking off the chrome process socket object's connection.
-[scriptable, uuid(be67b1b8-03b0-4171-a791-d004458021b6)]
+// This interface is the bridge of TCPSocketParent, which is written in C++,
+// and TCPSocket, which is written in Javascript. TCPSocketParentIntermediary
+// implements nsITCPSocketIntermediary in Javascript.
+[scriptable, uuid(c434224a-dbb7-4869-8b2b-e49cee990e85)]
 interface nsITCPSocketIntermediary : nsISupports {
   // Open the connection to the server with the given parameters
   nsIDOMTCPSocket open(in nsITCPSocketParent parent,
@@ -51,9 +63,9 @@ interface nsITCPSocketIntermediary : nsISupports {
                                in unsigned short port, in unsigned short backlog,
                                in DOMString binaryType);
 
-  // Send a basic string along the connection
-  void sendString(in DOMString data);
+  // Called when received a child request to send a string.
+  void onRecvSendString(in DOMString data);
 
-  // Send a typed array
-  void sendArrayBuffer(in jsval data);
+  // Called when received a child request to send an array buffer.
+  void onRecvSendArrayBuffer(in jsval data);
 };

dom/network/src/PTCPSocket.ipdl

@@ -35,14 +35,27 @@ protocol PTCPSocket
   manager PNecko;
 
 parent:
+  // Forward calling to child's open() method to parent, expect TCPOptions
+  // is expanded to |useSSL| (from TCPOptions.useSecureTransport) and
+  // |binaryType| (from TCPOption.binaryType).
   Open(nsString host, uint16_t port, bool useSSL, nsString binaryType);
+
   Data(SendableData data);
+
+  // Forward calling to child's upgradeToSecure() method to parent.
   StartTLS();
+
+  // Forward calling to child's send() method to parent.
   Suspend();
+
+  // Forward calling to child's resume() method to parent.
   Resume();
+
+  // Forward calling to child's close() method to parent.
   Close();
 
 child:
+  // Forward events that are dispatched by parent.
   Callback(nsString type, CallbackData data,
            nsString readyState, uint32_t bufferedAmount);
 

dom/network/src/TCPSocket.js

@@ -517,7 +517,7 @@ TCPSocket.prototype = {
     if (this._inChild) {
       that._socketBridge = Cc["@mozilla.org/tcp-socket-child;1"]
                              .createInstance(Ci.nsITCPSocketChild);
-      that._socketBridge.open(that, host, port, !!that._ssl,
+      that._socketBridge.sendOpen(that, host, port, !!that._ssl,
                                   that._binaryType, this.useWin, this.useWin || this);
       return that;
     }
@@ -551,7 +551,7 @@ TCPSocket.prototype = {
     this._ssl = 'ssl';
 
     if (this._inChild) {
-      this._socketBridge.startTLS();
+      this._socketBridge.sendStartTLS();
       return;
     }
 
@@ -585,7 +585,7 @@ TCPSocket.prototype = {
     this._readyState = kCLOSING;
 
     if (this._inChild) {
-      this._socketBridge.close();
+      this._socketBridge.sendClose();
       return;
     }
 
@@ -605,7 +605,7 @@ TCPSocket.prototype = {
     }
 
     if (this._inChild) {
-      this._socketBridge.send(data, byteOffset, byteLength);
+      this._socketBridge.sendSend(data, byteOffset, byteLength);
     }
 
     let length = this._binaryType === "arraybuffer" ? byteLength : data.length;
@@ -655,7 +655,7 @@ TCPSocket.prototype = {
 
   suspend: function ts_suspend() {
     if (this._inChild) {
-      this._socketBridge.suspend();
+      this._socketBridge.sendSuspend();
       return;
     }
 
@@ -668,7 +668,7 @@ TCPSocket.prototype = {
 
   resume: function ts_resume() {
     if (this._inChild) {
-      this._socketBridge.resume();
+      this._socketBridge.sendResume();
       return;
     }
 

dom/network/src/TCPSocketChild.cpp

@@ -77,8 +77,9 @@ TCPSocketChild::TCPSocketChild()
 }
 
 NS_IMETHODIMP
-TCPSocketChild::Open(nsITCPSocketInternal* aSocket, const nsAString& aHost,
-                     uint16_t aPort, bool aUseSSL, const nsAString& aBinaryType,
+TCPSocketChild::SendOpen(nsITCPSocketInternal* aSocket,
+                         const nsAString& aHost, uint16_t aPort,
+                         bool aUseSSL, const nsAString& aBinaryType,
                          nsIDOMWindow* aWindow, const JS::Value& aWindowObj,
                          JSContext* aCx)
 {
@@ -91,7 +92,8 @@ TCPSocketChild::Open(nsITCPSocketInternal* aSocket, const nsAString& aHost,
   }
   AddIPDLReference();
   gNeckoChild->SendPTCPSocketConstructor(this);
-  SendOpen(nsString(aHost), aPort, aUseSSL, nsString(aBinaryType));
+  PTCPSocketChild::SendOpen(nsString(aHost), aPort,
+                            aUseSSL, nsString(aBinaryType));
   return NS_OK;
 }
 
@@ -159,35 +161,35 @@ TCPSocketChild::RecvCallback(const nsString& aType,
 }
 
 NS_IMETHODIMP
-TCPSocketChild::StartTLS()
+TCPSocketChild::SendStartTLS()
 {
-  SendStartTLS();
+  PTCPSocketChild::SendStartTLS();
   return NS_OK;
 }
 
 NS_IMETHODIMP
-TCPSocketChild::Suspend()
+TCPSocketChild::SendSuspend()
 {
-  SendSuspend();
+  PTCPSocketChild::SendSuspend();
   return NS_OK;
 }
 
 NS_IMETHODIMP
-TCPSocketChild::Resume()
+TCPSocketChild::SendResume()
 {
-  SendResume();
+  PTCPSocketChild::SendResume();
   return NS_OK;
 }
 
 NS_IMETHODIMP
-TCPSocketChild::Close()
+TCPSocketChild::SendClose()
 {
-  SendClose();
+  PTCPSocketChild::SendClose();
   return NS_OK;
 }
 
 NS_IMETHODIMP
-TCPSocketChild::Send(const JS::Value& aData,
+TCPSocketChild::SendSend(const JS::Value& aData,
                          uint32_t aByteOffset,
                          uint32_t aByteLength,
                          JSContext* aCx)

dom/network/src/TCPSocketParent.cpp

@@ -168,13 +168,13 @@ TCPSocketParent::RecvData(const SendableData& aData)
       JS::Rooted<JS::Value> val(cx);
       JS::Rooted<JSObject*> obj(cx, mIntermediaryObj);
       IPC::DeserializeArrayBuffer(obj, aData.get_ArrayOfuint8_t(), &val);
-      rv = mIntermediary->SendArrayBuffer(val);
+      rv = mIntermediary->OnRecvSendArrayBuffer(val);
       NS_ENSURE_SUCCESS(rv, true);
       break;
     }
 
     case SendableData::TnsString:
-      rv = mIntermediary->SendString(aData.get_nsString());
+      rv = mIntermediary->OnRecvSendString(aData.get_nsString());
       NS_ENSURE_SUCCESS(rv, true);
       break;
 
@@ -194,9 +194,8 @@ TCPSocketParent::RecvClose()
 }
 
 NS_IMETHODIMP
-TCPSocketParent::SendCallback(const nsAString& aType, const JS::Value& aDataVal,
-                              const nsAString& aReadyState, uint32_t aBuffered,
-                              JSContext* aCx)
+TCPSocketParent::SendEvent(const nsAString& aType, const JS::Value& aDataVal,
+                           const nsAString& aReadyState, JSContext* aCx)
 {
   if (!mIPCOpen) {
     NS_WARNING("Dropping callback due to no IPC connection");

dom/network/src/TCPSocketParentIntermediary.js

@@ -23,7 +23,7 @@ TCPSocketParentIntermediary.prototype = {
     ["open", "drain", "data", "error", "close"].forEach(
       function(p) {
         socket["on" + p] = function(data) {
-          aParentSide.sendCallback(p, data.data, socket.readyState,
+          aParentSide.sendEvent(p, data.data, socket.readyState,
                                 socket.bufferedAmount);
         };
       }
@@ -79,11 +79,11 @@ TCPSocketParentIntermediary.prototype = {
     return serverSocket;
   },
 
-  sendString: function(aData) {
+  onRecvSendString: function(aData) {
     return this._socket.send(aData);
   },
 
-  sendArrayBuffer: function(aData) {
+  onRecvSendArrayBuffer: function(aData) {
     return this._socket.send(aData, 0, aData.byteLength);
   },