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

يمكن للإضافات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات مشابهة لواجهات برمجة التطبيقات الأخرى لنقل الرسائل. يجب أن تسجّل التطبيقات الأصلية التي تتوافق مع هذه الميزة مضيف تبادل معلومات مع التطبيقات المثبّتة على نظام التشغيل يمكنه التواصل مع الإضافة. يبدأ 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 من التطبيقات الأصلية التي لا تعمل بشكل سليم. يبلغ الحد الأقصى لحجم الرسالة المُرسَلة إلى مضيف الرسائل الأصلية 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.