From c5b5bbbeb27801255f5f2a4d16deb264b5c89d31 Mon Sep 17 00:00:00 2001 From: Robo Date: Fri, 4 Dec 2015 05:33:56 +0530 Subject: [PATCH] add documentation --- atom/browser/net/atom_network_delegate.cc | 8 ++ docs/api/session.md | 175 ++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) diff --git a/atom/browser/net/atom_network_delegate.cc b/atom/browser/net/atom_network_delegate.cc index c8d341c..1ee886b 100644 --- a/atom/browser/net/atom_network_delegate.cc +++ b/atom/browser/net/atom_network_delegate.cc @@ -266,6 +266,8 @@ void AtomNetworkDelegate::OnBeforeRedirect(net::URLRequest* request, if (!ip.empty()) details->SetString("ip", ip); details->SetBoolean("fromCache", request->was_cached()); + details->Set("responseHeaders", + GetResponseHeadersDict(request->response_headers())); BrowserThread::PostTask(BrowserThread::UI, FROM_HERE, base::Bind(base::IgnoreResult(wrapped_callback), @@ -291,6 +293,9 @@ void AtomNetworkDelegate::OnResponseStarted(net::URLRequest* request) { details->SetInteger("statusCode", request->response_headers() ? request->response_headers()->response_code() : 200); + details->SetString("statusLine", + request->response_headers() ? + request->response_headers()->GetStatusLine() : std::string()); BrowserThread::PostTask(BrowserThread::UI, FROM_HERE, base::Bind(base::IgnoreResult(wrapped_callback), @@ -325,6 +330,9 @@ void AtomNetworkDelegate::OnCompleted(net::URLRequest* request, bool started) { details->SetInteger("statusCode", request->response_headers() ? request->response_headers()->response_code() : 200); + details->SetString("statusLine", + request->response_headers() ? + request->response_headers()->GetStatusLine() : std::string()); BrowserThread::PostTask(BrowserThread::UI, FROM_HERE, base::Bind(base::IgnoreResult(wrapped_callback), diff --git a/docs/api/session.md b/docs/api/session.md index a69c593..d889ace 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -286,3 +286,178 @@ myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, c callback(false); }); ``` + +#### `ses.webRequest` + +The `webRequest` api allows to intercept and modify contents of a request at various +stages of its lifetime. + +```javascript +// Modify the user agent for all requests to the following urls. + +var filter = { + urls: ["https://*.github.com/*", "*://electron.github.io"] +} + +myWindow.webContents.session.webRequest.onBeforeSendHeaders(filter, function(details) { + details.requestHeaders['User-Agent'] = "MyAgent"; + return {cancel: false, requestHeaders: details.requestHeaders}; +}) +``` + +#### `ses.webRequest.onBeforeRequest([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double +* `blockingResponse` Object + * `cancel` Boolean - Whether to continue or block the request. + * `redirectURL` String **optional** - The original request is prevented from being sent or + completed, and is instead redirected to the given URL. + +Fired when a request is about to occur. Should return a `blockingResponse`. + +#### `ses.webRequest.onBeforeSendHeaders([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `requestHeaders` Object +* `blockingResponse` Object + * `cancel` Boolean - Whether to continue or block the request. + * `requestHeaders` Object **optional** - When provided, request will be made with these + headers. + +Fired before sending an HTTP request, once the request headers are available. This may +occur after a TCP connection is made to the server, but before any http data is sent. +Should return a `blockingResponse`. + +#### `ses.webRequest.onSendHeaders([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `requestHeaders` Object + +Fired just before a request is going to be sent to the server, modifications of previous +`onBeforeSendHeaders` response are visible by the time this listener is fired. + +#### `ses.webRequest.onHeadersReceived([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `statusLine` String + * `statusCode` Integer + * `responseHeaders` Object +* `blockingResponse` Object + * `cancel` Boolean - Whether to continue or block the request. + * `responseHeaders` Object **optional** - When provided, the server is assumed to have + responded with these headers. + +Fired when HTTP response headers of a request have been received. Should return a +`blockingResponse`. + +#### `ses.webRequest.onResponseStarted([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `responseHeaders` Object + * `fromCache` Boolean + * `statusCode` Integer + * `statusLine` String + +Fired when first byte of the response body is received. For HTTP requests, this means that the +status line and response headers are available. + +#### `ses.webRequest.onBeforeRedirect([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `redirectURL` String + * `statusCode` Integer + * `ip` String - The server IP address that the request was actually sent to. + * `fromCache` Boolean + * `responseHeaders` Object + +Fired when a server initiated redirect is about to occur. + +#### `ses.webRequest.onCompleted([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `responseHeaders` Object + * `fromCache` Boolean - Indicates whether the response was fetched from disk cache. + * `statusCode` Integer + * `statusLine` String + +Fired when a request is completed. + +#### `ses.webRequest.onErrorOccurred([filter,] listener)` + +* `filter` Object + * `urls` Array - A list of URLs or URL patterns. Request that cannot match any of the URLs + will be filtered out. +* `listener` Function + * `details` Object + * `id` String - Request id. + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `fromCache` Boolean - Indicates whether the response was fetched from disk cache. + * `error` String - The error description. + +Fired when an error occurs. -- 2.7.4