नेटिव मैसेज की सुविधा

एक्सटेंशन, नेटिव ऐप्लिकेशन के साथ मैसेज शेयर कर सकते हैं. इसके लिए, वे ऐसे एपीआई का इस्तेमाल करते हैं जो मैसेज पास करने वाले अन्य एपीआई से मिलते-जुलते हैं. इस सुविधा के साथ काम करने वाले नेटिव ऐप्लिकेशन को, नेटिव मैसेजिंग होस्ट रजिस्टर करना होगा. यह होस्ट, एक्सटेंशन के साथ काम कर सकता है. Chrome, होस्ट को एक अलग प्रोसेस में शुरू करता है और स्टैंडर्ड इनपुट और स्टैंडर्ड आउटपुट स्ट्रीम का इस्तेमाल करके उससे संपर्क करता है.

नेटिव मैसेजिंग होस्ट

नेटिव मैसेजिंग होस्ट को रजिस्टर करने के लिए, ऐप्लिकेशन को एक ऐसी फ़ाइल सेव करनी होगी जो नेटिव मैसेजिंग होस्ट के कॉन्फ़िगरेशन के बारे में बताती हो.

फ़ाइल का उदाहरण यहां दिया गया है:

{
  "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/"]
}

नेटिव मैसेजिंग होस्ट मेनिफ़ेस्ट फ़ाइल, मान्य JSON फ़ॉर्मैट में होनी चाहिए. साथ ही, इसमें ये फ़ील्ड शामिल होने चाहिए:

name

नेटिव मैसेजिंग होस्ट का नाम. क्लाइंट इस स्ट्रिंग को runtime.connectNative() या runtime.sendNativeMessage() पर पास करते हैं. इस नाम में सिर्फ़ अक्षर, अंक, अंडरस्कोर, और बिंदु के छोटे अक्षर इस्तेमाल किए जा सकते हैं. नाम की शुरुआत या आखिर में डॉट नहीं हो सकता. साथ ही, डॉट के बाद कोई दूसरा डॉट नहीं हो सकता.

description

ऐप्लिकेशन के बारे में कम शब्दों में जानकारी.

path

नेटिव मैसेजिंग होस्ट बाइनरी का पाथ. Linux और macOS पर, पाथ एब्सोलूट होना चाहिए. Windows पर, यह मेनिफ़ेस्ट फ़ाइल वाली डायरेक्ट्री के हिसाब से हो सकता है. होस्ट प्रोसेस, मौजूदा डायरेक्ट्री से शुरू की जाती है. यह डायरेक्ट्री, होस्ट बाइनरी वाली डायरेक्ट्री पर सेट होती है. उदाहरण के लिए, अगर इस पैरामीटर को C:\Application\nm_host.exe पर सेट किया जाता है, तो इसे मौजूदा डायरेक्ट्री `C:\Application` से शुरू किया जाएगा.

type

नेटिव मैसेजिंग होस्ट से संपर्क करने के लिए इस्तेमाल किए जाने वाले इंटरफ़ेस का टाइप. इस पैरामीटर की एक वैल्यू हो सकती है: stdio. इससे पता चलता है कि Chrome को होस्ट के साथ बातचीत करने के लिए, stdin और stdout का इस्तेमाल करना चाहिए.

allowed_origins

उन एक्सटेंशन की सूची जिनके पास नेटिव मैसेजिंग होस्ट का ऐक्सेस होना चाहिए. allowed-origins वैल्यू में वाइल्डकार्ड नहीं शामिल किए जा सकते.

नेटिव मैसेजिंग होस्ट की जगह

मेनिफ़ेस्ट फ़ाइल की जगह, प्लैटफ़ॉर्म पर निर्भर करती है.

Windows पर, मेनिफ़ेस्ट फ़ाइल फ़ाइल सिस्टम में कहीं भी हो सकती है. ऐप्लिकेशन इंस्टॉलर को HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application या HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\com.my_company.my_application में से कोई एक रजिस्ट्री कुंजी बनानी होगी. साथ ही, उस कुंजी की डिफ़ॉल्ट वैल्यू को मेनिफ़ेस्ट फ़ाइल के पूरे पाथ पर सेट करना होगा. उदाहरण के लिए, इस कमांड का इस्तेमाल करके:

REG ADD "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application" /ve /t REG_SZ /d "C:\path\to\nmh-manifest.json" /f

या यहां दी गई .reg फ़ाइल का इस्तेमाल करके:

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, नेटिव मैसेजिंग होस्ट खोजता है, तो पहले 32-बिट रजिस्ट्री से क्वेरी की जाती है. इसके बाद, 64-बिट रजिस्ट्री से क्वेरी की जाती है.

macOS और Linux पर, नेटिव मैसेजिंग होस्ट की मेनिफ़ेस्ट फ़ाइल की जगह, ब्राउज़र (Google Chrome या Chromium) के हिसाब से अलग-अलग होती है. सिस्टम-वाइड नेटिव मैसेजिंग होस्ट को एक तय जगह पर खोजा जाता है, जबकि उपयोगकर्ता-लेवल के नेटिव मैसेजिंग होस्ट को उपयोगकर्ता प्रोफ़ाइल डायरेक्ट्री की NativeMessagingHosts/ सबडायरेक्ट्री में खोजा जाता है.

macOS (पूरे सिस्टम में)

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 (किसी उपयोगकर्ता के लिए, डिफ़ॉल्ट पाथ)

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 (पूरे सिस्टम में)

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 (उपयोगकर्ता के हिसाब से, डिफ़ॉल्ट पाथ)

Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/com.my_company.my_application.json

Chromium: ~/.config/chromium/NativeMessagingHosts/com.my_company.my_application.json

नेटिव मैसेजिंग प्रोटोकॉल

Chrome, हर नेटिव मैसेजिंग होस्ट को एक अलग प्रोसेस में शुरू करता है और स्टैंडर्ड इनपुट (stdin) और स्टैंडर्ड आउटपुट (stdout) का इस्तेमाल करके उससे संपर्क करता है. दोनों दिशाओं में मैसेज भेजने के लिए, एक ही फ़ॉर्मैट का इस्तेमाल किया जाता है. हर मैसेज को JSON का इस्तेमाल करके सीरियलाइज़ किया जाता है और UTF-8 में एन्कोड किया जाता है. साथ ही, मैसेज के पहले नेटिव बाइट ऑर्डर में 32-बिट मैसेज की लंबाई होती है. नेटिव मैसेजिंग होस्ट से भेजे गए किसी एक मैसेज का साइज़ 1 एमबी से ज़्यादा नहीं होना चाहिए. ऐसा इसलिए किया जाता है, ताकि Chrome को नेटिव ऐप्लिकेशन के गलत इस्तेमाल से बचाया जा सके. नेटिव मैसेजिंग होस्ट को भेजे गए मैसेज का ज़्यादा से ज़्यादा साइज़ 4 जीबी हो सकता है.

नेटिव मैसेजिंग होस्ट का पहला आर्ग्युमेंट, कॉल करने वाले का ऑरिजिन होता है. आम तौर पर, यह chrome-extension://[ID of allowed extension] होता है. इससे नेटिव मैसेजिंग होस्ट, मैसेज के सोर्स की पहचान कर पाते हैं. ऐसा तब होता है, जब नेटिव मैसेजिंग होस्ट मेनिफ़ेस्ट में, allowed_origins कुंजी में एक से ज़्यादा एक्सटेंशन दिए गए हों.

Windows पर, नेटिव मैसेजिंग होस्ट को एक कमांड लाइन आर्ग्युमेंट भी दिया जाता है. इसमें, Chrome की नेटिव विंडो को कॉल करने वाले हैंडल की जानकारी होती है: --parent-window=<decimal handle value>. इससे नेटिव मैसेजिंग होस्ट को ऐसी नेटिव यूआई विंडो बनाने में मदद मिलती है जिन्हें सही तरीके से पैरंट किया गया हो. ध्यान दें कि अगर कॉलिंग कॉन्टेक्स्ट एक सर्विस वर्कर है, तो यह वैल्यू 0 होगी.

runtime.connectNative() का इस्तेमाल करके मैसेजिंग पोर्ट बनाने पर, Chrome नेटिव मैसेजिंग होस्ट प्रोसेस शुरू करता है और उसे तब तक चलाता रहता है, जब तक पोर्ट बंद नहीं हो जाता. दूसरी ओर, जब मैसेज भेजने के लिए runtime.sendNativeMessage() का इस्तेमाल किया जाता है, तो मैसेज पोर्ट बनाए बिना, Chrome हर मैसेज के लिए एक नई नेटिव मैसेजिंग होस्ट प्रोसेस शुरू करता है. ऐसे में, होस्ट प्रोसेस से जनरेट किया गया पहला मैसेज, ओरिजनल अनुरोध के जवाब के तौर पर मैनेज किया जाता है. साथ ही, Chrome इसे runtime.sendNativeMessage() को कॉल करने पर, तय किए गए रिस्पॉन्स कॉलबैक पर भेज देगा. ऐसे में, नेटिव मैसेजिंग होस्ट से जनरेट किए गए अन्य सभी मैसेज को अनदेखा कर दिया जाता है.

स्थानीय ऐप्लिकेशन से कनेक्ट करना

किसी नेटिव ऐप्लिकेशन से मैसेज भेजना और पाना, क्रॉस-एक्सटेंशन मैसेजिंग की तरह ही होता है. मुख्य अंतर यह है कि runtime.connect() के बजाय runtime.connectNative() का इस्तेमाल किया जाता है और runtime.sendMessage() के बजाय runtime.sendNativeMessage() का इस्तेमाल किया जाता है.

इन तरीकों का इस्तेमाल करने के लिए, आपके एक्सटेंशन की मेनिफ़ेस्ट फ़ाइल में "nativeMessaging" अनुमति का एलान किया जाना चाहिए.

ये तरीके कॉन्टेंट स्क्रिप्ट में उपलब्ध नहीं हैं. ये सिर्फ़ आपके एक्सटेंशन के पेजों और सर्विस वर्कर में उपलब्ध हैं. अगर आपको कॉन्टेंट स्क्रिप्ट से नेटिव ऐप्लिकेशन के साथ कम्यूनिकेट करना है, तो अपने सेवा वर्कर को मैसेज भेजें, ताकि वह उसे नेटिव ऐप्लिकेशन को भेज सके.

इस उदाहरण में, एक runtime.Port ऑब्जेक्ट बनाया गया है जो नेटिव मैसेजिंग होस्ट com.my_company.my_application से कनेक्ट है. साथ ही, उस पोर्ट से मैसेज सुनना शुरू करता है और एक आउटगोइंग मैसेज भेजता है:

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 का इस्तेमाल करें. उदाहरण के लिए:

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

नेटिव मैसेजिंग को डीबग करना

नेटिव मैसेजिंग की कुछ गड़बड़ियां होने पर, आउटपुट को Chrome के गड़बड़ी लॉग में लिखा जाता है. इसमें ये स्थितियां शामिल हैं: नेटिव मैसेजिंग होस्ट शुरू नहीं हो पाता, stderr में लिखता है या कम्यूनिकेशन प्रोटोकॉल का उल्लंघन करता है. Linux और macOS पर, इस लॉग को ऐक्सेस करने के लिए, कमांड-लाइन से Chrome शुरू करें और टर्मिनल में उसका आउटपुट देखें. Windows पर, लॉग इन करने का तरीका बताने वाले लेख के मुताबिक --enable-logging का इस्तेमाल करें.

यहां कुछ आम गड़बड़ियां और उन्हें ठीक करने के तरीके बताए गए हैं:

नेटिव मैसेजिंग होस्ट को शुरू नहीं किया जा सका.

देखें कि आपके पास नेटिव मैसेजिंग होस्ट की फ़ाइल को एक्ज़ीक्यूट करने के लिए, ज़रूरी अनुमतियां हैं या नहीं.

नेटिव मैसेजिंग के लिए अमान्य होस्टनेम दिया गया है.

जांच करें कि नाम में अमान्य वर्ण तो नहीं हैं. सिर्फ़ अंग्रेज़ी के छोटे अक्षरों, अंडरस्कोर, और बिंदुओं का ही इस्तेमाल किया जा सकता है. नाम की शुरुआत या आखिर में बिंदु नहीं होना चाहिए. साथ ही, बिंदु के बाद कोई दूसरा बिंदु नहीं होना चाहिए.

नेटिव होस्ट बंद हो गया है.

Chrome के मैसेज पढ़ने से पहले, नेटिव मैसेजिंग होस्ट की पाइप टूट गई थी. ज़्यादातर मामलों में, यह प्रोसेस आपके नेटिव मैसेजिंग होस्ट से शुरू होती है.

बताया गया नेटिव मैसेजिंग होस्ट नहीं मिला.

इनकी जांच करें:

• क्या एक्सटेंशन और मेनिफ़ेस्ट फ़ाइल में नाम सही तरीके से लिखा गया है?
• क्या मेनिफ़ेस्ट सही डायरेक्ट्री में है और उसका नाम सही है? उम्मीद के मुताबिक फ़ॉर्मैट के लिए, नेटिव मैसेजिंग होस्ट की जगह देखें.
• क्या मेनिफ़ेस्ट फ़ाइल का फ़ॉर्मैट सही है? खास तौर पर, क्या JSON मान्य और सही फ़ॉर्मैट में है और क्या वैल्यू, नेटिव मैसेजिंग होस्ट मेनिफ़ेस्ट की परिभाषा से मेल खाती हैं?
• क्या path में दी गई फ़ाइल मौजूद है? Windows पर, पाथ रिलेटिव हो सकते हैं. हालांकि, macOS और Linux पर, पाथ ऐब्सलूट होने चाहिए.

नेटिव मैसेजिंग होस्ट का होस्ट नेम रजिस्टर नहीं किया गया है. (सिर्फ़ Windows के लिए)

Windows रजिस्ट्री में स्थानीय मैसेजिंग होस्ट नहीं मिला. regedit का इस्तेमाल करके दोबारा जांच लें कि कुंजी नेटिव मैसेजिंग होस्ट की जगह पर दिए गए दस्तावेज़ में बताए गए ज़रूरी फ़ॉर्मैट में है या नहीं. साथ ही, यह भी देखें कि कुंजी असल में बनाई गई है या नहीं.

बताए गए नेटिव मैसेजिंग होस्ट का ऐक्सेस नहीं है.

क्या एक्सटेंशन का ऑरिजिन, allowed_origins में शामिल है?

नेटिव मैसेजिंग होस्ट से संपर्क करने में गड़बड़ी हुई.

इससे पता चलता है कि नेटिव मैसेजिंग होस्ट में कम्यूनिकेशन प्रोटोकॉल को गलत तरीके से लागू किया गया है.

• पक्का करें कि stdout के सभी आउटपुट, नेटिव मैसेजिंग प्रोटोकॉल के मुताबिक हों. अगर आपको डीबग करने के लिए कुछ डेटा प्रिंट करना है, तो stderr पर लिखें.
• पक्का करें कि 32-बिट मैसेज की लंबाई, प्लैटफ़ॉर्म के नेटिव इंटिजर फ़ॉर्मैट (लिटल-इंडियन/ बिग-इंडियन) में हो.
• मैसेज की लंबाई 1024*1024 से ज़्यादा नहीं होनी चाहिए.
• मैसेज का साइज़, मैसेज में मौजूद बाइट की संख्या के बराबर होना चाहिए. यह स्ट्रिंग की "लंबाई" से अलग हो सकती है, क्योंकि वर्णों को कई बाइट से दिखाया जा सकता है.
• सिर्फ़ Windows के लिए: पक्का करें कि प्रोग्राम का I/O मोड O_BINARY पर सेट हो. डिफ़ॉल्ट रूप से, I/O मोड O_TEXT होता है. इससे मैसेज का फ़ॉर्मैट खराब हो जाता है, क्योंकि लाइन ब्रेक (\n = 0A) को Windows स्टाइल के लाइन एंडिंग (\r\n = 0D 0A) से बदल दिया जाता है. I/O मोड को __setmode का इस्तेमाल करके सेट किया जा सकता है.