Yerel Mesajlaşma

Uzantılar ve uygulamalar, 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 nasıl iletişim kuracağını bilen 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 makinesini kaydetmek için yerel mesajlaşma ana makinesi yapılandırmasını tanımlayan bir manifest dosyası yüklemesi gerekir. Manifest dosyasına 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ıdır ve aşağıdaki alanları içermelidir:

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ü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ını 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 ş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.

OS X 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 konumda aranırken, kullanıcı düzeyinde yerel mesajlaşma ana makineleri kullanıcı profili dizinindeki NativeMessagingHosts adlı bir alt dizinde aranır.

• OS X (sistem genelinde)
  • Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Krom: /Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
• OS X (kullanıcıya özel, varsayılan yol)
  • Google Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
  • Krom: ~/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
  • Krom: /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
  • Krom: ~/.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 ileti 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. Uyarı: Windows'da, Chrome 54 ve önceki sürümlerde kaynak, ilk parametre yerine ikinci parametre olarak aktarılıyordu.

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 her mesaj için yeni bir yerel mesajlaşma ana makinesi 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. Yani 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.

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 arka plan komut dosyası sayfasıysa bu değerin 0 olacağını unutmayın.

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 kullanılması ve runtime.sendMessage yerine runtime.sendNativeMessage kullanılmasıdır. Bu yöntemler yalnızca uygulamanızın manifest dosyasında "nativeMessaging" izni açıklanmışsa kullanılabilir.

Aşağıdaki örnek, yerel mesajlaşma ana makinesine bağlı bir runtime.Port nesnesi oluşturur com.my_company.my_application, bu bağlantı noktasından gelen mesajları dinlemeye başlar ve bir giden ileti 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" });

runtime.sendNativeMessage, bir bağlantı noktası oluşturmadan yerel uygulamaya mesaj göndermek için kullanılabilir. Örneğin:

chrome.runtime.sendNativeMessage('com.my_company.my_application',
  { text: "Hello" },
  function(response) {
    console.log("Received " + response);
  });

Yerel mesajlaşmada hata ayıklama

Yerel mesajlaşma ana makinesi başlatılamadığında, stderr adresine yazar veya iletişim protokolünü ihlal ettiğinde çıkış, Chrome'un hata günlüğüne yazılır. Linux ve OS X'te, Chrome'u komut satırından başlatıp terminalde çıkışını izleyerek bu günlüğe kolayca erişebilirsiniz. Windows'da, Günlük kaydını etkinleştirme bölümünde açıklandığı gibi --enable-logging kullanın.

Aşağıda bazı hatalar ve sorunları çözmeye yönelik ipuçları verilmiştir:

• Yerel mesajlaşma ana makinesi başlatılamadı.
  • Dosyayı 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ı.
  • Ad, uzantıda ve manifest dosyasında doğru yazılmış mı?
  • Manifest doğru dizine mi yerleştirilmiş ve doğru adla mı yer alıyor? Beklenen biçimler için yerel mesajlaşma ana makine konumuna bakın.
  • Manifest dosyası doğru biçimde mi? Özellikle JSON söz dizimi doğru mu ve değerler, yerel mesajlaşma ana makine manifestinin tanımıyla eşleşiyor mu?
  • path politikasında belirtilen dosya var mı? Windows'da yollar göreli olabilir ancak OS X 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 çok yaygın bir hatadır ve yerel mesajlaşma ana makinesinde iletişim protokolünün yanlış bir şekilde uygulandığını gösterir.
  • stdout iç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ız stderr adresine 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_BINARY olarak ayarlandığından emin olun. Varsayılan olarak G/Ç modu O_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 __setmode kullanılarak ayarlanabilir.