يمكن للإضافات والتطبيقات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات مشابهة لواجهات برمجة تطبيقات تمرير الرسائل الأخرى. يجب أن تسجِّل التطبيقات الأصلية التي توفِّر هذه الميزة مضيف مراسلة أصلي يعرف كيفية التواصل مع الإضافة. ويبدأ 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 وOSX، يجب أن يكون المسار مطلقًا. في نظام التشغيل Windows، يمكن أن تكون مرتبطة بالدليل الذي يوجد فيه ملف البيان. تبدأ عملية المضيف مع تعيين الدليل الحالي على الدليل الذي يحتوي على البرنامج الثنائي للمضيف. على سبيل المثال، إذا تم ضبط هذه المَعلمة على C:\Application\nm_host.exe ، سيتم البدء باستخدام الدليل الحالي C:\Application\ . |
type | نوع الواجهة المستخدمة للتواصل مع مضيف المراسلة الأصلية. في الوقت الحالي، هناك قيمة واحدة محتملة لهذه المَعلمة: stdio . يشير هذا الرمز إلى أنّ Chrome يجب أن يستخدم stdin وstdout للتواصل مع المضيف. |
allowed_origins | قائمة بالإضافات التي يمكنها الوصول إلى مضيف المراسلة مع التطبيقات الأصلية. لا يُسمح باستخدام أحرف البدل، مثل chrome-extension://*/* . |
الموقع الجغرافي لمضيف المراسلة الأصلي
يعتمد موقع ملف البيان على النظام الأساسي.
في 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 بت.
في نظامي التشغيل OS X وLinux، يختلف موقع ملف البيان لمضيف المراسلة الأصلي حسب المتصفح (Google Chrome أو Chromium). ويتم البحث عن مضيفي الرسائل الأصلية على مستوى النظام في موقع ثابت، بينما يتم البحث عن مضيفي الرسائل الأصلية على مستوى المستخدم في دليل فرعي ضمن دليل الملف الشخصي للمستخدم يُسمى NativeMessagingHosts
.
- OS X (على مستوى النظام)
- Google Chrome:
/Library/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- كروم:
/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
- OS X (المسار التلقائي الخاص بالمستخدم)
- Google Chrome:
~/Library/Application Support/Google/Chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- كروم:
~/Library/Application Support/Chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
- Linux (على مستوى النظام)
- Google Chrome:
/etc/opt/chrome/native-messaging-hosts/_com.my_company.my_application_.json
- كروم:
/etc/chromium/native-messaging-hosts/_com.my_company.my_application_.json
- Google Chrome:
- Linux (المسار الخاص بالمستخدم، المسار التلقائي)
- Google Chrome:
~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
- كروم:
~/.config/chromium/NativeMessagingHosts/_com.my_company.my_application_.json
- Google Chrome:
بروتوكول المراسلة الأصلي
ويبدأ Chrome كل مضيف للمراسلة الأصلية في عملية منفصلة، ويتواصل معه باستخدام الإدخال العادي (stdin
) والمخرجات العادية (stdout
). ويتم استخدام التنسيق نفسه لإرسال الرسائل في كلا الاتجاهين، حيث يتم تسلسل كل رسالة باستخدام JSON بترميز UTF-8 ومسبوقة بطول رسالة 32 بت بترتيب البايت الأصلي. ويبلغ الحد الأقصى لحجم الرسالة الواحدة من مضيف المراسلة الأصلي 1 ميغابايت، وذلك لحماية Chrome بشكل أساسي من حدوث خلل في أداء التطبيقات الأصلية. ويبلغ الحدّ الأقصى لحجم
الرسالة المُرسَلة إلى مضيف المراسلة الأصلية 4 غيغابايت.
إنّ الوسيطة الأولى لمضيف المراسلة الأصلية هي أصل المتصل، وعادةً ما يكون
chrome-extension://[ID of allowed extension]
. ويسمح ذلك لمضيفي الرسائل الأصلية بتحديد مصدر الرسالة عند تحديد إضافات متعدّدة في مفتاح allowed_origins
ضمن بيان مضيف المراسلة الأصلية.
تحذير: في نظام التشغيل Windows والإصدار 54 من Chrome والإصدارات الأقدم، تم تمرير المصدر كمَعلمة ثانية بدلاً من المَعلمة الأولى.
عند إنشاء منفذ مراسلة باستخدام runtime.connectNative، يبدأ Chrome عملية مضيف المراسلة الأصلية ويحافظ على تشغيلها حتى يتم تدمير المنفذ. ومن ناحية أخرى، عند إرسال رسالة باستخدام runtime.sendNativeMessage، بدون إنشاء منفذ مراسلة، يبدأ Chrome عملية مضيف مراسلة جديدة لكل رسالة. في هذه الحالة، يتم التعامل مع الرسالة الأولى التي تنشئها عملية المضيف كاستجابة للطلب الأصلي، أي أنّ Chrome سيمرّرها إلى معاودة الاتصال بالاستجابة التي يتم تحديدها عند استدعاء runtime.sendNativeMessage. ويتم في هذه الحالة تجاهل جميع الرسائل الأخرى التي أنشأها مضيف المراسلة الأصلية.
على نظام التشغيل Windows، يتم أيضًا تمرير وسيطة سطر أوامر مع مقبض إلى نافذة Chrome الأصلية التي تُسمى --parent-window=<decimal handle value>
. يتيح ذلك لمضيف المراسلة الأصلي إنشاء نوافذ واجهة مستخدم أصلية يتم تنظيمها بشكلٍ صحيح. تجدر الإشارة إلى أنّ هذه القيمة ستكون 0
إذا كان سياق الاستدعاء عبارة عن صفحة نص برمجي في الخلفية.
الاتصال بتطبيق محلي
يشبه إرسال الرسائل واستلامها من تطبيق أصلي وإلى إرسال رسائل الإضافات المتبادلة إلى حدٍ كبير. يكمن الاختلاف الرئيسي في استخدام runtime.connectNative بدلاً من runtime.connect،واستخدام runtime.sendNativeMessage بدلاً من runtime.sendMessage. ولا يمكن استخدام هذه الطرق إلا إذا تم الإعلان عن إذن "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);
});
تصحيح أخطاء المراسلة الأصلية
عندما يتعذّر بدء تشغيل مضيف المراسلة الأصلية أو يكتب إلى stderr
أو عند انتهاك بروتوكول الاتصال، تتم كتابة النتائج في سجلّ الأخطاء في Chrome. في نظامي التشغيل Linux وOS X، يمكن الوصول بسهولة إلى هذا السجلّ
عن طريق بدء تشغيل Chrome من سطر الأوامر ومشاهدة مخرجاته في
المحطة الطرفية. على نظام التشغيل Windows، استخدِم --enable-logging
كما هو موضَّح في كيفية تفعيل تسجيل الدخول.
إليك بعض الأخطاء والنصائح لحل المشكلات:
- تعذَّر بدء مضيف المراسلة مع التطبيقات الأصلية.
- تحقَّق مما إذا كانت لديك أذونات كافية لتنفيذ الملف.
- تم تحديد اسم غير صالح لمضيف المراسلة مع التطبيقات الأصلية.
- تحقَّق مما إذا كان الاسم يحتوي على أي أحرف غير صالحة. لا يُسمح إلا بالأحرف الأبجدية الرقمية الصغيرة والشرطة السفلية والنقاط. لا يمكن أن يبدأ الاسم أو ينتهي بنقطة، ولا يمكن أن تتبع النقطة نقطة أخرى.
- تم الخروج من المضيف الأصلي.
- تعطّل الممر المؤدي إلى مضيف المراسلة الأصلي قبل أن يقرأ Chrome الرسالة. ويبدأ هذا على الأرجح من مضيف المراسلة الأصلية.
- لم يتم العثور على مضيف المراسلة الأصلية المحدّد.
- هل تمت كتابة الاسم بشكل صحيح في الإضافة وفي ملف البيان؟
- هل تم وضع البيان في الدليل الصحيح وبالاسم الصحيح؟ راجِع موقع مضيف المراسلة الأصلي لمعرفة التنسيقات المتوقّعة.
- هل ملف البيان بالتنسيق الصحيح؟ على وجه التحديد، هل بنية JSON صحيحة وهل تتطابق القيم مع تعريف بيان مضيف المراسلة المدمجة مع المحتوى؟
- هل الملف المحدّد في
path
متوفّر؟ في نظامي التشغيل Windows، قد تكون المسارات نسبية، ولكن في نظامي التشغيل OS X وLinux، يجب أن تكون المسارات مطلقة.
- لم يتم تسجيل اسم مضيف مضيف المراسلة الأصلية. (نظام التشغيل Windows فقط)
- لم يتم العثور على مضيف المراسلة الأصلية في سجلّ Windows. تحقّق جيدًا باستخدام
regedit
ما إذا كان المفتاح قد تم إنشاؤه حقًا ويتطابق مع التنسيق المطلوب كما هو موثَّق في موقع مضيف المراسلة الأصلي.
- لم يتم العثور على مضيف المراسلة الأصلية في سجلّ Windows. تحقّق جيدًا باستخدام
- تم حظر الوصول إلى مضيف المراسلة الأصلية المحدّد.
- هل مصدر الإضافة مدرَج في
allowed_origins
؟
- هل مصدر الإضافة مدرَج في
- حدث خطأ عند الاتصال بمضيف المراسلة مع التطبيقات الأصلية.
- هذا خطأ شائع جدًا ويشير إلى تنفيذ غير صحيح لبروتوكول الاتصال في مضيف المراسلة الأصلية.
- تأكَّد من أنّ جميع المخرجات في
stdout
تتوافق مع بروتوكول المراسلة الأصلي. إذا كنت تريد طباعة بعض البيانات لأغراض تصحيح الأخطاء، اكتب إلىstderr
. - احرص على أن يكون طول الرسالة 32 بت بتنسيق العدد الصحيح الأصلي للنظام الأساسي (Little-endian / big-endian).
- يجب ألا يتجاوز طول الرسالة 1024*1024.
- يجب أن يكون حجم الرسالة مساويًا لعدد وحدات البايت في الرسالة. وقد يختلف هذا عن "طول" السلسلة، لأنه قد يتم تمثيل الأحرف بعدة وحدات بايت.
- نظام التشغيل Windows فقط: تأكَّد من ضبط وضع I/O للبرنامج على
O_BINARY
. يكون وضع الإدخال والإخراج هوO_TEXT
تلقائيًا، ما يؤدي إلى تلف تنسيق الرسالة عند استبدال فواصل الأسطر (\n
=0A
) بنهايات الأسطر في نمط Windows (\r\n
=0D 0A
). ويمكن ضبط وضع الإدخال والإخراج باستخدام__setmode
.