diff --git a/src/ElectronNET.API/API/Cookies.cs b/src/ElectronNET.API/API/Cookies.cs new file mode 100644 index 0000000..4959cd9 --- /dev/null +++ b/src/ElectronNET.API/API/Cookies.cs @@ -0,0 +1,67 @@ +using System; +using System.Threading.Tasks; +using ElectronNET.API.Entities; +using Newtonsoft.Json; +using Newtonsoft.Json.Linq; +using Newtonsoft.Json.Serialization; + +namespace ElectronNET.API +{ + /// + /// Query and modify a session's cookies. + /// + public class Cookies + { + /// + /// Gets the identifier. + /// + /// + /// The identifier. + /// + public int Id { get; private set; } + + internal Cookies(int id) + { + Id = id; + } + + /// + /// Emitted when a cookie is changed because it was added, edited, removed, or expired. + /// + public event Action OnChanged + { + add + { + if (_changed == null) + { + BridgeConnector.Socket.On("webContents-session-cookies-changed" + Id, (args) => + { + Cookie cookie = ((JArray)args)[0].ToObject(); + CookieChangedCause cause = ((JArray)args)[1].ToObject(); + bool removed = ((JArray)args)[2].ToObject(); + _changed(cookie, cause, removed); + }); + + BridgeConnector.Socket.Emit("register-webContents-session-cookies-changed", Id); + } + _changed += value; + } + remove + { + _changed -= value; + + if (_changed == null) + BridgeConnector.Socket.Off("webContents-session-cookies-changed" + Id); + } + } + + private event Action _changed; + + private JsonSerializer _jsonSerializer = new JsonSerializer() + { + ContractResolver = new CamelCasePropertyNamesContractResolver(), + NullValueHandling = NullValueHandling.Ignore, + DefaultValueHandling = DefaultValueHandling.Ignore + }; + } +} \ No newline at end of file diff --git a/src/ElectronNET.API/API/WebRequest.cs b/src/ElectronNET.API/API/WebRequest.cs new file mode 100644 index 0000000..3b55106 --- /dev/null +++ b/src/ElectronNET.API/API/WebRequest.cs @@ -0,0 +1,61 @@ +using Newtonsoft.Json.Linq; +using System; + +namespace ElectronNET.API.Entities +{ + public class OnBeforeRequestDetails + { + public int Id { get; set; } + public string Url { get; set; } + public string Method { get; set; } + public int? WebContentsId { get; set; } + // Ensure all necessary properties are included as per Electron documentation + } + + public class WebRequestFilter + { + public string[] Urls { get; set; } + } + + public class WebRequest + { + public int Id { get; private set; } + + internal WebRequest(int id) + { + Id = id; + } + + private event Action> _onBeforeRequest; + + public void OnBeforeRequest(WebRequestFilter filter, Action> listener) + { + if (_onBeforeRequest == null) + { + BridgeConnector.Socket.On($"webContents-session-webRequest-onBeforeRequest{Id}", + (args) => + { + ////var details = ((JObject)args[0]).ToObject(); + ////var callback = args.Length > 1 ? (Action)((response) => { BridgeConnector.Socket.Emit($"webContents-session-webRequest-onBeforeRequest-response{Id}", response); }) : null; + var details = ((JObject)args).ToObject(); + var callback = (Action)((response) => { BridgeConnector.Socket.Emit($"webContents-session-webRequest-onBeforeRequest-response{Id}", response); }); + + _onBeforeRequest?.Invoke(details, callback); + }); + + BridgeConnector.Socket.Emit("register-webContents-session-webRequest-onBeforeRequest", Id, JObject.FromObject(filter)); + } + + _onBeforeRequest += listener; + } + + public void RemoveListener(Action> listener) + { + _onBeforeRequest -= listener; + if (_onBeforeRequest == null) + { + BridgeConnector.Socket.Off($"webContents-session-webRequest-onBeforeRequest{Id}"); + } + } + } +} \ No newline at end of file diff --git a/src/ElectronNET.API/API/web-request.md b/src/ElectronNET.API/API/web-request.md new file mode 100644 index 0000000..a337836 --- /dev/null +++ b/src/ElectronNET.API/API/web-request.md @@ -0,0 +1,255 @@ +## Class: WebRequest + +> Intercept and modify the contents of a request at various stages of its lifetime. + +Process: [Main](../glossary.md#main-process)
+_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._ + +Instances of the `WebRequest` class are accessed by using the `webRequest` +property of a `Session`. + +The methods of `WebRequest` accept an optional `filter` and a `listener`. The +`listener` will be called with `listener(details)` when the API's event has +happened. The `details` object describes the request. + +⚠️ Only the last attached `listener` will be used. Passing `null` as `listener` will unsubscribe from the event. + +The `filter` object has a `urls` property which is an Array of URL +patterns that will be used to filter out the requests that do not match the URL +patterns. If the `filter` is omitted then all requests will be matched. + +For certain events the `listener` is passed with a `callback`, which should be +called with a `response` object when `listener` has done its work. + +An example of adding `User-Agent` header for requests: + +```js +const { session } = require('electron') + +// Modify the user agent for all requests to the following urls. +const filter = { + urls: ['https://*.github.com/*', '*://electron.github.io/*'] +} + +session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => { + details.requestHeaders['User-Agent'] = 'MyAgent' + callback({ requestHeaders: details.requestHeaders }) +}) +``` + +### Instance Methods + +The following methods are available on instances of `WebRequest`: + +#### `webRequest.onBeforeRequest([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `uploadData` [UploadData[]](structures/upload-data.md) + * `callback` Function + * `response` Object + * `cancel` boolean (optional) + * `redirectURL` string (optional) - The original request is prevented from + being sent or completed and is instead redirected to the given URL. + +The `listener` will be called with `listener(details, callback)` when a request +is about to occur. + +The `uploadData` is an array of `UploadData` objects. + +The `callback` has to be called with an `response` object. + +Some examples of valid `urls`: + +```js +'http://foo:1234/' +'http://foo.com/' +'http://foo:1234/bar' +'*://*/*' +'*://example.com/*' +'*://example.com/foo/*' +'http://*.foo:1234/' +'file://foo:1234/bar' +'http://foo:*/' +'*://www.foo.com/' +``` + +#### `webRequest.onBeforeSendHeaders([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `uploadData` [UploadData[]](structures/upload-data.md) (optional) + * `requestHeaders` Record + * `callback` Function + * `beforeSendResponse` Object + * `cancel` boolean (optional) + * `requestHeaders` Record (optional) - When provided, request will be made + with these headers. + +The `listener` will be called with `listener(details, callback)` 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. + +The `callback` has to be called with a `response` object. + +#### `webRequest.onSendHeaders([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `requestHeaders` Record + +The `listener` will be called with `listener(details)` 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. + +#### `webRequest.onHeadersReceived([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `statusLine` string + * `statusCode` Integer + * `responseHeaders` Record (optional) + * `callback` Function + * `headersReceivedResponse` Object + * `cancel` boolean (optional) + * `responseHeaders` Record (optional) - When provided, the server is assumed + to have responded with these headers. + * `statusLine` string (optional) - Should be provided when overriding + `responseHeaders` to change header status otherwise original response + header's status will be used. + +The `listener` will be called with `listener(details, callback)` when HTTP +response headers of a request have been received. + +The `callback` has to be called with a `response` object. + +#### `webRequest.onResponseStarted([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `responseHeaders` Record (optional) + * `fromCache` boolean - Indicates whether the response was fetched from disk + cache. + * `statusCode` Integer + * `statusLine` string + +The `listener` will be called with `listener(details)` when first byte of the +response body is received. For HTTP requests, this means that the status line +and response headers are available. + +#### `webRequest.onBeforeRedirect([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `redirectURL` string + * `statusCode` Integer + * `statusLine` string + * `ip` string (optional) - The server IP address that the request was + actually sent to. + * `fromCache` boolean + * `responseHeaders` Record (optional) + +The `listener` will be called with `listener(details)` when a server initiated +redirect is about to occur. + +#### `webRequest.onCompleted([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `responseHeaders` Record (optional) + * `fromCache` boolean + * `statusCode` Integer + * `statusLine` string + * `error` string + +The `listener` will be called with `listener(details)` when a request is +completed. + +#### `webRequest.onErrorOccurred([filter, ]listener)` + +* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional) +* `listener` Function | null + * `details` Object + * `id` Integer + * `url` string + * `method` string + * `webContentsId` Integer (optional) + * `webContents` WebContents (optional) + * `frame` WebFrameMain (optional) + * `resourceType` string - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`. + * `referrer` string + * `timestamp` Double + * `fromCache` boolean + * `error` string - The error description. + +The `listener` will be called with `listener(details)` when an error occurs. \ No newline at end of file