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 makinesini kaydettirmek için uygulamanın, doğal mesajlaşma ana makinesi 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ı. İstemciler bu dizeyi
runtime.connectNative()veyaruntime.sendNativeMessage()'e 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 makinesi ikili dosyası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 makinesi konumu
Manifest dosyasının konumu platforma bağlıdır.
Windows'ta 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 kayıt defteri anahtarı oluşturmalı ve bu anahtarın varsayılan değerini manifest dosyasının tam yoluna 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 barındırıcıları sabit bir konumda, kullanıcı düzeyindeki yerel mesajlaşma barındırıcıları ise kullanıcı profili dizininin NativeMessagingHosts/ alt dizininde bulunur.
- 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 düzeninde 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 64 MB'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 bir uygulamaya bağlanma
Yerleşik bir uygulamaya ve uygulamadan mesaj gönderip alma, uzantılar arası mesajlaşmaya ç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ında değil, yalnızca uzantınızın sayfalarında ve servis çalışanında kullanılabilir. Bir içerik komut dosyasından yerel uygulamaya iletişim kurmak istiyorsanız mesajı yerel uygulamaya iletmesi için hizmet işleyicinize 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. Yerel mesajlaşma ana makinesinin başlatılamaması, stderr adresine yazma veya iletişim protokolünü ihlal etmesi de buna 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'da, Günlük kaydını etkinleştirme bölümünde açıklandığı gibi --enable-logging kullanın.
Aşağıda, sık karşılaşılan bazı hatalar ve bunları çözmeye yönelik ipuçları verilmiştir:
Doğal mesajlaşma ana makinesi başlatılamadı.
Yerel mesajlaşma ana makine dosyasını yürütmek 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 noktanın ardından başka bir nokta gelemez.
Yerel düzenleyen ayrıldı.
İleti Chrome tarafından okunmadan önce yerel mesajlaşma ana makinesine giden boru 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ı ve manifest dosyasında doğru yazılmış mı?
- Manifest doğru dizinde ve doğru ada sahip mi? Beklenen biçimler için yerel mesajlaşma ana makinesinin 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?
pathiçinde belirtilen dosya var mı? Windows'ta yollar göreli olabilir ancak macOS ve Linux'ta yollar mutlak olmalıdır.
Ana makine adı olan yerel mesajlaşma ana makinesi kayıtlı değil. (Yalnızca Windows)
Yerel mesajlaşma ana makinesi Windows kayıt defterinde bulunamadı. Anahtarı regeditkullanarak gerçekten oluşturulup oluşturulmadığını ve yerel mesajlaşma barındırıcısının konumunda belirtilen gerekli biçimle eşleşip eşleşmediğini kontrol edin.
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.
stdoutiçindeki tüm çıkışların yerel mesajlaşma protokolüne uyduğ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 G/Ç moduO_TEXT'tür. Bu modda, satır sonları (\n=0A) Windows tarzı satır sonlarıyla (\r\n=0D 0A) değiştirildiğinden ileti biçimi bozulur. G/Ç modu__setmodekullanılarak ayarlanabilir.