Node-API

[مستقر: 2 - مستقر]

مستقر: 2 الاستقرار: 2 - مستقر

Node-API (سابقا N-API) هي واجهة برمجة تطبيقات لبناء الوظائف الإضافية الأصلية. إنها مستقلة عن بيئة تشغيل JavaScript الأساسية (مثل V8) ويتم صيانتها كجزء من Node.js نفسها. ستكون هذه الواجهة مستقرة على مستوى واجهة التطبيقات الثنائية (ABI) عبر إصدارات Node.js. يهدف إلى عزل الوظائف الإضافية عن التغييرات في محرك JavaScript الأساسي والسماح بتشغيل الوحدات المُجمعة لإصدار رئيسي واحد على إصدارات رئيسية لاحقة من Node.js بدون إعادة تجميع. يوفر دليل استقرار ABI شرحًا أكثر عمقًا.

يتم بناء/تعبئة الوظائف الإضافية بنفس النهج/الأدوات الموضحة في القسم المعنون الوظائف الإضافية C++. والفرق الوحيد هو مجموعة واجهات برمجة التطبيقات التي يستخدمها الكود الأصلي. بدلاً من استخدام واجهات برمجة التطبيقات V8 أو الواجهات المجردة الأصلية لـ Node.js، يتم استخدام الوظائف المتاحة في Node-API.

تُستخدم واجهات برمجة التطبيقات التي تعرضها Node-API بشكل عام لإنشاء قيم JavaScript والتلاعب بها. عادةً ما تُرسم المفاهيم والعمليات إلى الأفكار المحددة في مواصفات لغة ECMA-262. تتميز واجهات برمجة التطبيقات بالخصائص التالية:

• جميع مكالمات Node-API تُرجع رمز حالة من نوع napi_status. تشير هذه الحالة إلى نجاح أو فشل مكالمة واجهة برمجة التطبيقات.
• يتم تمرير قيمة الإرجاع لواجهة برمجة التطبيقات عبر معلمة إخراج.
• يتم تجريد جميع قيم JavaScript خلف نوع معتم يُسمى napi_value.
• في حالة رمز حالة خطأ، يمكن الحصول على معلومات إضافية باستخدام napi_get_last_error_info. يمكن العثور على مزيد من المعلومات في قسم معالجة الأخطاء معالجة الأخطاء.

Node-API هي واجهة برمجة تطبيقات C تضمن استقرار ABI عبر إصدارات Node.js ومستويات المُجمع المختلفة. قد تكون واجهة برمجة تطبيقات C++ أسهل في الاستخدام. لدعم استخدام C++، يقوم المشروع بصيانة وحدة مُغلف C++ تسمى node-addon-api. يوفر هذا المُغلف واجهة برمجة تطبيقات C++ قابلة للدمج المباشر. ستعتمد الملفات الثنائية المُبنية باستخدام node-addon-api على رموز وظائف Node-API القائمة على C التي تصدرها Node.js. node-addon-api هي طريقة أكثر كفاءة لكتابة الكود الذي يستدعي Node-API. خذ على سبيل المثال، كود node-addon-api التالي. يُظهر القسم الأول كود node-addon-api ويُظهر القسم الثاني ما يُستخدم بالفعل في الوظيفة الإضافية.

Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");

napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

النتيجة النهائية هي أن الوظيفة الإضافية تستخدم فقط واجهات برمجة التطبيقات C المصدرة. نتيجة لذلك، لا تزال تحصل على فوائد استقرار ABI التي توفرها واجهة برمجة التطبيقات C.

عند استخدام node-addon-api بدلاً من واجهات برمجة التطبيقات C، ابدأ بـ المستندات الخاصة بواجهة برمجة التطبيقات لـ node-addon-api.

يقدم مورد Node-API توجيهًا ممتازًا ونصائح للمطورين الذين يبدأون للتو باستخدام Node-API و node-addon-api. يمكن العثور على موارد وسائط إضافية على صفحة وسائط Node-API.

آثار استقرار واجهة برمجة التطبيقات الثنائية (ABI)

على الرغم من أن Node-API توفر ضمانًا لاستقرار واجهة برمجة التطبيقات الثنائية (ABI)، إلا أن أجزاء أخرى من Node.js لا توفر هذا الضمان، وقد لا توفره المكتبات الخارجية المستخدمة من الإضافة. على وجه الخصوص، لا توفر أي من واجهات برمجة التطبيقات التالية ضمانًا لاستقرار واجهة برمجة التطبيقات الثنائية (ABI) عبر الإصدارات الرئيسية:

• واجهات برمجة التطبيقات C++ الخاصة بـ Node.js المتاحة عبر أي من
• واجهات برمجة التطبيقات libuv التي يتم تضمينها أيضًا مع Node.js والمتاحة عبر
• واجهة برمجة التطبيقات V8 المتاحة عبر

وبالتالي، لكي تظل الإضافة متوافقة مع واجهة برمجة التطبيقات الثنائية (ABI) عبر إصدارات Node.js الرئيسية، يجب أن تستخدم Node-API حصريًا عن طريق تقييد نفسها باستخدام

#include <node_api.h>

وبالتحقق، بالنسبة لجميع المكتبات الخارجية التي تستخدمها، من أن المكتبة الخارجية تقدم ضمانات لاستقرار واجهة برمجة التطبيقات الثنائية (ABI) مشابهة لـ Node-API.

عملية البناء

على عكس الوحدات المكتوبة بلغة JavaScript، فإن تطوير ونشر إضافات Node.js الأصلية باستخدام Node-API يتطلب مجموعة إضافية من الأدوات. بالإضافة إلى الأدوات الأساسية المطلوبة للتطوير لـ Node.js، يحتاج مطور الإضافة الأصلية إلى سلسلة أدوات يمكنها تجميع رمز C و C++ في ملف ثنائي. بالإضافة إلى ذلك، بناءً على كيفية نشر الإضافة الأصلية، سيحتاج مستخدم الإضافة الأصلية أيضًا إلى تثبيت سلسلة أدوات C/C++.

بالنسبة لمطوري Linux، تتوفر حزم سلسلة أدوات C/C++ اللازمة بسهولة. GCC يستخدم على نطاق واسع في مجتمع Node.js لبناء واختبار عبر مجموعة متنوعة من المنصات. بالنسبة للعديد من المطورين، تعد بنية مُجمِّع LLVM خيارًا جيدًا أيضًا.

بالنسبة لمطوري Mac، يوفر Xcode جميع أدوات المُجمِّع المطلوبة. ومع ذلك، ليس من الضروري تثبيت بيئة تطوير متكاملة Xcode بالكامل. يقوم الأمر التالي بتثبيت سلسلة الأدوات اللازمة:

xcode-select --install

بالنسبة لمطوري Windows، يوفر Visual Studio جميع أدوات المُجمِّع المطلوبة. ومع ذلك، ليس من الضروري تثبيت بيئة تطوير متكاملة Visual Studio بالكامل. يقوم الأمر التالي بتثبيت سلسلة الأدوات اللازمة:

npm install --global windows-build-tools

تُصف الأجزاء أدناه الأدوات الإضافية المتاحة لتطوير ونشر إضافات Node.js الأصلية.

أدوات البناء

تتطلب كلتا الأداتين المذكورتين هنا أن يكون لدى مستخدمي الوحدة الإضافية الأصلية مجموعة أدوات C/C++ مثبتة لنجاح تثبيت الوحدة الإضافية الأصلية.

node-gyp

node-gyp هو نظام بناء قائم على فرع gyp-next من أداة GYP من جوجل، ويأتي مُضمّناً مع npm. يتطلب GYP، وبالتالي node-gyp، تثبيت Python.

تاريخياً، كانت node-gyp هي أداة الاختيار لبناء الوحدات الإضافية الأصلية. تتمتع باعتماد واسع النطاق ووثائق جيدة. ومع ذلك، واجه بعض المطورين قيودًا في node-gyp.

CMake.js

CMake.js هو نظام بناء بديل قائم على CMake.

يُعد CMake.js خيارًا جيدًا للمشاريع التي تستخدم CMake بالفعل أو للمطورين المتأثرين بالقيود في node-gyp. build_with_cmake هو مثال على مشروع وحدة إضافية أصلية قائم على CMake.

تحميل الملفات الثنائية المترجمة مسبقاً

تسمح الأدوات الثلاث المذكورة هنا لمطوري وصانعي الوحدات الإضافية الأصلية بإنشاء الملفات الثنائية وتحميلها إلى خوادم عامة أو خاصة. عادةً ما يتم دمج هذه الأدوات مع أنظمة بناء CI/CD مثل Travis CI و AppVeyor لبناء وتحميل الملفات الثنائية لمجموعة متنوعة من المنصات والعمارات. تتوفر هذه الملفات الثنائية بعد ذلك للتنزيل من قبل المستخدمين الذين لا يحتاجون إلى تثبيت مجموعة أدوات C/C++.

node-pre-gyp

node-pre-gyp هي أداة قائمة على node-gyp تضيف القدرة على تحميل الملفات الثنائية إلى خادم يختاره المطور. تتمتع node-pre-gyp بدعم جيد بشكل خاص لتحميل الملفات الثنائية إلى Amazon S3.

prebuild

prebuild هي أداة تدعم عمليات البناء باستخدام node-gyp أو CMake.js. على عكس node-pre-gyp التي تدعم مجموعة متنوعة من الخوادم، يقوم prebuild بتحميل الملفات الثنائية فقط إلى إصدارات GitHub. يُعد prebuild خيارًا جيدًا لمشاريع GitHub التي تستخدم CMake.js.

prebuildify

prebuildify أداة تعتمد على node-gyp. تكمن ميزة prebuildify في أن الملفات الثنائية المُبنية تُضمّن مع إضافة native عند رفعها إلى npm. يتم تنزيل الملفات الثنائية من npm وتكون متاحة على الفور لمستخدم الوحدة النمطية عند تثبيت إضافة native.

الاستخدام

من أجل استخدام دوال Node-API، قم بتضمين الملف node_api.h الموجود في دليل src في شجرة تطوير node:

#include <node_api.h>

سيؤدي هذا إلى اختيار إصدار NAPI_VERSION الافتراضي لإصدار Node.js المعطى. لضمان التوافق مع إصدارات محددة من Node-API، يمكن تحديد الإصدار صراحةً عند تضمين الرأس:

#define NAPI_VERSION 3
#include <node_api.h>

يُقيّد هذا سطح Node-API فقط بالوظائف المتاحة في الإصدارات المحددة (والإصدارات السابقة).

بعض أجزاء سطح Node-API تجريبي ويتطلب اشتراكًا صريحًا:

#define NAPI_EXPERIMENTAL
#include <node_api.h>

في هذه الحالة، سيكون سطح API بأكمله، بما في ذلك أي واجهات برمجة تطبيقات تجريبية، متاحًا لرمز الوحدة النمطية.

في بعض الأحيان، يتم تقديم ميزات تجريبية تؤثر على واجهات برمجة التطبيقات المستقرة والصادرة بالفعل. يمكن تعطيل هذه الميزات عن طريق إلغاء الاشتراك:

#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>

حيث أن <FEATURE_NAME> هو اسم ميزة تجريبية تؤثر على واجهات برمجة التطبيقات التجريبية والمستقرة.

مصفوفة إصدار Node-API

حتى الإصدار 9، كانت إصدارات Node-API تراكمية ومرقمة بشكل مستقل عن Node.js. وهذا يعني أن أي إصدار كان امتدادًا للإصدار السابق من حيث أنه كان يحتوي على جميع واجهات برمجة التطبيقات من الإصدار السابق مع بعض الإضافات. كل إصدار من Node.js يدعم إصدار Node-API واحد فقط. على سبيل المثال، يدعم الإصدار v18.15.0 إصدار Node-API 8 فقط. تم تحقيق ثبات ABI لأن 8 كانت مجموعة فرعية صارمة لجميع الإصدارات السابقة.

اعتبارًا من الإصدار 9، بينما تستمر إصدارات Node-API في الترقيم بشكل مستقل، فإن الإضافة التي تعمل مع إصدار Node-API 9 قد تحتاج إلى تحديثات في الكود للتشغيل مع إصدار Node-API 10. ومع ذلك، يتم الحفاظ على ثبات ABI، لأن إصدارات Node.js التي تدعم إصدارات Node-API أعلى من 8 ستدعم جميع الإصدارات بين 8 وأعلى إصدار تدعمه، وستقوم افتراضيًا بتوفير واجهات برمجة التطبيقات من الإصدار 8 ما لم تختار إضافة ما إصدارًا أعلى من Node-API. يوفر هذا النهج مرونة أفضل في تحسين وظائف Node-API الحالية مع الحفاظ على ثبات ABI. يمكن للإضافات الحالية الاستمرار في التشغيل دون إعادة التجميع باستخدام إصدار سابق من Node-API. إذا احتاجت إضافة ما إلى وظائف من إصدار أحدث من Node-API، فستكون هناك حاجة إلى إجراء تغييرات على الكود الحالي وإعادة التجميع لاستخدام هذه الوظائف الجديدة على أي حال.

في إصدارات Node.js التي تدعم إصدار Node-API 9 وما بعده، فإن تعريف NAPI_VERSION=X واستخدام وحدات الماكرو الحالية لتهيئة الإضافة سيُدمج إصدار Node-API المطلوب الذي سيتم استخدامه في وقت التشغيل في الإضافة. إذا لم يتم تعيين NAPI_VERSION، فسيكون الافتراضي 8.

قد لا يكون هذا الجدول محدثًا في التدفقات القديمة، وأحدث المعلومات متوفرة في أحدث وثائق API في: مصفوفة إصدار Node-API

إصدار Node-API	مدعوم في
9	v18.17.0+، 20.3.0+، 21.0.0 وجميع الإصدارات الأحدث
8	v12.22.0+، v14.17.0+، v15.12.0+، 16.0.0 وجميع الإصدارات الأحدث
7	v10.23.0+، v12.19.0+، v14.12.0+، 15.0.0 وجميع الإصدارات الأحدث
6	v10.20.0+، v12.17.0+، 14.0.0 وجميع الإصدارات الأحدث
5	v10.17.0+، v12.11.0+، 13.0.0 وجميع الإصدارات الأحدث
4	v10.16.0+، v11.8.0+، 12.0.0 وجميع الإصدارات الأحدث
3	v6.14.2*، 8.11.2+، v9.11.0+*، 10.0.0 وجميع الإصدارات الأحدث
2	v8.10.0+، v9.3.0+، 10.0.0 وجميع الإصدارات الأحدث
1	v8.6.0*، v9.0.0+، 10.0.0 وجميع الإصدارات الأحدث

• كان Node-API تجريبيًا.

** تضمن Node.js 8.0.0 Node-API كتجربة. تم إصداره كإصدار Node-API 1 ولكنه استمر في التطور حتى Node.js 8.6.0. تختلف واجهة برمجة التطبيقات في الإصدارات السابقة لـ Node.js 8.6.0. نوصي باستخدام إصدار Node-API 3 أو أحدث.

كل واجهة برمجة تطبيقات موثقة لـ Node-API ستحتوي على رأس باسم added in:، وستحتوي واجهات برمجة التطبيقات المستقرة على رأس إضافي Node-API version:. يمكن استخدام واجهات برمجة التطبيقات مباشرة عند استخدام إصدار Node.js الذي يدعم إصدار Node-API الموضح في Node-API version: أو أعلى. عند استخدام إصدار Node.js لا يدعم Node-API version: المدرج أو إذا لم يكن هناك Node-API version: مدرجًا، فسيكون API متاحًا فقط إذا سبق تضمين node_api.h أو js_native_api.h عبارة #define NAPI_EXPERIMENTAL. إذا بدا أن API غير متاح في إصدار من Node.js أحدث من الإصدار الموضح في added in:، فهذا هو على الأرجح سبب الغياب الظاهري.

يمكن العثور على واجهات برمجة تطبيقات Node-API المرتبطة بشكل صارم بالوصول إلى ميزات ECMAScript من التعليمات البرمجية الأصلية بشكل منفصل في js_native_api.h و js_native_api_types.h. يتم تضمين واجهات برمجة التطبيقات المعرّفة في هذه الرؤوس في node_api.h و node_api_types.h. تم هيكلة الرؤوس بهذه الطريقة للسماح بتنفيذ Node-API خارج Node.js. بالنسبة لتلك التنفيذات، قد لا تكون واجهات برمجة تطبيقات Node.js محددة قابلة للتطبيق.

يمكن فصل الأجزاء الخاصة بـ Node.js من الإضافة عن الكود الذي يعرض الوظائف الفعلية لبيئة JavaScript بحيث يمكن استخدام الأخير مع تنفيذات متعددة لـ Node-API. في المثال أدناه، يشير addon.c و addon.h فقط إلى js_native_api.h. هذا يضمن إمكانية إعادة استخدام addon.c ليتم تجميعه ضد تنفيذ Node.js لـ Node-API أو أي تنفيذ لـ Node-API خارج Node.js.

addon_node.c هو ملف منفصل يحتوي على نقطة دخول Node.js الخاصة بالإضافة والتي تقوم بإنشاء مثيل للإضافة من خلال الاتصال بـ addon.c عند تحميل الإضافة في بيئة Node.js.

// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif  // _ADDON_H_

// addon.c
#include "addon.h"

#define NODE_API_CALL(env, call)                                  \
  do {                                                            \
    napi_status status = (call);                                  \
    if (status != napi_ok) {                                      \
      const napi_extended_error_info* error_info = NULL;          \
      napi_get_last_error_info((env), &error_info);               \
      const char* err_message = error_info->error_message;        \
      bool is_pending;                                            \
      napi_is_exception_pending((env), &is_pending);              \
      /* If an exception is already pending, don't rethrow it */  \
      if (!is_pending) {                                          \
        const char* message = (err_message == NULL)               \
            ? "empty error message"                               \
            : err_message;                                        \
        napi_throw_error((env), NULL, message);                   \
      }                                                           \
      return NULL;                                                \
    }                                                             \
  } while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
  // Do something useful.
  return NULL;
}

napi_value create_addon(napi_env env) {
  napi_value result;
  NODE_API_CALL(env, napi_create_object(env, &result));

  napi_value exported_function;
  NODE_API_CALL(env, napi_create_function(env,
                                          "doSomethingUseful",
                                          NAPI_AUTO_LENGTH,
                                          DoSomethingUseful,
                                          NULL,
                                          &exported_function));

  NODE_API_CALL(env, napi_set_named_property(env,
                                             result,
                                             "doSomethingUseful",
                                             exported_function));

  return result;
}

// addon_node.c
#include <node_api.h>
#include "addon.h"

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  // This function body is expected to return a `napi_value`.
  // The variables `napi_env env` and `napi_value exports` may be used within
  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
  return create_addon(env);
}

واجهات برمجة تطبيقات دورة حياة البيئة

يُعرّف القسم 8.7 من مواصفات لغة ECMAScript مفهوم "الوكيل" كبيئة مستقلة تعمل فيها شفرة JavaScript. يمكن بدء وإنهاء العديد من هذه الوكلاء بشكل متزامن أو تسلسلي بواسطة العملية.

تتوافق بيئة Node.js مع وكيل ECMAScript. في العملية الرئيسية، يتم إنشاء بيئة عند بدء التشغيل، ويمكن إنشاء بيئات إضافية على مؤشرات ترابط منفصلة لتكون بمثابة مؤشرات ترابط عامل. عندما يتم تضمين Node.js في تطبيق آخر، قد يقوم مؤشر الترابط الرئيسي للتطبيق أيضًا ببناء وتدمير بيئة Node.js عدة مرات خلال دورة حياة عملية التطبيق بحيث يمكن لكل بيئة Node.js التي أنشأها التطبيق، بدورها، خلال دورة حياتها إنشاء وتدمير بيئات إضافية كخيوط عاملة.

من منظور إضافة أصلية، هذا يعني أن الربطات التي توفرها يمكن استدعاؤها عدة مرات، من سياقات متعددة، وحتى بشكل متزامن من مؤشرات ترابط متعددة.

قد تحتاج الإضافات الأصلية إلى تخصيص حالة عالمية تستخدمها خلال دورة حياة بيئة Node.js بحيث يمكن أن تكون الحالة فريدة لكل مثيل للإضافة.

تحقيقًا لهذه الغاية، توفر Node-API طريقة لربط البيانات بحيث تكون دورة حياتها مرتبطة بدورة حياة بيئة Node.js.

napi_set_instance_data

مضاف في: v12.8.0، v10.20.0

إصدار N-API: 6

napi_status napi_set_instance_data(node_api_basic_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint);

• [in] env: البيئة التي يتم استدعاء مكالمة Node-API بموجبها.
• [in] data: عنصر البيانات الذي يتوفر للروابط الخاصة بهذا المثال.
• [in] finalize_cb: الدالة التي سيتم استدعاؤها عند تفكيك البيئة. تتلقى الدالة data بحيث يمكنها تحريرها. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_hint: تلميح اختياري لإرساله إلى وظيفة الإنهاء أثناء التجميع.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تربط هذه واجهة برمجة التطبيقات data ببيئة Node.js قيد التشغيل حاليًا. يمكن استرداد data لاحقًا باستخدام napi_get_instance_data(). سيتم الكتابة فوق أي بيانات موجودة مرتبطة ببيئة Node.js قيد التشغيل حاليًا والتي تم تعيينها بواسطة مكالمة سابقة إلى napi_set_instance_data(). إذا تم توفير finalize_cb بواسطة المكالمة السابقة، فلن يتم استدعاؤها.

napi_get_instance_data

أضيف في: v12.8.0، v10.20.0

إصدار N-API: 6

napi_status napi_get_instance_data(node_api_basic_env env,
                                   void** data);

• [in] env: بيئة استدعاء مُدعمة Node-API.
• [out] data: عنصر البيانات الذي تم ربطه سابقًا ببيئة Node.js قيد التشغيل حاليًا بواسطة مكالمة إلى napi_set_instance_data().

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسترد هذه واجهة برمجة التطبيقات البيانات التي تم ربطها سابقًا ببيئة Node.js قيد التشغيل حاليًا عبر napi_set_instance_data(). إذا لم يتم تعيين أي بيانات، فستنجح المكالمة وسيتم تعيين data على NULL.

أنواع بيانات Node-API الأساسية

يعرض Node-API أنواع البيانات الأساسية التالية كملخصات تستهلكها واجهات برمجة التطبيقات المختلفة. يجب التعامل مع هذه واجهات برمجة التطبيقات على أنها معتمة، قابلة للتفتيش فقط باستخدام مكالمات Node-API الأخرى.

napi_status

أضيف في: v8.0.0

إصدار N-API: 1

رمز الحالة التكاملية الذي يشير إلى نجاح أو فشل مكالمة Node-API. حاليًا، يتم دعم رموز الحالة التالية.

typedef enum {
  napi_ok,
  napi_invalid_arg,
  napi_object_expected,
  napi_string_expected,
  napi_name_expected,
  napi_function_expected,
  napi_number_expected,
  napi_boolean_expected,
  napi_array_expected,
  napi_generic_failure,
  napi_pending_exception,
  napi_cancelled,
  napi_escape_called_twice,
  napi_handle_scope_mismatch,
  napi_callback_scope_mismatch,
  napi_queue_full,
  napi_closing,
  napi_bigint_expected,
  napi_date_expected,
  napi_arraybuffer_expected,
  napi_detachable_arraybuffer_expected,
  napi_would_deadlock,  /* unused */
  napi_no_external_buffers_allowed,
  napi_cannot_run_js
} napi_status;

إذا كانت هناك حاجة إلى معلومات إضافية عند إرجاع واجهة برمجة التطبيقات حالة فاشلة، فيمكن الحصول عليها عن طريق الاتصال بـ napi_get_last_error_info.

napi_extended_error_info

أضيف في: v8.0.0

إصدار N-API: 1

typedef struct {
  const char* error_message;
  void* engine_reserved;
  uint32_t engine_error_code;
  napi_status error_code;
} napi_extended_error_info;

• error_message: سلسلة مُشفّرة بـ UTF8 تحتوي على وصف محايد للآلة الظاهرية للخطأ.
• engine_reserved: مُخصص لتفاصيل الخطأ الخاصة بالآلة الظاهرية. لم يتم تنفيذ هذا حاليًا لأي آلة ظاهرية.
• engine_error_code: رمز خطأ خاص بالآلة الظاهرية. لم يتم تنفيذ هذا حاليًا لأي آلة ظاهرية.
• error_code: رمز حالة Node-API الذي نشأ مع آخر خطأ.

راجع قسم معالجة الأخطاء للحصول على معلومات إضافية.

napi_env

يستخدم napi_env لتمثيل سياق يمكن لتنفيذ Node-API الأساسي استخدامه للاحتفاظ بحالة خاصة بـ VM. يتم تمرير هذا الهيكل إلى الدوال الأصلية عند استدعاؤها، ويجب إعادة تمريره عند إجراء مكالمات Node-API. على وجه التحديد، يجب تمرير نفس napi_env الذي تم تمريره عند استدعاء الدالة الأصلية الأولية إلى أي مكالمات Node-API متداخلة لاحقة. لا يُسمح بتخزين napi_env لغرض إعادة الاستخدام العام، ولا بتمرير napi_env بين مثيلات نفس الوحدة الإضافية التي تعمل على خيوط Worker مختلفة. يصبح napi_env غير صالح عند إلغاء تحميل مثيل لوحدة إضافية أصلية. يتم تسليم إشعار بهذا الحدث من خلال الاستدعاءات العكسية المعطاة إلى napi_add_env_cleanup_hook و napi_set_instance_data.

node_api_basic_env

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

يتم تمرير هذا المتغير من napi_env إلى المُنهيات المتزامنة (node_api_basic_finalize). هناك مجموعة فرعية من Node-APIs التي تقبل معلمة من نوع node_api_basic_env كحجة أولى لها. لا تصل هذه واجهات برمجة التطبيقات إلى حالة محرك JavaScript وبالتالي فهي آمنة للاستدعاء من المُنهيات المتزامنة. يُسمح بتمرير معلمة من نوع napi_env إلى هذه واجهات برمجة التطبيقات، ومع ذلك، لا يُسمح بتمرير معلمة من نوع node_api_basic_env إلى واجهات برمجة التطبيقات التي تصل إلى حالة محرك JavaScript. سيؤدي محاولة القيام بذلك بدون عملية بث إلى إنشاء تحذير من المُجمع أو خطأ عند تجميع الوحدات الإضافية باستخدام علامات تجعلها تُصدر تحذيرات و/أو أخطاء عند تمرير أنواع مؤشرات غير صحيحة إلى دالة. سيؤدي استدعاء مثل هذه واجهات برمجة التطبيقات من مُنهي متزامن في النهاية إلى إنهاء التطبيق.

napi_value

هذا مؤشر معتم يُستخدم لتمثيل قيمة JavaScript.

napi_threadsafe_function

مُضاف في: v10.6.0

إصدار N-API: 4

هذا مُشير مُعتم يُمثّل دالة JavaScript والتي يُمكن استدعاؤها بشكل غير متزامن من خيوط متعددة عبر napi_call_threadsafe_function().

napi_threadsafe_function_release_mode

مُضاف في: v10.6.0

إصدار N-API: 4

قيمة تُعطى إلى napi_release_threadsafe_function() للإشارة إلى ما إذا كان يجب إغلاق الدالة الآمنة للخيوط على الفور (napi_tsfn_abort) أم مجرد إطلاقها (napi_tsfn_release) وبالتالي تكون متاحة للاستخدام اللاحق عبر napi_acquire_threadsafe_function() و napi_call_threadsafe_function().

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

napi_threadsafe_function_call_mode

مُضاف في: v10.6.0

إصدار N-API: 4

قيمة تُعطى إلى napi_call_threadsafe_function() للإشارة إلى ما إذا كان يجب حجب الاستدعاء عندما تكون قائمة الانتظار المرتبطة بالدالة الآمنة للخيوط ممتلئة.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

أنواع إدارة ذاكرة Node-API

napi_handle_scope

هذا تجريد يُستخدم للتحكم في وتعديل عمر الكائنات المُنشأة ضمن نطاق مُحدد. بشكل عام، تُنشأ قيم Node-API ضمن سياق نطاق المُعالجة. عندما يُستدعى أسلوب أصلي من JavaScript، سيوجد نطاق مُعالجة افتراضي. إذا لم يُنشئ المستخدم نطاق مُعالجة جديدًا صراحةً، فستُنشأ قيم Node-API في نطاق المُعالجة الافتراضي. لأي استدعاءات للرمز خارج تنفيذ أسلوب أصلي (على سبيل المثال، أثناء استدعاء مُنعكس libuv)، يجب على الوحدة إنشاء نطاق قبل استدعاء أي دالات قد تؤدي إلى إنشاء قيم JavaScript.

تُنشأ نطاقات المُعالجة باستخدام napi_open_handle_scope وتُدمر باستخدام napi_close_handle_scope. يمكن لإغلاق النطاق أن يُشير إلى جامع القمامة أن جميع قيم napi_value المُنشأة أثناء عمر نطاق المُعالجة لم تعد مُشار إليها من إطار المُكدس الحالي.

لمزيد من التفاصيل، راجع إدارة عمر الكائن.

napi_escapable_handle_scope

تم الإضافة في: v8.0.0

إصدار N-API: 1

تُعد نطاقات المقابض القابلة للهروب نوعًا خاصًا من نطاقات المقابض لإرجاع القيم المُنشأة داخل نطاق مُعَيّن للمقابض إلى نطاق أعلى.

napi_ref

تم الإضافة في: v8.0.0

إصدار N-API: 1

هذا هو التجريد المُستخدم للإشارة إلى napi_value. يسمح هذا للمستخدمين بإدارة أعمار قيم JavaScript، بما في ذلك تحديد أعمارهم الدنيا صراحةً.

للمزيد من التفاصيل، راجع إدارة عمر الكائن.

napi_type_tag

تم الإضافة في: v14.8.0، v12.19.0

إصدار N-API: 8

قيمة 128 بت مخزنة كرقمين صحيحين بدون إشارة 64 بت. تعمل كـ UUID يمكن من خلاله "وسم" كائنات JavaScript أو العناصر الخارجية لضمان أنها من نوع معين. هذا التحقق أقوى من napi_instanceof، لأن الأخير يمكن أن يُبلغ عن إيجابية خاطئة إذا تم التلاعب بنموذج الكائن. يكون وضع العلامات حسب النوع مفيدًا للغاية بالاقتران مع napi_wrap لأنه يضمن إمكانية الإرسال الآمن للمُشير المُسترد من كائن مُغلف إلى النوع الأصلي المُقابل لعلامة النوع التي تم تطبيقها مسبقًا على كائن JavaScript.

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;

napi_async_cleanup_hook_handle

تم الإضافة في: v14.10.0، v12.19.0

قيمة غير شفافة تُرجعها napi_add_async_cleanup_hook. يجب تمريرها إلى napi_remove_async_cleanup_hook عند اكتمال سلسلة أحداث التنظيف غير المتزامنة.

أنواع استدعاءات Node-API

napi_callback_info

تم الإضافة في: v8.0.0

إصدار N-API: 1

نوع بيانات غير شفاف يتم تمريره إلى دالة الاستدعاء. يمكن استخدامه للحصول على معلومات إضافية حول السياق الذي تم فيه استدعاء دالة الاستدعاء.

napi_callback

تم الإضافة في: v8.0.0

إصدار N-API: 1

نوع مؤشر الدالة للدوال الأصلية المُقدمة من قِبل المستخدم والتي سيتم عرضها على JavaScript عبر Node-API. يجب أن تلبي دوال الاستدعاء التوقيع التالي:

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);

إلا لأسباب مُناقشة في إدارة عمر الكائن، فإن إنشاء مقبض و/أو نطاق استدعاء داخل napi_callback ليس ضروريًا.

node_api_basic_finalize

تم الإضافة في: v21.6.0، v20.12.0، v18.20.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

نوع مؤشر دالة لإضافات الوظائف التي تسمح للمستخدم أن يتم إعلامه عندما تكون البيانات المملوكة خارجيًا جاهزة للتنظيف لأن الكائن الذي تم ربطه به قد تم جمعه بواسطة "جاربج كوليكتور". يجب على المستخدم توفير دالة تلبي التوقيع التالي والذي سيتم استدعاؤه عند جمع الكائن. حاليًا، يمكن استخدام node_api_basic_finalize للعثور على وقت جمع الكائنات التي تحتوي على بيانات خارجية.

typedef void (*node_api_basic_finalize)(node_api_basic_env env,
                                      void* finalize_data,
                                      void* finalize_hint);

إلا لأسباب تمت مناقشتها في إدارة عمر الكائن، ليس من الضروري إنشاء مقياس معالجة و/أو استدعاء داخل جسم الدالة.

بما أن هذه الوظائف قد يتم استدعاؤها بينما تكون محرّك جافا سكريبت في حالة لا يمكنها فيها تنفيذ شفرة جافا سكريبت، فيمكن فقط استدعاء واجهات برمجة التطبيقات Node التي تقبل node_api_basic_env كمعاملها الأول. يمكن استخدام node_api_post_finalizer لجدولة مكالمات واجهة برمجة التطبيقات Node التي تتطلب الوصول إلى حالة محرّك جافا سكريبت لتشغيلها بعد اكتمال دورة جمع القمامة الحالية.

في حالة node_api_create_external_string_latin1 و node_api_create_external_string_utf16 ، قد تكون معلمة env فارغة، لأن السلاسل الخارجية يمكن جمعها خلال الجزء الأخير من إيقاف تشغيل البيئة.

سجل التغييرات:

• تجريبي (NAPI_EXPERIMENTAL): يمكن فقط استدعاء مكالمات واجهة برمجة التطبيقات Node التي تقبل node_api_basic_env كمعاملها الأول، وإلا فسيتم إنهاء التطبيق برسالة خطأ مناسبة. يمكن إيقاف تشغيل هذه الميزة عن طريق تعريف NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_finalize

أضيف في: v8.0.0

إصدار N-API: 1

نوع مؤشر دالة لإضافة وظيفة مقدمة من الإضافة تسمح للمستخدم بجدولة مجموعة من المكالمات إلى Node-APIs استجابةً لحدث جمع البيانات المهملة، بعد اكتمال دورة جمع البيانات المهملة. يمكن استخدام مؤشرات الدالة هذه مع node_api_post_finalizer.

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint);

سجل التغييرات:

• تجريبي (NAPI_EXPERIMENTAL مُعرّف): لم يعد من الممكن استخدام دالة من هذا النوع كعامل نهائي، إلا مع node_api_post_finalizer. يجب استخدام node_api_basic_finalize بدلاً من ذلك. يمكن إيقاف تشغيل هذه الميزة عن طريق تعريف NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_async_execute_callback

أضيف في: v8.0.0

إصدار N-API: 1

مؤشر دالة مستخدم مع الدوال التي تدعم العمليات غير المتزامنة. يجب أن تلبي دوال الاستدعاء مرة أخرى التوقيع التالي:

typedef void (*napi_async_execute_callback)(napi_env env, void* data);

يجب على تنفيذات هذه الدالة تجنب إجراء مكالمات Node-API التي تنفذ JavaScript أو تتفاعل مع كائنات JavaScript. يجب أن تكون مكالمات Node-API في napi_async_complete_callback بدلاً من ذلك. لا تستخدم معامل napi_env لأنه من المرجح أن يؤدي ذلك إلى تنفيذ JavaScript.

napi_async_complete_callback

أضيف في: v8.0.0

إصدار N-API: 1

مؤشر دالة مستخدم مع الدوال التي تدعم العمليات غير المتزامنة. يجب أن تلبي دوال الاستدعاء مرة أخرى التوقيع التالي:

typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data);

إلا لأسباب تمت مناقشتها في إدارة عمر الكائن، ليس من الضروري إنشاء مقبض و/أو نطاق استدعاء مرة أخرى داخل جسم الدالة.

napi_threadsafe_function_call_js

تم الإضافة في: v10.6.0

إصدار N-API: 4

مؤشر دالة مستخدم مع عمليات استدعاء الدوال الآمنة للخيوط بشكل غير متزامن. سيتم استدعاء دالة المُراجعة على الخيط الرئيسي. هدفها هو استخدام عنصر بيانات يصل عبر قائمة الانتظار من أحد الخيوط الثانوية لإنشاء المعلمات اللازمة لإجراء استدعاء إلى JavaScript، عادةً عبر napi_call_function، ثم إجراء الاستدعاء إلى JavaScript.

يتم تقديم البيانات الواردة من الخيط الثانوي عبر قائمة الانتظار في معامل data، ويتم تقديم دالة JavaScript التي سيتم استدعاءها في معامل js_callback.

تقوم Node-API بإعداد البيئة قبل استدعاء دالة المُراجعة هذه، لذلك يكفي استدعاء دالة JavaScript عبر napi_call_function بدلاً من napi_make_callback.

يجب أن تلبي دوال المُراجعة التوقيع التالي:

typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data);

• [in] env: البيئة المُستخدمة لاستدعاءات واجهة برمجة التطبيقات، أو NULL إذا كان يتم تفكيك الدالة الآمنة للخيوط وقد تحتاج إلى تحرير data.
• [in] js_callback: دالة JavaScript التي سيتم استدعاءها، أو NULL إذا كان يتم تفكيك الدالة الآمنة للخيوط وقد تحتاج إلى تحرير data. قد تكون أيضًا NULL إذا تم إنشاء الدالة الآمنة للخيوط بدون js_callback.
• [in] context: البيانات الاختيارية التي تم إنشاء الدالة الآمنة للخيوط بها.
• [in] data: البيانات التي أنشأها الخيط الثانوي. تقع على عاتق دالة المُراجعة مسؤولية تحويل هذه البيانات الأصلية إلى قيم JavaScript (باستخدام دوال Node-API) التي يمكن تمريرها كمعلمات عند استدعاء js_callback. يتم إدارة هذا المؤشر بالكامل بواسطة الخيوط ودالة المُراجعة هذه. وبالتالي، يجب أن تقوم دالة المُراجعة هذه بتحرير البيانات.

إلا لأسباب مُناقشة في إدارة عمر الكائن، ليس من الضروري إنشاء مقبض و/أو نطاق مُراجعة داخل جسم الدالة.

napi_cleanup_hook

أضيف في: v19.2.0، v18.13.0

إصدار N-API: 3

مؤشر دالة يُستخدم مع napi_add_env_cleanup_hook. سيتم استدعاؤه عند تفكيك البيئة.

يجب أن تلبي دوال المُراجعة التوقيع التالي:

typedef void (*napi_cleanup_hook)(void* data);

• [in] data: البيانات التي تم تمريرها إلى napi_add_env_cleanup_hook.

napi_async_cleanup_hook

أضيف في: v14.10.0، v12.19.0

مؤشر دالة يُستخدم مع napi_add_async_cleanup_hook. سيتم استدعاؤه عند تفكيك البيئة.

يجب أن تلبي دوال المُراجعة التوقيع التالي:

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data);

• [in] handle: المقبض الذي يجب تمريره إلى napi_remove_async_cleanup_hook بعد اكتمال التنظيف غير المتزامن.
• [in] data: البيانات التي تم تمريرها إلى napi_add_async_cleanup_hook.

يجب أن يبدأ جسم الدالة إجراءات التنظيف غير المتزامنة في نهايتها يجب تمرير handle في دعوة إلى napi_remove_async_cleanup_hook.

معالجة الأخطاء

تستخدم Node-API كل من قيم الإرجاع واستثناءات JavaScript لمعالجة الأخطاء. تشرح الأقسام التالية النهج لكل حالة.

قيم الإرجاع

تشارك جميع دوال Node-API نمط معالجة الأخطاء نفسه. نوع الإرجاع لجميع دوال واجهة برمجة التطبيقات هو napi_status.

ستكون قيمة الإرجاع napi_ok إذا نجح الطلب ولم يتم طرح أي استثناء JavaScript غير معالج. إذا حدث خطأ وتم طرح استثناء، فسيتم إرجاع قيمة napi_status للخطأ. إذا تم طرح استثناء ولم يحدث خطأ، فسيتم إرجاع napi_pending_exception.

في الحالات التي يتم فيها إرجاع قيمة إرجاع بخلاف napi_ok أو napi_pending_exception، يجب استدعاء napi_is_exception_pending للتحقق مما إذا كان هناك استثناء معلق. راجع قسم الاستثناءات لمزيد من التفاصيل.

المجموعة الكاملة لقيم napi_status الممكنة مُعرّفة في napi_api_types.h.

توفر قيمة الإرجاع napi_status تمثيلًا مستقلًا عن VM للخطأ الذي حدث. في بعض الحالات، يكون من المفيد الحصول على معلومات أكثر تفصيلًا، بما في ذلك سلسلة تمثل الخطأ بالإضافة إلى معلومات محددة بـ VM (المحرك).

من أجل استرداد هذه المعلومات، يتم توفير napi_get_last_error_info الذي يُرجع بنية napi_extended_error_info. تنسيق بنية napi_extended_error_info هو كما يلي:

أضيف في: v8.0.0

إصدار N-API: 1

typedef struct napi_extended_error_info {
  const char* error_message;
  void* engine_reserved;
  uint32_t engine_error_code;
  napi_status error_code;
};

• error_message: تمثيل نصي للخطأ الذي حدث.
• engine_reserved: مقبض معتم مُخصص للاستخدام الخاص بالمحرك فقط.
• engine_error_code: رمز خطأ محدد بـ VM.
• error_code: رمز حالة Node-API للخطأ الأخير.

يُرجع napi_get_last_error_info المعلومات الخاصة بأحدث مكالمة Node-API التي تم إجراؤها.

لا تعتمد على محتوى أو تنسيق أي من المعلومات الموسعة لأنها ليست خاضعة لـ SemVer وقد تتغير في أي وقت. إنها مخصصة لأغراض التسجيل فقط.

napi_get_last_error_info

مضاف في: v8.0.0

نسخة N-API: 1

napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: بنية napi_extended_error_info التي تحتوي على مزيد من المعلومات حول الخطأ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات باسترداد بنية napi_extended_error_info مع معلومات حول آخر خطأ حدث.

يُعد محتوى napi_extended_error_info المُرجَع صالحًا فقط حتى يتم استدعاء دالة Node-API على نفس env. يتضمن ذلك استدعاء napi_is_exception_pending، لذلك قد يكون من الضروري في كثير من الأحيان عمل نسخة من المعلومات لاستخدامها لاحقًا. يشير المؤشر المُرجَع في error_message إلى سلسلة مُعرّفة ثابتًا، لذلك من الآمن استخدام هذا المؤشر إذا قمت بنسخه من حقل error_message (الذي سيتم الكتابة فوقه) قبل استدعاء دالة Node-API أخرى.

لا تعتمد على محتوى أو تنسيق أي من المعلومات الموسعة لأنها غير خاضعة لـ SemVer وقد تتغير في أي وقت. إنها مخصصة لأغراض التسجيل فقط.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء JavaScript معلق.

الاستثناءات

قد يؤدي أي استدعاء لدالة Node-API إلى استثناء JavaScript معلق. هذا هو الحال بالنسبة لأي من دوال واجهة برمجة التطبيقات، حتى تلك التي قد لا تسبب تنفيذ JavaScript.

إذا كانت napi_status التي تُرجَع بواسطة دالة هي napi_ok، فلا يوجد استثناء معلق ولا يلزم أي إجراء إضافي. إذا كانت napi_status المُرجعة أي شيء آخر غير napi_ok أو napi_pending_exception، من أجل محاولة الاسترداد والاستمرار بدلاً من العودة على الفور، يجب استدعاء napi_is_exception_pending لتحديد ما إذا كان هناك استثناء معلق أم لا.

في كثير من الحالات، عندما يتم استدعاء دالة Node-API ويوجد استثناء معلق بالفعل، ستعود الدالة على الفور مع napi_status من napi_pending_exception. ومع ذلك، هذا ليس هو الحال بالنسبة لجميع الدوال. تسمح Node-API لمجموعة فرعية من الدوال بالاستدعاء للسماح ببعض التنظيف الأدنى قبل العودة إلى JavaScript. في هذه الحالة، ستعكس napi_status حالة الدالة. لن تعكس الاستثناءات المعلقة السابقة. لتجنب الارتباك، تحقق من حالة الخطأ بعد كل استدعاء للدالة.

عندما يكون هناك استثناء معلق، يمكن استخدام أحد نهجين.

النهج الأول هو القيام بأي تنظيف مناسب ثم العودة بحيث يعود التنفيذ إلى JavaScript. كجزء من الانتقال مرة أخرى إلى JavaScript، سيتم طرح الاستثناء في تلك النقطة من رمز JavaScript حيث تم استدعاء الأسلوب الأصلي. سلوك معظم استدعاءات Node-API غير محدد بينما يكون هناك استثناء معلق، والعديد منها ببساطة سيُعيد napi_pending_exception، لذا افعل أقل ما يمكن ثم عد إلى JavaScript حيث يمكن التعامل مع الاستثناء.

النهج الثاني هو محاولة التعامل مع الاستثناء. ستكون هناك حالات حيث يمكن للرمز الأصلي التقاط الاستثناء، واتخاذ الإجراء المناسب، ثم المتابعة. يُنصح بهذا فقط في حالات محددة حيث يُعرف أنه يمكن التعامل مع الاستثناء بأمان. في هذه الحالات، يمكن استخدام napi_get_and_clear_last_exception للحصول على الاستثناء ومسحه. عند النجاح، ستحتوي النتيجة على مقبض إلى آخر كائن JavaScript Object تم طرحه. إذا تم تحديده، بعد استرداد الاستثناء، لا يمكن التعامل مع الاستثناء على الإطلاق، يمكن إعادة طرحه باستخدام napi_throw حيث يكون الخطأ هو قيمة JavaScript التي سيتم طرحها.

تتوفر أيضًا دوال المرافق التالية في حالة احتياج الرمز الأصلي إلى طرح استثناء أو تحديد ما إذا كان napi_value مثيلًا لكائن JavaScript Error أم لا: napi_throw_error، napi_throw_type_error، napi_throw_range_error، node_api_throw_syntax_error و napi_is_error.

تتوفر أيضًا دوال المرافق التالية في حالة احتياج الرمز الأصلي إلى إنشاء كائن Error: napi_create_error، napi_create_type_error، napi_create_range_error و node_api_create_syntax_error، حيث تكون النتيجة هي napi_value التي تشير إلى كائن JavaScript Error المُنشأ حديثًا.

يضيف مشروع Node.js رموز أخطاء إلى جميع الأخطاء التي تم إنشاؤها داخليًا. الهدف هو أن تستخدم التطبيقات رموز الأخطاء هذه لجميع عمليات فحص الأخطاء. ستظل رسائل الخطأ المرتبطة موجودة، ولكنها ستكون مخصصة فقط للاستخدام في التسجيل والعرض مع توقع أن الرسالة يمكن أن تتغير دون تطبيق SemVer. لدعم هذا النموذج مع Node-API، سواء في الوظائف الداخلية أو لوظائف محددة بالوحدة (كما هو الحال في الممارسات الجيدة)، تأخذ دوال throw_ و create_ معلمة رمز اختيارية وهي السلسلة لرمز المراد إضافته إلى كائن الخطأ. إذا كانت المعلمة الاختيارية هي NULL، فلن يتم ربط أي رمز بالخطأ. إذا تم توفير رمز، فسيتم تحديث الاسم المرتبط بالخطأ ليصبح:

originalName [code]

حيث originalName هو الاسم الأصلي المرتبط بالخطأ و code هو الرمز الذي تم توفيره. على سبيل المثال، إذا كان الرمز هو 'ERR_ERROR_1' ويتم إنشاء TypeError، فسيكون الاسم:

TypeError [ERR_ERROR_1]

napi_throw

تم الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] error: قيمة JavaScript التي سيتم رميها.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات برمي قيمة JavaScript المُقدمة.

napi_throw_error

تم الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: رمز خطأ اختياري ليتم تعيينه على الخطأ.
• [in] msg: سلسلة C تمثل النص الذي سيتم ربطه بالخطأ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات برمي خطأ JavaScript Error مع النص المُقدم.

napi_throw_type_error

تم الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: رمز خطأ اختياري ليتم تعيينه على الخطأ.
• [in] msg: سلسلة C تمثل النص الذي سيتم ربطه بالخطأ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات برمي خطأ JavaScript TypeError مع النص المُقدم.

napi_throw_range_error

تم الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: رمز خطأ اختياري ليتم تعيينه على الخطأ.
• [in] msg: سلسلة C تمثل النص الذي سيتم ربطه بالخطأ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات برمي خطأ JavaScript RangeError مع النص المُقدم.

node_api_throw_syntax_error

أضيف في: v17.2.0، v16.14.0

إصدار N-API: 9

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: رمز الخطأ الاختياري الذي سيتم تعيينه على الخطأ.
• [in] msg: سلسلة C تمثل النص الذي سيتم ربطه بالخطأ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإلقاء SyntaxError في جافا سكريبت مع النص المُقدم.

napi_is_error

أضيف في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة napi_value التي سيتم التحقق منها.
• [out] result: قيمة منطقية يتم تعيينها على true إذا كانت napi_value تمثل خطأ، و false بخلاف ذلك.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تستعلم هذه واجهة برمجة التطبيقات عن napi_value للتحقق مما إذا كانت تمثل كائن خطأ.

napi_create_error

أضيف في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: napi_value اختياري مع سلسلة لرمز الخطأ الذي سيتم ربطه بالخطأ.
• [in] msg: napi_value تشير إلى سلسلة جافا سكريبت لاستخدامها كرسالة لـ Error.
• [out] result: napi_value يمثل الخطأ الذي تم إنشاؤه.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات Error في جافا سكريبت مع النص المُقدم.

napi_create_type_error

أضيف في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
                                               napi_value code,
                                               napi_value msg,
                                               napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] code: napi_value اختياري مع سلسلة لرمز الخطأ الذي سيتم ربطه بالخطأ.
• [in] msg: napi_value تشير إلى سلسلة جافا سكريبت لاستخدامها كرسالة لـ Error.
• [out] result: napi_value يمثل الخطأ الذي تم إنشاؤه.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات TypeError في جافا سكريبت مع النص المُقدم.

napi_create_range_error

تم الإضافة في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                napi_value msg,
                                                napi_value* result);

• [in] env: بيئة تنفيذ واجهة برمجة التطبيقات.
• [in] code: napi_value اختياري يحتوي على سلسلة نصية لرمز الخطأ المرتبط بالخطأ.
• [in] msg: napi_value يشير إلى سلسلة نصية JavaScript تُستخدم كرسالة للخطأ.
• [out] result: napi_value يمثل الخطأ الذي تم إنشاؤه.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات خطأ JavaScript RangeError مع النص المُقدم.

node_api_create_syntax_error

تم الإضافة في: v17.2.0، v16.14.0

نسخة N-API: 9

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result);

• [in] env: بيئة تنفيذ واجهة برمجة التطبيقات.
• [in] code: napi_value اختياري يحتوي على سلسلة نصية لرمز الخطأ المرتبط بالخطأ.
• [in] msg: napi_value يشير إلى سلسلة نصية JavaScript تُستخدم كرسالة للخطأ.
• [out] result: napi_value يمثل الخطأ الذي تم إنشاؤه.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات خطأ JavaScript SyntaxError مع النص المُقدم.

napi_get_and_clear_last_exception

تم الإضافة في: v8.0.0

نسخة N-API: 1

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result);

• [in] env: بيئة تنفيذ واجهة برمجة التطبيقات.
• [out] result: الاستثناء إذا كان هناك استثناء معلق، NULL خلاف ذلك.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء JavaScript معلق.

napi_is_exception_pending

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_is_exception_pending(napi_env env, bool* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: قيمة منطقية تُعيّن على true إذا كان هناك استثناء معلق.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء JavaScript معلق.

napi_fatal_exception

تم الإضافة في: v9.10.0

إصدار N-API: 3

napi_status napi_fatal_exception(napi_env env, napi_value err);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] err: الخطأ الذي يتم تمريره إلى 'uncaughtException'.

تشغيل 'uncaughtException' في JavaScript. مفيد إذا ألقى مُستدعى غير متزامن استثناءً بدون وسيلة للتعافي.

الأخطاء القاتلة

في حالة حدوث خطأ لا يمكن استعادته في إضافة أصلية، يمكن إلقاء خطأ قاتل لإنهاء العملية على الفور.

napi_fatal_error

تم الإضافة في: v8.2.0

إصدار N-API: 1

NAPI_NO_RETURN void napi_fatal_error(const char* location,
                                     size_t location_len,
                                     const char* message,
                                     size_t message_len);

• [in] location: الموقع الاختياري الذي حدث فيه الخطأ.
• [in] location_len: طول الموقع بالبايت، أو NAPI_AUTO_LENGTH إذا كان مُنهيًا بـ null.
• [in] message: الرسالة المرتبطة بالخطأ.
• [in] message_len: طول الرسالة بالبايت، أو NAPI_AUTO_LENGTH إذا كان مُنهيًا بـ null.

لا تُرجع مُكالمة الدالة، سيتم إنهاء العملية.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء JavaScript معلق.

إدارة عمر الكائن

عند إجراء مكالمات Node-API، قد يتم إرجاع مقابض لكائنات في الكومة لـ VM الأساسية كـ napi_values. يجب أن تُبقي هذه المقابض الكائنات "حية" حتى لم تعد مطلوبة بواسطة التعليمات البرمجية الأصلية، وإلا فقد يتم جمع الكائنات قبل انتهاء التعليمات البرمجية الأصلية من استخدامها.

عند إرجاع مقابض الكائنات، يتم ربطها بـ "نطاق". ترتبط فترة حياة النطاق الافتراضي بفترة حياة مكالمة الأسلوب الأصلية. والنتيجة هي أنه، بشكل افتراضي، تظل المقابض صالحة وستُحفظ الكائنات المرتبطة بهذه المقابض حية لفترة حياة مكالمة الأسلوب الأصلية.

ولكن، في العديد من الحالات، من الضروري أن تظل المقابض صالحة لفترة حياة أقصر أو أطول من فترة حياة الأسلوب الأصلي. تصف الأقسام التالية دوال Node-API التي يمكن استخدامها لتغيير عمر المقبض من الافتراضي.

جعل عمر المقبض أقصر من عمر الأسلوب الأصلي

غالبًا ما يكون من الضروري جعل عمر المقابض أقصر من عمر الأسلوب الأصلي. على سبيل المثال، ضع في اعتبارك أسلوبًا أصليًا يحتوي على حلقة تتكرر عبر العناصر في مصفوفة كبيرة:

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // القيام بشيء ما مع العنصر
}

سيتسبب هذا في إنشاء عدد كبير من المقابض، مما يستهلك موارد كبيرة. بالإضافة إلى ذلك، على الرغم من أن التعليمات البرمجية الأصلية لا يمكنها استخدام سوى المقبض الأخير، إلا أن جميع الكائنات المرتبطة ستبقى على قيد الحياة أيضًا لأنها جميعًا تشترك في نفس النطاق.

للتعامل مع هذه الحالة، توفر Node-API القدرة على إنشاء "نطاق" جديد سيتم ربط المقابض التي تم إنشاؤها حديثًا به. بمجرد عدم الحاجة إلى هذه المقابض، يمكن "إغلاق" النطاق وإبطال أي مقابض مرتبطة بالنطاق. الطرق المتاحة لفتح/إغلاق النطاقات هي napi_open_handle_scope و napi_close_handle_scope.

تدعم Node-API تسلسلًا هرميًا متداخلًا واحدًا فقط للنطاقات. يوجد نطاق نشط واحد فقط في أي وقت، وسيتم ربط جميع المقابض الجديدة بهذا النطاق أثناء نشاطه. يجب إغلاق النطاقات بترتيب عكسي للترتيب الذي تم فتحها به. بالإضافة إلى ذلك، يجب إغلاق جميع النطاقات التي تم إنشاؤها داخل أسلوب أصلي قبل الرجوع من هذا الأسلوب.

بأخذ المثال السابق، فإن إضافة مكالمات إلى napi_open_handle_scope و napi_close_handle_scope سيضمن أن مقبضًا واحدًا على الأكثر يكون صالحًا طوال تنفيذ الحلقة:

for (int i = 0; i < 1000000; i++) {
  napi_handle_scope scope;
  napi_status status = napi_open_handle_scope(env, &scope);
  if (status != napi_ok) {
    break;
  }
  napi_value result;
  status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // القيام بشيء ما مع العنصر
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
}

عند تضمين النطاقات، توجد حالات يحتاج فيها مقبض من نطاق داخلي إلى البقاء بعد عمر هذا النطاق. تدعم Node-API "نطاقًا قابلاً للهروب" لدعم هذه الحالة. يسمح النطاق القابل للهروب بـ "ترقية" مقبض واحد بحيث "يهرب" من النطاق الحالي ويتغير عمر المقبض من النطاق الحالي إلى نطاق النطاق الخارجي.

الطرق المتاحة لفتح/إغلاق النطاقات القابلة للهروب هي napi_open_escapable_handle_scope و napi_close_escapable_handle_scope.

يتم تقديم طلب ترقية مقبض من خلال napi_escape_handle والذي لا يمكن استدعاؤه إلا مرة واحدة.

napi_open_handle_scope

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل النطاق الجديد.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تفتح هذه واجهة برمجة التطبيقات نطاقًا جديدًا.

napi_close_handle_scope

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] scope: napi_value يمثل النطاق المراد إغلاقه.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإغلاق النطاق الممرر. يجب إغلاق النطاقات بترتيب عكسي لترتيب إنشائها.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء جافا سكريبت معلق.

napi_open_escapable_handle_scope

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل النطاق الجديد.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تفتح هذه واجهة برمجة التطبيقات نطاقًا جديدًا يمكن منه ترقية كائن واحد إلى النطاق الخارجي.

napi_close_escapable_handle_scope

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] scope: napi_value يمثل النطاق المراد إغلاقه.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإغلاق النطاق الممرر. يجب إغلاق النطاقات بترتيب عكسي لترتيب إنشائها.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى إذا كان هناك استثناء جافا سكريبت معلق.

napi_escape_handle

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result);

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] scope: napi_value يمثل النطاق الحالي.
• [in] escapee: napi_value يمثل كائن JavaScript المراد إزالته.
• [out] result: napi_value يمثل المقبض إلى الكائن الذي تم إزالته في النطاق الخارجي.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تعزز هذه واجهة برمجة التطبيقات المقبض إلى كائن JavaScript بحيث يكون صالحًا لفترة حياة النطاق الخارجي. لا يمكن استدعاء هذه الوظيفة إلا مرة واحدة لكل نطاق. إذا تم استدعاؤها أكثر من مرة، فسيتم إرجاع خطأ.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى لو كان هناك استثناء JavaScript معلق.

المراجع إلى القيم التي تزيد مدة صلاحيتها عن مدة الطريقة الأصلية

في بعض الحالات، سيحتاج الإضافي إلى القدرة على إنشاء ومرجع القيم التي تزيد مدة صلاحيتها عن استدعاء طريقة أصلية واحدة. على سبيل المثال، لإنشاء منشئ واستخدام هذا المنشئ لاحقًا في طلب لإنشاء مثيلات، يجب أن يكون من الممكن الرجوع إلى كائن المنشئ عبر العديد من طلبات إنشاء المثيلات المختلفة. لن يكون هذا ممكنًا باستخدام مقبض عادي تم إرجاعه كـ napi_value كما هو موضح في القسم السابق. يتم إدارة عمر المقبض العادي بواسطة النطاقات، ويجب إغلاق جميع النطاقات قبل نهاية طريقة أصلية.

توفر Node-API طرقًا لإنشاء مراجع دائمة للقيم. حاليًا، تسمح Node-API فقط بإنشاء مراجع لمجموعة محدودة من أنواع القيم، بما في ذلك الكائن، والخارجي، والوظيفة، والرمز.

كل مرجع له عداد مرتبط بقيمة 0 أو أعلى، والتي تحدد ما إذا كان المرجع سيحافظ على القيمة المقابلة على قيد الحياة. المراجع التي يكون عدادها 0 لا تمنع جمع القيم. أصبحت قيم أنواع الكائن (الكائن، الوظيفة، الخارجي) والرمز مراجعًا "ضعيفة" ويمكن الوصول إليها بينما لم يتم جمعها. أي عدد أكبر من 0 سيمنع جمع القيم.

تحتوي قيم الرمز على نكهات مختلفة. لا يُدعم سلوك المرجع الضعيف الحقيقي إلا بواسطة الرموز المحلية التي تم إنشاؤها باستخدام دالة napi_create_symbol أو استدعاءات مُنشئ JavaScript Symbol (). تظل الرموز المسجلة عالميًا التي تم إنشاؤها باستخدام دالة node_api_symbol_for أو استدعاءات دالة JavaScript Symbol.for() مراجعًا قوية دائمًا لأن جامع القمامة لا يجمعها. وينطبق الشيء نفسه على الرموز المعروفة جيدًا مثل Symbol.iterator. كما أنها لا يتم جمعها أبدًا بواسطة جامع القمامة.

يمكن إنشاء المراجع مع عدد مرجعي أولي. يمكن بعد ذلك تعديل العدد من خلال napi_reference_ref و napi_reference_unref. إذا تم جمع كائن أثناء كون العداد المرجعي 0، فإن جميع المكالمات اللاحقة للحصول على الكائن المرتبط بالمرجع napi_get_reference_value ستعيد NULL بالنسبة إلى napi_value المُرجعة. تؤدي محاولة استدعاء napi_reference_ref لمرجع تم جمع كائنه إلى حدوث خطأ.

يجب حذف المراجع بمجرد أن لا يحتاج إليها الإضافة بعد الآن. عند حذف مرجع، لن يمنع بعد ذلك جمع الكائن المقابل. يؤدي عدم حذف مرجع دائم إلى "تسرب ذاكرة" مع الاحتفاظ بكل من الذاكرة الأصلية للمرجع الدائم والكائن المقابل على الكومة إلى الأبد.

يمكن إنشاء العديد من المراجع الدائمة التي تشير إلى نفس الكائن، كل منها إما سيحافظ على الكائن حيًا أو لا بناءً على عداده الفردي. يمكن أن تؤدي المراجع الدائمة المتعددة لنفس الكائن إلى الاحتفاظ بالذاكرة الأصلية بشكل غير متوقع. يجب الحفاظ على الهياكل الأصلية للمرجع الدائم على قيد الحياة حتى يتم تنفيذ المُنهيات للكائن المرجعي. إذا تم إنشاء مرجع دائم جديد لنفس الكائن، فلن يتم تشغيل المُنهيات لذلك الكائن ولن يتم تحرير الذاكرة الأصلية التي يشير إليها المرجع الدائم السابق. يمكن تجنب ذلك عن طريق استدعاء napi_delete_reference بالإضافة إلى napi_reference_unref إن أمكن.

سجل التغييرات:

• تجريبي (NAPI_EXPERIMENTAL مُعرّف): يمكن إنشاء المراجع لجميع أنواع القيم. لا تدعم أنواع القيم المدعومة الجديدة دلالات المرجع الضعيف ويتم إصدار قيم هذه الأنواع عندما يصبح عدد المراجع 0 ولا يمكن الوصول إليها من المرجع بعد الآن.

napi_create_reference

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة napi_value التي يتم إنشاء مرجع لها.
• [in] initial_refcount: عدد المراجع الأولي للمرجع الجديد.
• [out] result: napi_ref يشير إلى المرجع الجديد.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء مرجع جديد بعدد المراجع المحدد للقيمة المُمرّرة.

napi_delete_reference

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] ref: napi_ref المراد حذفه.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بحذف المرجع المُمرَّر.

يمكن استدعاء هذه واجهة برمجة التطبيقات حتى في حالة وجود استثناء جافا سكريبت معلق.

napi_reference_ref

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] ref: napi_ref الذي سيزداد عدد مراجعاته.
• [out] result: عدد المراجع الجديد.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بزيادة عدد المراجع للمرجع المُمرَّر، وتُرجع عدد المراجع الناتج.

napi_reference_unref

أضيف في: v8.0.0

نسخة N-API: 1

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] ref: napi_ref الذي سينقص عدد مراجعاته.
• [out] result: عدد المراجع الجديد.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بنقصان عدد المراجع للمرجع المُمرَّر، وتُرجع عدد المراجع الناتج.

napi_get_reference_value

تم الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] ref: napi_ref الذي يتم طلب القيمة المقابلة له.
• [out] result: napi_value المُشار إليه بواسطة napi_ref.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

إذا كانت لا تزال صالحة، تُرجع هذه واجهة برمجة التطبيقات napi_value التي تمثل قيمة جافا سكريبت المرتبطة بـ napi_ref. خلاف ذلك، ستكون النتيجة NULL.

التنظيف عند الخروج من بيئة Node.js الحالية

في حين أن عملية Node.js عادةً ما تطلق جميع مواردها عند الخروج، قد يتطلب مُدمجو Node.js، أو دعم عامل التشغيل في المستقبل، إضافة خطافات تنظيف سيتم تشغيلها بمجرد خروج بيئة Node.js الحالية.

توفر Node-API دوال لتسجيل وإلغاء تسجيل هذه المُدعيات. عندما يتم تشغيل هذه المُدعيات، يجب تحرير جميع الموارد التي تحتفظ بها الإضافة.

napi_add_env_cleanup_hook

تم الإضافة في: v10.2.0

إصدار N-API: 3

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
                                                  napi_cleanup_hook fun,
                                                  void* arg);

تسجل fun كدالة سيتم تشغيلها باستخدام معلمة arg بمجرد خروج بيئة Node.js الحالية.

يمكن تحديد دالة بأمان عدة مرات باستخدام قيم arg مختلفة. في هذه الحالة، سيتم استدعاؤها عدة مرات أيضًا. لا يُسمح بتوفير قيم fun و arg نفسها عدة مرات، وسيتسبب ذلك في توقف العملية.

سيتم استدعاء الخطافات بترتيب عكسي، أي أن الخطاف المُضاف مؤخرًا سيتم استدعاؤه أولاً.

يمكن إزالة هذا الخطاف باستخدام napi_remove_env_cleanup_hook. عادةً ما يحدث ذلك عندما يتم تفكيك المورد الذي تمت إضافة هذا الخطاف من أجله.

للتنظيف غير المتزامن، يتوفر napi_add_async_cleanup_hook.

napi_remove_env_cleanup_hook

مضاف في: v10.2.0

نسخة N-API: 3

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg);

يلغي تسجيل fun كدالة يتم تشغيلها باستخدام معامل arg بمجرد خروج بيئة Node.js الحالية. يجب أن يكون كل من المعامل وقيمة الدالة مطابقين تمامًا.

يجب أن تكون الدالة قد تم تسجيلها في الأصل باستخدام napi_add_env_cleanup_hook، وإلا ستتوقف العملية.

napi_add_async_cleanup_hook

[السجل]

الإصدار	التغييرات
v14.10.0، v12.19.0	تم تغيير توقيع استدعاء الوظيفة hook.
v14.8.0، v12.19.0	مضاف في: v14.8.0، v12.19.0

نسخة N-API: 8

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    node_api_basic_env env,
    napi_async_cleanup_hook hook,
    void* arg,
    napi_async_cleanup_hook_handle* remove_handle);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] hook: مؤشر الدالة التي سيتم استدعائها عند إزالة البيئة.
• [in] arg: المؤشر المراد تمريره إلى hook عند استدعائه.
• [out] remove_handle: مقبض اختياري يشير إلى خطاف التنظيف غير المتزامن.

يسجل hook، وهي دالة من نوع napi_async_cleanup_hook، كدالة يتم تشغيلها باستخدام معاملي remove_handle و arg بمجرد خروج بيئة Node.js الحالية.

على عكس napi_add_env_cleanup_hook، يُسمح بأن يكون الخطاف غير متزامن.

وإلا، فإن السلوك يطابق بشكل عام سلوك napi_add_env_cleanup_hook.

إذا لم يكن remove_handle يساوي NULL، فسيتم تخزين قيمة معتمة فيه يجب تمريرها لاحقًا إلى napi_remove_async_cleanup_hook، بغض النظر عما إذا كان الخطاف قد تم استدعاؤه بالفعل. وعادةً ما يحدث ذلك عندما يتم تفكيك المورد الذي تمت إضافة هذا الخطاف من أجله على أي حال.

napi_remove_async_cleanup_hook

[السجل]

الإصدار	التغييرات
v14.10.0، v12.19.0	تمت إزالة معلمة env.
v14.8.0، v12.19.0	تمت الإضافة في: v14.8.0، v12.19.0

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle);

• [in] remove_handle: المقبض الخاص بمعلّم تنظيف غير متزامن تم إنشاؤه باستخدام napi_add_async_cleanup_hook.

يلغي تسجيل معلّم التنظيف المقابل لـ remove_handle. سيمنع هذا تنفيذ المعلّم، إلا إذا كان قد بدأ تنفيذه بالفعل. يجب استدعاء هذا على أي قيمة napi_async_cleanup_hook_handle تم الحصول عليها من napi_add_async_cleanup_hook.

الإنهاء عند خروج بيئة Node.js

قد يتم تفكيك بيئة Node.js في أي وقت عشوائي في أقرب وقت ممكن مع منع تنفيذ JavaScript، كما هو الحال عند طلب worker.terminate(). عند تفكيك البيئة، يتم استدعاء عمليات استدعاء napi_finalize المسجلة لكائنات JavaScript، والوظائف الآمنة للخيوط، وبيانات مثيل البيئة على الفور وبشكل مستقل.

يتم جدولة استدعاء عمليات استدعاء napi_finalize بعد معلّمي التنظيف المسجلين يدويًا. لضمان الترتيب الصحيح لإنهاء الإضافة أثناء إيقاف تشغيل البيئة لتجنب استخدام-بعد-التحرير في عملية استدعاء napi_finalize، يجب على الإضافات تسجيل معلّم تنظيف باستخدام napi_add_env_cleanup_hook و napi_add_async_cleanup_hook لإصدار المورد المخصص يدويًا بترتيب صحيح.

تسجيل الوحدة

يتم تسجيل وحدات Node-API بطريقة مشابهة للوحدات الأخرى، باستثناء أنه بدلاً من استخدام ماكرو NODE_MODULE، يتم استخدام ما يلي:

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

الفرق التالي هو توقيع طريقة Init. بالنسبة لوحدة Node-API، يكون كما يلي:

napi_value Init(napi_env env, napi_value exports);

يتم التعامل مع قيمة الإرجاع من Init ككائن exports للوحدة. يتم تمرير كائن فارغ إلى طريقة Init عبر معلمة exports كتسهيل. إذا قامت Init بإرجاع NULL، فسيتم تصدير المعلمة التي تم تمريرها كـ exports بواسطة الوحدة. لا يمكن لوحدات Node-API تعديل كائن module، ولكن يمكنها تحديد أي شيء كخاصية exports للوحدة.

لإضافة الطريقة hello كدالة بحيث يمكن استدعاؤها كطريقة مقدمة بواسطة الإضافة:

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor desc = {
    "hello",
    NULL,
    Method,
    NULL,
    NULL,
    NULL,
    napi_writable | napi_enumerable | napi_configurable,
    NULL
  };
  status = napi_define_properties(env, exports, 1, &desc);
  if (status != napi_ok) return NULL;
  return exports;
}

لتعيين دالة لإرجاعها بواسطة require() للإضافة:

napi_value Init(napi_env env, napi_value exports) {
  napi_value method;
  napi_status status;
  status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
  if (status != napi_ok) return NULL;
  return method;
}

لتعريف فئة بحيث يمكن إنشاء مثيلات جديدة (غالبًا ما تُستخدم مع Object wrap):

// ملاحظة: مثال جزئي، لم يتم تضمين كل الكود المشار إليه
napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor properties[] = {
    { "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
    DECLARE_NAPI_METHOD("plusOne", PlusOne),
    DECLARE_NAPI_METHOD("multiply", Multiply),
  };

  napi_value cons;
  status =
      napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
  if (status != napi_ok) return NULL;

  status = napi_create_reference(env, cons, 1, &constructor);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "MyObject", cons);
  if (status != napi_ok) return NULL;

  return exports;
}

يمكنك أيضًا استخدام ماكرو NAPI_MODULE_INIT، والذي يعمل كاختصار لـ NAPI_MODULE وتحديد دالة Init:

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  napi_value answer;
  napi_status result;

  status = napi_create_int64(env, 42, &answer);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "answer", answer);
  if (status != napi_ok) return NULL;

  return exports;
}

يتم توفير المعلمتان env و exports إلى جسم ماكرو NAPI_MODULE_INIT.

جميع إضافات Node-API واعية بالسياق، مما يعني أنه يمكن تحميلها عدة مرات. هناك بعض الاعتبارات التصميمية عند إعلان مثل هذه الوحدة. توفر الوثائق المتعلقة بـ الإضافات الواعية بالسياق المزيد من التفاصيل.

ستكون المتغيرات env و exports متاحة داخل جسم الدالة بعد استدعاء الماكرو.

لمزيد من التفاصيل حول تعيين الخصائص على الكائنات، راجع القسم الخاص بـ العمل مع خصائص JavaScript.

لمزيد من التفاصيل حول إنشاء وحدات الإضافة بشكل عام، يُرجى الرجوع إلى واجهة برمجة التطبيقات الحالية.

التعامل مع قيم جافاسكريبت

يعرض Node-API مجموعة من واجهات برمجة التطبيقات لإنشاء جميع أنواع قيم جافاسكريبت. تم توثيق بعض هذه الأنواع في القسم 6 من مواصفات لغة ECMAScript.

بشكل أساسي، تُستخدم واجهات برمجة التطبيقات هذه للقيام بأحد الأمور التالية:

تُمثَّل قيم Node-API بواسطة النوع napi_value. أيّ دعوة لـ Node-API تتطلب قيمة جافاسكريبت تأخذ في napi_value. في بعض الحالات، تتحقق واجهة برمجة التطبيقات من نوع napi_value مسبقًا. ومع ذلك، لتحقيق أداء أفضل، من الأفضل للجهة المُستدعِية التأكد من أن napi_value المعنية هي من نوع جافاسكريبت المتوقع بواسطة واجهة برمجة التطبيقات.

أنواع التعداد

napi_key_collection_mode

تمت الإضافة في: v13.7.0، v12.17.0، v10.20.0

إصدار N-API: 6

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode;

يصف تعدادات فلتر المفاتيح/الخصائص:

يحد napi_key_collection_mode نطاق الخصائص المُجمَّعة.

يحدّ napi_key_own_only الخصائص المُجمَّعة على الكائن المعطى فقط. سيُضمّن napi_key_include_prototypes جميع مفاتيح سلسلة النموذج الأولي للكائنات أيضًا.

napi_key_filter

تمت الإضافة في: v13.7.0، v12.17.0، v10.20.0

إصدار N-API: 6

typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter;

بتات فلتر الخصائص. يمكن أن تُوَحَّد باستخدام or لبناء فلتر مركب.

napi_key_conversion

تمت الإضافة في: v13.7.0، v12.17.0، v10.20.0

إصدار N-API: 6

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion;

سيُحوّل napi_key_numbers_to_strings المؤشرات الصحيحة إلى سلاسل. سيُعيد napi_key_keep_numbers الأرقام للمؤشرات الصحيحة.

napi_valuetype

typedef enum {
  // أنواع ES6 (يتوافق مع typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype;

يصف نوع napi_value. يتوافق هذا بشكل عام مع الأنواع الموصوفة في القسم 6.1 من مواصفات لغة ECMAScript. بالإضافة إلى الأنواع الموجودة في هذا القسم، يمكن أن يمثل napi_valuetype أيضًا الدوال والكائنات ذات البيانات الخارجية.

تظهر قيمة جافاسكريبت من نوع napi_external في جافاسكريبت كائنًا عاديًا بحيث لا يمكن تعيين أي خصائص عليه، ولا نموذج أولي.

napi_typedarray_type

typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type;

يمثل هذا النوع الثنائي القياسي الأساسي لـTypedArray. تتوافق عناصر هذا التعداد مع القسم 22.2 من مواصفات لغة ECMAScript.

دوال إنشاء الكائنات

napi_create_array

تمت الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_array(napi_env env, napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء نداء Node-API.
• [out] result: قيمة napi_value تمثل مصفوفة JavaScript Array.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات قيمة Node-API تتوافق مع نوع مصفوفة JavaScript Array. تُوصف مصفوفات JavaScript في القسم 22.1 من مواصفات لغة ECMAScript.

napi_create_array_with_length

تمت الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] length: الطول الأولي للمصفوفة Array.
• [out] result: قيمة napi_value تمثل مصفوفة JavaScript Array.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات قيمة Node-API تتوافق مع نوع مصفوفة JavaScript Array. يتم تعيين خاصية طول Array إلى معلمة الطول المدخلة. ومع ذلك، لا يُضمن أن يتم تخصيص المخزن المؤقت الأساسي مسبقًا بواسطة آلة الظاهرية عند إنشاء المصفوفة. يُترك هذا السلوك لتنفيذ آلة الظاهرية الأساسية. إذا كان يجب أن يكون المخزن المؤقت كتلة متصلة من الذاكرة يمكن قراءتها و/أو كتابتها مباشرةً عبر C، فكر في استخدام napi_create_external_arraybuffer.

تُوصف مصفوفات JavaScript في القسم 22.1 من مواصفات لغة ECMAScript.

napi_create_arraybuffer

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] length: طول بايتات مؤقت المصفوفة المراد إنشاؤه.
• [out] data: مؤشر إلى مؤقت البايت الأساسي لـ ArrayBuffer. يمكن تجاهل data اختياريًا عن طريق تمرير NULL.
• [out] result: قيمة napi_value تمثل ArrayBuffer في جافاسكريبت.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات قيمة Node-API تتوافق مع ArrayBuffer في جافاسكريبت. تُستخدم ArrayBuffers لتمثيل مؤقتات البيانات الثنائية ذات الطول الثابت. تُستخدم عادةً كمؤقت دعم لكائنات TypedArray. سيكون لمؤقت ArrayBuffer المُخصص مؤقت بايت أساسي يحدد حجمه بواسطة المعلمة length المُمررة. يتم إرجاع المؤقت الأساسي اختياريًا إلى المُستدعي في حالة رغبة المُستدعي في معالجة المؤقت مباشرةً. لا يمكن الكتابة على هذا المؤقت إلا مباشرةً من التعليمات البرمجية الأصلية. للكتابة على هذا المؤقت من جافاسكريبت، يلزم إنشاء مصفوفة مُكتوبة أو كائن DataView.

تُوصف كائنات ArrayBuffer في جافاسكريبت في القسم 24.1 من مواصفات لغة ECMAScript.

napi_create_buffer

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] size: حجم المؤقت الأساسي بالبايت.
• [out] data: مؤشر خام إلى المؤقت الأساسي. يمكن تجاهل data اختياريًا عن طريق تمرير NULL.
• [out] result: قيمة napi_value تمثل node::Buffer.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُخصص هذه واجهة برمجة التطبيقات كائن node::Buffer. بينما لا يزال هذا هيكل بيانات مدعوم بالكامل، في معظم الحالات، يكفي استخدام TypedArray.

napi_create_buffer_copy

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] size: حجم المخزن المؤقت للإدخال بالبايت (يجب أن يكون نفس حجم المخزن المؤقت الجديد).
• [in] data: مؤشر خام إلى المخزن المؤقت الأساسي للنسخ منه.
• [out] result_data: مؤشر إلى المخزن المؤقت للبيانات الأساسي لـ Buffer الجديد. يمكن تجاهل result_data اختياريًا عن طريق تمرير NULL.
• [out] result: قيمة napi_value تمثل node::Buffer.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتخصيص كائن node::Buffer وتهيئته باستخدام البيانات التي تم نسخها من المخزن المؤقت الذي تم تمريره. في حين أن هذا لا يزال بنية بيانات مدعومة بالكامل، في معظم الحالات، فإن استخدام TypedArray سيكون كافياً.

napi_create_date

تم الإضافة في: v11.11.0، v10.17.0

إصدار N-API: 5

napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] time: قيمة وقت ECMAScript بالميلي ثانية منذ 1 يناير 1970 بتوقيت غرينتش.
• [out] result: قيمة napi_value تمثل كائن Date في جافا سكريبت.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

لا تلاحظ هذه واجهة برمجة التطبيقات الثواني الكبيسة؛ يتم تجاهلها، حيث يتوافق ECMAScript مع مواصفات وقت POSIX.

تقوم هذه واجهة برمجة التطبيقات بتخصيص كائن Date في جافا سكريبت.

يتم وصف كائنات Date في جافا سكريبت في القسم 20.3 من مواصفات لغة ECMAScript.

napi_create_external

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] data: مؤشر خام إلى البيانات الخارجية.
• [in] finalize_cb: مكالمة مُرجّعة اختيارية ليتم استدعاؤها عندما يتم جمع القيمة الخارجية. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_hint: تلميح اختياري ليتم تمريره إلى مكالمة المُرجّعة النهائية أثناء عملية الجمع.
• [out] result: قيمة napi_value تمثل قيمة خارجية.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتخصيص قيمة جافا سكريبت مع بيانات خارجية مُرفقة بها. يستخدم هذا لإرسال البيانات الخارجية من خلال كود جافا سكريبت، بحيث يمكن استردادها لاحقًا بواسطة كود أصلي باستخدام napi_get_value_external.

تضيف واجهة برمجة التطبيقات مكالمة مُرجّعة napi_finalize والتي سيتم استدعاؤها عندما يتم جمع كائن جافا سكريبت الذي تم إنشاؤه للتو.

القيمة التي تم إنشاؤها ليست كائنًا، وبالتالي لا تدعم خصائص إضافية. تعتبر نوع قيمة مميزًا: يؤدي استدعاء napi_typeof() بقيمة خارجية إلى napi_external.

napi_create_external_arraybuffer

أضيف في: v8.0.0

نسخة N-API: 1

napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] external_data: مؤشر إلى المخزن المؤقت للبايت الأساسي لـ ArrayBuffer.
• [in] byte_length: طول المخزن المؤقت الأساسي بالبايت.
• [in] finalize_cb: مكالمة اختيارية يتم استدعاؤها عند جمع ArrayBuffer. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_hint: تلميح اختياري لإرساله إلى مكالمة الإنهاء أثناء عملية الجمع.
• [out] result: قيمة napi_value تمثل ArrayBuffer في جافا سكريبت.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

بعض بيئات التشغيل بخلاف Node.js قد ألغت دعم المخازن المؤقتة الخارجية. في بيئات التشغيل بخلاف Node.js، قد تُرجع هذه الطريقة napi_no_external_buffers_allowed للإشارة إلى عدم دعم المخازن المؤقتة الخارجية. إحدى هذه بيئات التشغيل هي Electron كما هو موضح في هذه المشكلة electron/issues/35801.

من أجل الحفاظ على أوسع توافق مع جميع بيئات التشغيل، يمكنك تعريف NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED في الإضافة الخاصة بك قبل تضمين عناوين node-api. سيؤدي القيام بذلك إلى إخفاء دالتين تقومان بإنشاء مخازن مؤقتة خارجية. سيضمن هذا حدوث خطأ في التجميع إذا استخدمت إحدى هذه الطرق عن طريق الخطأ.

ترجع هذه واجهة برمجة التطبيقات قيمة Node-API تتوافق مع ArrayBuffer في جافا سكريبت. يتم تخصيص المخزن المؤقت للبايت الأساسي لـ ArrayBuffer وإدارته خارجيًا. يجب على المتصل التأكد من أن المخزن المؤقت للبايت يبقى صالحًا حتى يتم استدعاء مكالمة الإنهاء.

تضيف واجهة برمجة التطبيقات مكالمة napi_finalize والتي سيتم استدعاؤها عندما يتم جمع كائن جافا سكريبت الذي تم إنشاؤه للتو بواسطة عملية جمع القمامة.

تم وصف ArrayBuffers في جافا سكريبت في القسم 24.1 من مواصفات لغة ECMAScript.

napi_create_external_buffer

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة البرمجة التطبيقات ضمنها.
• [in] length: حجم المخزن المؤقت المدخل بوحدات البايت (يجب أن يكون نفس حجم المخزن المؤقت الجديد).
• [in] data: مؤشر خام إلى المخزن المؤقت الأساسي لجعله متاحًا لـ JavaScript.
• [in] finalize_cb: استدعاء اختياري يتم استدعاءه عند جمع ArrayBuffer. يوفر napi_finalize مزيدًا من التفاصيل.
• [in] finalize_hint: تلميح اختياري لإرساله إلى استدعاء الإنهاء أثناء عملية الجمع.
• [out] result: قيمة napi_value تمثل node::Buffer.

يرجع napi_ok إذا نجحت واجهة البرمجة التطبيقات.

بعض أوقات التشغيل بخلاف Node.js قد ألغت دعم المخازن المؤقتة الخارجية. في أوقات التشغيل بخلاف Node.js، قد تُرجع هذه الطريقة napi_no_external_buffers_allowed للإشارة إلى عدم دعم المخازن المؤقتة الخارجية. أحد أوقات التشغيل هذه هو Electron كما هو موضح في هذه المشكلة electron/issues/35801.

من أجل الحفاظ على أوسع توافق مع جميع أوقات التشغيل، يمكنك تعريف NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED في الإضافة الخاصة بك قبل التضمينات الخاصة برؤوس node-api. سيؤدي القيام بذلك إلى إخفاء دالتين تقومان بإنشاء مخازن مؤقتة خارجية. سيضمن هذا حدوث خطأ في التجميع إذا استخدمت إحدى هذه الطرق عن طريق الخطأ.

تقوم هذه واجهة البرمجة التطبيقات بتخصيص كائن node::Buffer وتهيئته ببيانات مدعومة بالمخزن المؤقت المُمرر. على الرغم من أن هذا لا يزال بنية بيانات مدعومة بالكامل، إلا أن استخدام TypedArray في معظم الحالات سيكون كافيًا.

تضيف واجهة البرمجة التطبيقات استدعاء napi_finalize والذي سيتم استدعاءه عند جمع كائن JavaScript الذي تم إنشاؤه للتو.

بالنسبة إلى Node.js >=4، فإن Buffers هي Uint8Arrays.

napi_create_object

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_create_object(napi_env env, napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل كائن JavaScript Object.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُخصّص واجهة برمجة التطبيقات هذه كائن JavaScript Object افتراضيًا. وهو ما يعادل إجراء new Object() في JavaScript.

يُوصف نوع كائن JavaScript في القسم 6.1.7 من مواصفات لغة ECMAScript.

napi_create_symbol

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] description: napi_value اختياري يشير إلى سلسلة JavaScript string ليتم تعيينها كوصف للرمز.
• [out] result: napi_value يمثل رمز JavaScript symbol.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُنشئ واجهة برمجة التطبيقات هذه قيمة رمز JavaScript symbol من سلسلة C مُشفّرة بترميز UTF8.

يُوصف نوع رمز JavaScript في القسم 19.4 من مواصفات لغة ECMAScript.

node_api_symbol_for

أضيف في: v17.5.0، v16.15.0

إصدار N-API: 9

napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] utf8description: سلسلة C مُشفّرة بترميز UTF-8 تمثل النص الذي سيتم استخدامه كوصف للرمز.
• [in] length: طول سلسلة الوصف بالبايت، أو NAPI_AUTO_LENGTH إذا كانت مُنهية بالصفر.
• [out] result: napi_value يمثل رمز JavaScript symbol.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تبحث واجهة برمجة التطبيقات هذه في السجل العام عن رمز موجود ذي الوصف المُعطى. إذا كان الرمز موجودًا بالفعل، فسيتم إرجاعه، وإلا سيتم إنشاء رمز جديد في السجل.

يُوصف نوع رمز JavaScript في القسم 19.4 من مواصفات لغة ECMAScript.

napi_create_typedarray

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_create_typedarray(napi_env env,
                                   napi_typedarray_type type,
                                   size_t length,
                                   napi_value arraybuffer,
                                   size_t byte_offset,
                                   napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] type: نوع البيانات القياسية للعناصر داخل TypedArray.
• [in] length: عدد العناصر في TypedArray.
• [in] arraybuffer: ArrayBuffer الأساسي لمصفوفة الأنواع.
• [in] byte_offset: الإزاحة البايتية داخل ArrayBuffer التي يجب البدء منها في عرض TypedArray.
• [out] result: قيمة napi_value تمثل مصفوفة TypedArray في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء كائن TypedArray في جافا سكريبت فوق ArrayBuffer موجود. توفر كائنات TypedArray عرضًا يشبه المصفوفة فوق مخزن بيانات أساسي حيث يكون لكل عنصر نفس نوع البيانات القياسية الثنائية الأساسية.

من المطلوب أن يكون (length * size_of_element) + byte_offset <= حجم المصفوفة المُمرّرة بالبايت. إذا لم يكن الأمر كذلك، فسيتم إثارة استثناء RangeError.

تم وصف كائنات TypedArray في جافا سكريبت في القسم 22.2 من مواصفات لغة ECMAScript.

node_api_create_buffer_from_arraybuffer

أضيف في: v23.0.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1 - تجريبي

napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
                                                              napi_value arraybuffer,
                                                              size_t byte_offset,
                                                              size_t byte_length,
                                                              napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] arraybuffer: ArrayBuffer الذي سيتم إنشاء المخزن المؤقت منه.
• [in] byte_offset: الإزاحة البايتية داخل ArrayBuffer التي يجب البدء منها في إنشاء المخزن المؤقت.
• [in] byte_length: طول المخزن المؤقت الذي سيتم إنشاؤه من ArrayBuffer بالبايت.
• [out] result: قيمة napi_value تمثل كائن Buffer المُنشأ في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء كائن Buffer في جافا سكريبت من ArrayBuffer موجود. كائن Buffer هو فئة خاصة بـ Node.js توفر طريقة للعمل مع البيانات الثنائية مباشرةً في جافا سكريبت.

يجب أن يكون النطاق البايتي [byte_offset, byte_offset + byte_length) ضمن حدود ArrayBuffer. إذا تجاوز byte_offset + byte_length حجم ArrayBuffer، فسيتم إثارة استثناء RangeError.

napi_create_dataview

تم الإضافة في: v8.3.0

نسخة N-API: 1

napi_status napi_create_dataview(napi_env env,
                                 size_t byte_length,
                                 napi_value arraybuffer,
                                 size_t byte_offset,
                                 napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] length: عدد العناصر في DataView.
• [in] arraybuffer: ArrayBuffer الأساسي لـ DataView.
• [in] byte_offset: الإزاحة البايتية ضمن ArrayBuffer التي يبدأ منها إسقاط DataView.
• [out] result: قيمة napi_value تمثل كائن DataView في جافا سكريبت.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء كائن DataView في جافا سكريبت فوق ArrayBuffer موجود. توفر كائنات DataView عرضًا مشابهًا للمصفوفة فوق مخزن بيانات أساسي، ولكنها تسمح بعناصر ذات حجم ونوع مختلفين في ArrayBuffer.

من الضروري أن يكون byte_length + byte_offset أقل من أو يساوي حجم البايتات للمصفوفة المُمررة. وإلا، فسيتم إثارة استثناء RangeError.

تُوصف كائنات DataView في جافا سكريبت في القسم 24.3 من مواصفات لغة ECMAScript.

دوال للتحويل من أنواع C إلى Node-API

napi_create_int32

تم الإضافة في: v8.4.0

نسخة N-API: 1

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: القيمة الصحيحة التي سيتم تمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل رقمًا في جافا سكريبت.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه واجهة برمجة التطبيقات للتحويل من نوع int32_t في C إلى نوع number في جافا سكريبت.

يُوصف نوع number في جافا سكريبت في القسم 6.1.6 من مواصفات لغة ECMAScript.

napi_create_uint32

تم الإضافة في: v8.4.0

إصدار N-API: 1

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة عدد صحيح بدون إشارة لتمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل رقم جافا سكريبت number.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه واجهة برمجة التطبيقات للتحويل من نوع C uint32_t إلى نوع جافا سكريبت number.

يُوصف نوع جافا سكريبت number في القسم 6.1.6 من مواصفات لغة ECMAScript.

napi_create_int64

تم الإضافة في: v8.4.0

إصدار N-API: 1

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة عدد صحيح لتمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل رقم جافا سكريبت number.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه واجهة برمجة التطبيقات للتحويل من نوع C int64_t إلى نوع جافا سكريبت number.

يُوصف نوع جافا سكريبت number في القسم 6.1.6 من مواصفات لغة ECMAScript. لاحظ أن النطاق الكامل لـ int64_t لا يمكن تمثيله بدقة كاملة في جافا سكريبت. ستفقد القيم الصحيحة خارج نطاق Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) الدقة.

napi_create_double

تم الإضافة في: v8.4.0

إصدار N-API: 1

napi_status napi_create_double(napi_env env, double value, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة ذات دقة مزدوجة لتمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل رقم جافا سكريبت number.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه واجهة برمجة التطبيقات للتحويل من نوع C double إلى نوع جافا سكريبت number.

يُوصف نوع جافا سكريبت number في القسم 6.1.6 من مواصفات لغة ECMAScript.

napi_create_bigint_int64

أضيف في: v10.7.0

إصدار N-API: 6

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: القيمة الصحيحة التي سيتم تمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل قيمة BigInt في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتحويل نوع int64_t في لغة C إلى نوع BigInt في جافا سكريبت.

napi_create_bigint_uint64

أضيف في: v10.7.0

إصدار N-API: 6

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: القيمة الصحيحة غير الموقعة التي سيتم تمثيلها في جافا سكريبت.
• [out] result: قيمة napi_value تمثل قيمة BigInt في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتحويل نوع uint64_t في لغة C إلى نوع BigInt في جافا سكريبت.

napi_create_bigint_words

أضيف في: v10.7.0

إصدار N-API: 6

napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] sign_bit: يحدد ما إذا كانت قيمة BigInt الناتجة موجبة أم سالبة.
• [in] word_count: طول مصفوفة words.
• [in] words: مصفوفة من الكلمات ذات 64 بت little-endian من نوع uint64_t.
• [out] result: قيمة napi_value تمثل قيمة BigInt في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتحويل مصفوفة من الكلمات غير الموقعة ذات 64 بت إلى قيمة BigInt واحدة.

يتم حساب قيمة BigInt الناتجة على النحو التالي: (–1) (words[0] × (2) + words[1] × (2) + …)

napi_create_string_latin1

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result);

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] str: مُخزن مؤقت للرموز يمثل سلسلة مُشفّرة بترميز ISO-8859-1.
• [in] length: طول السلسلة بالبايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بالصفر.
• [out] result: قيمة napi_value تمثل سلسلة نصية في جافاسكريبت.

يُعيد napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة نصية في جافاسكريبت من سلسلة نصية مُشفّرة بترميز ISO-8859-1 في لغة C. يتم نسخ السلسلة الأصلية.

يُوصف نوع السلسلة النصية في جافاسكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

node_api_create_external_string_latin1

مضاف في: v20.4.0، v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1 - تجريبي

napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied);

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.

• [in] str: مُخزن مؤقت للرموز يمثل سلسلة مُشفّرة بترميز ISO-8859-1.

• [in] length: طول السلسلة بالبايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بالصفر.

• [in] finalize_callback: الدالة التي سيتم استدعاؤها عند جمع السلسلة. سيتم استدعاء الدالة بالمعلمات التالية:

  • [in] env: البيئة التي يعمل فيها الإضافة. قد تكون هذه القيمة فارغة إذا كانت السلسلة تُجمع كجزء من إنهاء عامل التشغيل أو مثيل Node.js الرئيسي.
  • [in] data: هذه هي قيمة str كمؤشر void*.
  • [in] finalize_hint: هذه هي قيمة finalize_hint التي تم تقديمها لواجهة برمجة التطبيقات. يوفر napi_finalize مزيدًا من التفاصيل. هذه المعلمة اختيارية. يعني تمرير قيمة فارغة أن الإضافة لا تحتاج إلى إعلام عند جمع السلسلة النصية في جافاسكريبت المقابلة.

• [in] finalize_hint: تلميح اختياري ليتم تمريره إلى دالة الإكمال أثناء عملية الجمع.

• [out] result: قيمة napi_value تمثل سلسلة نصية في جافاسكريبت.

• [out] copied: ما إذا كانت السلسلة قد نُسخت. إذا كانت كذلك، فسيتم بالفعل استدعاء مُنهي لإزالة str.

يُعيد napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة نصية في جافاسكريبت من سلسلة نصية مُشفّرة بترميز ISO-8859-1 في لغة C. قد لا يتم نسخ السلسلة الأصلية، وبالتالي يجب أن توجد طوال دورة حياة قيمة جافاسكريبت.

يُوصف نوع السلسلة النصية في جافاسكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

napi_create_string_utf16

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] str: مخزن مؤقت للرموز يمثل سلسلة مشفرة بتشفير UTF16-LE.
• [in] length: طول السلسلة بوحدات رمز ثنائية البايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بصفر.
• [out] result: قيمة napi_value تمثل سلسلة جافا سكريبت string.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة جافا سكريبت string من سلسلة C مشفرة بتشفير UTF16-LE. يتم نسخ السلسلة الأصلية.

تم وصف نوع سلسلة جافا سكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

node_api_create_external_string_utf16

مضاف في: v20.4.0، v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 ثبات: 1 - تجريبي

napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.

• [in] str: مخزن مؤقت للرموز يمثل سلسلة مشفرة بتشفير UTF16-LE.

• [in] length: طول السلسلة بوحدات رمز ثنائية البايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بصفر.

• [in] finalize_callback: الدالة التي سيتم استدعاؤها عند جمع السلسلة. سيتم استدعاء الدالة بالمعلمات التالية:

  • [in] env: البيئة التي تعمل فيها الإضافة. قد تكون هذه القيمة فارغة إذا تم جمع السلسلة كجزء من إنهاء عامل التشغيل أو مثيل Node.js الرئيسي.
  • [in] data: هذه هي قيمة str كمؤشر void*.
  • [in] finalize_hint: هذه هي قيمة finalize_hint التي تم تقديمها لواجهة برمجة التطبيقات. يوفر napi_finalize المزيد من التفاصيل. هذه المعلمة اختيارية. يعني تمرير قيمة فارغة أن الإضافة لا تحتاج إلى إعلام عند جمع سلسلة جافا سكريبت المقابلة.

• [in] finalize_hint: تلميح اختياري لتمريره إلى دالة الاستدعاء النهائية أثناء عملية الجمع.

• [out] result: قيمة napi_value تمثل سلسلة جافا سكريبت string.

• [out] copied: ما إذا تم نسخ السلسلة. إذا كان الأمر كذلك، فسيتم بالفعل استدعاء المُنهي لتدمير str.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة جافا سكريبت string من سلسلة C مشفرة بتشفير UTF16-LE. قد لا يتم نسخ السلسلة الأصلية، وبالتالي يجب أن توجد طوال دورة حياة قيمة جافا سكريبت.

تم وصف نوع سلسلة جافا سكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

napi_create_string_utf8

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] str: مُخزن مؤقت للرموز يمثل سلسلة مُشفّرة بترميز UTF8.
• [in] length: طول السلسلة بالبايت، أو NAPI_AUTO_LENGTH إذا كانت مُنتهية بـ null.
• [out] result: قيمة napi_value تمثل سلسلة نصية في جافا سكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة نصية في جافا سكريبت من سلسلة نصية مُشفّرة بترميز UTF8 مكتوبة بلغة C. يتم نسخ السلسلة الأصلية.

تم وصف نوع السلسلة النصية في جافا سكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

دوال لإنشاء مفاتيح خصائص مُحسّنة

تستخدم العديد من محركات جافا سكريبت، بما في ذلك V8، سلاسل مُدمجة كمفاتيح لتعيين وحصول على قيم الخصائص. عادةً ما تستخدم جدول تبديل لإنشاء هذه السلاسل والبحث عنها. بينما يضيف ذلك بعض التكلفة لكل إنشاء مفتاح، إلا أنه يحسّن الأداء بعد ذلك من خلال تمكين مقارنة مُشير سلسلة بدلاً من السلاسل الكاملة.

إذا كان من المقصود استخدام سلسلة نصية جديدة في جافا سكريبت كمفتاح خاصية، فبالنسبة لبعض محركات جافا سكريبت سيكون من الأكثر كفاءة استخدام الدوال الموجودة في هذا القسم. خلاف ذلك، استخدم دوال سلسلة napi_create_string_utf8 أو node_api_create_external_string_utf8 لأن قد يكون هناك عبء إضافي في إنشاء/ تخزين السلاسل باستخدام طرق إنشاء مفتاح الخاصية.

node_api_create_property_key_latin1

مضاف في: v22.9.0، v20.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] str: مُخزن مؤقت للرموز يمثل سلسلة مُشفّرة بترميز ISO-8859-1.
• [in] length: طول السلسلة بالبايت، أو NAPI_AUTO_LENGTH إذا كانت مُنتهية بـ null.
• [out] result: قيمة napi_value تمثل سلسلة نصية مُحسّنة في جافا سكريبت لاستخدامها كمفتاح خاصية للكائنات.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة نصية مُحسّنة في جافا سكريبت من سلسلة نصية مُشفّرة بترميز ISO-8859-1 لاستخدامها كمفتاح خاصية للكائنات. يتم نسخ السلسلة الأصلية. على عكس napi_create_string_latin1، قد تستفيد المكالمات اللاحقة لهذه الدالة باستخدام نفس مُشير str من زيادة السرعة في إنشاء napi_value المطلوب، اعتمادًا على المحرّك.

تم وصف نوع السلسلة النصية في جافا سكريبت في القسم 6.1.4 من مواصفات لغة ECMAScript.

node_api_create_property_key_utf16

تم الإضافة في: v21.7.0، v20.12.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] str: مخزن مؤقت للرموز يمثل سلسلة مشفرة بترميز UTF16-LE.
• [in] length: طول السلسلة بوحدات التعليمات البرمجية ثنائية البايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بصفر.
• [out] result: napi_value يمثل سلسلة JavaScript مُحسّنة تُستخدم كمفتاح خاصية للكائنات.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة JavaScript مُحسّنة من سلسلة C مشفرة بترميز UTF16-LE لاستخدامها كمفتاح خاصية للكائنات. يتم نسخ السلسلة الأصلية.

يُوصف نوع سلسلة JavaScript في القسم 6.1.4 من مواصفات لغة ECMAScript.

node_api_create_property_key_utf8

تم الإضافة في: v22.9.0، v20.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] str: مخزن مؤقت للرموز يمثل سلسلة مشفرة بترميز UTF8.
• [in] length: طول السلسلة بوحدات التعليمات البرمجية ثنائية البايت، أو NAPI_AUTO_LENGTH إذا كانت منتهية بصفر.
• [out] result: napi_value يمثل سلسلة JavaScript مُحسّنة تُستخدم كمفتاح خاصية للكائنات.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء قيمة سلسلة JavaScript مُحسّنة من سلسلة C مشفرة بترميز UTF8 لاستخدامها كمفتاح خاصية للكائنات. يتم نسخ السلسلة الأصلية.

يُوصف نوع سلسلة JavaScript في القسم 6.1.4 من مواصفات لغة ECMAScript.

دوال للتحويل من Node-API إلى أنواع C

napi_get_array_length

تمت الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] value: napi_value يمثل مصفوفة JavaScript التي يتم الاستعلام عن طولها.
• [out] result: uint32 يمثل طول المصفوفة.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع واجهة برمجة التطبيقات هذه طول المصفوفة.

تم وصف طول Array في القسم 22.1.4.1 من مواصفات لغة ECMAScript.

napi_get_arraybuffer_info

تمت الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] arraybuffer: napi_value يمثل ArrayBuffer الذي يتم الاستعلام عنه.
• [out] data: المخزن المؤقت للبيانات الأساسي لـ ArrayBuffer. إذا كان byte_length يساوي 0، فقد يكون هذا NULL أو أي قيمة مؤشر أخرى.
• [out] byte_length: الطول بالبايت للمخزن المؤقت للبيانات الأساسي.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم واجهة برمجة التطبيقات هذه لاسترداد المخزن المؤقت للبيانات الأساسي لـ ArrayBuffer وطوله.

تحذير: استخدم الحذر أثناء استخدام واجهة برمجة التطبيقات هذه. يتم إدارة عمر المخزن المؤقت للبيانات الأساسي بواسطة ArrayBuffer حتى بعد إرجاعه. قد تكون هناك طريقة آمنة لاستخدام واجهة برمجة التطبيقات هذه بالاقتران مع napi_create_reference، والتي يمكن استخدامها لضمان التحكم في عمر ArrayBuffer. من الآمن أيضًا استخدام المخزن المؤقت للبيانات المُرجع ضمن نفس وظيفة الاستدعاء طالما لا توجد مكالمات لواجهات برمجة تطبيقات أخرى قد تُشغل عملية جمع البيانات المهملة.

napi_get_buffer_info

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length)

• [in] env: بيئة استدعاء واجهة البرمجة.
• [in] value: napi_value يمثل node::Buffer أو Uint8Array قيد الاستعلام.
• [out] data: المخزن المؤقت للبيانات الأساسي لـ node::Buffer أو Uint8Array. إذا كان الطول 0، فقد يكون هذا NULL أو أي قيمة مؤشر أخرى.
• [out] length: طول المخزن المؤقت للبيانات الأساسي بالبايت.

يرجع napi_ok إذا نجحت واجهة البرمجة.

تعيد هذه الطريقة نفس data و byte_length مثل napi_get_typedarray_info. و napi_get_typedarray_info تقبل node::Buffer (وهو Uint8Array) كقيمة أيضًا.

تُستخدم هذه واجهة البرمجة لاسترداد المخزن المؤقت للبيانات الأساسي لـ node::Buffer وطوله.

تحذير: استخدم الحذر عند استخدام هذه واجهة البرمجة لأن عمر المخزن المؤقت للبيانات الأساسي غير مضمون إذا كان مُدارًا بواسطة الجهاز الظاهري.

napi_get_prototype

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result)

• [in] env: بيئة استدعاء واجهة البرمجة.
• [in] object: napi_value يمثل كائن JavaScript Object الذي سيتم إرجاع النموذج الأولي له. هذا يُرجع ما يعادل Object.getPrototypeOf (الذي ليس هو نفسه خاصية prototype للدالة).
• [out] result: napi_value يمثل النموذج الأولي للكائن المعطى.

يرجع napi_ok إذا نجحت واجهة البرمجة.

napi_get_typedarray_info

أضيف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_typedarray_info(napi_env env,
                                     napi_value typedarray,
                                     napi_typedarray_type* type,
                                     size_t* length,
                                     void** data,
                                     napi_value* arraybuffer,
                                     size_t* byte_offset)

• [in] env: بيئة استدعاء واجهة البرمجة.
• [in] typedarray: napi_value يمثل TypedArray الذي سيتم الاستعلام عن خصائصه.
• [out] type: نوع البيانات القياسي للعناصر داخل TypedArray.
• [out] length: عدد العناصر في TypedArray.
• [out] data: المخزن المؤقت للبيانات الأساسي لـ TypedArray المُعدّل بقيمة byte_offset بحيث يشير إلى العنصر الأول في TypedArray. إذا كان طول المصفوفة 0، فقد يكون هذا NULL أو أي قيمة مؤشر أخرى.
• [out] arraybuffer: ArrayBuffer الأساسي لـ TypedArray.
• [out] byte_offset: الإزاحة البايتية داخل المصفوفة الأصلية الأساسية حيث يقع العنصر الأول للمصفوفات. تم بالفعل تعديل قيمة معامل data بحيث يشير data إلى العنصر الأول في المصفوفة. لذلك، سيكون أول بايت في المصفوفة الأصلية في data - byte_offset.

يرجع napi_ok إذا نجحت واجهة البرمجة.

تعيد هذه واجهة البرمجة خصائص متنوعة لمصفوفة مُكتوبة.

قد يكون أي من معلمات الإخراج NULL إذا لم تكن تلك الخاصية مطلوبة.

تحذير: استخدم الحذر عند استخدام هذه واجهة البرمجة لأن المخزن المؤقت للبيانات الأساسي مُدار بواسطة الجهاز الظاهري.

napi_get_dataview_info

مضاف في: v8.3.0

نسخة N-API: 1

napi_status napi_get_dataview_info(napi_env env,
                                   napi_value dataview,
                                   size_t* byte_length,
                                   void** data,
                                   napi_value* arraybuffer,
                                   size_t* byte_offset)

• [in] env: بيئة يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] dataview: napi_value يمثل DataView الذي يتم الاستعلام عن خصائصه.
• [out] byte_length: عدد البايتات في DataView.
• [out] data: المخزن المؤقت للبيانات الأساسي لـ DataView. إذا كان byte_length يساوي 0، فقد يكون هذا NULL أو أي قيمة مؤشر أخرى.
• [out] arraybuffer: ArrayBuffer الأساسي لـ DataView.
• [out] byte_offset: إزاحة البايت داخل مخزن البيانات المؤقت الذي يبدأ منه إسقاط DataView.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

قد يكون أي من معلمات الإخراج NULL إذا لم تكن هذه الخاصية مطلوبة.

ترجع هذه واجهة برمجة التطبيقات خصائص مختلفة لـ DataView.

napi_get_date_value

مضاف في: v11.11.0، v10.17.0

نسخة N-API: 5

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result)

• [in] env: بيئة يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] value: napi_value يمثل تاريخ JavaScript Date.
• [out] result: قيمة الوقت كـ double تمثل بالميلي ثانية منذ منتصف الليل في بداية 01 يناير 1970 بتوقيت جرينتش.

لا تلاحظ هذه واجهة برمجة التطبيقات الثواني الكبيسة؛ يتم تجاهلها، حيث يتوافق ECMAScript مع مواصفات وقت POSIX.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير napi_value غير تاريخ، فإنها ترجع napi_date_expected.

ترجع هذه واجهة برمجة التطبيقات قيمة الوقت البدائية المزدوجة C لقيمة التاريخ JavaScript المعطاة.

napi_get_value_bool

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)

• [in] env: بيئة يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] value: napi_value يمثل قيمة منطقية JavaScript Boolean.
• [out] result: قيمة منطقية بدائية C تعادل القيمة المنطقية JavaScript المعطاة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير napi_value غير منطقي، فإنها ترجع napi_boolean_expected.

ترجع هذه واجهة برمجة التطبيقات القيمة المنطقية البدائية C المكافئة للقيمة المنطقية JavaScript المعطاة.

napi_get_value_double

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] value: napi_value يمثل رقم JavaScript.
• [out] result: قيمة بدائية مزدوجة من نوع C تعادل الرقم المُعطى من JavaScript.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير قيمة napi_value ليست رقمًا، فإنها ترجع napi_number_expected.

ترجع هذه واجهة برمجة التطبيقات القيمة البدائية المزدوجة من نوع C المكافئة للرقم المُعطى من JavaScript.

napi_get_value_bigint_int64

تم الإضافة في: v10.7.0

إصدار N-API: 6

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] value: napi_value يمثل JavaScript BigInt.
• [out] result: قيمة بدائية من نوع C int64_t تعادل JavaScript BigInt المُعطى.
• [out] lossless: يشير إلى ما إذا تم تحويل قيمة BigInt بدون فقدان.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير قيمة ليست من نوع BigInt، فإنها ترجع napi_bigint_expected.

ترجع هذه واجهة برمجة التطبيقات القيمة البدائية من نوع C int64_t المكافئة لـ JavaScript BigInt المُعطى. إذا لزم الأمر، فسوف تقصّر القيمة، مع ضبط lossless على false.

napi_get_value_bigint_uint64

تم الإضافة في: v10.7.0

إصدار N-API: 6

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] value: napi_value يمثل JavaScript BigInt.
• [out] result: قيمة بدائية من نوع C uint64_t تعادل JavaScript BigInt المُعطى.
• [out] lossless: يشير إلى ما إذا تم تحويل قيمة BigInt بدون فقدان.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير قيمة ليست من نوع BigInt، فإنها ترجع napi_bigint_expected.

ترجع هذه واجهة برمجة التطبيقات القيمة البدائية من نوع C uint64_t المكافئة لـ JavaScript BigInt المُعطى. إذا لزم الأمر، فسوف تقصّر القيمة، مع ضبط lossless على false.

napi_get_value_bigint_words

تم الإضافة في: v10.7.0

إصدار N-API: 6

napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] value: napi_value يمثل JavaScript BigInt.
• [out] sign_bit: عدد صحيح يمثل ما إذا كان JavaScript BigInt موجبًا أم سالبًا.
• [in/out] word_count: يجب تهيئته إلى طول مصفوفة words. عند الإرجاع، سيتم تعيينه إلى العدد الفعلي للكلمات التي ستكون مطلوبة لتخزين هذا BigInt.
• [out] words: مؤشر إلى مصفوفة كلمات مكونة من 64 بت تم تخصيصها مسبقًا.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتحويل قيمة BigInt واحدة إلى بت إشارة، ومصفوفة little-endian مكونة من 64 بت، وعدد العناصر في المصفوفة. يمكن تعيين كل من sign_bit و words على NULL، من أجل الحصول على word_count فقط.

napi_get_value_external

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] value: napi_value يمثل قيمة خارجية لـ JavaScript.
• [out] result: مؤشر إلى البيانات التي تم تغليفها بواسطة القيمة الخارجية لـ JavaScript.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير napi_value غير خارجي، فإنه يرجع napi_invalid_arg.

تقوم هذه واجهة برمجة التطبيقات باسترداد مؤشر بيانات خارجي تم تمريره مسبقًا إلى napi_create_external().

napi_get_value_int32

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] value: napi_value يمثل JavaScript number.
• [out] result: بدائي C int32 يعادل JavaScript number المعطى.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير napi_value غير رقمي، فإنه يرجع napi_number_expected.

تقوم هذه واجهة برمجة التطبيقات بإرجاع البدائي C int32 المكافئ لـ JavaScript number المعطى.

إذا تجاوز الرقم نطاق عدد صحيح 32 بت، فسيتم تقصير النتيجة إلى ما يعادل البتات السفلية 32. قد يؤدي هذا إلى تحويل رقم موجب كبير إلى رقم سالب إذا كانت القيمة > 2³¹ - 1.

تقوم قيم الأعداد غير المحدودة (NaN، +Infinity، أو -Infinity) بتعيين النتيجة على صفر.

napi_get_value_int64

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] value: napi_value يمثل رقم JavaScript.
• [out] result: قيمة بدائية من نوع C int64 تعادل الرقم المُعطى في JavaScript.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير قيمة napi_value ليست رقمًا، فإنها تُرجع napi_number_expected.

ترجع هذه واجهة برمجة التطبيقات القيمة البدائية من نوع C int64 المكافئة للرقم المُعطى في JavaScript.

ستفقد قيم number خارج نطاق Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) دقتها.

تعيّن قيم الأعداد غير المحدودة (NaN, +Infinity, أو -Infinity) النتيجة إلى صفر.

napi_get_value_string_latin1

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] value: napi_value يمثل سلسلة JavaScript.
• [in] buf: مُخزن مؤقت لكتابة السلسلة المُشفرة بـ ISO-8859-1 فيه. إذا تم تمرير NULL، فسيتم إرجاع طول السلسلة بالبايتات، باستثناء المُنهي، في result.
• [in] bufsize: حجم المخزن المؤقت للوجهة. عندما تكون هذه القيمة غير كافية، يتم اقتطاع السلسلة المُرجعة ووضع مُنهي فارغ.
• [out] result: عدد البايتات المُنسوخة في المخزن المؤقت، باستثناء المُنهي.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير قيمة napi_value ليست سلسلة، فإنها تُرجع napi_string_expected.

ترجع هذه واجهة برمجة التطبيقات السلسلة المُشفرة بـ ISO-8859-1 المُقابلة للقيمة المُمررة.

napi_get_value_string_utf8

مُضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result)

• [in] env: بيئة تنفيذ واجهة البرمجة.
• [in] value: napi_value يمثل سلسلة نصية في جافاسكريبت.
• [in] buf: مُخزن مؤقت لكتابة السلسلة المُشفّرة بـ UTF8 فيه. إذا تم تمرير NULL، يتم إرجاع طول السلسلة بالبايتات، باستثناء مُنهي الصفر، في result.
• [in] bufsize: حجم المخزن المؤقت للوجهة. عندما تكون هذه القيمة غير كافية، يتم اقتطاع السلسلة المُرجعّة ووضع مُنهي الصفر.
• [out] result: عدد البايتات المُنسوخة في المخزن المؤقت، باستثناء مُنهي الصفر.

يُعيد napi_ok إذا نجحت واجهة البرمجة. إذا تم تمرير napi_value غير string، فإنه يُعيد napi_string_expected.

تعيد هذه واجهة البرمجة السلسلة المُشفّرة بـ UTF8 المُناظرة للقيمة المُمرّرة.

napi_get_value_string_utf16

مُضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_value_string_utf16(napi_env env,
                                        napi_value value,
                                        char16_t* buf,
                                        size_t bufsize,
                                        size_t* result)

• [in] env: بيئة تنفيذ واجهة البرمجة.
• [in] value: napi_value يمثل سلسلة نصية في جافاسكريبت.
• [in] buf: مُخزن مؤقت لكتابة السلسلة المُشفّرة بـ UTF16-LE فيه. إذا تم تمرير NULL، يتم إرجاع طول السلسلة بوحدات الشفرة ذات البايتين، باستثناء مُنهي الصفر.
• [in] bufsize: حجم المخزن المؤقت للوجهة. عندما تكون هذه القيمة غير كافية، يتم اقتطاع السلسلة المُرجعّة ووضع مُنهي الصفر.
• [out] result: عدد وحدات الشفرة ذات البايتين المُنسوخة في المخزن المؤقت، باستثناء مُنهي الصفر.

يُعيد napi_ok إذا نجحت واجهة البرمجة. إذا تم تمرير napi_value غير string، فإنه يُعيد napi_string_expected.

تعيد هذه واجهة البرمجة السلسلة المُشفّرة بـ UTF16 المُناظرة للقيمة المُمرّرة.

napi_get_value_uint32

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: napi_value يمثل رقم JavaScript.
• [out] result: ما يعادل النوع البدائي في C لـ napi_value المعطاة كـ uint32_t.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير napi_value غير رقمي، فإنها ترجع napi_number_expected.

ترجع هذه واجهة برمجة التطبيقات ما يعادل النوع البدائي في C لـ napi_value المعطاة كـ uint32_t.

دوال الحصول على مثيلات عالمية

napi_get_boolean

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة القيمة المنطقية التي سيتم استرجاعها.
• [out] result: napi_value يمثل كائن قيمة منطقية مفرد في JavaScript لاسترجاعه.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه واجهة برمجة التطبيقات لإرجاع كائن JavaScript المفرد المستخدم لتمثيل قيمة منطقية معينة.

napi_get_global

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_global(napi_env env, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل كائن global في JavaScript.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات كائن global.

napi_get_null

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_null(napi_env env, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل كائن null في JavaScript.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات كائن null.

napi_get_undefined

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_undefined(napi_env env, napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: napi_value يمثل قيمة غير معرفة في JavaScript.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات الكائن غير المعرفة.

التعامل مع قيم JavaScript والعمليات المجردة

يعرض Node-API مجموعة من واجهات برمجة التطبيقات لأداء بعض العمليات المجردة على قيم JavaScript. تم توثيق بعض هذه العمليات في القسم 7 من مواصفات لغة ECMAScript.

تدعم هذه واجهات برمجة التطبيقات القيام بإحدى الأمور التالية:

napi_coerce_to_bool

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] value: قيمة JavaScript التي سيتم إجبارها.
• [out] result: napi_value يمثل قيمة JavaScript Boolean المُجبرة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتنفيذ العملية المجردة ToBoolean() كما هو محدد في القسم 7.1.2 من مواصفات لغة ECMAScript.

napi_coerce_to_number

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] value: قيمة JavaScript التي سيتم إجبارها.
• [out] result: napi_value يمثل قيمة JavaScript number المُجبرة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتنفيذ العملية المجردة ToNumber() كما هو محدد في القسم 7.1.3 من مواصفات لغة ECMAScript. قد تقوم هذه الوظيفة بتشغيل رمز JS إذا كانت القيمة المدخلة هي كائن.

napi_coerce_to_object

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] value: قيمة JavaScript التي سيتم إجبارها.
• [out] result: napi_value يمثل قيمة JavaScript Object المُجبرة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتنفيذ العملية المجردة ToObject() كما هو محدد في القسم 7.1.13 من مواصفات لغة ECMAScript.

napi_coerce_to_string

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة جافاسكريبت المراد تحويلها.
• [out] result: napi_value يمثل سلسلة جافاسكريبت المحولة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم واجهة برمجة التطبيقات هذه بتنفيذ العملية المجردة ToString() كما هو محدد في القسم 7.1.13 من مواصفات لغة ECMAScript. قد تقوم هذه الدالة بتشغيل شفرة جافاسكريبت إذا كانت القيمة المُمرّرة كائنًا.

napi_typeof

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة جافاسكريبت التي سيتم الاستعلام عن نوعها.
• [out] result: نوع قيمة جافاسكريبت.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

• napi_invalid_arg إذا لم يكن نوع value نوعًا معروفًا في ECMAScript وvalue ليست قيمة خارجية.

تمثل واجهة برمجة التطبيقات هذه سلوكًا مشابهًا لاستدعاء عامل التشغيل typeof على الكائن كما هو محدد في القسم 12.5.5 من مواصفات لغة ECMAScript. ومع ذلك، هناك بعض الاختلافات:

إذا كان لـ value نوع غير صالح، فسيتم إرجاع خطأ.

napi_instanceof

مضاف في: v8.0.0

إصدار N-API: 1

napi_status napi_instanceof(napi_env env,
                            napi_value object,
                            napi_value constructor,
                            bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] object: قيمة جافاسكريبت المراد التحقق منها.
• [in] constructor: كائن دالة جافاسكريبت لدالة المُنشئ للتحقق منها.
• [out] result: قيمة منطقية تُعيّن على true إذا كان object instanceof constructor صحيحًا.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تمثل واجهة برمجة التطبيقات هذه استدعاء عامل التشغيل instanceof على الكائن كما هو محدد في القسم 12.10.4 من مواصفات لغة ECMAScript.

napi_is_array

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_is_array(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كان الكائن المعطى عبارة عن مصفوفة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تمثل واجهة برمجة التطبيقات هذه استدعاء عملية IsArray على الكائن كما هو محدد في القسم 7.2.2 من مواصفات لغة ECMAScript.

napi_is_arraybuffer

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كان الكائن المعطى عبارة عن ArrayBuffer.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق واجهة برمجة التطبيقات هذه مما إذا كان Object المُمرر عبارة عن مخزن مؤقت مصفوفة.

napi_is_buffer

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كانت napi_value المعطاة تمثل كائن node::Buffer أو Uint8Array.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق واجهة برمجة التطبيقات هذه مما إذا كان Object المُمرر عبارة عن مخزن مؤقت أو Uint8Array. يجب تفضيل napi_is_typedarray إذا احتاج المُستدعي إلى التحقق مما إذا كانت القيمة عبارة عن Uint8Array.

napi_is_date

تم الإضافة في: v11.11.0، v10.17.0

إصدار N-API: 5

napi_status napi_is_date(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كانت napi_value المعطاة تمثل كائن JavaScript Date.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق واجهة برمجة التطبيقات هذه مما إذا كان Object المُمرر عبارة عن تاريخ.

napi_is_error

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_is_error(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كانت قيمة napi_value المعطاة تمثل كائن Error.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق هذه واجهة برمجة التطبيقات مما إذا كان الكائن المُمرَّر هو كائن Error.

napi_is_typedarray

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كانت قيمة napi_value المعطاة تمثل مصفوفة مُنَوَّعَة TypedArray.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق هذه واجهة برمجة التطبيقات مما إذا كان الكائن المُمرَّر هو مصفوفة مُنَوَّعَة.

napi_is_dataview

أضيف في: v8.3.0

إصدار N-API: 1

napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: قيمة JavaScript المراد التحقق منها.
• [out] result: ما إذا كانت قيمة napi_value المعطاة تمثل DataView.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتحقق هذه واجهة برمجة التطبيقات مما إذا كان الكائن المُمرَّر هو DataView.

napi_strict_equals

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_strict_equals(napi_env env,
                               napi_value lhs,
                               napi_value rhs,
                               bool* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] lhs: قيمة JavaScript المراد التحقق منها.
• [in] rhs: قيمة JavaScript المراد المقارنة بها.
• [out] result: ما إذا كان كائنا napi_value متساويين.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تمثل هذه واجهة برمجة التطبيقات تنفيذ خوارزمية المساواة الصارمة كما هو محدد في القسم 7.2.14 من مواصفات لغة ECMAScript.

napi_detach_arraybuffer

أضيف في: v13.0.0، v12.16.0، v10.22.0

إصدار N-API: 7

napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] arraybuffer: مصفوفة JavaScript ArrayBuffer المراد فصلها.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات. إذا تم تمرير ArrayBuffer غير قابل للفصل، فإنها ترجع napi_detachable_arraybuffer_expected.

بشكل عام، يكون ArrayBuffer غير قابل للفصل إذا تم فصله من قبل. قد يفرض المحرك شروطًا إضافية حول ما إذا كان ArrayBuffer قابلًا للفصل. على سبيل المثال، يتطلب V8 أن يكون ArrayBuffer خارجيًا، أي تم إنشاؤه باستخدام napi_create_external_arraybuffer.

تمثل واجهة برمجة التطبيقات هذه استدعاء عملية فصل ArrayBuffer كما هو محدد في القسم 24.1.1.3 من مواصفات لغة ECMAScript.

napi_is_detached_arraybuffer

أضيف في: v13.3.0، v12.16.0، v10.22.0

إصدار N-API: 7

napi_status napi_is_detached_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         bool* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] arraybuffer: مصفوفة JavaScript ArrayBuffer المراد التحقق منها.
• [out] result: ما إذا كانت arraybuffer مفصولة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يُعتبر ArrayBuffer مفصولًا إذا كانت بياناته الداخلية null.

تمثل واجهة برمجة التطبيقات هذه استدعاء عملية IsDetachedBuffer الخاصة بـ ArrayBuffer كما هو محدد في القسم 24.1.1.2 من مواصفات لغة ECMAScript.

التعامل مع خصائص JavaScript

يكشف Node-API عن مجموعة من واجهات برمجة التطبيقات للحصول على خصائص كائنات JavaScript وتعيينها. تم توثيق بعض هذه الأنواع ضمن القسم 7 من مواصفات لغة ECMAScript.

يتم تمثيل الخصائص في JavaScript على أنها زوج من مفتاح وقيمة. بشكل أساسي، يمكن تمثيل جميع مفاتيح الخصائص في Node-API بأحد الأشكال التالية:

• باسم: سلسلة نصية مشفرة بـ UTF8 بسيطة
• مُفهرسة بالرقم الصحيح: قيمة فهرس ممثلة بواسطة uint32_t
• قيمة JavaScript: يتم تمثيلها في Node-API بواسطة napi_value. يمكن أن تكون napi_value تمثل سلسلة نصية (string) أو رقمًا (number) أو رمزًا (symbol).

يتم تمثيل قيم Node-API بواسطة النوع napi_value. أي استدعاء لـ Node-API يتطلب قيمة JavaScript يأخذ napi_value. ومع ذلك، تقع على عاتق المُستدعي مسؤولية التأكد من أن napi_value المعنية من نوع JavaScript المتوقع بواسطة واجهة برمجة التطبيقات.

توفر واجهات برمجة التطبيقات الموثقة في هذا القسم واجهة بسيطة للحصول على خصائص كائنات JavaScript التعسفية الممثلة بواسطة napi_value وتعيينها.

على سبيل المثال، ضع في اعتبارك مقتطف التعليمات البرمجية التالي لـ JavaScript:

const obj = {}
obj.myProp = 123

يمكن القيام بالمثيل باستخدام قيم Node-API باستخدام المقتطف التالي:

napi_status status = napi_generic_failure;

// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// إنشاء napi_value لـ 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;

// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;

يمكن تعيين الخصائص المفهرسة بطريقة مشابهة. ضع في اعتبارك مقتطف التعليمات البرمجية التالي لـ JavaScript:

const arr = []
arr[123] = 'hello'

يمكن القيام بالمثيل باستخدام قيم Node-API باستخدام المقتطف التالي:

napi_status status = napi_generic_failure;

// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// إنشاء napi_value لـ 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;

// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;

يمكن استرداد الخصائص باستخدام واجهات برمجة التطبيقات الموضحة في هذا القسم. ضع في اعتبارك مقتطف التعليمات البرمجية التالي لـ JavaScript:

const arr = []
const value = arr[123]

ما يلي هو المكافئ التقريبي لنظير Node-API:

napi_status status = napi_generic_failure;

// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;

أخيرًا، يمكن أيضًا تعريف خصائص متعددة على كائن لأسباب تتعلق بالأداء. ضع في اعتبارك ما يلي JavaScript:

const obj = {}
Object.defineProperties(obj, {
  foo: { value: 123, writable: true, configurable: true, enumerable: true },
  bar: { value: 456, writable: true, configurable: true, enumerable: true },
})

ما يلي هو المكافئ التقريبي لنظير Node-API:

napi_status status = napi_status_generic_failure;

// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// إنشاء napi_values لـ 123 و 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;

// تعيين الخصائص
napi_property_descriptor descriptors[] = {
  { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
  { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
                                obj,
                                sizeof(descriptors) / sizeof(descriptors[0]),
                                descriptors);
if (status != napi_ok) return status;

الهياكل

napi_property_attributes

[السجل]

الإصدار	التغييرات
v14.12.0	تمت إضافة napi_default_method و napi_default_property.

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // يستخدم مع napi_define_class للتمييز بين خصائص الكلاس الثابتة
  // عن خصائص مثيل الكلاس. يتم تجاهله بواسطة napi_define_properties.
  napi_static = 1 << 10,

  // الافتراضي لأساليب الكلاس.
  napi_default_method = napi_writable | napi_configurable,

  // الافتراضي لخصائص الكائن، كما هو الحال في JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes;

napi_property_attributes هي علامات تستخدم للتحكم في سلوك الخصائص المُعيّنة على كائن JavaScript. بخلاف napi_static، فإنها تتوافق مع السمات المدرجة في القسم 6.1.7.1 من مواصفات لغة ECMAScript. يمكن أن تكون إحدى علامات البت التالية أو أكثر:

• napi_default: لا يتم تعيين سمات صريحة على الخاصية. بشكل افتراضي، تكون الخاصية للقراءة فقط، وغير قابلة للعد، وغير قابلة للتكوين.
• napi_writable: الخاصية قابلة للكتابة.
• napi_enumerable: الخاصية قابلة للعد.
• napi_configurable: الخاصية قابلة للتكوين كما هو محدد في القسم 6.1.7.1 من مواصفات لغة ECMAScript.
• napi_static: سيتم تعريف الخاصية كخاصية ثابتة في الكلاس بدلاً من خاصية مثيل، وهو الافتراضي. يُستخدم هذا فقط بواسطة napi_define_class. يتم تجاهله بواسطة napi_define_properties.
• napi_default_method: مثل طريقة في كلاس JS، الخاصية قابلة للتكوين والكتابة، ولكنها غير قابلة للعد.
• napi_default_jsproperty: مثل الخاصية المُعيّنة عبر التعيين في JavaScript، الخاصية قابلة للكتابة، وقابلة للعد، وقابلة للتكوين.

napi_property_descriptor

typedef struct {
  // يجب أن يكون أحدهما utf8name أو name مساويًا لـ NULL.
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor;

• utf8name: سلسلة اختيارية تصف مفتاح الخاصية، مشفرة بتشفير UTF8. يجب توفير أحدهما utf8name أو name للخاصية.
• name: napi_value اختياري يشير إلى سلسلة نصية أو رمز JavaScript لاستخدامه كمفتاح للخاصية. يجب توفير أحدهما utf8name أو name للخاصية.
• value: القيمة التي يتم استردادها من خلال وصول get للخاصية إذا كانت الخاصية هي خاصية بيانات. إذا تم تمرير هذا، فقم بتعيين getter و setter و method و data إلى NULL (حيث لن يتم استخدام هذه الأعضاء).
• getter: دالة يتم استدعاؤها عند إجراء وصول get للخاصية. إذا تم تمرير هذا، فقم بتعيين value و method إلى NULL (حيث لن يتم استخدام هذه الأعضاء). يتم استدعاء الدالة المعطاة ضمنيًا بواسطة وقت التشغيل عندما يتم الوصول إلى الخاصية من رمز JavaScript (أو إذا تم إجراء get على الخاصية باستخدام مكالمة Node-API). يوفر napi_callback المزيد من التفاصيل.
• setter: دالة يتم استدعاؤها عند إجراء وصول set للخاصية. إذا تم تمرير هذا، فقم بتعيين value و method إلى NULL (حيث لن يتم استخدام هذه الأعضاء). يتم استدعاء الدالة المعطاة ضمنيًا بواسطة وقت التشغيل عند تعيين الخاصية من رمز JavaScript (أو إذا تم إجراء set على الخاصية باستخدام مكالمة Node-API). يوفر napi_callback المزيد من التفاصيل.
• method: قم بتعيين هذا لجعل خاصية value لكائن وصف الخاصية دالة JavaScript ممثلة بواسطة method. إذا تم تمرير هذا، فقم بتعيين value و getter و setter إلى NULL (حيث لن يتم استخدام هذه الأعضاء). يوفر napi_callback المزيد من التفاصيل.
• attributes: السمات المرتبطة بالخاصية المعينة. انظر napi_property_attributes.
• data: بيانات الاستدعاء المُمرّرة إلى method و getter و setter إذا تم استدعاء هذه الدالة.

الدوال

napi_get_property_names

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result);

• [in] env: البيئة التي يتم فيها استدعاء مكالمة Node-API.
• [in] object: الكائن الذي سيتم استرداد خصائصه منه.
• [out] result: قيمة napi_value تمثل مصفوفة من قيم JavaScript تمثل أسماء خصائص الكائن. يمكن استخدام واجهة برمجة التطبيقات للتكرار عبر result باستخدام napi_get_array_length و napi_get_element.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات أسماء الخصائص القابلة للعد من object كمصفوفة من السلاسل. لن يتم تضمين خصائص object التي يكون مفتاحها رمزًا.

napi_get_all_property_names

أضيف في: v13.7.0، v12.17.0، v10.20.0

إصدار N-API: 6

napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result);

• [in] env: البيئة التي يتم فيها استدعاء مكالمة Node-API.
• [in] object: الكائن الذي سيتم استرداد خصائصه منه.
• [in] key_mode: ما إذا كان سيتم استرداد خصائص النموذج الأولي أيضًا.
• [in] key_filter: الخصائص التي سيتم استردادها (قابلة للعد/قراءة/كتابة).
• [in] key_conversion: ما إذا كان سيتم تحويل مفاتيح خصائص الأرقام إلى سلاسل.
• [out] result: قيمة napi_value تمثل مصفوفة من قيم JavaScript تمثل أسماء خصائص الكائن. يمكن استخدام napi_get_array_length و napi_get_element للتكرار عبر result.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات مصفوفة تحتوي على أسماء الخصائص المتاحة لهذا الكائن.

napi_set_property

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم تعيين الخاصية عليه.
• [in] key: اسم الخاصية التي سيتم تعيينها.
• [in] value: قيمة الخاصية.

يرجع napi_ok إذا نجح API.

يُعيّن هذا الـ API خاصية على الكائن المُمرَّر.

napi_get_property

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم استرداد الخاصية منه.
• [in] key: اسم الخاصية التي سيتم استردادها.
• [out] result: قيمة الخاصية.

يرجع napi_ok إذا نجح API.

يسترد هذا الـ API الخاصية المطلوبة من الكائن المُمرَّر.

napi_has_property

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استعلامه.
• [in] key: اسم الخاصية التي سيتم التحقق من وجودها.
• [out] result: ما إذا كانت الخاصية موجودة في الكائن أم لا.

يرجع napi_ok إذا نجح API.

يُحقق هذا الـ API ما إذا كان الكائن المُمرَّر يحتوي على الخاصية المسمّاة.

napi_delete_property

تم الإضافة في: v8.2.0

إصدار N-API: 1

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استعلامه.
• [in] key: اسم الخاصية التي سيتم حذفها.
• [out] result: ما إذا نجح حذف الخاصية أم لا. يمكن تجاهل result اختياريًا عن طريق تمرير NULL.

يرجع napi_ok إذا نجح API.

يحاول هذا الـ API حذف الخاصية key من object.

napi_has_own_property

مضاف في: v8.2.0

نسخة N-API: 1

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استعلامه.
• [in] key: اسم الخاصية المراد التحقق من وجودها.
• [out] result: هل توجد الخاصية في الكائن أم لا.

يعيد napi_ok إذا نجحت واجهة البرمجة.

تتحقق هذه واجهة البرمجة من وجود الخاصية المحددة في الكائن المُمرر. يجب أن يكون key من نوع string أو symbol، وإلا سيتم إرسال خطأ. لن تقوم Node-API بأي تحويل بين أنواع البيانات.

napi_set_named_property

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم تعيين الخاصية عليه.
• [in] utf8Name: اسم الخاصية التي سيتم تعيينها.
• [in] value: قيمة الخاصية.

يعيد napi_ok إذا نجحت واجهة البرمجة.

تُعادل هذه الطريقة استدعاء napi_set_property باستخدام napi_value تم إنشاؤه من السلسلة المُمررة كـ utf8Name.

napi_get_named_property

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم استرداد الخاصية منه.
• [in] utf8Name: اسم الخاصية التي سيتم الحصول عليها.
• [out] result: قيمة الخاصية.

يعيد napi_ok إذا نجحت واجهة البرمجة.

تُعادل هذه الطريقة استدعاء napi_get_property باستخدام napi_value تم إنشاؤه من السلسلة المُمررة كـ utf8Name.

napi_has_named_property

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استفساره.
• [in] utf8Name: اسم الخاصية التي سيتم التحقق من وجودها.
• [out] result: ما إذا كانت الخاصية موجودة في الكائن أم لا.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

هذه الطريقة تعادل استدعاء napi_has_property بقيمة napi_value تم إنشاؤها من السلسلة الممررة كـ utf8Name.

napi_set_element

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم تعيين خصائصه منه.
• [in] index: مؤشر الخاصية التي سيتم تعيينها.
• [in] value: قيمة الخاصية.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بتعيين عنصر على كائن Object الممرر.

napi_get_element

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم استرداد الخاصية منه.
• [in] index: مؤشر الخاصية التي سيتم الحصول عليها.
• [out] result: قيمة الخاصية.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تحصل هذه واجهة برمجة التطبيقات على العنصر في المؤشر المطلوب.

napi_has_element

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استفساره.
• [in] index: مؤشر الخاصية التي سيتم التحقق من وجودها.
• [out] result: ما إذا كانت الخاصية موجودة في الكائن أم لا.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات ما إذا كان الكائن Object الممرر يحتوي على عنصر في المؤشر المطلوب.

napi_delete_element

أضيف في: v8.2.0

إصدار N-API: 1

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد استعلامه.
• [in] index: مُؤشر الخاصية المراد حذفها.
• [out] result: ما إذا نجح حذف العنصر أم لا. يمكن تجاهل result اختياريًا عن طريق تمرير NULL.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تحاول هذه واجهة برمجة التطبيقات حذف index المحدد من object.

napi_define_properties

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن الذي سيتم استرداد الخصائص منه.
• [in] property_count: عدد العناصر في مصفوفة properties.
• [in] properties: مصفوفة من مُوصِفات الخصائص.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسمح هذه الطريقة بتعريف العديد من الخصائص بكفاءة على كائن معين. يتم تعريف الخصائص باستخدام مُوصِفات الخصائص (انظر napi_property_descriptor). بالنظر إلى مصفوفة من مُوصِفات الخصائص هذه، ستقوم هذه واجهة برمجة التطبيقات بتعيين الخصائص على الكائن واحداً تلو الآخر، كما هو مُعرّف بواسطة DefineOwnProperty() (موصوف في القسم 9.1.6 من مواصفات ECMA-262).

napi_object_freeze

أضيف في: v14.14.0، v12.20.0

إصدار N-API: 8

napi_status napi_object_freeze(napi_env env,
                               napi_value object);

• [in] env: بيئة استدعاء Node-API.
• [in] object: الكائن المراد تجميده.

يُرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تجمد هذه الطريقة كائنًا معينًا. هذا يمنع إضافة خصائص جديدة إليه، أو إزالة خصائص موجودة، أو تغيير قابلية تعداد الخصائص الموجودة، أو قابليتها للتكوين، أو قابلية كتابتها، ويمنع تغيير قيم الخصائص الموجودة. كما يمنع تغيير نموذج الكائن. هذا موصوف في القسم 19.1.2.6 من مواصفات ECMA-262.

napi_object_seal

أضيف في: v14.14.0، v12.20.0

إصدار N-API: 8

napi_status napi_object_seal(napi_env env,
                             napi_value object);

• [in] env: بيئة استدعاء مكالمة Node-API.
• [in] object: الكائن الذي سيتم إغلاقه.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه الطريقة بإغلاق كائن معين. هذا يمنع إضافة خصائص جديدة إليه، بالإضافة إلى وضع علامة على جميع الخصائص الموجودة على أنها غير قابلة للتكوين. وهذا موضح في القسم 19.1.2.20 من مواصفات ECMA-262.

العمل مع دوال JavaScript

يوفر Node-API مجموعة من واجهات برمجة التطبيقات التي تسمح لرمز JavaScript بالاتصال مرة أخرى بالرمز الأصلي. تأخذ واجهات برمجة تطبيقات Node التي تدعم الاتصال مرة أخرى بالرمز الأصلي دوال استدعاء مُمثلة بنوع napi_callback. عندما يقوم جهاز VM في JavaScript بالاتصال مرة أخرى بالرمز الأصلي، يتم استدعاء دالة napi_callback المُقدمة. تسمح واجهات برمجة التطبيقات الموثقة في هذا القسم لدالة الاستدعاء بما يلي:

• الحصول على معلومات حول السياق الذي تم فيه استدعاء الاستدعاء.
• الحصول على الوسائط المُمررة إلى الاستدعاء.
• إرجاع napi_value من الاستدعاء.

بالإضافة إلى ذلك، يوفر Node-API مجموعة من الدوال التي تسمح باستدعاء دوال JavaScript من الرمز الأصلي. يمكن للمرء إما استدعاء دالة مثل استدعاء دالة JavaScript عادي، أو كدالة منشئ.

يمكن ربط أي بيانات غير فارغة NULL يتم تمريرها إلى واجهة برمجة التطبيقات هذه عبر حقل data من عناصر napi_property_descriptor بـ object وإطلاق سراحها كلما تم جمع القمامة object عن طريق تمرير كل من object والبيانات إلى napi_add_finalizer.

napi_call_function

أضيف في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_call_function(napi_env env,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] recv: قيمة this المُمررة إلى الدالة المُستدعاه.
• [in] func: napi_value يمثل دالة JavaScript التي سيتم استدعاؤها.
• [in] argc: عدد العناصر في مصفوفة argv.
• [in] argv: مصفوفة من napi_values تمثل قيم JavaScript المُمررة كوسائط إلى الدالة.
• [out] result: napi_value يمثل كائن JavaScript المُرجع.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسمح هذه الطريقة باستدعاء كائن دالة JavaScript من إضافة أصلية. هذه هي الآلية الأساسية للاتصال من الرمز الأصلي للإضافة إلى JavaScript. في حالة خاصة الاتصال بـ JavaScript بعد عملية غير متزامنة، راجع napi_make_callback.

قد تبدو حالة استخدام نموذجية كما يلي. ضع في اعتبارك مقتطف JavaScript التالي:

function AddTwo(num) {
  return num + 2
}
global.AddTwo = AddTwo

ثم، يمكن استدعاء الدالة أعلاه من إضافة أصلية باستخدام التعليمات البرمجية التالية:

// الحصول على الدالة المسماة "AddTwo" على الكائن العام
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;

// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;

// تحويل النتيجة مرة أخرى إلى نوع أصلي
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;

napi_create_function

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] utf8Name: اسم اختياري للدالة مشفر بتنسيق UTF8. يظهر هذا ضمن JavaScript كخاصية name لكائن الدالة الجديد.
• [in] length: طول utf8name بالبايت، أو NAPI_AUTO_LENGTH إذا كان منتهيًا بـ null.
• [in] cb: الدالة الأصلية التي يجب استدعاءها عند استدعاء كائن هذه الدالة. يوفر napi_callback مزيدًا من التفاصيل.
• [in] data: سياق بيانات مقدم من المستخدم. سيتم إعادة تمريره إلى الدالة عند استدعائها لاحقًا.
• [out] result: napi_value يمثل كائن دالة JavaScript للدالة التي تم إنشاؤها حديثًا.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تتيح هذه واجهة برمجة التطبيقات لمؤلف الإضافة إنشاء كائن دالة في الكود الأصلي. هذه هي الآلية الأساسية للسماح بالاتصال بـ داخل الكود الأصلي للإضافة من JavaScript.

الدالة التي تم إنشاؤها حديثًا ليست مرئية تلقائيًا من البرنامج النصي بعد هذه المكالمة. بدلاً من ذلك، يجب تعيين خاصية بشكل صريح على أي كائن مرئي لـ JavaScript، لكي تصبح الدالة قابلة للوصول من البرنامج النصي.

لكي تعرض دالة كجزء من صادرات وحدة الإضافة، قم بتعيين الدالة التي تم إنشاؤها حديثًا على كائن الصادرات. قد تبدو وحدة نموذجية كما يلي:

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;

  napi_value fn;
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

بافتراض الكود أعلاه، يمكن استخدام الإضافة من JavaScript كما يلي:

const myaddon = require('./addon')
myaddon.sayHello()

السلسلة الممررة إلى require() هي اسم الهدف في binding.gyp المسؤول عن إنشاء ملف .node.

أي بيانات غير NULL يتم تمريرها إلى هذه واجهة برمجة التطبيقات عبر المعلمة data يمكن ربطها بدالة JavaScript الناتجة (التي يتم إرجاعها في معلمة result) وإطلاقها كلما تم جمع القمامة للدالة عن طريق تمرير كل من دالة JavaScript والبيانات إلى napi_add_finalizer.

تم وصف دالات JavaScript Function في القسم 19.2 من مواصفات لغة ECMAScript.

napi_get_cb_info

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* thisArg,
                             void** data)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] cbinfo: معلومات الاستدعاء المُمرّرة إلى دالة الاستدعاء.
• [in-out] argc: يحدد طول مصفوفة argv المُقدّمة ويتلقى العدد الفعلي للحجج. يمكن تجاهل argc اختياريًا عن طريق تمرير NULL.
• [out] argv: مصفوفة C من نوع napi_value سيتم نسخ الحجج إليها. إذا كان هناك المزيد من الحجج من العدد المُقدّم، فسيتم نسخ عدد الحجج المطلوبة فقط. إذا كان هناك عدد أقل من الحجج المُقدّمة من المُدّعى به، فسيتم ملء باقي argv بقيم napi_value تمثل undefined. يمكن تجاهل argv اختياريًا عن طريق تمرير NULL.
• [out] thisArg: يتلقى حجة JavaScript this للاتصال. يمكن تجاهل thisArg اختياريًا عن طريق تمرير NULL.
• [out] data: يتلقى مؤشر البيانات للاستدعاء. يمكن تجاهل data اختياريًا عن طريق تمرير NULL.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تُستخدم هذه الطريقة داخل دالة الاستدعاء لاسترداد تفاصيل حول الاتصال مثل الحجج ومؤشر this من معلومات استدعاء مُعطاة.

napi_get_new_target

تم الإضافة في: v8.6.0

إصدار N-API: 1

napi_status napi_get_new_target(napi_env env,
                                napi_callback_info cbinfo,
                                napi_value* result)

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] cbinfo: معلومات الاستدعاء المُمرّرة إلى دالة الاستدعاء.
• [out] result: new.target لاتصال المُنشئ.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات new.target لاتصال المُنشئ. إذا لم يكن الاستدعاء الحالي عبارة عن اتصال مُنشئ، فإن النتيجة هي NULL.

napi_new_instance

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_new_instance(napi_env env,
                              napi_value cons,
                              size_t argc,
                              napi_value* argv,
                              napi_value* result)

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] cons: napi_value يمثل دالة جافا سكريبت التي سيتم استدعائها كمنشئ.
• [in] argc: عدد العناصر في مصفوفة argv.
• [in] argv: مصفوفة من قيم جافا سكريبت كـ napi_value تمثل الوسائط للمنشئ. إذا كانت argc تساوي صفرًا، فيمكن حذف هذه المعلمة عن طريق تمرير NULL.
• [out] result: napi_value يمثل كائن جافا سكريبت المُرجع، والذي في هذه الحالة هو الكائن المُنشأ.

تُستخدم هذه الطريقة لإنشاء قيمة جافا سكريبت جديدة باستخدام napi_value معين يمثل المنشئ للكائن. على سبيل المثال، ضع في اعتبارك المقتطف التالي:

function MyObject(param) {
  this.param = param
}

const arg = 'hello'
const value = new MyObject(arg)

يمكن تقريب ما يلي في Node-API باستخدام المقتطف التالي:

// الحصول على دالة المنشئ MyObject
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;

// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تغليف الكائن

يوفر Node-API طريقة "لتغليف" فئات C++ وحالاتها بحيث يمكن استدعاء منشئ الفئة والطرق من جافا سكريبت.

بالنسبة للكائنات المُغلّفة، قد يكون من الصعب التمييز بين دالة مُستدعَاة على نموذج أولي للفئة ودالة مُستدعَاة على مثيل لفئة. نمط شائع يُستخدم لمعالجة هذه المشكلة هو حفظ مرجع دائم لمنشئ الفئة للتحقق من instanceof لاحقًا.

napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
  // napi_unwrap() ...
} else {
  // otherwise...
}

يجب تحرير المرجع بمجرد عدم الحاجة إليه.

هناك مناسبات يكون فيها napi_instanceof() غير كافٍ لضمان أن كائن جافا سكريبت هو غلاف لنوع أصلي معين. هذه هي الحالة خاصة عندما يتم تمرير كائنات جافا سكريبت المُغلّفة مرة أخرى إلى الإضافة عبر طرق ثابتة بدلاً من قيمة this لأساليب النموذج الأولي. في مثل هذه الحالات، هناك فرصة لإلغاء تغليفها بشكل غير صحيح.

const myAddon = require('./build/Release/my_addon.node')

// `openDatabase()` ترجع كائن جافا سكريبت يلف مقبض قاعدة بيانات أصلي.
const dbHandle = myAddon.openDatabase()

// `query()` ترجع كائن جافا سكريبت يلف مقبض استعلام أصلي.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')

// هناك خطأ عرضي في السطر أدناه. يجب أن تكون المعلمة الأولى لـ
// `myAddon.queryHasRecords()` هي مقبض قاعدة البيانات (`dbHandle`)، وليس
// مقبض الاستعلام (`query`)، لذلك يجب أن تكون الحالة الصحيحة لحلقة while هي
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // استرداد السجلات
}

في المثال أعلاه، myAddon.queryHasRecords() هي طريقة تقبل وسيطين. الأول هو مقبض قاعدة البيانات والثاني هو مقبض الاستعلام. داخليًا، يقوم بإلغاء تغليف الوسيطة الأولى ويرمي المؤشر الناتج إلى مقبض قاعدة بيانات أصلي. ثم يقوم بإلغاء تغليف الوسيطة الثانية ويرمي المؤشر الناتج إلى مقبض استعلام. إذا تم تمرير الوسائط بالترتيب الخاطئ، فستعمل عمليات الإلقاء، ومع ذلك، هناك فرصة جيدة لفشل عملية قاعدة البيانات الأساسية، أو حتى أن تسبب وصولاً غير صالح للذاكرة.

لتأكيد أن المؤشر المسترد من الوسيطة الأولى هو بالفعل مؤشر إلى مقبض قاعدة بيانات، وبالمثل، أن المؤشر المسترد من الوسيطة الثانية هو بالفعل مؤشر إلى مقبض استعلام، يجب أن يقوم تنفيذ queryHasRecords() بالتحقق من النوع. يمكن أن يساعد الاحتفاظ بمنشئ فئة جافا سكريبت الذي تم إنشاء مقبض قاعدة البيانات منه والمنشئ الذي تم إنشاء مقبض الاستعلام منه في napi_refs، لأن napi_instanceof() يمكن استخدامه بعد ذلك للتأكد من أن الحالات التي تم تمريرها إلى queryHashRecords() هي بالفعل من النوع الصحيح.

لسوء الحظ، لا يحمي napi_instanceof() من معالجة النموذج الأولي. على سبيل المثال، يمكن تعيين النموذج الأولي لمثيل مقبض قاعدة البيانات إلى النموذج الأولي لمنشئات حالات مقبض الاستعلام. في هذه الحالة، قد يبدو مثيل مقبض قاعدة البيانات كمثيل مقبض استعلام، وسيجتاز اختبار napi_instanceof() لمثيل مقبض استعلام، مع احتوائه لا يزال على مؤشر إلى مقبض قاعدة بيانات.

لهذه الغاية، يوفر Node-API إمكانيات وضع علامات على الأنواع.

علامة النوع هي عدد صحيح مكون من 128 بت فريد للإضافة. يوفر Node-API بنية napi_type_tag لتخزين علامة النوع. عندما يتم تمرير مثل هذه القيمة مع كائن جافا سكريبت أو خارجي مخزّن في napi_value إلى napi_type_tag_object()، سيتم "وضع علامة" على كائن جافا سكريبت بعلامة النوع. العلامة غير مرئية على جانب جافا سكريبت. عندما يصل كائن جافا سكريبت إلى ارتباط أصلي، يمكن استخدام napi_check_object_type_tag() مع علامة النوع الأصلية لتحديد ما إذا كان كائن جافا سكريبت قد تم "وضع علامة" عليه مسبقًا بعلامة النوع. هذا يخلق إمكانية للتحقق من النوع بدقة أعلى مما يمكن أن يوفره napi_instanceof()، لأن هذا النوع من وضع العلامات يبقى بعد معالجة النموذج الأولي وتفريغ الإضافة/إعادة تحميلها.

باستمرار المثال أعلاه، يوضح هيكل تنفيذ الإضافة التالي استخدام napi_type_tag_object() و napi_check_object_type_tag().

// هذه القيمة هي علامة النوع لمقبض قاعدة البيانات. الأمر
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// يمكن استخدامه للحصول على القيمتين اللتين سيتم تهيئة البنية بهما.
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// هذه القيمة هي علامة النوع لمقبض الاستعلام.
static const napi_type_tag QueryHandleTypeTag = {
  0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};

static napi_value
openDatabase(napi_env env, napi_callback_info info) {
  napi_status status;
  napi_value result;

  // تنفيذ الإجراء الأساسي الذي ينتج عنه مقبض قاعدة بيانات.
  DatabaseHandle* dbHandle = open_database();

  // إنشاء كائن JS جديد فارغ.
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // وضع علامة على الكائن للإشارة إلى أنه يحتوي على مؤشر إلى `DatabaseHandle`.
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // تخزين المؤشر إلى بنية `DatabaseHandle` داخل كائن JS.
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// لاحقًا عندما نتلقى كائن جافا سكريبت يدعي أنه مقبض قاعدة بيانات
// يمكننا استخدام `napi_check_object_type_tag()` للتأكد من أنه بالفعل مثل هذا
// المقبض.

static napi_value
query(napi_env env, napi_callback_info info) {
  napi_status status;
  size_t argc = 2;
  napi_value argv[2];
  bool is_db_handle;

  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
  if (status != napi_ok) return NULL;

  // التحقق من أن الكائن الذي تم تمريره كمعلمة أولى له العلامة المطبقة مسبقًا.
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // طرح `TypeError` إذا لم يكن كذلك.
  if (!is_db_handle) {
    // طرح TypeError.
    return NULL;
  }
}

napi_define_class

أضيف في: v8.0.0

إصدار N-API: 1

napi_status napi_define_class(napi_env env,
                              const char* utf8name,
                              size_t length,
                              napi_callback constructor,
                              void* data,
                              size_t property_count,
                              const napi_property_descriptor* properties,
                              napi_value* result);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] utf8name: اسم دالة مُنشئ جافا سكريبت. للوضوح، يُنصح باستخدام اسم فئة C++ عند تغليف فئة C++.
• [in] length: طول utf8name بالبايت، أو NAPI_AUTO_LENGTH إذا كان مُنتهيًا بالصفر.
• [in] constructor: دالة الاستدعاء التي تُعالِج إنشاء مثيلات الفئة. عند تغليف فئة C++، يجب أن تكون هذه الطريقة عضوًا ثابتًا بتوقيع napi_callback. لا يمكن استخدام مُنشئ فئة C++. يوفر napi_callback المزيد من التفاصيل.
• [in] data: بيانات اختيارية سيتم تمريرها إلى دالة استدعاء المُنشئ كخاصية data لمعلومات الاستدعاء.
• [in] property_count: عدد العناصر في وسيطة المصفوفة properties.
• [in] properties: مصفوفة من واصفات الخصائص التي تصف خصائص البيانات الثابتة وحالاتها، والمتغيرات، والطرق في الفئة. انظر napi_property_descriptor.
• [out] result: قيمة napi_value تمثل دالة المُنشئ للفئة.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يُعرّف فئة جافا سكريبت، بما في ذلك:

• دالة مُنشئ جافا سكريبت لها اسم الفئة. عند تغليف فئة C++ المقابلة، يمكن استخدام دالة الاستدعاء المُمرّرة عبر constructor لإنشاء مثيل جديد لفئة C++، والذي يمكن بعد ذلك وضعه داخل مثيل كائن جافا سكريبت الذي يتم إنشاؤه باستخدام napi_wrap.
• الخصائص الموجودة على دالة المُنشئ التي يمكن لتنفيذها أن تستدعي خصائص البيانات الثابتة المقابلة، والمتغيرات، والطرق لفئة C++ (المُعرّفة بواسطة واصفات الخصائص ذات السمة napi_static).
• خصائص كائن prototype لدالة المُنشئ. عند تغليف فئة C++، يمكن استدعاء خصائص البيانات غير الثابتة، والمتغيرات، والطرق لفئة C++ من الدوال الثابتة الواردة في واصفات الخصائص بدون السمة napi_static بعد استرداد مثيل فئة C++ الموجود داخل مثيل كائن جافا سكريبت باستخدام napi_unwrap.

عند تغليف فئة C++، يجب أن تكون دالة استدعاء مُنشئ C++ المُمرّرة عبر constructor طريقة ثابتة في الفئة تستدعي مُنشئ الفئة الفعلي، ثم تُغلف مثيل C++ الجديد في كائن جافا سكريبت، وتُعيد كائن المُغلّف. انظر napi_wrap للحصول على التفاصيل.

غالبًا ما يتم حفظ دالة مُنشئ جافا سكريبت المُرجع من napi_define_class واستخدامها لاحقًا لإنشاء مثيلات جديدة للفئة من التعليمات البرمجية الأصلية، و/أو للتحقق مما إذا كانت القيم المُقدّمة هي مثيلات للفئة. في هذه الحالة، لمنع فقدان قيمة الدالة، يمكن إنشاء مرجع دائم قوي لها باستخدام napi_create_reference، مما يضمن أن عدد المراجع يُحفظ >= 1.

يمكن ربط أي بيانات غير NULL يتم تمريرها إلى هذه واجهة برمجة التطبيقات عبر وسيطة data أو عبر حقل data من عناصر مصفوفة napi_property_descriptor مع مُنشئ جافا سكريبت الناتج (الذي يُرجع في وسيطة result) وتحريره كلما تم جمع القمامة للفئة عن طريق تمرير كل من دالة جافا سكريبت والبيانات إلى napi_add_finalizer.

napi_wrap

مضاف في: v8.0.0

نسخة N-API: 1

napi_status napi_wrap(napi_env env,
                      napi_value js_object,
                      void* native_object,
                      napi_finalize finalize_cb,
                      void* finalize_hint,
                      napi_ref* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] js_object: كائن JavaScript الذي سيكون الغلاف للكائن الأصلي.
• [in] native_object: مثيل أصلي سيتم تضمينه في كائن JavaScript.
• [in] finalize_cb: مُنعطف أصلي اختياري يمكن استخدامه لتحرير مثيل أصلي عند جمع كائن JavaScript بواسطة Garbage Collector. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_hint: تلميح سياقي اختياري يتم تمريره إلى مُنعطف الإنهاء.
• [out] result: مرجع اختياري للكائن المُغلف.

يُعيد napi_ok إذا نجحت واجهة برمجة التطبيقات.

يُغلف مثيلاً أصلياً في كائن JavaScript. يمكن استرداد المثيل الأصلي لاحقًا باستخدام napi_unwrap().

عندما يستدعي رمز JavaScript مُنشئًا لفئة تم تعريفها باستخدام napi_define_class(), يتم استدعاء napi_callback للمُنشئ. بعد إنشاء مثيل من الفئة الأصلية، يجب على المُنعطف بعد ذلك استدعاء napi_wrap() لتغليف المثيل المُنشأ حديثًا في كائن JavaScript المُنشأ بالفعل والذي يُعد وسيطة this لمُنعطف المُنشئ. (تم إنشاء كائن this من prototype دالة المُنشئ، لذلك يحتوي بالفعل على تعاريف لجميع خصائص ومُنعطفات المثيل).

عادةً عند تغليف مثيل فئة، يجب توفير مُنعطف إنهاء يحذف ببساطة المثيل الأصلي الذي يتم استلامه كوسيطة data إلى مُنعطف الإنهاء.

يُعد المرجع المُرجع المُرجع اختياريًا في البداية مرجعًا ضعيفًا، مما يعني أنه يحتوي على عداد مرجعي يساوي 0. عادةً ما يتم زيادة عدد المرجع هذا مؤقتًا أثناء العمليات غير المتزامنة التي تتطلب بقاء المثيل صالحًا.

تحذير: يجب حذف المرجع المُرجع المُرجع الاختياري (إذا تم الحصول عليه) عبر napi_delete_reference فقط استجابةً لاستدعاء مُنعطف الإنهاء. إذا تم حذفه قبل ذلك، فقد لا يتم استدعاء مُنعطف الإنهاء أبدًا. لذلك، عند الحصول على مرجع، يلزم أيضًا مُنعطف إنهاء لتمكين التخلص الصحيح من المرجع.

قد يتم تأجيل مُنعطفات المُنهي، تاركة نافذة حيث تم جمع كائن القمامة (والمرجع الضعيف غير صالح) لكن لم يتم استدعاء المُنهي بعد. عند استخدام napi_get_reference_value() على المراجع الضعيفة التي تُرجعها napi_wrap(), يجب عليك معالجة نتيجة فارغة.

سيؤدي استدعاء napi_wrap() مرة ثانية على كائن إلى إرجاع خطأ. لربط مثيل أصلي آخر بالكائن، استخدم napi_remove_wrap() أولاً.

napi_unwrap

تم الإضافة في: v8.0.0

نسخة N-API: 1

napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] js_object: الكائن المرتبط بالمثيل الأصلي.
• [out] result: مؤشر إلى مثيل أصلي مُغلف.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسترد مثيلًا أصليًا تم تغليفه مسبقًا في كائن JavaScript باستخدام napi_wrap().

عندما يستدعي رمز JavaScript طريقة أو مُحسّن خاصية في الفئة، يتم استدعاء napi_callback المُقابلة. إذا كانت المُراجعة لطريقة أو مُحسّن مثيل، فإن وسيطة this للمراجعة هي كائن المُغلف؛ يمكن الحصول على مثيل C++ المُغلف الذي هو هدف المُكالمة بعد ذلك من خلال استدعاء napi_unwrap() على كائن المُغلف.

napi_remove_wrap

تم الإضافة في: v8.5.0

نسخة N-API: 1

napi_status napi_remove_wrap(napi_env env,
                             napi_value js_object,
                             void** result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] js_object: الكائن المرتبط بالمثيل الأصلي.
• [out] result: مؤشر إلى مثيل أصلي مُغلف.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسترد مثيلًا أصليًا تم تغليفه مسبقًا في كائن JavaScript js_object باستخدام napi_wrap() وتزيل التغليف. إذا تم ربط مراجعة إنهاء بالتغليف، فلن يتم استدعائها بعد الآن عندما يصبح كائن JavaScript قمامة.

napi_type_tag_object

تم الإضافة في: v14.8.0، v12.19.0

نسخة N-API: 8

napi_status napi_type_tag_object(napi_env env,
                                 napi_value js_object,
                                 const napi_type_tag* type_tag);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] js_object: كائن JavaScript أو خارجي ليتم تمييزه.
• [in] type_tag: العلامة التي سيتم تمييز الكائن بها.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تربط قيمة مؤشر type_tag بكائن JavaScript أو خارجي. يمكن بعد ذلك استخدام napi_check_object_type_tag() لمقارنة العلامة التي تم إرفاقها بالكائن مع علامة مملوكة للإضافة لضمان أن الكائن من النوع الصحيح.

إذا كان الكائن يحتوي بالفعل على علامة نوع مرتبطة، فستعيد واجهة برمجة التطبيقات هذه napi_invalid_arg.

napi_check_object_type_tag

أضيف في: v14.8.0، v12.19.0

نسخة N-API: 8

napi_status napi_check_object_type_tag(napi_env env,
                                       napi_value js_object,
                                       const napi_type_tag* type_tag,
                                       bool* result);

• [in] env: بيئة استدعاء واجهة البرمجة التطبيقيّة.
• [in] js_object: كائن جافا سكريبت أو خارجي لفحص علامة نوعه.
• [in] type_tag: العلامة التي سيتمّ مقارنتها بأيّ علامة موجودة على الكائن.
• [out] result: ما إذا كانت علامة النوع المُعطاة تطابق علامة النوع الموجودة على الكائن. يتمّ أيضًا إرجاع false إذا لم يتمّ العثور على علامة نوع على الكائن.

يرجع napi_ok إذا نجحت واجهة البرمجة التطبيقيّة.

يقارن المؤشر المُعطى كـ type_tag بأي مؤشر يمكن العثور عليه في js_object. إذا لم يتمّ العثور على أيّ علامة في js_object، أو إذا تمّ العثور على علامة ولكنّها لا تطابق type_tag، فسيتمّ تعيين result إلى false. إذا تمّ العثور على علامة وتطابق type_tag، فسيتمّ تعيين result إلى true.

napi_add_finalizer

أضيف في: v8.0.0

نسخة N-API: 5

napi_status napi_add_finalizer(napi_env env,
                               napi_value js_object,
                               void* finalize_data,
                               node_api_basic_finalize finalize_cb,
                               void* finalize_hint,
                               napi_ref* result);

• [in] env: بيئة استدعاء واجهة البرمجة التطبيقيّة.
• [in] js_object: كائن جافا سكريبت الذي سيتمّ إرفاق البيانات الأصلية به.
• [in] finalize_data: بيانات اختيارية سيتمّ تمريرها إلى finalize_cb.
• [in] finalize_cb: مُنادٍ أصلي سيتمّ استخدامه لتحرير البيانات الأصلية عندما يتمّ جمع كائن جافا سكريبت بواسطة المُجمع القمّام. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_hint: تلميح سياقي اختياري يتمّ تمريره إلى مُنادٍ النهائي.
• [out] result: مرجع اختياري لكائن جافا سكريبت.

يرجع napi_ok إذا نجحت واجهة البرمجة التطبيقيّة.

يضيف مُنادٍ napi_finalize والذي سيتمّ استدعاؤه عندما يتمّ جمع كائن جافا سكريبت في js_object بواسطة المُجمع القمّام.

يمكن استدعاء واجهة البرمجة التطبيقيّة هذه عدة مرات على كائن جافا سكريبت واحد.

تحذير: يجب حذف المرجع المُرجع الاختياري (إذا تمّ الحصول عليه) عبر napi_delete_reference فقط استجابةً لاستدعاء المُنادٍ النهائي. إذا تمّ حذفه قبل ذلك، فقد لا يتمّ استدعاء المُنادٍ النهائي أبدًا. لذلك، عند الحصول على مرجع، يلزم أيضًا مُنادٍ نهائي لتمكين التخلّص الصحيح من المرجع.

node_api_post_finalizer

أضيف في: v21.0.0، v20.10.0، v18.19.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1 - تجريبي

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint);

• [in] env: البيئة التي يتم فيها استدعاء واجهة برمجة التطبيقات.
• [in] finalize_cb: استدعاء وظيفة أصلي سيتم استخدامه لتحرير البيانات الأصلية عندما يتم جمع كائن JavaScript بواسطة مَجمّع القمامة. يوفر napi_finalize المزيد من التفاصيل.
• [in] finalize_data: بيانات اختيارية سيتم تمريرها إلى finalize_cb.
• [in] finalize_hint: تلميح سياقي اختياري يتم تمريره إلى استدعاء وظيفة الإنهاء.

يعيد napi_ok إذا نجحت واجهة برمجة التطبيقات.

يُحدد جدولة استدعاء وظيفة napi_finalize بشكل غير متزامن في حلقة الأحداث.

عادةً، يتم استدعاء مُنهيات العملية أثناء قيام مَجمّع القمامة (GC) بجمع الكائنات. في تلك المرحلة، سيتم تعطيل استدعاء أي واجهة برمجة تطبيقات Node قد تسبب تغييرات في حالة GC، وسيتسبب ذلك في تعطل Node.js.

يساعد node_api_post_finalizer على تجاوز هذا القيد من خلال السماح للإضافة بتأجيل المكالمات إلى واجهات برمجة تطبيقات Node هذه إلى نقطة زمنية خارج عملية إنهاء GC.

عمليات غير متزامنة بسيطة

غالبًا ما تحتاج وحدات الإضافة إلى الاستفادة من المساعدين غير المتزامنين من libuv كجزء من تنفيذها. يسمح هذا لهم بجدولة العمل ليتم تنفيذه بشكل غير متزامن بحيث يمكن لأساليبهم أن تعود قبل اكتمال العمل. يسمح لهم هذا بتجنب حظر التنفيذ العام لتطبيق Node.js.

توفر Node-API واجهة مستقرة على مستوى ABI لهذه الوظائف الداعمة والتي تغطي أكثر حالات الاستخدام غير المتزامنة شيوعًا.

يُعرّف Node-API بنية napi_async_work التي تُستخدم لإدارة عمال غير متزامنين. يتم إنشاء/حذف مثيلات باستخدام napi_create_async_work و napi_delete_async_work.

استدعاءات الوظائف execute و complete هي وظائف سيتم استدعاؤها عندما يكون المُنفذ جاهزًا للتنفيذ وعندما يكمل مهمته على التوالي.

يجب أن تتجنب دالة execute إجراء أي مكالمات لواجهة برمجة تطبيقات Node قد تؤدي إلى تنفيذ JavaScript أو التفاعل مع كائنات JavaScript. في أغلب الأحيان، يجب إجراء أي رمز يحتاج إلى إجراء مكالمات واجهة برمجة تطبيقات Node في استدعاء الوظيفة complete بدلاً من ذلك. تجنب استخدام معلمة napi_env في استدعاء الوظيفة execute لأنه من المحتمل أن يقوم بتنفيذ JavaScript.

تقوم هذه الوظائف بتنفيذ واجهات البرمجة التالية:

typedef void (*napi_async_execute_callback)(napi_env env,
                                            void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data);

عندما يتم استدعاء هذه الأساليب، ستكون معلمة data المُمررة هي بيانات void* التي وفرتها الإضافة والتي تم تمريرها إلى استدعاء napi_create_async_work.

بمجرد إنشاء العامل غير المتزامن، يمكن وضعه في قائمة الانتظار للتنفيذ باستخدام دالة napi_queue_async_work:

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

يمكن استخدام napi_cancel_async_work إذا كان العمل بحاجة إلى إلغائه قبل بدء تنفيذ العمل.

بعد استدعاء napi_cancel_async_work، سيتم استدعاء استدعاء الوظيفة complete بقيمة حالة napi_cancelled. يجب عدم حذف العمل قبل استدعاء استدعاء الوظيفة complete، حتى عندما تم إلغاؤه.

napi_create_async_work

[السجل]

الإصدار	التغييرات
v8.6.0	تمت إضافة معلماتي async_resource و async_resource_name.
v8.0.0	تمت الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_create_async_work(napi_env env,
                                   napi_value async_resource,
                                   napi_value async_resource_name,
                                   napi_async_execute_callback execute,
                                   napi_async_complete_callback complete,
                                   void* data,
                                   napi_async_work* result);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات (API) تحتها.
• [in] async_resource: كائن اختياري مرتبط بعمل غير متزامن سيتم تمريره إلى خطافات async_hooks المحتملة init hooks.
• [in] async_resource_name: معرف لنوع المورد الذي يتم توفيره للحصول على معلومات تشخيصية تُعرض بواسطة واجهة برمجة التطبيقات async_hooks.
• [in] execute: الدالة الأصلية التي يجب استدعاؤها لتنفيذ المنطق بشكل غير متزامن. يتم استدعاء الدالة المعطاة من مؤشر ترابط تجمع العاملين ويمكنها التنفيذ بالتوازي مع مؤشر ترابط حلقة الحدث الرئيسي.
• [in] complete: الدالة الأصلية التي سيتم استدعاؤها عند اكتمال المنطق غير المتزامن أو إلغاؤه. يتم استدعاء الدالة المعطاة من مؤشر ترابد حلقة الحدث الرئيسي. يوفر napi_async_complete_callback المزيد من التفاصيل.
• [in] data: سياق بيانات مقدمة من المستخدم. سيتم إعادة تمريره إلى دالتي execute و complete.
• [out] result: napi_async_work* وهو مقبض لعمل غير متزامن تم إنشاؤه حديثًا.

ترجع napi_ok إذا نجحت واجهة برمجة التطبيقات (API).

تقوم هذه واجهة برمجة التطبيقات (API) بتخصيص كائن عمل يستخدم لتنفيذ المنطق بشكل غير متزامن. يجب تحريره باستخدام napi_delete_async_work بمجرد عدم الحاجة إلى العمل بعد الآن.

يجب أن يكون async_resource_name سلسلة مُنهية بالصفر ومُشفّرة بتشفير UTF-8.

يُقدم مُعرّف async_resource_name من قِبل المستخدم ويجب أن يكون مُمثِّلاً لنوع العمل غير المتزامن الذي يتم تنفيذه. يُنصح أيضًا بتطبيق تسمية مسافات إلى المُعرّف، مثل تضمين اسم الوحدة النمطية. راجع وثائق async_hooks لمزيد من المعلومات.

napi_delete_async_work

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work);

• [in] env: بيئة استدعاء واجهة البرمجة التطبيقيّة.
• [in] work: المُقبض المُرجَع من خلال استدعاء napi_create_async_work.

يُرجِع napi_ok إذا نجحت واجهة البرمجة التطبيقيّة.

تقوم هذه واجهة البرمجة التطبيقيّة بتحرير كائن العمل المُخصّص مسبقًا.

يمكن استدعاء هذه واجهة البرمجة التطبيقيّة حتى في حالة وجود استثناء JavaScript معلّق.

napi_queue_async_work

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_queue_async_work(node_api_basic_env env,
                                  napi_async_work work);

• [in] env: بيئة استدعاء واجهة البرمجة التطبيقيّة.
• [in] work: المُقبض المُرجَع من خلال استدعاء napi_create_async_work.

يُرجِع napi_ok إذا نجحت واجهة البرمجة التطبيقيّة.

تطلب هذه واجهة البرمجة التطبيقيّة جدولة عمل مُخصّص مسبقًا للتنفيذ. بعد أن تُرجِع بنجاح، يجب عدم استدعاء هذه واجهة البرمجة التطبيقيّة مرة أخرى باستخدام نفس عنصر napi_async_work وإلا ستكون النتيجة غير مُعرّفة.

napi_cancel_async_work

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_cancel_async_work(node_api_basic_env env,
                                   napi_async_work work);

• [in] env: بيئة استدعاء واجهة البرمجة التطبيقيّة.
• [in] work: المُقبض المُرجَع من خلال استدعاء napi_create_async_work.

يُرجِع napi_ok إذا نجحت واجهة البرمجة التطبيقيّة.

تلغي هذه واجهة البرمجة التطبيقيّة العمل المُجمّع إذا لم يبدأ بعد. إذا بدأ بالفعل في التنفيذ، فلا يمكن إلغاؤه وسيتم إرجاع napi_generic_failure. في حالة النجاح، سيتم استدعاء مُدعًى complete بقيمة حالة napi_cancelled. يجب عدم حذف العمل قبل استدعاء مُدعًى complete، حتى لو تم إلغاؤه بنجاح.

يمكن استدعاء هذه واجهة البرمجة التطبيقيّة حتى في حالة وجود استثناء JavaScript معلّق.

العمليات المُزامنة المُخصّصة

قد لا تكون واجهات برمجة التطبيقات البسيطة للعمل المُزامن المذكورة أعلاه مناسبة لكل سيناريو. عند استخدام أي آلية مُزامنة أخرى، فإن واجهات برمجة التطبيقات التالية ضرورية لضمان تتبّع تشغيل العملية المُزامنة بشكل صحيح بواسطة وقت التشغيل.

napi_async_init

مضاف في: v8.6.0

إصدار N-API: 1

napi_status napi_async_init(napi_env env,
                            napi_value async_resource,
                            napi_value async_resource_name,
                            napi_async_context* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات بموجبها.
• [in] async_resource: الكائن المرتبط بالعمل غير المتزامن الذي سيتم تمريره إلى async_hooks المحتملة init hooks ويمكن الوصول إليه بواسطة async_hooks.executionAsyncResource().
• [in] async_resource_name: معرف لنوع المورد الذي يتم توفيره لمعلومات التشخيص التي تعرضها واجهة برمجة التطبيقات async_hooks.
• [out] result: سياق غير متزامن تم تهيئته.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يجب الاحتفاظ بالكائن async_resource حتى napi_async_destroy للحفاظ على تصرفات واجهة برمجة التطبيقات ذات الصلة بـ async_hooks بشكل صحيح. من أجل الاحتفاظ بالتوافق مع واجهة برمجة التطبيقات الثنائية مع الإصدارات السابقة، لا تحتفظ napi_async_context بالإشارة القوية إلى كائنات async_resource لتجنب التسبب في تسرب الذاكرة. ومع ذلك، إذا تم جمع async_resource بواسطة محرك جافا سكريبت قبل تدمير napi_async_context بواسطة napi_async_destroy، فإن استدعاء واجهات برمجة التطبيقات ذات الصلة بـ napi_async_context مثل napi_open_callback_scope و napi_make_callback يمكن أن يسبب مشاكل مثل فقدان السياق غير المتزامن عند استخدام واجهة برمجة التطبيقات AsyncLocalStorage.

من أجل الاحتفاظ بالتوافق مع واجهة برمجة التطبيقات الثنائية مع الإصدارات السابقة، فإن تمرير NULL لـ async_resource لا يؤدي إلى حدوث خطأ. ومع ذلك، هذا غير موصى به لأنه سيؤدي إلى سلوك غير مرغوب فيه مع async_hooks init hooks و async_hooks.executionAsyncResource() حيث أصبح المورد الآن مطلوبًا بواسطة تنفيذ async_hooks الأساسي من أجل توفير الارتباط بين عمليات الاستدعاء غير المتزامنة.

napi_async_destroy

أضيف في: v8.6.0

إصدار N-API: 1

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] async_context: سياق غير متزامن ليتم تدميره.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

يمكن استدعاء واجهة برمجة التطبيقات هذه حتى إذا كان هناك استثناء JavaScript معلق.

napi_make_callback

[السجل]

الإصدار	التغييرات
v8.6.0	تمت إضافة معلمة async_context.
v8.0.0	تمت الإضافة في: v8.0.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_make_callback(napi_env env,
                                           napi_async_context async_context,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] async_context: سياق العملية غير المتزامنة التي تستدعي وظيفة الاستدعاء. يجب أن يكون هذا عادةً قيمة تم الحصول عليها مسبقًا من napi_async_init. للحفاظ على توافق ABI مع الإصدارات السابقة، فإن تمرير NULL لـ async_context لا يؤدي إلى حدوث خطأ. ومع ذلك، هذا يؤدي إلى تشغيل غير صحيح لخطافات غير متزامنة. تتضمن المشكلات المحتملة فقدان السياق غير المتزامن عند استخدام واجهة برمجة التطبيقات AsyncLocalStorage.
• [in] recv: قيمة this التي تم تمريرها إلى الوظيفة التي تم استدعاؤها.
• [in] func: napi_value يمثل دالة JavaScript التي سيتم استدعاؤها.
• [in] argc: عدد العناصر في مصفوفة argv.
• [in] argv: مصفوفة من قيم JavaScript كـ napi_value تمثل الوسائط للوظيفة. إذا كانت argc تساوي صفرًا، فيمكن حذف هذه المعلمة عن طريق تمرير NULL.
• [out] result: napi_value يمثل كائن JavaScript الذي تم إرجاعه.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تسمح هذه الطريقة باستدعاء كائن دالة JavaScript من إضافة أصلية. هذه واجهة برمجة التطبيقات مشابهة لـ napi_call_function. ومع ذلك، يتم استخدامها للاتصال من التعليمات البرمجية الأصلية إلى داخل JavaScript بعد الرجوع من عملية غير متزامنة (عندما لا توجد نصوص أخرى على المكدس). إنها عبارة عن ملف غلاف بسيط حول node::MakeCallback.

لاحظ أنه ليس من الضروري استخدام napi_make_callback من داخل napi_async_complete_callback؛ في هذه الحالة، تم بالفعل إعداد سياق الاستدعاء غير المتزامن، لذلك يكون الاتصال المباشر بـ napi_call_function كافيًا ومناسبًا. قد يكون استخدام دالة napi_make_callback مطلوبًا عند تنفيذ سلوك غير متزامن مخصص لا يستخدم napi_create_async_work.

أي process.nextTick أو وعود مجدولة على قائمة الانتظار ذات المهمة الصغرى بواسطة JavaScript أثناء الاستدعاء يتم تشغيلها قبل الرجوع إلى C/C++.

napi_open_callback_scope

أضيف في: v9.6.0

إصدار N-API: 3

NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
                                                 napi_value resource_object,
                                                 napi_async_context context,
                                                 napi_callback_scope* result)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] resource_object: كائن مرتبط بالعمل غير المتزامن الذي سيتم تمريره إلى خطافات async_hooks المحتملة init. تم إهمال هذه المعلمة وتم تجاهلها أثناء وقت التشغيل. استخدم معلمة async_resource في napi_async_init بدلاً من ذلك.
• [in] context: سياق العملية غير المتزامنة التي تستدعي وظيفة الإرجاع. يجب أن تكون هذه قيمة تم الحصول عليها سابقًا من napi_async_init.
• [out] result: النطاق الذي تم إنشاؤه حديثًا.

هناك حالات (على سبيل المثال، حل الوعود) حيث من الضروري وجود ما يعادل النطاق المرتبط بوظيفة الإرجاع قيد التشغيل عند إجراء بعض مكالمات Node-API. إذا لم يكن هناك نص برمجي آخر على المكدس، فيمكن استخدام دالتي napi_open_callback_scope و napi_close_callback_scope لفتح/إغلاق النطاق المطلوب.

napi_close_callback_scope

أضيف في: v9.6.0

إصدار N-API: 3

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
                                                  napi_callback_scope scope)

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [in] scope: النطاق الذي سيتم إغلاقه.

يمكن استدعاء واجهة برمجة التطبيقات هذه حتى لو كان هناك استثناء JavaScript معلق.

إدارة الإصدارات

napi_get_node_version

أضيف في: v8.4.0

إصدار N-API: 1

typedef struct {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
  const char* release;
} napi_node_version;

napi_status napi_get_node_version(node_api_basic_env env,
                                  const napi_node_version** version);

• [in] env: البيئة التي يتم استدعاء واجهة برمجة التطبيقات تحتها.
• [out] version: مؤشر إلى معلومات الإصدار لـ Node.js نفسها.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه الدالة بملء بنية version بإصدار Node.js الرئيسي والثانوي والتصحيح الذي يعمل حاليًا، وحقل release بقيمة process.release.name.

يتم تخصيص المخزن المؤقت المرتجع بشكل ثابت ولا يلزم تحريره.

napi_get_version

تم الإضافة في: v8.0.0

إصدار N-API: 1

napi_status napi_get_version(node_api_basic_env env,
                             uint32_t* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: أعلى إصدار من Node-API مدعوم.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

ترجع هذه واجهة برمجة التطبيقات أعلى إصدار من Node-API مدعوم بواسطة وقت تشغيل Node.js. من المخطط أن يكون Node-API مضافًا بحيث قد تدعم الإصدارات الأحدث من Node.js وظائف واجهة برمجة تطبيقات إضافية. للسماح لإضافة باستخدام دالة أحدث عند التشغيل مع إصدارات Node.js التي تدعمها، مع توفير سلوك بديل عند التشغيل مع إصدارات Node.js التي لا تدعمها:

• استدعاء napi_get_version() لتحديد ما إذا كانت واجهة برمجة التطبيقات متوفرة.
• إذا كانت متوفرة، قم بتحميل مؤشر إلى الدالة ديناميكيًا باستخدام uv_dlsym().
• استخدم المؤشر المحمل ديناميكيًا لاستدعاء الدالة.
• إذا لم تكن الدالة متوفرة، فوفر تنفيذًا بديلًا لا يستخدم الدالة.

إدارة الذاكرة

napi_adjust_external_memory

تم الإضافة في: v8.5.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] change_in_bytes: التغيير في الذاكرة المخصصة خارجيًا والتي يتم الاحتفاظ بها بواسطة كائنات JavaScript.
• [out] result: القيمة المعدلة

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تمنح هذه الدالة V8 مؤشرًا على مقدار الذاكرة المخصصة خارجيًا والتي يتم الاحتفاظ بها بواسطة كائنات JavaScript (أي كائن JavaScript يشير إلى ذاكرته الخاصة المخصصة بواسطة إضافة أصلية). سيتسبب تسجيل الذاكرة المخصصة خارجيًا في إجراء عمليات جمع قمامة عالمية أكثر مما هو عليه خلاف ذلك.

الوعود

توفر Node-API مرافق لإنشاء كائنات Promise كما هو موضح في القسم 25.4 من مواصفات ECMA. تقوم بتنفيذ الوعود كزوج من الكائنات. عندما يتم إنشاء وعد بواسطة napi_create_promise()، يتم إنشاء كائن "مؤجل" ويتم إرجاعه إلى جانب Promise. يتم ربط الكائن المؤجل بـ Promise الذي تم إنشاؤه وهو الوسيلة الوحيدة لحل أو رفض Promise باستخدام napi_resolve_deferred() أو napi_reject_deferred(). يتم تحرير الكائن المؤجل الذي تم إنشاؤه بواسطة napi_create_promise() بواسطة napi_resolve_deferred() أو napi_reject_deferred(). يمكن إرجاع كائن Promise إلى JavaScript حيث يمكن استخدامه بالطريقة المعتادة.

على سبيل المثال، لإنشاء وعد ومروره إلى عامل غير متزامن:

napi_deferred deferred;
napi_value promise;
napi_status status;

// إنشاء الوعد.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// تمرير المؤجل إلى دالة تقوم بعمل غير متزامن.
do_something_asynchronous(deferred);

// إرجاع الوعد إلى JS
return promise;

ستقوم الدالة أعلاه do_something_asynchronous() بأداء عملها غير المتزامن ثم ستحل أو ترفض المؤجل، وبالتالي ستختتم الوعد وتحرر المؤجل:

napi_deferred deferred;
napi_value undefined;
napi_status status;

// إنشاء قيمة لإنهاء المؤجل.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// حل أو رفض الوعد المرتبط بالمؤجل بناءً على
// ما إذا نجح العمل غير المتزامن.
if (asynchronous_action_succeeded) {
  status = napi_resolve_deferred(env, deferred, undefined);
} else {
  status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;

// في هذه المرحلة، تم تحرير المؤجل، لذلك يجب أن نعين NULL له.
deferred = NULL;

napi_create_promise

مضاف في: v8.5.0

نسخة N-API: 1

napi_status napi_create_promise(napi_env env,
                                napi_deferred* deferred,
                                napi_value* promise);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] deferred: كائن مؤجل تم إنشاؤه حديثًا، والذي يمكن تمريره لاحقًا إلى napi_resolve_deferred() أو napi_reject_deferred() لحل أو رفض الوعد المرتبط به على التوالي.
• [out] promise: الوعد JavaScript المرتبط بالكائن المؤجل.

يرجع napi_ok إذا نجحت واجهة برمجة التطبيقات.

تقوم هذه واجهة برمجة التطبيقات بإنشاء كائن مؤجل ووعد JavaScript.

napi_resolve_deferred

مضاف في: v8.5.0

نسخة N-API: 1

napi_status napi_resolve_deferred(napi_env env,
                                  napi_deferred deferred,
                                  napi_value resolution);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] deferred: الكائن المؤجل الذي يجب حل الوعد المرتبط به.
• [in] resolution: القيمة التي سيتم حل الوعد بها.

تقوم هذه واجهة برمجة التطبيقات بحل وعد JavaScript عبر الكائن المؤجل المرتبط به. وبالتالي، لا يمكن استخدامها إلا لحل وعود JavaScript التي يتوفر لها الكائن المؤجل المقابل. وهذا يعني فعليًا أنه يجب إنشاء الوعد باستخدام napi_create_promise() ويجب الاحتفاظ بالكائن المؤجل المرتجع من تلك المكالمة من أجل تمريره إلى هذه واجهة برمجة التطبيقات.

يتم تحرير الكائن المؤجل عند اكتمال العملية بنجاح.

napi_reject_deferred

مضاف في: v8.5.0

نسخة N-API: 1

napi_status napi_reject_deferred(napi_env env,
                                 napi_deferred deferred,
                                 napi_value rejection);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] deferred: الكائن المؤجل الذي يجب رفض الوعد المرتبط به.
• [in] rejection: القيمة التي سيتم رفض الوعد بها.

تقوم هذه واجهة برمجة التطبيقات برفض وعد JavaScript عبر الكائن المؤجل المرتبط به. وبالتالي، لا يمكن استخدامها إلا لرفض وعود JavaScript التي يتوفر لها الكائن المؤجل المقابل. وهذا يعني فعليًا أنه يجب إنشاء الوعد باستخدام napi_create_promise() ويجب الاحتفاظ بالكائن المؤجل المرتجع من تلك المكالمة من أجل تمريره إلى هذه واجهة برمجة التطبيقات.

يتم تحرير الكائن المؤجل عند اكتمال العملية بنجاح.

napi_is_promise

أضيف في: v8.5.0

إصدار N-API: 1

napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] value: القيمة المراد فحصها.
• [out] is_promise: علم يشير إلى ما إذا كان promise كائن وعد أصلي (أي كائن وعد تم إنشاؤه بواسطة المحرك الأساسي).

تنفيذ البرنامج النصي

يوفر Node-API واجهة برمجة تطبيقات لتنفيذ سلسلة تحتوي على جافا سكريبت باستخدام محرك جافا سكريبت الأساسي.

napi_run_script

أضيف في: v8.5.0

إصدار N-API: 1

NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                        napi_value script,
                                        napi_value* result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [in] script: سلسلة جافا سكريبت تحتوي على البرنامج النصي المراد تنفيذه.
• [out] result: القيمة الناتجة عن تنفيذ البرنامج النصي.

تقوم هذه الدالة بتنفيذ سلسلة من تعليمات جافا سكريبت وإرجاع نتيجتها مع التحذيرات التالية:

• على عكس eval، لا تسمح هذه الدالة للبرنامج النصي بالوصول إلى نطاق المعجم الحالي، وبالتالي لا تسمح أيضًا بالوصول إلى نطاق الوحدة، مما يعني أن العناصر شبه العالمية مثل require لن تكون متاحة.
• يمكن للبرنامج النصي الوصول إلى النطاق العالمي. سيتم إضافة إعلانات الدوال وvar في البرنامج النصي إلى كائن global. ستكون إعلانات المتغيرات التي تم إجراؤها باستخدام let وconst مرئية عالميًا، ولكن لن يتم إضافتها إلى كائن global.
• قيمة this هي global داخل البرنامج النصي.

حلقة أحداث libuv

يوفر Node-API دالة للحصول على حلقة الأحداث الحالية المرتبطة بـ napi_env محدد.

napi_get_uv_event_loop

أضيف في: v9.3.0، v8.10.0

إصدار N-API: 2

NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
                                               struct uv_loop_s** loop);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] loop: مثيل حلقة libuv الحالي.

ملاحظة: على الرغم من أن libuv كانت مستقرة نسبيًا بمرور الوقت، إلا أنها لا توفر ضمانًا لاستقرار واجهة برمجة التطبيقات الثنائية. يجب تجنب استخدام هذه الدالة. قد يؤدي استخدامها إلى إضافة إضافية لا تعمل عبر إصدارات Node.js. تعد مكالمات الدوال الآمنة لخيوط غير متزامنة بديلاً لكثير من حالات الاستخدام.

دعوات الدوال الآمنة للخيوط بشكل غير متزامن

لا يمكن عادةً استدعاء دوال JavaScript إلا من الخيط الرئيسي لإضافة النظام الأصلي. إذا أنشأت إضافة ما خيوطًا إضافية، فلا يجب استدعاء دوال Node-API التي تتطلب napi_env أو napi_value أو napi_ref من تلك الخيوط.

عندما تحتوي إضافة ما على خيوط إضافية، وتحتاج إلى استدعاء دوال JavaScript بناءً على المعالجة التي أنجزتها تلك الخيوط، يجب أن تتواصل تلك الخيوط مع الخيط الرئيسي للإضافة بحيث يمكن للخيط الرئيسي استدعاء دالة JavaScript نيابةً عنها. توفر واجهات برمجة التطبيقات الآمنة للخيوط طريقة سهلة للقيام بذلك.

توفر واجهات برمجة التطبيقات هذه النوع napi_threadsafe_function بالإضافة إلى واجهات برمجة التطبيقات لإنشاء وكسر واستدعاء كائنات هذا النوع. ينشئ napi_create_threadsafe_function() مرجعًا دائمًا لـ napi_value الذي يحتوي على دالة JavaScript يمكن استدعاؤها من خيوط متعددة. تحدث المكالمات بشكل غير متزامن. هذا يعني أنه سيتم وضع القيم التي سيتم استدعاء دالة الاستدعاء مرة أخرى لـ JavaScript بها في قائمة انتظار، وبالنسبة لكل قيمة في قائمة الانتظار، سيتم في النهاية إجراء استدعاء لدالة JavaScript.

عند إنشاء napi_threadsafe_function، يمكن توفير استدعاء مرة أخرى napi_finalize. سيتم استدعاء استدعاء الاستدعاء مرة أخرى هذا على الخيط الرئيسي عندما يوشك على تدمير دالة آمنة للخيوط. يستقبل السياق وبيانات الاستدعاء مرة أخرى المعطاة أثناء الإنشاء، ويوفر فرصة لتنظيف الخيوط، على سبيل المثال عن طريق استدعاء uv_thread_join(). بخلاف خيط الحلقة الرئيسي، لا يجب أن تستخدم أي خيوط دالة آمنة للخيوط بعد اكتمال استدعاء الاستدعاء مرة أخرى.

يمكن استرداد context المعطى أثناء الاستدعاء إلى napi_create_threadsafe_function() من أي خيط باستخدام استدعاء إلى napi_get_threadsafe_function_context().

استدعاء دالة آمنة للخيوط

يمكن استخدام napi_call_threadsafe_function() لبدء استدعاء إلى JavaScript. يقبل napi_call_threadsafe_function() معلمة تتحكم في ما إذا كانت واجهة برمجة التطبيقات تتصرف بشكل حظر. إذا تم تعيينه على napi_tsfn_nonblocking، تتصرف واجهة برمجة التطبيقات بشكل غير حظر، وتعيد napi_queue_full إذا كانت قائمة الانتظار ممتلئة، مما يمنع إضافة البيانات بنجاح إلى قائمة الانتظار. إذا تم تعيينه على napi_tsfn_blocking، فإن واجهة برمجة التطبيقات تحظر حتى تصبح مساحة متاحة في قائمة الانتظار. لا يحظر napi_call_threadsafe_function() أبدًا إذا تم إنشاء دالة آمنة للخيوط بحجم أقصى لقائمة الانتظار يساوي 0.

لا يجب استدعاء napi_call_threadsafe_function() باستخدام napi_tsfn_blocking من خيط JavaScript، لأنه، إذا كانت قائمة الانتظار ممتلئة، فقد يتسبب ذلك في تعطل خيط JavaScript.

يتم التحكم في الاستدعاء الفعلي إلى JavaScript بواسطة استدعاء الاستدعاء مرة أخرى المعطى عبر معلمة call_js_cb. يتم استدعاء call_js_cb على الخيط الرئيسي مرة واحدة لكل قيمة تم وضعها في قائمة الانتظار بواسطة استدعاء ناجح إلى napi_call_threadsafe_function(). إذا لم يتم إعطاء استدعاء الاستدعاء مرة أخرى كهذا، فسيتم استخدام استدعاء الاستدعاء مرة أخرى افتراضي، ولن يحتوي استدعاء JavaScript الناتج على أي وسيطات. يستقبل استدعاء الاستدعاء مرة أخرى call_js_cb دالة JavaScript لاستدعاءها كـ napi_value في معلماتها، بالإضافة إلى مؤشر سياق void* المستخدم عند إنشاء napi_threadsafe_function، ومؤشر البيانات التالي الذي تم إنشاؤه بواسطة أحد الخيوط الثانوية. يمكن بعد ذلك لاستدعاء الاستدعاء مرة أخرى استخدام واجهة برمجة تطبيقات مثل napi_call_function() للاستدعاء إلى JavaScript.

قد يتم استدعاء استدعاء الاستدعاء مرة أخرى أيضًا باستخدام env و call_js_cb تم تعيين كليهما على NULL للإشارة إلى أن المكالمات إلى JavaScript لم تعد ممكنة، بينما تظل العناصر في قائمة الانتظار التي قد تحتاج إلى تحريرها. يحدث هذا عادةً عندما تخرج عملية Node.js بينما لا تزال هناك دالة آمنة للخيوط نشطة.

ليس من الضروري إجراء استدعاء إلى JavaScript عبر napi_make_callback() لأن Node-API يقوم بتشغيل call_js_cb في سياق مناسب لاستدعاءات الاستدعاء مرة أخرى.

قد يتم استدعاء صفر أو أكثر من العناصر الموجودة في قائمة الانتظار في كل دورة من حلقات الأحداث. لا يجب أن تعتمد التطبيقات على سلوك معين بخلاف التقدم في استدعاء استدعاءات الاستدعاء مرة أخرى وسيتم استدعاء الأحداث مع مرور الوقت.

تعداد المرجعية لوظائف آمنة للخيوط

يمكن إضافة الخيوط وإزالتها من كائن napi_threadsafe_function أثناء وجوده. وبالتالي، بالإضافة إلى تحديد عدد أولي من الخيوط عند الإنشاء، يمكن استدعاء napi_acquire_threadsafe_function للإشارة إلى أن خيطًا جديدًا سيبدأ في استخدام الوظيفة الآمنة للخيوط. وبالمثل، يمكن استدعاء napi_release_threadsafe_function للإشارة إلى أن خيطًا موجودًا سيتوقف عن استخدام الوظيفة الآمنة للخيوط.

يتم تدمير كائنات napi_threadsafe_function عندما يكون كل خيط يستخدم الكائن قد قام باستدعاء napi_release_threadsafe_function() أو تلقى حالة إرجاع napi_closing استجابةً لاستدعاء napi_call_threadsafe_function. يتم إفراغ قائمة الانتظار قبل تدمير napi_threadsafe_function. يجب أن يكون napi_release_threadsafe_function() آخر مكالمة واجهة برمجة التطبيقات التي تتم بالاقتران مع napi_threadsafe_function معين، لأنه بعد اكتمال المكالمة، لا يوجد ضمان بأن napi_threadsafe_function لا يزال مخصصًا. لنفس السبب، لا تستخدم وظيفة آمنة للخيوط بعد تلقي قيمة إرجاع napi_closing استجابةً لاستدعاء napi_call_threadsafe_function. يمكن تحرير البيانات المرتبطة بـ napi_threadsafe_function في مُستدعي napi_finalize الخاص به والذي تم تمريره إلى napi_create_threadsafe_function(). تُشير المعلمة initial_thread_count لـ napi_create_threadsafe_function إلى العدد الأولي لاكتساب وظائف آمنة للخيوط، بدلاً من استدعاء napi_acquire_threadsafe_function عدة مرات عند الإنشاء.

بمجرد أن يصل عدد الخيوط التي تستخدم napi_threadsafe_function إلى صفر، لا يمكن لأي خيوط أخرى البدء في استخدامها عن طريق استدعاء napi_acquire_threadsafe_function(). في الواقع، ستعيد جميع مكالمات واجهة برمجة التطبيقات اللاحقة المرتبطة بها، باستثناء napi_release_threadsafe_function(), قيمة خطأ napi_closing.

يمكن "إلغاء" الوظيفة الآمنة للخيوط عن طريق إعطاء قيمة napi_tsfn_abort إلى napi_release_threadsafe_function(). سيؤدي هذا إلى جعل جميع واجهات برمجة التطبيقات اللاحقة المرتبطة بالوظيفة الآمنة للخيوط باستثناء napi_release_threadsafe_function() تُعيد napi_closing حتى قبل وصول عدد مراجعها إلى صفر. على وجه الخصوص، ستُعيد napi_call_threadsafe_function() قيمة napi_closing، وبالتالي تُبلغ الخيوط بأنه لم يعد من الممكن إجراء مكالمات غير متزامنة إلى الوظيفة الآمنة للخيوط. يمكن استخدام هذا كمعيار لإنهاء الخيط. عند تلقي قيمة إرجاع napi_closing من napi_call_threadsafe_function() يجب ألا يستخدم الخيط الوظيفة الآمنة للخيوط بعد الآن لأنه لم يعد مضمونًا تخصيصه.

تحديد ما إذا كان يجب الحفاظ على تشغيل العملية

بالمثل مع مقابض libuv، يمكن "الإشارة" إلى الدوال الآمنة للخيوط و"إلغاء الإشارة" عنها. ستؤدي الدالة الآمنة للخيوط "المُشار إليها" إلى بقاء حلقة الحدث على الخيط الذي تم إنشاؤها فيه على قيد الحياة حتى يتم تدمير الدالة الآمنة للخيوط. على النقيض من ذلك، فإن الدالة الآمنة للخيوط "غير المُشار إليها" لن تمنع حلقة الحدث من الخروج. توجد واجهات برمجة التطبيقات napi_ref_threadsafe_function و napi_unref_threadsafe_function لهذا الغرض.

لا تُشير napi_unref_threadsafe_function إلى إمكانية تدمير الدوال الآمنة للخيوط، كما أن napi_ref_threadsafe_function لا تمنع تدميرها.

napi_create_threadsafe_function

[السجل]

الإصدار	التغييرات
v12.6.0، v10.17.0	تم جعل معلمة func اختيارية مع call_js_cb المخصص.
v10.6.0	تمت الإضافة في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
                                napi_value func,
                                napi_value async_resource,
                                napi_value async_resource_name,
                                size_t max_queue_size,
                                size_t initial_thread_count,
                                void* thread_finalize_data,
                                napi_finalize thread_finalize_cb,
                                void* context,
                                napi_threadsafe_function_call_js call_js_cb,
                                napi_threadsafe_function* result);

• [in] env: بيئة يتم استدعاء واجهة برمجة التطبيقات ضمنها.
• [in] func: دالة JavaScript اختيارية لاستدعائها من خيط آخر. يجب توفيرها إذا تم تمرير NULL إلى call_js_cb.
• [in] async_resource: كائن اختياري مرتبط بالعمل غير المتزامن الذي سيتم تمريره إلى خطافات async_hooks المحتملة init.
• [in] async_resource_name: سلسلة JavaScript لتوفير مُعرّف لنوع المورد الذي يتم توفيره لمعلومات التشخيص التي تعرضها واجهة برمجة التطبيقات async_hooks.
• [in] max_queue_size: الحجم الأقصى للطابور. 0 لعدم وجود حد.
• [in] initial_thread_count: عدد عمليات الاستحواذ الأولية، أي العدد الأولي للخيوط، بما في ذلك الخيط الرئيسي، الذي سيستخدم هذه الدالة.
• [in] thread_finalize_data: بيانات اختيارية سيتم تمريرها إلى thread_finalize_cb.
• [in] thread_finalize_cb: دالة اختيارية يتم استدعاؤها عند تدمير napi_threadsafe_function.
• [in] context: بيانات اختيارية لإرفاقها بـ napi_threadsafe_function الناتجة.
• [in] call_js_cb: استدعاء عكسي اختياري يستدعي دالة JavaScript استجابةً لاستدعاء على خيط مختلف. سيتم استدعاء هذا الاستدعاء العكسي على الخيط الرئيسي. إذا لم يتم إعطاؤه، فسيتم استدعاء دالة JavaScript بدون معلمات وبدون قيمة undefined كقيمة this. توفر napi_threadsafe_function_call_js مزيدًا من التفاصيل.
• [out] result: دالة JavaScript غير المتزامنة الآمنة للخيوط.

سجل التغييرات:

• تجريبية (NAPI_EXPERIMENTAL مُعرّف): يتم التعامل مع الاستثناءات غير المُعالجة التي تم طرحها في call_js_cb باستخدام حدث 'uncaughtException'، بدلاً من تجاهلها.

napi_get_threadsafe_function_context

تم الإضافة في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
                                     void** result);

• [in] func: دالة آمنة للخيوط لاسترداد السياق الخاص بها.
• [out] result: الموقع الذي سيتم تخزين السياق فيه.

يمكن استدعاء هذا الـ API من أي خيط يستخدم func.

napi_call_threadsafe_function

[السجل]

الإصدار	التغييرات
v14.5.0	تم التراجع عن دعم napi_would_deadlock.
v14.1.0	إرجاع napi_would_deadlock عند الاستدعاء باستخدام napi_tsfn_blocking من الخيط الرئيسي أو خيط عامل والطابور ممتلئ.
v10.6.0	تم الإضافة في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
                              void* data,
                              napi_threadsafe_function_call_mode is_blocking);

• [in] func: دالة JavaScript غير متزامنة آمنة للخيوط لتنفيذها.
• [in] data: البيانات المراد إرسالها إلى JavaScript عبر وظيفة الاستدعاء call_js_cb المقدمة أثناء إنشاء دالة JavaScript الآمنة للخيوط.
• [in] is_blocking: علم قيمته إما napi_tsfn_blocking للإشارة إلى أن الاستدعاء يجب أن يُحجِز إذا كان الطابور ممتلئًا أو napi_tsfn_nonblocking للإشارة إلى أن الاستدعاء يجب أن يُرجع على الفور بحالة napi_queue_full عندما يكون الطابور ممتلئًا.

يجب عدم استدعاء هذا الـ API باستخدام napi_tsfn_blocking من خيط JavaScript، لأنه، إذا كان الطابور ممتلئًا، فقد يتسبب ذلك في تعليق خيط JavaScript.

سيُرجع هذا الـ API napi_closing إذا تم استدعاء napi_release_threadsafe_function() مع تعيين abort إلى napi_tsfn_abort من أي خيط. لا يتم إضافة القيمة إلى الطابور إلا إذا أرجع الـ API napi_ok.

يمكن استدعاء هذا الـ API من أي خيط يستخدم func.

napi_acquire_threadsafe_function

تم الإضافة في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);

• [in] func: دالة JavaScript غير متزامنة آمنة للخيوط لبدء استخدامها.

يجب على الخيط استدعاء هذا الـ API قبل تمرير func إلى أي واجهات برمجة تطبيقات أخرى آمنة للخيوط للإشارة إلى أنه سيتم استخدام func. هذا يمنع تدمير func عندما يتوقف جميع الخيوط الأخرى عن استخدامها.

يمكن استدعاء هذا الـ API من أي خيط سيبدأ في استخدام func.

napi_release_threadsafe_function

مضاف في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• [in] func: دالة JavaScript غير متزامنة آمنة للخيوط، يتم تقليل عدد مراجعها.
• [in] mode: علم قيمته إما napi_tsfn_release للإشارة إلى أن الخيط الحالي لن يقوم بمزيد من المكالمات إلى الدالة الآمنة للخيوط، أو napi_tsfn_abort للإشارة إلى أنه بالإضافة إلى الخيط الحالي، لا يجب أن يقوم أي خيط آخر بأي مكالمات أخرى إلى الدالة الآمنة للخيوط. إذا تم تعيينه على napi_tsfn_abort، فإن المكالمات الإضافية إلى napi_call_threadsafe_function() ستعيد napi_closing، ولن يتم وضع المزيد من القيم في قائمة الانتظار.

يجب على الخيط استدعاء هذا الواجهة البرمجية عند توقف استخدامه لـ func. إن تمرير func إلى أي واجهات برمجية آمنة للخيوط بعد استدعاء هذا الواجهة البرمجية له نتائج غير محددة، حيث قد تم تدمير func.

يمكن استدعاء هذا الواجهة البرمجية من أي خيط سيتوقف عن استخدام func.

napi_ref_threadsafe_function

مضاف في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env: البيئة التي يتم استدعاء الواجهة البرمجية بموجبها.
• [in] func: الدالة الآمنة للخيوط المراد الرجوع إليها.

تُستخدم هذه الواجهة البرمجية للإشارة إلى أن حلقة الأحداث التي تعمل على الخيط الرئيسي لا يجب أن تخرج حتى يتم تدمير func. على غرار uv_ref ، فهي أيضًا قوية التأثير.

لا تُشير napi_unref_threadsafe_function إلى إمكانية تدمير الدوال الآمنة للخيوط، ولا تمنع napi_ref_threadsafe_function من تدميرها. تتوفر napi_acquire_threadsafe_function و napi_release_threadsafe_function لهذا الغرض.

لا يمكن استدعاء هذا الواجهة البرمجية إلا من الخيط الرئيسي.

napi_unref_threadsafe_function

مضاف في: v10.6.0

إصدار N-API: 4

NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);

• [in] env: البيئة التي يتم استدعاء الواجهة البرمجية بموجبها.
• [in] func: الدالة الآمنة للخيوط المراد إلغاء الرجوع إليها.

تُستخدم هذه الواجهة البرمجية للإشارة إلى أن حلقة الأحداث التي تعمل على الخيط الرئيسي قد تخرج قبل تدمير func. على غرار uv_unref ، فهي أيضًا قوية التأثير.

لا يمكن استدعاء هذا الواجهة البرمجية إلا من الخيط الرئيسي.

أدوات مساعدة متنوعة

node_api_get_module_file_name

مضاف في: v15.9.0، v14.18.0، v12.22.0

إصدار N-API: 9

NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);

• [in] env: بيئة استدعاء واجهة برمجة التطبيقات.
• [out] result: عنوان URL يحتوي على المسار المطلق للموقع الذي تم تحميل الوحدة الإضافية منه. بالنسبة للملف الموجود في نظام الملفات المحلي، سيبدأ بـ file://. السلسلة منتهية بالصفر ومملوكة لـ env وبالتالي يجب عدم تعديلها أو تحريرها.

قد يكون result سلسلة فارغة إذا فشلت عملية تحميل الوحدة الإضافية في تحديد اسم ملف الوحدة الإضافية أثناء التحميل.