// 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_
