Chromium 中chrome.webRequest扩展接口定义c++

一、chrome.webRequest

注意：从 Manifest V3 开始，"webRequestBlocking"权限不再适用于大多数扩展程序。以"declarativeNetRequest"为例，它允许使用declarativeNetRequest API。除了"webRequestBlocking"之外，webRequest API 保持不变，仍可正常使用。通过政策安装的扩展程序可以继续使用"webRequestBlocking"。

使用chrome.webRequestAPI 可观察和分析流量，以及拦截、阻止或修改传输中的请求。

权限

webRequest

您必须在扩展程序清单中声明"webRequest"权限，才能使用 Web 请求 API 以及必要的主机权限。要拦截子资源请求， 扩展程序必须同时有权访问请求的网址及其发起者。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

必须填写此字段，才能注册屏蔽事件处理脚本。从 Manifest V3 开始， 适用于通过政策安装的扩展程序

webRequestAuthProvider

使用onAuthRequired方法的必需条件。请参阅处理身份验证。

请求的生命周期

Web 请求 API 定义了一组遵循 Web 请求生命周期的事件。您可以使用 来观察和分析流量。某些同步事件允许您拦截、 屏蔽或修改请求

成功请求的事件生命周期如下所示，其后是事件定义：

更多参考chrome.webRequest ?|? API ?|? Chrome for Developers

二、chrome.webRequest c++接口定义：

1、web_request.json接口描述文件：

extensionscommonapiweb_request.json

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

[
  {
    "namespace": "webRequest",
    "description": "Use the <code>chrome.webRequest</code> API to observe and analyze traffic and to intercept, block, or modify requests in-flight.",
    "properties": {
      "MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES": {
        "value": 20,
        "description": "The maximum number of times that <code>handlerBehaviorChanged</code> can be called per 10 minute sustained interval. <code>handlerBehaviorChanged</code> is an expensive function call that shouldn't be called often."
      }
    },
    "types": [
      {
        "id": "ResourceType",
        "type": "string",
        "enum": [
          {"name": "main_frame", "description": "Specifies the resource as the main frame."},
          {"name": "sub_frame", "description": "Specifies the resource as a sub frame."},
          {"name":  "stylesheet", "description": "Specifies the resource as a stylesheet."},
          {"name": "script", "description": "Specifies the resource as a script."},
          {"name": "image", "description": "Specifies the resource as an image."},
          {"name": "font", "description": "Specifies the resource as a font."},
          {"name": "object", "description": "Specifies the resource as an object."},
          {"name": "xmlhttprequest",
           "description": "Specifies the resource as an XMLHttpRequest."},
          {"name": "ping",
           "description": "Specifies the resource as a ping."},
          {"name": "csp_report",
          "description": "Specifies the resource as a Content Security Policy (CSP) report."},
          {"name": "media", "description": "Specifies the resource as a media object."},
          {"name": "websocket", "description": "Specifies the resource as a WebSocket."},
          {"name": "webbundle", "description": "Specifies the resource as a WebBundle."},
          {"name": "other", "description": "Specifies the resource as a type not included in the listed types."}
        ]
      },
      {
        "id": "OnBeforeRequestOptions",
        "type": "string",
        "enum": [
          {"name": "blocking", "description": "Specifies the request is blocked until the callback function returns."},
          {"name": "requestBody", "description": "Specifies that the request body should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnBeforeSendHeadersOptions",
        "type": "string",
        "enum": [
          {"name": "requestHeaders", "description": "Specifies that the request header should be included in the event."},
          {"name": "blocking", "description": "Specifies the request is blocked until the callback function returns."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnSendHeadersOptions",
        "type": "string",
        "enum": [
          {"name": "requestHeaders", "description": "Specifies that the request header should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnHeadersReceivedOptions",
        "type": "string",
        "enum": [
          {"name": "blocking", "description": "Specifies the request is blocked until the callback function returns."},
          {"name": "responseHeaders", "description": "Specifies that the response headers should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnAuthRequiredOptions",
        "type": "string",
        "enum": [
          {"name": "responseHeaders", "description": "Specifies that the response headers should be included in the event."},
          {"name": "blocking", "description": "Specifies the request is blocked until the callback function returns."},
          {"name": "asyncBlocking", "description": "Specifies that the callback function is handled asynchronously."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnResponseStartedOptions",
        "type": "string",
        "enum": [
          {"name": "responseHeaders", "description": "Specifies that the response headers should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnBeforeRedirectOptions",
        "type": "string",
        "enum": [
          {"name": "responseHeaders", "description": "Specifies that the response headers should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnCompletedOptions",
        "type": "string",
        "enum": [
          {"name": "responseHeaders", "description": "Specifies that the response headers should be included in the event."},
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "OnErrorOccurredOptions",
        "type": "string",
        "enum": [
          {"name": "extraHeaders", "description": "Specifies that headers can violate Cross-Origin Resource Sharing (CORS)."}
        ]
      },
      {
        "id": "RequestFilter",
        "type": "object",
        "description": "An object describing filters to apply to webRequest events.",
        "properties": {
          "urls": {
            "type": "array",
            "description": "A list of URLs or URL patterns. Requests that cannot match any of the URLs will be filtered out.",
            "items": { "type": "string" }
          },
          "types": {
            "type": "array",
            "optional": true,
            "description": "A list of request types. Requests that cannot match any of the types will be filtered out.",
            "items": { "$ref": "ResourceType" }
          },
          "tabId": { "type": "integer", "optional": true },
          "windowId": { "type": "integer", "optional": true }
        }
      },
      {
        "id": "HttpHeaders",
        "nocompile": true,
        "type": "array",
        "description": "An array of HTTP headers. Each header is represented as a dictionary containing the keys <code>name</code> and either <code>value</code> or <code>binaryValue</code>.",
        "items": {
          "type": "object",
          "properties": {
            "name": {"type": "string", "description": "Name of the HTTP header."},
            "value": {"type": "string", "optional": true, "description": "Value of the HTTP header if it can be represented by UTF-8."},
            "binaryValue": {
              "type": "array",
              "optional": true,
              "description": "Value of the HTTP header if it cannot be represented by UTF-8, stored as individual byte values (0..255).",
              "items": {"type": "integer"}
            }
          }
        }
      },
      {
        "id": "BlockingResponse",
        "nocompile": true,
        "type": "object",
        "description": "Returns value for event handlers that have the 'blocking' extraInfoSpec applied. Allows the event handler to modify network requests.",
        "properties": {
          "cancel": {
            "type": "boolean",
            "optional": true,
            "description": "If true, the request is cancelled. This prevents the request from being sent. This can be used as a response to the onBeforeRequest, onBeforeSendHeaders, onHeadersReceived and onAuthRequired events."
          },
          "redirectUrl": {
            "type": "string",
            "optional": true,
            "description": "Only used as a response to the onBeforeRequest and onHeadersReceived events. If set, the original request is prevented from being sent/completed and is instead redirected to the given URL. Redirections to non-HTTP schemes such as <code>data:</code> are allowed. Redirects initiated by a redirect action use the original request method for the redirect, with one exception: If the redirect is initiated at the onHeadersReceived stage, then the redirect will be issued using the GET method. Redirects from URLs with <code>ws://</code> and <code>wss://</code> schemes are <b>ignored</b>."
          },
          "requestHeaders": {
            "$ref": "HttpHeaders",
            "optional": true,
            "description": "Only used as a response to the onBeforeSendHeaders event. If set, the request is made with these request headers instead."
          },
          "responseHeaders": {
            "$ref": "HttpHeaders",
            "optional": true,
            "description": "Only used as a response to the onHeadersReceived event. If set, the server is assumed to have responded with these response headers instead. Only return <code>responseHeaders</code> if you really want to modify the headers in order to limit the number of conflicts (only one extension may modify <code>responseHeaders</code> for each request)."
          },
          "authCredentials": {
            "type": "object",
            "description": "Only used as a response to the onAuthRequired event. If set, the request is made using the supplied credentials.",
            "optional": true,
            "properties": {
              "username": {"type": "string"},
              "password": {"type": "string"}
            }
          }
        }
      },
      {
        "id": "UploadData",
        "type": "object",
        "properties": {
          "bytes": {
            "type": "any",
            "optional": true,
            "description": "An ArrayBuffe