Uzantılar, diğer mesaj aktarma API'lerine benzer bir API kullanarak yerel uygulamalarla mesaj alışverişi yapabilir. Bu özelliği destekleyen yerel uygulamalar, uzantı ile iletişim kurabilen bir yerel mesajlaşma ana makinesi kaydettirmelidir. Chrome, ana makineyi ayrı bir işlemde başlatır ve standart giriş ve standart çıkış akışlarını kullanarak ana makineyle iletişim kurar.
Yerel mesajlaşma ana makinesi
Yerel mesajlaşma ana makinesi kaydetmek için uygulamanın yerel mesajlaşma ana makine yapılandırmasını tanımlayan bir dosya kaydetmesi gerekir.
Dosya örneği aşağıda verilmiştir:
{
"name": "com.my_company.my_application",
"description": "My Application",
"path": "C:\\Program Files\\My Application\\chrome_native_messaging_host.exe",
"type": "stdio",
"allowed_origins": ["chrome-extension://knldjmfmopnpolahpmmgbagdohdnhkik/"]
}
Yerleşik mesajlaşma ana makine manifest dosyası geçerli JSON biçiminde olmalı ve aşağıdaki alanları içermelidir:
name- Yerel mesajlaşma ana makinesinin adı. Müşteriler bu dizeyi
runtime.connectNative()veyaruntime.sendNativeMessage()adreslerine iletir. Bu ad yalnızca küçük alfanümerik karakterler, alt çizgiler ve noktalar içerebilir. Ad noktayla başlayamaz veya bitemez ve bir noktanın ardından başka bir nokta gelemez. description- Kısa uygulama açıklaması.
path- Yerel mesajlaşma ana makine ikili programının yolu. Linux ve macOS'te yol mutlak olmalıdır. Windows'ta, manifesto dosyasını içeren dizine göreli olabilir. Ana makine işlemi, mevcut dizin ana makine ikilisini içeren dizin olarak ayarlanarak başlatılır. Örneğin, bu parametre
C:\Application\nm_host.exeolarak ayarlanırsa "C:\Application" geçerli dizini ile başlatılır. type- Doğal mesajlaşma ana makinesiyle iletişim kurmak için kullanılan arayüz türü. Bu parametrenin tek bir olası değeri vardır:
stdio. Chrome'un ana makineyle iletişim kurmak içinstdinvestdoutkullanması gerektiğini gösterir. allowed_origins- Yerel mesajlaşma ana makinesine erişmesi gereken uzantıların listesi.
allowed-originsdeğerleri joker karakterler içeremez.
Yerel mesajlaşma ana makine konumu
Manifest dosyasının konumu platforma bağlıdır.
Windows'da, manifest dosyası, dosya sisteminin herhangi bir yerinde bulunabilir. Uygulama yükleyici HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application veya HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application şeklinde bir kayıt defteri anahtarı oluşturmalı ve bu anahtarın varsayılan değerini manifest dosyasının tam yolu olarak ayarlamalıdır. Örneğin, aşağıdaki komutu kullanarak:
REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f
veya aşağıdaki .reg dosyasını kullanarak:
Windows Registry Editor Version 5.00
[HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application]
@="C:\\path\\to\\nmh-manifest.json"
Chrome, yerel mesajlaşma ana makinelerini ararken önce 32 bit kayıt defteri, ardından 64 bit kayıt defteri sorgulanır.
macOS ve Linux'ta yerel mesajlaşma ana makinesinin manifest dosyasının konumu tarayıcıya (Google Chrome veya Chromium) göre değişir. Sistem genelindeki yerel mesajlaşma ana makineleri sabit bir konuma bakarken kullanıcı düzeyindeki yerel mesajlaşma ana makineleri ise kullanıcı profili dizininin NativeMessagingHosts/ alt dizininde aranır.
- macOS (sistem genelinde)
- Google Chrome:
/Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json - macOS (kullanıcıya özel, varsayılan yol)
- Google Chrome:
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
~/Library/Application Support/Chromium/NativeMessagingHosts/com.my_company.my_application.json - Linux (sistem genelinde)
- Google Chrome:
/etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json - Chromium:
/etc/chromium/native-messaging-hosts/com.my_company.my_application.json - Linux (kullanıcıya özel, varsayılan yol)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json - Chromium:
~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json
Yerel mesajlaşma protokolü
Chrome, her yerel mesajlaşma ana makinesini ayrı bir işlemde başlatır ve standart giriş (stdin) ile standart çıkışı (stdout) kullanarak ana makineyle iletişim kurar. Her iki yönde de ileti göndermek için aynı biçim kullanılır; her ileti, JSON kullanılarak serileştirilir, UTF-8 ile kodlanır ve yerel bayt sırasına göre 32 bitlik ileti uzunluğuyla başlar. Yerleşik mesajlaşma ana makinesindeki tek bir iletinin maksimum boyutu 1 MB'tır. Bu, Chrome'u kötüye çalışan yerel uygulamalardan korumak içindir. Yerleşik mesajlaşma ana makinesine gönderilen mesajın maksimum boyutu 4 GB'tır.
Yerleşik mesajlaşma ana makinesinin ilk bağımsız değişkeni, arayanın kaynağıdır (genellikle chrome-extension://[ID of allowed extension]). Bu, yerel mesajlaşma ana makinesi manifest dosyasında allowed_origins anahtarında birden fazla uzantı belirtildiğinde yerel mesajlaşma ana makinelerinin ileti kaynağını tanımlamasına olanak tanır.
Windows'da yerel mesajlaşma ana makinesine, çağıran Chrome yerel penceresinin adını içeren bir komut satırı bağımsız değişkeni de iletilir: --parent-window=<decimal handle value>. Bu sayede yerel mesajlaşma ana makinesi, doğru üst öğeye sahip yerel kullanıcı arayüzü pencereleri oluşturabilir. Çağıran bağlam bir hizmet çalışanıysa bu değerin 0 olacağını unutmayın.
runtime.connectNative() kullanılarak bir mesajlaşma bağlantı noktası oluşturulduğunda Chrome, yerel mesajlaşma ana makine sürecini başlatır ve bağlantı noktası yok edilene kadar bu süreci çalışır durumda tutar. Öte yandan, bir mesaj runtime.sendNativeMessage() kullanılarak gönderildiğinde, mesaj bağlantı noktası oluşturulmadan Chrome her mesaj için yeni bir yerel mesajlaşma ana makine işlemi başlatır. Bu durumda, ana makine işlemi tarafından oluşturulan ilk mesaj orijinal isteğe yanıt olarak işlenir ve Chrome, runtime.sendNativeMessage() çağrıldığında belirtilen yanıt geri çağırma işlevine iletir. Bu durumda yerel mesajlaşma ana makinesi tarafından oluşturulan diğer tüm mesajlar yoksayılır.
Yerel uygulamaya bağlanma
Yerel uygulamaya mesaj gönderip almak, çapraz uzantı mesajlarına çok benzer. Temel fark, runtime.connect() yerine runtime.connectNative() ve runtime.sendMessage() yerine runtime.sendNativeMessage() kullanılmasıdır.
Bu yöntemleri kullanabilmek için "nativeMessaging" izninin uzantılarınızın manifest dosyasında beyan edilmesi gerekir.
Bu yöntemler içerik komut dosyalarının içinde kullanılamaz, yalnızca uzantınızın sayfalarında ve hizmet çalışanının içinde kullanılabilir. Bir içerik komut dosyasından yerel uygulamayla iletişim kurmak istiyorsanız mesajı yerel uygulamaya iletmesi için hizmet çalışanınıza gönderin.
Aşağıdaki örnekte, yerel mesajlaşma ana makinesine com.my_company.my_application bağlı bir runtime.Port nesnesi oluşturulur, bu bağlantı noktasından gelen mesajları dinlemeye başlanır ve bir giden mesaj gönderilir:
var port = chrome.runtime.connectNative('com.my_company.my_application');
port.onMessage.addListener(function (msg) {
console.log('Received' + msg);
});
port.onDisconnect.addListener(function () {
console.log('Disconnected');
});
port.postMessage({text: 'Hello, my_application'});
Bağlantı noktası oluşturmadan yerel uygulamaya mesaj göndermek için runtime.sendNativeMessage kullanın. Örneğin:
chrome.runtime.sendNativeMessage(
'com.my_company.my_application',
{text: 'Hello'},
function (response) {
console.log('Received ' + response);
}
);
Yerel mesajlaşmayı hata ayıklama
Belirli yerel mesajlaşma hataları oluştuğunda çıkış, Chrome'un hata günlüğüne yazılır. Buna yerel mesajlaşma ana makinesinin başlamaması, stderr adresine yazması veya iletişim protokolünü ihlal etmesi dahildir. Linux ve macOS'te bu günlüke, Chrome'u komut satırından başlatıp çıkışını terminalde izleyerek erişilebilir. Windows'ta, Günlük kaydını etkinleştirme bölümünde açıklandığı gibi --enable-logging simgesini kullanın.
Aşağıda, sık karşılaşılan bazı hatalar ve bunları çözmeyle ilgili ipuçları verilmiştir:
Yerel mesajlaşma ana makinesi başlatılamadı.
Yerel mesajlaşma barındırıcı dosyasını çalıştırmak için yeterli izinleriniz olup olmadığını kontrol edin.
Geçersiz yerel mesajlaşma ana makine adı belirtildi.
Adın geçersiz karakterler içerip içermediğini kontrol edin. Yalnızca küçük alfanümerik karakterlere, alt çizgilere ve noktalara izin verilir. Adlar noktayla başlayamaz veya bitemez ve bir noktanın ardından başka bir nokta gelemez.
Yerel ana makineden çıkıldı.
Yerel mesajlaşma ana makinesinin bağlantısı, mesaj Chrome tarafından okunmadan önce bozuldu. Bu işlem büyük olasılıkla yerel mesajlaşma ana makinenizde başlatılır.
Belirtilen yerel mesajlaşma ana makinesi bulunamadı.
Aşağıdakileri kontrol edin:
- Ad, uzantıda ve manifest dosyasında doğru yazılmış mı?
- Manifest doğru dizinde ve doğru adla mı? Beklenen biçimler için yerel mesajlaşma ana makine konumu bölümüne bakın.
- Manifest dosyası doğru biçimde mi? Özellikle, JSON geçerli ve iyi biçimlendirilmiş midir? Değerler yerel mesajlaşma ana makine manifesti tanımı ile eşleşiyor mu?
pathpolitikasında belirtilen dosya mevcut mu? Windows'ta yollar göreli olabilir ancak macOS ve Linux'ta yollar mutlak olmalıdır.
Yerel mesajlaşma ana makinesi ana makine adı kayıtlı değil. (Yalnızca Windows)
Yerel mesajlaşma ana makinesi Windows kayıt defterinde bulunamadı. regedit��
Belirtilen yerel mesajlaşma ana makinesine erişim yasaktır.
Uzantının kaynağı allowed_origins'te listeleniyor mu?
Yerel mesajlaşma ana makinesiyle iletişim kurulurken hata oluştu.
Bu, yerel mesajlaşma ana makinesinde iletişim protokolünün yanlış uygulandığını gösterir.
stdoutürünündeki tüm çıkışların yerel mesajlaşma protokolüne uygun olduğundan emin olun. Hata ayıklama amacıyla bazı verileri yazdırmak istiyorsanızstderradresine yazın.- 32 bitlik ileti uzunluğunun platformun yerel tam sayı biçiminde (az bayttan büyük bayt) olduğundan emin olun.
- Mesaj uzunluğu 1024*1024'ü aşmamalıdır.
- Mesaj boyutu, mesajdaki bayt sayısına eşit olmalıdır. Karakterler birden fazla baytla temsil edilebileceğinden bu değer, dizenin "uzunluğundan" farklı olabilir.
- Yalnızca Windows: Programın G/Ç modunun
O_BINARYolarak ayarlandığından emin olun. Varsayılan olarak, G/Ç moduO_TEXTşeklindedir ve satır sonları (\n=0A), Windows stili satır sonlarıyla (\r\n=0D 0A) değiştirildiğinden mesaj biçimini bozar. G/Ç modu__setmodekullanılarak ayarlanabilir.