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

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

الاتصال بتطبيق أصلي

ويشبه إرسال الرسائل واستلامها من تطبيق محلي إلى حد كبير المراسلة عبر الإضافات. والفرق الرئيسي بينهما هو أنّه يتم استخدام runtime.connectNative() بدلاً من runtime.connect()، ويتم استخدام runtime.sendNativeMessage() بدلاً من runtime.sendMessage().

لاستخدام هذه الطرق، يجب الإفصاح عن الإذن nativeMessaging في ملف بيان الإضافات.

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

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