Uzantılar, diğer mesaj iletme API'lerine benzer bir API kullanarak yerel uygulamalarla mesaj alışverişi yapabilir. Bu özelliği destekleyen yerel uygulamalar, uzantıyla iletişim kurabilecek yerel bir mesajlaşma ana makinesi kaydetmelidir. Chrome, ana makineyi ayrı bir işlemde başlatır ve standart giriş ve standart çıkış akışları kullanarak iletişim kurar.
Yerel mesajlaşma ana makinesi
Uygulamanın, yerel mesajlaşma ana makinesi yapılandırmasını kaydettirmek için yerel mesajlaşma ana makinesi yapılandırmasını tanımlayan bir dosya kaydetmesi gerekir.
Dosyayla ilgili bir örnek 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/"]
}
Yerel mesajlaşma ana makinesi manifest dosyası geçerli JSON olmalı ve aşağıdaki alanları içermelidir:
name- Yerel mesajlaşma ana makinesinin adı. Müşteriler bu dizeyi
runtime.connectNative()veyaruntime.sendNativeMessage()parametrelerine iletir. Bu ad yalnızca küçük alfanümerik karakterler, alt çizgiler ve noktalar içerebilir. Adın başında ya da sonunda nokta olamaz ve bir noktadan sonra başka bir nokta gelemez. description- Kısa uygulama açıklaması.
path- Yerel mesajlaşma ana makinesi ikili programının yolu. Linux ve macOS'te yol mutlak olmalıdır. Windows'da bu dosya, manifest dosyasını içeren dizine göreli olabilir. Ana bilgisayar işlemi, geçerli dizin ana makine ikili programını içeren dizine ayarlanarak başlatılır. Örneğin, bu parametre
C:\Application\nm_host.exeolarak ayarlanırsa mevcut dizin "C:\Application" ile başlatılır. type- Yerel mesajlaşma ana makinesi ile iletişim kurmak için kullanılan arayüz türü. Bu parametre bir olası değere sahip:
stdio. Chrome'un ana makineyle iletişim kurmak içinstdinvestdoutkullanması gerektiğini belirtir. allowed_origins- Yerel mesajlaşma ana makinesine erişmesi gereken uzantıların listesi.
allowed-originsdeğerleri joker karakter içermez.
Yerel mesajlaşma ana makine konumu
Manifest dosyasının konumu platforma göre değişir.
Windows'da manifest dosyası, dosya sisteminde herhangi bir yerde bulunabilir. Uygulama yükleyicinin 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 gibi bir kayıt defteri anahtarı oluşturması ve bu anahtarın varsayılan değerini, manifest dosyasının tam yoluna ayarlaması gerekir. Ö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 şu .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 aradığında ö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şiklik gösterir. Sistem genelindeki yerel mesajlaşma ana makineleri sabit bir konumda aranırken, kullanıcı düzeyinde yerel mesajlaşma ana makineleri 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 bir yerel mesajlaşma ana makinesini ayrı bir süreçte başlatır ve standart giriş (stdin) ve standart çıkış (stdout) kullanarak her iki yönde de mesaj göndermek için aynı biçim kullanılır. Her mesaj, JSON, UTF-8 kodlamalı olarak serileştirilir ve başa yerel bayt sırasında 32 bit ileti uzunluğu eklenir. Yerel mesajlaşma ana makinesinden gelen tek bir mesajın maksimum boyutu 1 MB'tır. Bu boyut, temel olarak Chrome'un yanlış çalışan yerel uygulamalara karşı korunmasını amaçlar. Yerel mesajlaşma ana makinesine gönderilen mesajın maksimum boyutu 4 GB'tır.
Yerel 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 manifestindeki allowed_origins anahtarında birden fazla uzantı belirtildiğinde yerel mesajlaşma ana makinelerinin mesajın kaynağını tanımlamasını sağlar.
Windows'da yerel mesajlaşma ana makinesine, Chrome yerel penceresine şu işleyiciyle birlikte bir komut satırı bağımsız değişkeni de aktarılır: --parent-window=<decimal handle value>. Bu, yerel mesajlaşma ana makinesinin, doğru şekilde üst yönetime sahip yerel kullanıcı arayüzü pencereleri oluşturmasına olanak tanır. Çağrı 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 işlemini başlatır ve bağlantı noktası kaldırılana kadar bu işlemi çalışır. Diğer yandan, runtime.sendNativeMessage() kullanılarak bir mesaj gönderildiğinde Chrome, mesajlaşma bağlantı noktası oluşturmadan 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, bu mesajı runtime.sendNativeMessage() çağrıldığında belirtilen yanıt geri çağırmasına 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 bir uygulamaya mesaj gönderip almak, 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öntemlerin kullanılabilmesi için uzantınızın manifest dosyasında "nativeMessaging" izninin açıklanması gerekir.
Bu yöntemler içerik komut dosyalarında kullanılamaz, yalnızca uzantınızın sayfalarında ve hizmet çalışanında kullanılabilir. Bir içerik komut dosyasından yerel uygulamayla iletişim kurmak isterseniz mesajı yerel uygulamaya iletmesi için hizmet çalışanınıza gönderin.
Aşağıdaki örnek, yerel mesajlaşma ana makinesine (com.my_company.my_application) bağlı bir runtime.Port nesnesi oluşturur, bu bağlantı noktasından gelen mesajları dinlemeye başlar ve bir giden mesaj gönderir:
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. Örnek:
chrome.runtime.sendNativeMessage(
'com.my_company.my_application',
{text: 'Hello'},
function (response) {
console.log('Received ' + response);
}
);
Yerel mesajlaşmada 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şlatılamaması, stderr öğesine yazması veya iletişim protokolünü ihlal etmesi dahildir. Linux ve macOS'te, Chrome'u komut satırından başlatıp terminalde çıkışını izleyerek bu günlüğe 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:
Yerel mesajlaşma ana makinesi başlatılamadı.
Yerel mesajlaşma ana makine dosyasını yürütmek için yeterli izniniz 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. Bir ad noktayla başlayamaz veya bitemez ve bir noktanın ardından başka bir nokta gelemez.
Yerel ana makineden çıkıldı.
Mesaj Chrome tarafından okunmadan önce yerel mesajlaşma ana makinesine giden kanal bozuktu. Bu, büyük olasılıkla yerel mesajlaşma ana makinenizden 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 ada sahip mi? Beklenen biçimler için yerel mesajlaşma ana makine konumuna bakın.
- Manifest dosyası doğru biçimde mi? Özellikle, JSON geçerli ve iyi biçimlendirilmiş mi ve değerler yerel mesajlaşma ana makinesi manifest tanımıyla eşleşiyor mu?
pathpolitikasında belirtilen dosya var mı? Windows'da 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ı. Anahtarın gerçekten oluşturulup oluşturulmadığını ve yerel mesajlaşma ana makinesi konumunda belirtilen gerekli biçimle eşleşip eşleşmediğini regedit kullanarak tekrar kontrol edin.
Belirtilen yerel mesajlaşma ana makinesine erişim yasaklandı.
Uzantının kaynağı allowed_origins konumunda mı?
Yerel mesajlaşma ana makinesiyle iletişim kurulurken hata oluştu.
Bu durum, 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 uygun olduğundan emin olun. Hata ayıklama amacıyla bazı verileri yazdırmak istiyorsanızstderradresine yazın.- 32 bit mesaj uzunluğunun platformun yerel tam sayı biçiminde (little-endian/big-endian) olduğundan emin olun.
- İleti uzunluğu 1024*1024 değerini aşmamalıdır.
- İletinin boyutu, iletideki bayt sayısına eşit olmalıdır. Karakterler birden çok baytla temsil edilebileceği için bu, bir dizenin "uzunluğundan" farklı olabilir.
- Yalnızca Windows: Programın G/Ç modunun
O_BINARYolarak ayarlandığından emin olun. Varsayılan olarak G/Ç moduO_TEXT'dir. Bu mod, satır sonları (\n=0A) yerine Windows stili satır sonları (\r\n=0D 0A) ile değiştirildiğinde mesaj biçimini bozar. G/Ç modu__setmodekullanılarak ayarlanabilir.