المراسلة الأصلية

يمكن للإضافات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات مشابهة لواجهات برمجة تطبيقات تمرير الرسائل الأخرى. يجب أن تسجِّل التطبيقات الأصلية التي توفِّر هذه الميزة مضيف مراسلة أصلي يمكنه التواصل مع الإضافة. ويبدأ 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.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);
  }
);

تصحيح أخطاء المراسلة الأصلية

وعند حدوث إخفاقات معيّنة في المراسلة الأصلية، تتم كتابة النتائج في سجلّ الأخطاء في Chrome. ويشمل ذلك عندما يتعذّر بدء تشغيل مضيف المراسلة الأصلية أو عندما يكتب رسالة إلى stderr أو ينتهك بروتوكول الاتصال. على نظامَي التشغيل Linux وmacOS، يمكن الوصول إلى هذا السجلّ عن طريق بدء تشغيل Chrome من سطر الأوامر ومشاهدة مخرجاته في الوحدة الطرفية. على نظام التشغيل Windows، استخدِم --enable-logging كما هو موضَّح في كيفية تفعيل تسجيل الدخول.

وإليك بعض الأخطاء الشائعة والنصائح لحلها:

تعذَّر بدء مضيف المراسلة مع التطبيقات الأصلية.

تحقَّق مما إذا كانت لديك أذونات كافية لتنفيذ ملف مضيف المراسلة الأصلية.

تم تحديد اسم مضيف المراسلة الأصلية غير صالح.

تحقَّق مما إذا كان الاسم يحتوي على أحرف غير صالحة. لا يُسمح إلا بالأحرف الأبجدية الرقمية الصغيرة والشرطة السفلية والنقاط. لا يمكن أن يبدأ الاسم أو ينتهي بنقطة، ولا يمكن أن تتبع النقطة نقطة أخرى.

تم الخروج من المضيف الأصلي.

تعطّل الممر المؤدي إلى مضيف المراسلة الأصلي قبل أن يقرأ Chrome الرسالة. ويبدأ هذا على الأرجح من مضيف المراسلة الأصلية.

لم يتم العثور على مضيف المراسلة الأصلية المحدّد.

يُرجى الاطّلاع على الروابط التالية:

• هل تمت كتابة الاسم بشكل صحيح في الإضافة وفي ملف البيان؟
• هل البيان في الدليل الصحيح وبالاسم الصحيح؟ راجِع موقع مضيف المراسلة الأصلي لمعرفة التنسيقات المتوقّعة.
• هل ملف البيان بالتنسيق الصحيح؟ وعلى وجه التحديد، هل JSON صالح ومنسّق بشكل جيد، وهل تتطابق القيم مع تعريف بيان مضيف المراسلة المدمجة مع المحتوى؟
• هل الملف المحدّد في path متوفّر؟ في نظام التشغيل Windows، قد تكون المسارات نسبية، ولكن في نظامي التشغيل macOS وLinux، يجب أن تكون المسارات مطلقة.

لم يتم تسجيل اسم مضيف المراسلة الأصلية. (نظام التشغيل Windows فقط)

لم يتم العثور على مضيف المراسلة الأصلية في سجلّ Windows. تحقّق جيدًا باستخدام regedit ما إذا كان المفتاح قد تم إنشاؤه حقًا ويتطابق مع التنسيق المطلوب كما هو موثَّق في موقع مضيف المراسلة الأصلي.

تم حظر الوصول إلى مضيف المراسلة مع التطبيقات الأصلية المحدّد.

هل مصدر الإضافة مدرَج في 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.