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 kurabilen bir yerel mesajlaşma ana makinesi kaydetmelidir. 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
Uygulamanın, yerel mesajlaşma ana makinesi yapılandırmasını tanımlayan bir dosyayı kaydetmesi gerekir.
Dosya örneği aşağıdaki gibidir:
{
"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ı. İstemciler bu dizeyi
runtime.connectNative()veyaruntime.sendNativeMessage()'a iletir. Bu ad yalnızca küçük harfli alfanümerik karakterler, alt çizgi ve nokta içerebilir. Ad nokta ile başlayamaz veya bitemez ve bir noktadan sonra başka bir nokta gelemez. description- Kısa uygulama açıklaması.
path- Yerel mesajlaşma ana makinesi ikilisine giden yol. Linux ve macOS'te yol mutlak olmalıdır. Windows'da, bildirim dosyasını içeren dizine göreli olabilir. Ana makine işlemi, geçerli dizin ana makine ikilisini içeren dizin olarak ayarlanmış şekilde başlatılır. Örneğin, bu parametre
C:\Application\nm_host.exeolarak ayarlanırsa geçerli dizin olan "C:\Application" ile başlatılır. type- Yerel mesajlaşma ana makinesiyle iletişim kurmak için kullanılan arayüzün türü. Bu parametrenin olası tek değeri
stdio'dır. Bu, 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 karakter içeremez.
Yerel mesajlaşma ana makinesinin konumu
Manifest dosyasının konumu platforma bağlıdır.
Windows'da manifest dosyası, dosya sisteminin herhangi bir yerinde bulunabilir. Uygulama yükleyicisi, 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 yolu olarak ayarlamalıdır. Örneğin, aşağıdaki komutu kullanma:
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 defterine, ardından 64 bit kayıt defterine sorgu gönderir.
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 genelinde yerel mesajlaşma barındırıcıları sabit bir konumda aranırken kullanıcı düzeyinde yerel mesajlaşma barındırıcıları 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. İletileri her iki yönde de 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ındaki 32 bitlik ileti uzunluğuyla başlar. Yerel mesajlaşma ana makinesinden gelen tek bir iletinin maksimum boyutu 1 MB'tır. Bunun temel nedeni, Chrome'u hatalı çalışan yerel uygulamalardan korumaktır. Yerel mesajlaşma ana makinesine gönderilen iletinin maksimum boyutu 64 MiB'tir.
Yerel mesajlaşma ana makinesine iletilen ilk bağımsız değişken, arayanın kaynağıdır ve genellikle chrome-extension://[ID of allowed extension] olur. Bu, yerel mesajlaşma ana makinesi manifestosundaki allowed_origins anahtarında birden fazla uzantı belirtildiğinde yerel mesajlaşma ana makinelerinin iletinin kaynağını tanımlamasına olanak tanır.
Windows'da, yerel mesajlaşma ana makinesine, çağıran Chrome yerel penceresinin tutamacını içeren bir komut satırı bağımsız değişkeni de iletilir: --parent-window=<decimal handle value>. Bu, yerel mesajlaşma ana makinesinin doğru şekilde üst öğe atanmış yerel kullanıcı arayüzü pencereleri oluşturmasına olanak tanır. Arama 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 çalışmaya devam eder. Diğer yandan, runtime.sendNativeMessage() kullanılarak mesajlaşma bağlantı noktası oluşturulmadan bir mesaj gönderildiğinde Chrome, her mesaj için yeni bir yerel mesajlaşma ana makine işlemi başlatır. Bu durumda, ana makine süreci tarafından oluşturulan ilk mesaj, orijinal isteğe yanıt olarak ele alınır ve Chrome, 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 bir uygulamaya bağlanma
Yerel bir uygulamaya ileti gönderme ve alma, uzantılar arası mesajlaşmaya çok benzer. Temel fark, runtime.connect() yerine runtime.connectNative(), runtime.sendMessage() yerine ise runtime.sendNativeMessage() kullanılmasıdır.
Bu yöntemleri kullanmak için uzantılarınızın manifest dosyasında "nativeMessaging" izni bildirilmelidir.
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. İçerik komut dosyasından yerel uygulamaya iletişim kurmak istiyorsanız mesajı, yerel uygulamaya iletmesi için hizmet çalışanıza gönderin.
Aşağıdaki örnek, yerel mesajlaşma ana makinesi com.my_company.my_application'e 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. Örneğin:
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. Yerel mesajlaşma ana makinesinin başlatılamaması, stderr konumuna yazması veya iletişim protokolünü ihlal etmesi bu durumlara dahildir. Linux ve macOS'te bu günlük, Chrome komut satırından başlatılarak ve terminaldeki çıkışı izlenerek erişilebilir. Windows'da Günlük kaydını etkinleştirme bölümünde açıklandığı gibi --enable-logging kullanın.
Sık karşılaşılan bazı hatalar ve bunları çözmeye yönelik ipuçları aşağıda verilmiştir:
Yerel mesajlaşma ana makinesi başlatılamadı.
Yerel mesajlaşma ana makine dosyasını yürütmek için yeterli izne sahip olup olmadığınızı 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. Ad nokta ile başlayamaz veya bitemez ve noktadan sonra başka bir nokta gelemez.
Yerel düzenleyen çıktı.
İleti, Chrome tarafından okunmadan önce yerel mesajlaşma ana makinesine giden kanal bozuldu. Bu durum büyük olasılıkla yerel mesajlaşma barındırıcınızdan başlatılmıştır.
Belirtilen yerel mesajlaşma ana makinesi bulunamadı.
Aşağıdakileri kontrol edin:
- Uzantıda ve bildiri dosyasında ad doğru yazılmış mı?
- Bildiri doğru dizinde ve doğru adla mı yer alıyor? Beklenen biçimler için native messaging host location bölümüne bakın.
- Manifest dosyası doğru biçimde mi? Özellikle JSON'ın geçerli ve iyi biçimlendirilmiş olup olmadığı ve değerlerin yerel mesajlaşma ana makinesi manifest tanımına uygun olup olmadığı kontrol edilir.
pathiçinde belirtilen dosya var mı? Windows'da yollar göreceli 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 native messaging host location adresinde belgelendiği gibi gerekli biçime uygun olup olmadığını regedit kullanarak tekrar kontrol edin.
Belirtilen yerel mesajlaşma ana makinesine erişim yasaktır.
Uzantının kaynağı allowed_origins içinde listeleniyor mu?
Yerel mesajlaşma ana bilgisayarıyla 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 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'ü aşmamalıdır.
- İleti boyutu, iletideki 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, I/O moduO_TEXTşeklindedir. 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. I/O modu,__setmodekullanılarak ayarlanabilir.