tor-browser

agent_win.h (7790B)

---

// Copyright 2022 The Chromium Authors.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef CONTENT_ANALYSIS_AGENT_SRC_AGENT_WIN_H_
#define CONTENT_ANALYSIS_AGENT_SRC_AGENT_WIN_H_

#include <windows.h>

#include <memory>
#include <sstream>
#include <string>
#include <vector>

#include "agent_base.h"

namespace content_analysis {
namespace sdk {

// Agent implementaton for Windows.
class AgentWin : public AgentBase {
public:
 // Creates a new agent given the specific configuration and handler.
 // If an error occurs during creation, `rc` is set to the specific
 // error.  Otherwise `rc` is ResultCode::OK.
 AgentWin(Config config, std::unique_ptr<AgentEventHandler> handler,
          ResultCode* rc);
 ~AgentWin() override;

 // Agent:
 ResultCode HandleEvents() override;
 ResultCode Stop() override;
 std::string DebugString() const override;

 // Handles one pipe event and returns.  Used only in tests.
 ResultCode HandleOneEventForTesting();

 // Returns true if there is at least one client connected to this agent.
 bool IsAClientConnectedForTesting();

private:
 // Represents one connection to a Google Chrome browser, or one pipe
 // listening for a Google Chrome browser to connect.
 class Connection {
  public:
   // Starts listening on a pipe with the given name. `is_first_pipe` should
   // be true only for the first pipe created by the agent.  If an error
   // occurs while creating the connction object it is returned in `rc`.
   // If no errors occur then rc is set to ResultCode::OK.
   //
   // When `user_specific` is true there is a different agent instance per OS
   // user.
   //
   // `Connection` objects cannot be copied or moved because the OVERLAPPED
   // structure cannot be changed or moved in memory while an I/O operation
   // is in progress.
   Connection(const std::string& pipename,
              bool user_specific,
              AgentEventHandler* handler,
              bool is_first_pipe,
              ResultCode* rc);
   Connection(const Connection& other) = delete;
   Connection(Connection&& other) = delete;
   Connection& operator=(const Connection& other) = delete;
   Connection& operator=(Connection&& other) = delete;
   ~Connection();

   bool IsValid() const { return handle_ != INVALID_HANDLE_VALUE; }
   bool IsConnected() const { return is_connected_; }
   HANDLE GetWaitHandle() const { return overlapped_.hEvent; }

   // Resets this connection object to listen for a new Google Chrome browser.
   // When `user_specific` is true there is a different agent instance per OS
   // user.
   ResultCode Reset(const std::string& pipename, bool user_specific);

   // Hnadles an event for this connection.  `wait_handle` corresponds to
   // this connections wait handle.
   ResultCode HandleEvent(HANDLE wait_handle);

   // Append debuf information to the string stream.
   void AppendDebugString(std::stringstream& state) const;

  private:
   // Listens for a new connection from Google Chrome.
   ResultCode ConnectPipe();

   // Resets this connection object to listen for a new Google Chrome browser.
   // When `user_specific` is true there is a different agent instance per OS
   // user.
   ResultCode ResetInternal(const std::string& pipename,
                            bool user_specific,
                            bool is_first_pipe);

   // Cleans up this connection object so that it can be reused with a new
   // Google Chroem browser instance.  The handles assocated with this object
   // are not closed.  On return, this object is neither connected nor
   // listening and any buffer used to hold browser messages are cleared.
   void Cleanup();

   // Queues a read on the pipe to receive a message from Google Chrome.
   // ERROR_SUCCESS, ERROR_IO_PENDING, and ERROR_MORE_DATA are successful
   // return values. Other values represent an error with the connection.
   // If `reset_cursor` is true the internal read buffer cursor is reset to
   // the start of the buffer, otherwise it is unchanged.
   ResultCode QueueReadFile(bool reset_cursor);

   // Called when data from Google Chrome is available for reading from the
   // pipe. ERROR_SUCCESS and ERROR_MORE_DATA are both successful return
   // values.  Other values represent an error with the connection.
   //
   // `done_reading` is true if the code has finished reading an entire message
   // from chrome.  Regardless of whether reading is done, `count` contains
   // the number of bytes read.
   //
   // If `done_reading` is true, the data received from the browser is parsed
   // as if it were a `ChromeToAgent` proto message and the handler is called
   // as needed.
   //
   // If `done_reading` is false, the data received from the browser is
   // appended to the data already received from the browser.  `buffer_` is
   // resized to allow reading more data from the browser.
   //
   // In all cases the caller is expected to use QueueReadFile() to continue
   // reading data from the browser.
   ResultCode OnReadFile(BOOL done_reading, DWORD count);

   // Calls the appropriate method the handler depending on the message
   // received from Google Chrome.
   ResultCode CallHandler();

   // Fills in the browser_info_ member of this Connection.  Assumes
   // IsConnected() is true.
   ResultCode BuildBrowserInfo();

   // Notifies the handler of the given error iff `rc` is not equal to
   // ResultCode::OK.  Appends the Google Chrome browser process id to the
   // context before calling the handler.  Also append `err` to the context
   // if it is not ERROR_SUCCESS.
   //
   // Returns the error passed into the method.
   ResultCode NotifyIfError(const char* context,
                            ResultCode rc,
                            DWORD err=ERROR_SUCCESS);

   // The handler to call for various agent events.
   AgentEventHandler* handler_ = nullptr;

   // Members used to communicate with Google Chrome.
   HANDLE handle_ = INVALID_HANDLE_VALUE;
   OVERLAPPED overlapped_;

   // True if this connection is assigned to a specific Google Chrome browser,
   // otherwise this connection is listening for a new browser.
   bool is_connected_ = false;

   // Information about the Google Chrome browser process.
   BrowserInfo browser_info_;

   // Members used to read messages from Google Chrome.
   std::vector<char> buffer_;
   char* cursor_ = nullptr;
   DWORD read_size_ = 0;
   DWORD final_size_ = 0;
 };

 // Returns handles that can be used to wait for events from all handles
 // managed by this agent.  This includes all connection objects and the
 // stop event.  The stop event is always last in the list.
 void GetHandles(std::vector<HANDLE>& wait_handles) const;

 // Handles one pipe event and returns.  If the return value is
 // ResultCode::OK, the `stopped` argument is set to true if the agent
 // should stop handling more events.  If the return value is not
 // ResultCode::OK, `stopped` is undefined.
 ResultCode HandleOneEvent(std::vector<HANDLE>& wait_handles, bool* stopped);

 // Performs a clean shutdown of the agent.
 void Shutdown();

 // Name used to create the pipes between the agent and Google Chrome browsers.
 std::string pipename_;

 // A list of pipes to already connected Google Chrome browsers.
 // The first kMinNumListeningPipeInstances pipes in the list correspond to
 // listening pipes.
 std::vector<std::unique_ptr<Connection>> connections_;

 // An event that is set when the agent should stop.  Set in Stop().
 HANDLE stop_event_ = nullptr;
};

}  // namespace sdk
}  // namespace content_analysis

#endif  // CONTENT_ANALYSIS_AGENT_SRC_AGENT_WIN_H_