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

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

الموقع الجغرافي لمضيف المراسلة الأصلي

يعتمد موقع ملف البيان على النظام الأساسي.

في 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 والإصدار 54 من Chrome والإصدارات الأقدم، تم تمرير المصدر كمَعلمة ثانية بدلاً من المَعلمة الأولى.

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

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

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

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

• تعذَّر بدء مضيف المراسلة مع التطبيقات الأصلية.
  • تحقَّق مما إذا كانت لديك أذونات كافية لتنفيذ الملف.
• تم تحديد اسم غير صالح لمضيف المراسلة مع التطبيقات الأصلية.
  • تحقَّق مما إذا كان الاسم يحتوي على أي أحرف غير صالحة. لا يُسمح إلا بالأحرف الأبجدية الرقمية الصغيرة والشرطة السفلية والنقاط. لا يمكن أن يبدأ الاسم أو ينتهي بنقطة، ولا يمكن أن تتبع النقطة نقطة أخرى.
• تم الخروج من المضيف الأصلي.
  • تعطّل الممر المؤدي إلى مضيف المراسلة الأصلي قبل أن يقرأ Chrome الرسالة. ويبدأ هذا على الأرجح من مضيف المراسلة الأصلية.
• لم يتم العثور على مضيف المراسلة الأصلية المحدّد.
  • هل تمت كتابة الاسم بشكل صحيح في الإضافة وفي ملف البيان؟
  • هل تم وضع البيان في الدليل الصحيح وبالاسم الصحيح؟ راجِع موقع مضيف المراسلة الأصلي لمعرفة التنسيقات المتوقّعة.
  • هل ملف البيان بالتنسيق الصحيح؟ على وجه التحديد، هل بنية JSON صحيحة وهل تتطابق القيم مع تعريف بيان مضيف المراسلة المدمجة مع المحتوى؟
  • هل الملف المحدّد في path متوفّر؟ في نظامي التشغيل Windows، قد تكون المسارات نسبية، ولكن في نظامي التشغيل OS X و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.