session

sessionモジュールは、新しいSessionオブジェクトを作成するのに使われます。

BrowserWindowのプロパティである webContentsプロパティのsessionを使うことで既存ページの sessionにアクセスできます。

const BrowserWindow = require('electron').BrowserWindow;

var win = new BrowserWindow({ width: 800, height: 600 });
win.loadURL("http://github.com");

var ses = win.webContents.session;

メソッド

sessionメソッドは次のメソッドを持ちます：

session.fromPartition(partition)

• partition String

partition文字列から新しいSessionインスタンスを返します。

partitionがpersist:から始まっている場合、同じpartitionのアプリ内のすべてのページに永続セッションを提供するのにページが使います。persist:プレフィックスが無い場合、ページはインメモリセッションを使います。partitionが空の場合、アプリの既定のセッションを返します。

プロパティ

sessionモジュールは次のプロパティを持ちます:

session.defaultSession

アプリの既定のセッションオブジェクトを返します。

クラス: Session

sessionモジュールで、Sessionオブジェクトを作成できます:

const session = require('electron').session;

var ses = session.fromPartition('persist:name');

インスタンスイベント

Sessionのインスタンス上で次のイベントが提供されます:

イベント: 'will-download'

• event Event
• item DownloadItem
• webContents WebContents

ElectronがwebContentsでitemをダウンロードしようとすると出力されます。

event.preventDefault() をコールするとダウンロードをキャンセルできます。

session.defaultSession.on('will-download', function(event, item, webContents) {
  event.preventDefault();
  require('request')(item.getURL(), function(data) {
    require('fs').writeFileSync('/somewhere', data);
  });
});

インスタンスのメソッド

Sessionのインスタンス上で次のメソッドが提供されています:

ses.cookies

cookiesは、cookiesに問い合わせしたり、修正をできるようにします。例：

// Query all cookies.
session.defaultSession.cookies.get({}, function(error, cookies) {
  console.log(cookies);
});

// Query all cookies associated with a specific url.
session.defaultSession.cookies.get({ url : "http://www.github.com" }, function(error, cookies) {
  console.log(cookies);
});

// Set a cookie with the given cookie data;
// may overwrite equivalent cookies if they exist.
var cookie = { url : "http://www.github.com", name : "dummy_name", value : "dummy" };
session.defaultSession.cookies.set(cookie, function(error) {
  if (error)
    console.error(error);
});

ses.cookies.get(filter, callback)

• filter Object
  • url String (オプション) - urlに関連付けられているcookiesを取得します。空の場合すべてのurlのcookiesを取得します
  • name String (オプション) - nameでcookiesをフィルタリングします
  • domain String (オプション) - domainsのドメインまたはサブドメインに一致するcookiesを取得します
  • path String (オプション) - pathに一致するパスのcookiesを取得します
  • secure Boolean (オプション) - Secure プロパティでcookiesをフィルターします
  • session Boolean (オプション) - Filters out sessionまたは永続cookiesを除外します
• callback Function

detailsに一致するすべてのcookiesを取得するためにリクエストを送信し、完了時にcallback(error, cookies)でcallbackがコールされます。

cookies はcookieオブジェクトの配列です。

• cookie Object
  • name String - cookieの名前
  • value String - cookieの値
  • domain String - cookieのドメイン
  • hostOnly String - cookieがホストのみのcookieかどうか
  • path String - cookieのパス
  • secure Boolean - cookieがセキュアとマークされているかどうか
  • httpOnly Boolean - HTTPのみとしてcookieがマークされているかどうか
  • session Boolean - cookieがセッションcookieまたは有効期限付きの永続cookieかどうか
  • expirationDate Double (オプション) -

cookieの有効期限をUNIX時間で何秒かを示します。セッションcookiesは提供されません。

ses.cookies.set(details, callback)

• details Object
  • url String - urlに関連付けられているcookiesを取得します。
  • name String - cookieの名前。省略した場合、既定では空です。
  • value String - cookieの名前。省略した場合、既定では空です。
  • domain String - cookieのドメイン。省略した場合、既定では空です。
  • path String - cookieのパス。 省略した場合、既定では空です。
  • secure Boolean - cookieをセキュアとしてマークする必要があるかどうか。既定ではfalseです。
  • session Boolean - cookieをHTTPのみとしてマークする必要があるかどうか。既定ではfalseです。
  • expirationDate Double - cookieの有効期限をUNIX時間で何秒か。省略した場合、cookieはセッションcookieになります。
• callback Function

detailsでcookieを設定し、完了するとcallback(error)でcallbackがコールされます。

ses.cookies.remove(url, name, callback)

• url String - cookieに関連付けられているURL
• name String - 削除するcookieの名前
• callback Function

url と nameと一致するcookiesを削除し、完了するとcallbackが、callback()でコールされます。

ses.getCacheSize(callback)

• callback Function
  • size Integer - 使用しているキャッシュサイズバイト数

現在のセッションのキャッシュサイズを返します。

ses.clearCache(callback)

• callback Function - 操作が完了したら、コールされます。

セッションのHTTPキャッシュをクリアします。

ses.clearStorageData([options, ]callback)

• options Object (オプション)
  • origin String - window.location.originの説明で、scheme://host:portに従う
  • storages Array - クリアするストレージの種類で、次を含められます: appcache、 cookies、 filesystem、 indexdb、 local storage、 shadercache、 websql、 serviceworkers
  • quotas Array - クリアするクォーターの種類で、次を含められます: temporary, persistent, syncable.
• callback Function - 操作をするとコールされます。

ウェブストレージのデータをクリアします。

ses.flushStorageData()

書き込まれていないDOMStorageデータをディスクに書き込みます。

ses.setProxy(config, callback)

• config Object
  • pacScript String - PACファイルに関連付けらえたURL
  • proxyRules String - 使用するプロキシを指定するルール
• callback Function - 操作をするとコールされます。

プロキシ設定を設定します。

pacScript と proxyRulesが一緒に渡されたら、proxyRulesオプションは無視され、pacScript設定が適用されます。

proxyRulesはつふぃのルールに従います。

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

具体例:

• http=foopy:80;ftp=foopy2 - http://URLはfoopy:80HTTPプロキシを使用し、ftp://URLはfoopy2:80 HTTPプロキシを使用します。
• foopy:80 - 全てのURLでfoopy:80を使用します。
• foopy:80,bar,direct:// - 全てのURLでfoopy:80HTTPプロキシを使用し、foopy:80が提供されていなければbarを使用し、さらに使えない場合はプロキシを使いません。
• socks4://foopy - 全てのURLでSOCKS foopy:1080プロキシを使います。
• http=foopy,socks5://bar.com - http URLでfoopyHTTPプロキシを使い、foopyが提供されていなければ、SOCKS5 proxy bar.comを使います。
• http=foopy,direct:// - 　http URLでfoopyHTTPプロキシを使い、foopyが提供されていなければ、プロキシを使いません。
• http=foopy;socks=foopy2 - http URLでfoopyHTTPプロキシを使い、それ以外のすべてのURLでsocks4://foopy2を使います。

ses.resolveProxy(url, callback)

• url URL
• callback Function

urlをプロキシ情報で解決します。リクエストが実行された時、callback(proxy)で callbackがコールされます。

ses.setDownloadPath(path)

• path String - ダウンロード場所

ダウンロードの保存ディレクトリを設定します。既定では、ダウンロードディレクトリは、個別のアプリフォルダー下のDownloadsです。

ses.enableNetworkEmulation(options)

• options Object
  • offline Boolean - ネットワーク停止を再現するかどうか
  • latency Double - RTT ms秒
  • downloadThroughput Double - Bpsでのダウンロード割合
  • uploadThroughput Double - Bpsでのアップロード割合

再現ネットワークは、session用の設定を付与します。

// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
    latency: 500,
    downloadThroughput: 6400,
    uploadThroughput: 6400
});

// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({offline: true});

ses.disableNetworkEmulation()

sessionですでに有効になっているネットワークエミュレーションを無効化します。オリジナルのネットワーク設定にリセットします。

ses.setCertificateVerifyProc(proc)

• proc Function

sessionの証明書検証ロジックを設定し、サーバー証明書確認がリクエストされた時、proc(hostname, certificate, callback)でprocがコールされます。callback(true)がコールされると証明書を受け入れ、callback(false)がコールされると拒否します。

Calling setCertificateVerifyProc(null)をコールして、既定の証明書検証ロジックに戻します。

myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) {
  if (hostname == 'github.com')
    callback(true);
  else
    callback(false);
});

ses.webRequest

webRequestAPIセットをインターセプトし、そのライフタイムの様々な段階でリクエストの内容を変更できます。

APIのイベントが発生したとき、それぞれのAPIはオプションでfilterと listenerを受け入れ、listener(details) でlistenerがコールされ、detailsはリクエストを説明するオブジェクトです。listenerにnullが渡されるとイベントの購読をやめます。

filterはurlsプロパティを持つオブジェクトで、URLパターンにマッチしないリクエストを除外するのに使われるURLパターンの配列です。filterを省略した場合、全てのリクエストにマッチします。

いくつかのイベントでcallbackでlistenerに渡され、listenerが動作するとき、responseオブジェクトでコールされる必要があります。

// Modify the user agent for all requests to the following urls.
var filter = {
  urls: ["https://*.github.com/*", "*://electron.github.io"]
};

session.defaultSession.webRequest.onBeforeSendHeaders(filter, function(details, callback) {
  details.requestHeaders['User-Agent'] = "MyAgent";
  callback({cancel: false, requestHeaders: details.requestHeaders});
});

ses.webRequest.onBeforeRequest([filter, ]listener)

• filter Object
• listener Function

リクエストが発生しようとしている時、listener(details, callback)でlistener がコールされます。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • uploadData Array (オプション)
  • callback Function

uploadDataは dataオブジェクトの配列です。

• data Object
  • bytes Buffer - 送信されるコンテンツ
  • file String - アップロードされるファイルパス

callbackはresponseオブジェクトでコールされる必要があります:

• response Object
  • cancel Boolean (オプション)
  • redirectURL String (オプション) - オリジナルリクエストが送信もしくは完了するのを中断し、代わりに付与したURLにリダイレクトします。

ses.webRequest.onBeforeSendHeaders([filter, ]listener)

• filter Object
• listener Function

リクエストヘッダーが提供されれば、HTTPリクエストが送信される前に、listener(details, callback)でlistenerがコールされます。TCP接続がサーバーに対して行われた後に発生することがありますが、HTTPデータは送信前です。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • requestHeaders Object
• callback Function

The callback has to be called with an response object:

• response Object
  • cancel Boolean (オプション)
  • requestHeaders Object (オプション) - 付与されると、リクエストはそれらのヘッダーで作成されます。

ses.webRequest.onSendHeaders([filter, ]listener)

• filter Object
• listener Function

サーバーにリクエストを送信しようする直前にlistener(details)で、listener がコールされます。前回のonBeforeSendHeadersレスポンスの変更箇所は、このリスナーが起動した時点で表示されます。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • requestHeaders Object

ses.webRequest.onHeadersReceived([filter,] listener)

• filter Object
• listener Function

リクエストのHTTPレスポンスヘッダーを受信したとき、listenerはlistener(details, callback)でコールされます。

• details Object
  • id String
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • statusLine String
  • statusCode Integer
  • responseHeaders Object
• callback Function

callbackはresponseオブジェクトでコールされる必要があります:

• response Object
  • cancel Boolean
  • responseHeaders Object (オプション) - 付与されていると、これらのヘッダーでサーバーはレスポンスしたと仮定します。

ses.webRequest.onResponseStarted([filter, ]listener)

• filter Object
• listener Function

レスポンスボディの最初のバイトを受信したとき、listener はlistener(details) でコールされます。HTTPリクエストでは、ステータス行とレスポンスヘッダーを意味します。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • responseHeaders Object
  • fromCache Boolean -ディスクキャッシュから取得したレスポンスかどうかを示します
  • statusCode Integer
  • statusLine String

ses.webRequest.onBeforeRedirect([filter, ]listener)

• filter Object
• listener Function

サーバーがリダイレクトを開始しはじめたとき、listener(details)でlistener がコールされます。

• details Object
  • id String
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • redirectURL String
  • statusCode Integer
  • ip String (オプション) - 実際にリクエストが送信されるサーバーIPアドレス
  • fromCache Boolean
  • responseHeaders Object

ses.webRequest.onCompleted([filter, ]listener)

• filter Object
• listener Function

リクエスト完了時、listenerがlistener(details)でコールされます。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • responseHeaders Object
  • fromCache Boolean
  • statusCode Integer
  • statusLine String

ses.webRequest.onErrorOccurred([filter, ]listener)

• filter Object
• listener Function

エラー発生時、 listener(details) でlistenerがコールされます。

• details Object
  • id Integer
  • url String
  • method String
  • resourceType String
  • timestamp Double
  • fromCache Boolean
  • error String - エラーの説明