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

يمكن للإضافات والتطبيقات تبادل الرسائل مع التطبيقات الأصلية باستخدام واجهة برمجة تطبيقات تشبه واجهات برمجة تطبيقات تمرير الرسائل الأخرى. يجب أن تسجِّل التطبيقات الأصلية التي تدعم هذه الميزة مضيف المراسلة الأصلي الذي يعرف كيفية الاتصال بالإضافة. يبدأ 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
  • 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
  • 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
  • Linux (المسار التلقائي الخاص بالمستخدم)
    • Google Chrome: ~/.config/google-chrome/NativeMessagingHosts/_com.my_company.my_application_.json
    • كروم: ~/.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 54 والإصدارات الأقدم، تم تمرير المصدر كمَعلمة ثانية. بدلاً من المعلمة الأولى.

عند إنشاء منفذ مراسلة باستخدام 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. ولا يمكن استخدام هذه الطرق إلا إذا كانت طريقة "المراسلة الأصلية" تم الإفصاح عن الإذن في تطبيقك. ملف البيان.

ينشئ المثال التالي كائن 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. ما إذا كان المفتاح قد تم إنشاؤه بالفعل ويطابق التنسيق المطلوب كما هو موثق على الموقع الجغرافي لمضيف المراسلة.
  • تم حظر الدخول إلى مضيف المراسلة مع التطبيقات الأصلية المحدّد.
    • هل مصدر الإضافة مُدرَج في allowed_origins؟
  • حدث خطأ أثناء الاتصال بمضيف المراسلة مع التطبيقات الأصلية.
    • هذا خطأ شائع جدًا ويشير إلى تنفيذ غير صحيح لبروتوكول الاتصال في مضيف المراسلة مع التطبيقات الأصلية.
    • تأكَّد من أنّ جميع النتائج في stdout تلتزم ببروتوكول المراسلة الأصلي. إذا أردت لطباعة بعض البيانات لأغراض تصحيح الأخطاء، أرسِلها إلى stderr.
    • احرص على أن يكون عدد الرسائل ذات 32 بت بتنسيق العدد الصحيح الأصلي للنظام الأساسي (الحد الأدنى لطول الرسالة). / كبيرة).
    • يجب ألا يتجاوز طول الرسالة 1024*1024.
    • يجب أن يكون حجم الرسالة مساويًا لعدد وحدات البايت في الرسالة. قد يختلف هذا عن "الطول" السلسلة، لأن الأحرف يمكن تمثيلها بواسطة وحدات بايت متعددة.
    • نظام التشغيل Windows فقط: تأكَّد من ضبط وضع الإدخال/الإخراج في البرنامج على O_BINARY. بشكل تلقائي، يبثّ مؤتمر I/O الوضع هو O_TEXT، ويؤدي ذلك إلى تلف تنسيق الرسالة عند استبدال فواصل الأسطر (\n = 0A) بـ نهايات الأسطر بنمط Windows (\r\n = 0D 0A) يمكن ضبط وضع I/O باستخدام __setmode.