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

يمكن للإضافات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات مشابهة لواجهات برمجة التطبيقات الأخرى لنقل الرسائل. يجب أن تسجّل التطبيقات الأصلية التي تتوافق مع هذه الميزة مضيف المراسلة مع التطبيقات الأصلية يمكنه التواصل مع الإضافة. يبدأ 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 أو Google Chrome for Testing أو Chromium). يتم البحث عن مضيفي المراسلة الأصلية على مستوى النظام في موقع ثابت، بينما يتم البحث عن مضيفي المراسلة الأصلية على مستوى المستخدم في الدليل الفرعي NativeMessagingHosts/ ضمن دليل ملف المستخدم الشخصي.

‫macOS (على مستوى النظام): Google Chrome: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json; Google Chrome for Testing: /Library/Google/ChromeForTesting/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; Google Chrome for Testing: ~/Library/Application Support/Google/ChromeForTesting/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; Google Chrome for Testing: /etc/opt/chrome_for_testing/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; Google Chrome for Testing: ~/.config/google-chrome-for-testing/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 من التطبيقات الأصلية التي لا تعمل بشكل سليم. يبلغ الحد الأقصى لحجم الرسالة المُرسَلة إلى مضيف المراسلة مع التطبيقات الأصلية 64 ميغابايت.

الوسيطة الأولى لمضيف المراسلة مع التطبيقات الأصلية هي مصدر المتصل، وعادةً ما تكون 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 فقط: تأكَّد من ضبط وضع الإدخال/الإخراج للبرنامج على O_BINARY. يكون وضع الإدخال/الإخراج تلقائيًا O_TEXT، ما يؤدي إلى تلف تنسيق الرسالة لأنّه يتم استبدال فواصل الأسطر (\n = 0A) بنهايات أسطر بنمط Windows (\r\n = 0D 0A). يمكن ضبط وضع الإدخال/الإخراج باستخدام __setmode.