فئة ara::nm::NetworkHandle

الاستخدام ودورة الحياة

تعمل الفئة NetworkHandle ككائن وصول إلى مقبض شبكة تتم مخاطبته عبر ara::core::InstanceSpecifier، وهي مخصصة لـ State Management [SWS_ANM_01000]. يتم إنشاء النسخ عبر تمرير الـ Instance-Specifier لنموذج أولي لمنفذ NetworkManagementPortInterface [SWS_ANM_01001]. وبما أن الفئة معلنة كـ final، فلا يمكن استخدامها كفئة أساسية للاشتقاقات [SWS_ANM_01000].

دلالات النقل والتزامن

تمتلك كائنات هذه الفئة دلالات نقل خالصة: منشئ النسخ [SWS_ANM_01005] وعامل إسناد النسخ [SWS_ANM_01006] محذوفان (= delete). ويمكن نقل النسخ بدلاً من ذلك عبر منشئ النقل [SWS_ANM_01003] وعامل إسناد النقل [SWS_ANM_01004].

فيما يتعلق بأمان مؤشرات الترابط (Thread Safety)، تسري المتطلبات التالية:

• منشئ الفئة المزود بـ InstanceSpecifier آمن بالنسبة لمؤشرات الترابط (thread-safe) [SWS_ANM_01001].
• بالنسبة لمنشئ النقل، تم تعريف أمان مؤشرات الترابط بصورة خاصة بالتنفيذ (implementation-defined) [SWS_ANM_01003].
• تم تحديد هادم الفئة [SWS_ANM_01002] وعامل تعيين النقل [SWS_ANM_01004] صراحةً على أنهما غير آمنين بالنسبة لمؤشرات الترابط (not thread-safe). تفسير: نظرًا لعدم ضمان أمان مؤشرات الترابط، يُرجّح أن يكون سياق الاستدعاء مسؤولًا عن إجراء مزامنة خارجية، إذا كانت عدة مؤشرات ترابط تستخدم المقبض نفسه. سؤال Q-7172baaffab79218 (مفتوح)

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

تم التصريح عن جميع المنشئات، وعوامل التعيين، بالإضافة إلى هادم الفئة على أنها noexcept [SWS_ANM_01001]، [SWS_ANM_01002]، [SWS_ANM_01003]، [SWS_ANM_01004]. لا تنص واجهة الفئة هذه على وجود استثناءات أو قيم إرجاع للأخطاء.

يحدد الاسم المستعار للنوع NetworkStateChangeNotifier من ملف الترويسة ara/nm/network_handle.h مغلف دالة لدوال رد الاتصال عند تغييرات حالة الشبكة [SWS_ANM_01020]. يستقبل التوقيع std::function<void(const NetworkStateType&)> كمعامل الحالة الجديدة كمرجع ثابت إلى NetworkStateType وليس له قيمة إرجاع [SWS_ANM_01020].

يُستخدم المُنبه (notifier) عند مراقبة إدارة الشبكة عبر نقطتي تسجيل:

• للإشارة إلى حالة الشبكة الفعلية، يتم تسجيل المُنبه عبر RegisterNetworkStateChangeNotifier [SWS_ANM_01010]. كبديل، يسمح التحميل الزائد للقالب (template overload) بتمرير executor محدد من قِبل المستخدم، والذي يتم تنفيذ المُنبه في سياقه [SWS_ANM_01015]. يمكن أن يكون هناك مُنبه نشط واحد كحد أقصى لكل مثيل [SWS_ANM_01010].
• بالنسبة للإشعارات حول حالة الشبكة المطلوبة، يتم التسجيل عبر RegisterNetworkRequestedStateChangeNotifier، إما مباشرة [SWS_ANM_01012] أو بتحديد منفذ هدف (target executor) [SWS_ANM_01014]. هنا أيضًا، يُسمح بمعالج واحد كحد أقصى [SWS_ANM_01012].

فيما يتعلق بمعالجة الأخطاء، تُرجع جميع دوال التسجيل ara::core::Result<void>؛ وفي حال فشل التسجيل، يتم الإبلاغ عن الخطأ NmErrc::kInvalidHandler [SWS_ANM_01010]، [SWS_ANM_01012]. من المرجح أن يحدث هذا بشكل خاص إذا تم تمرير كائن دالة فارغ أو غير مهيأ بالكامل. سؤال Q-04452871df619a94 (مفتوح)

كقيد، تم تحديد NetworkStateChangeNotifier على أنه غير آمن لخيوط المعالجة (not thread-safe) [SWS_ANM_01020]. كما أن دوال التسجيل المقترنة به مصممة لتكون غير آمنة لخيوط المعالجة [SWS_ANM_01010]، [SWS_ANM_01012]. لذلك، يجب على المستدعين التأكد من أن التعيين وكذلك التسجيل يتمان بشكل متزامن أو تسلسلي.

يمثل التعداد NetworkStateType حالة شبكة في الوحدة anm (Adaptive Network Management) [SWS_ANM_01358]. ويميز بين الحالة غير النشطة kNoCom = 0 (إذا لم تكن جميع الشبكات المرتبطة في الحالة FULL_COM) والحالة النشطة kFullCom = 1 (عندما تكون جميع الشبكات المرتبطة FULL_COM) [SWS_ANM_01358].

يُستخدم هذا النوع في استخدامات متعددة في واجهات ara/nm/network_handle.h:

• الاستعلام عن الحالة: تُرجع الطريقة GetNetworkState() الحالة الفعلية الحالية للشبكة كـ ara::core::Result<NetworkStateType> بشكل متزامن وآمن لمؤشرات الترابط [SWS_ANM_01007]. وبالمثل، تقرأ GetNetworkRequestedState() الحالة المطلوبة حاليًا لـ PNC أو VLAN أو شبكة فعلية بأمان بالنسبة لمؤشرات الترابط [SWS_ANM_01008].
• طلب الحالة: عبر SetNetworkRequestedState(NetworkStateType networkState)، يتم طلب حالة لـ PNC أو VLAN أو شبكة فعلية بشكل نشط (kFullCom) أو تحريرها (kNoCom) [SWS_ANM_01009]. تم تحديد هذه العملية على أنها غير آمنة لمؤشرات الترابط [SWS_ANM_01009].
• إشعار الحدث: عبر مغلّف الدالة NetworkStateChangeNotifier (std::function<void(const NetworkStateType&)>)، يتم تمرير النوع كـمعلمة لإبلاغ منطق التطبيق بتغيرات الحالة [SWS_ANM_01020].

معالجة الأخطاء: عند الاستعلام عن NetworkStateType أو ضبطه عبر الطرق المذكورة، يمكن إرجاع الرمز NmErrc::kServiceNotAvailable في ara::core::Result في حالة حدوث خطأ [SWS_ANM_01007] [SWS_ANM_01008] [SWS_ANM_01009].

الاستخدام

تسجل الدالة RegisterNetworkRequestedStateChangeNotifier من ملف الرأس ara/nm/network_handle.h دالة رد نداء للإخطار بتغييرات حالة الشبكة المطلوبة [SWS_ANM_01012]. وتُمرَّر إليها كمعلمة NetworkStateChangeNotifier. يمكن تسجيل مُخطِر واحد كحد أقصى لتغييرات الحالة المطلوبة [SWS_ANM_01012]. الدالة مُصرَّح بها كـ noexcept وتُرجع ara::core::Result<void>.

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

إذا حدث خطأ أثناء التسجيل، يتم الإبلاغ عنه عبر ara::core::Result برمز الخطأ المحدد NmErrc::kInvalidHandler [SWS_ANM_01012]. تفسير: يُرجَّح إطلاق هذا الخطأ إذا كان المُخطِر المُمرَّر غير صالح أو غير قابل للاستدعاء. سؤال Q-57a28e90a933e6de (مفتوح)

التزامن والقيود

تم تحديد الدالة بأنها غير آمنة للخيوط (not thread-safe) [SWS_ANM_01012]. لذلك يجب على جهات الاستدعاء إلزامياً مزامنة عمليات الوصول المتزامنة ومحاولات التسجيل من خيوط متعددة خارجياً.

تفاعل

كبديل للتنفيذ المباشر، يتوفر تحميل زائد للقالب للدالة [SWS_ANM_01014] يقبل بشكل إضافي معلمة executor. يتيح ذلك تشغيل المُخطِر في سياق تنفيذ مُقدَّم صراحة؛ وهذا التحميل الزائد أيضاً ليس آمناً للخيوط ويُبلغ في حالة الخطأ عن NmErrc::kInvalidHandler [SWS_ANM_01014].

تسجل دالة القالب RegisterNetworkRequestedStateChangeNotifier المُصرَّح بها في ملف الرأس ara/nm/network_handle.h رد نداء من النوع NetworkStateChangeNotifier للإخطار بتغييرات حالة الشبكة المطلوبة [SWS_ANM_01014]. ومن خلال المعلمة الإضافية executor من النوع ExecutorT&&، يتم تحديد سياق التنفيذ المرغوب الذي يجب تشغيل هذا المُخطِر ضمنه عند حدوث تغييرات في الحالة. الاستدعاء المتزامن لتسجيل المعالج مُصرَّح به كـ noexcept ويُرجع ara::core::Result<void> إلى جهة الاستدعاء.

لمعالجة الأخطاء، تشير الواجهة إلى المشكلات عبر نوع الإرجاع ara::core::Result. إذا تم تمرير معالج غير صالح، تفشل العملية وتُرجع الدالة رمز الخطأ المحدد NmErrc::kInvalidHandler [SWS_ANM_01014].

فيما يتعلق بالتزامن وقيود الاستدعاء، تم تحديد الدالة صراحة بأنها not thread-safe [SWS_ANM_01014]. وهذا يعني أنه يتعين على جهات الاستدعاء توفير مزامنة خارجية عند الوصول المتزامن إلى نفس مثيل المؤشر (Handle) لتجنب تعارض البيانات.

في إطار تفاعل النظام، تمثل هذه الدالة توسعة للمتغير ذي المعلمات الأقل [SWS_ANM_01012]، والذي يسجل مُخطِراً واحداً كحد أقصى لتغييرات الحالة المطلوبة. تفسير: نظراً لأن المواصفة الأساسية في [SWS_ANM_01012] تسمح بمُخطِر واحد فقط كحد أقصى، يُرجَّح أن يشغل هذا الاستدعاء أيضاً خانة المُخطِر نفسها ويكتب فوق المعالج المضبوط مسبقاً عند إعادة التسجيل. سؤال Q-5d8c1832558ac15b (مفتوح)

الاستخدام

تُستخدم الدالة RegisterNetworkStateChangeNotifier لتسجيل مُخطِر للحالة الفعلية للشبكة [SWS_ANM_01010]. وهي مُصرَّح بها في ملف الرأس ara/nm/network_handle.h ومُعرَّفة كـ noexcept [SWS_ANM_01010]. وتُمرَّر كمعلمة NetworkStateChangeNotifier notifier؛ ويتم الإرجاع بشكل متزامن عبر ara::core::Result<void> [SWS_ANM_01010]. يمكن تسجيل مُخطِر واحد كحد أقصى للحالة [SWS_ANM_01010].

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

في حالة حدوث خطأ، يُرجع ara::core::Result رمز الخطأ NmErrc::kInvalidHandler [SWS_ANM_01010]. ويشير هذا لجهة الاستدعاء إلى أن المعالج المُمرَّر غير صالح [SWS_ANM_01010].

التزامن والقيود

تم تحديد الواجهة صراحة بأنها not thread-safe [SWS_ANM_01010]. لذلك يجب على المكونات المُستدعِية التأكد من أن استدعاءات RegisterNetworkStateChangeNotifier لا تتم بالتزامن دون مزامنة خارجية. ونظراً لأن المواصفة تنص على مُخطِر واحد كحد أقصى، فمن المفترض على الأرجح أن يؤدي الاستدعاء المتكرر إلى الكتابة فوق تسجيل موجود أو رفضه [SWS_ANM_01010]. سؤال Q-5e3ac4e4d2b33e9f (مفتوح)

تفاعل

ترتبط الدالة بشكل مباشر بالتحميل الزائد للقالب [SWS_ANM_01015]. فبينما تقوم الدالة الأساسية بربط المُخطِر دون سياق تنفيذ صريح، يتيح [SWS_ANM_01015] تمرير معلمة إضافية ExecutorT&& executor للتحكم في تنفيذ المعالج في سياق محدد مسبقاً [SWS_ANM_01015]. يُحقق كلا المتغيرين متطلبات من RS_Nm_00051، وهما معرفان في ملف الرأس نفسه، ويشتركان في التصنيف not thread-safe وكذلك الخطأ NmErrc::kInvalidHandler [SWS_ANM_01010] [SWS_ANM_01015].

تسجل دالة القالب RegisterNetworkStateChangeNotifier ([SWS_ANM_01015]) من ملف الرأس ara/nm/network_handle.h دالة رد نداء لمراقبة تغييرات الحالة الفعلية للشبكة. وبالمقارنة مع المتغير ذي المعلمات الأقل، تقبل هذه الواجهة بالإضافة إلى notifier من النوع NetworkStateChangeNotifier سياق تنفيذ مخصصاً من قِبل المستخدم executor (ExecutorT&&)، تُجدول الإخطارات من خلاله وتتم معالجتها بشكل غير متزامن.

معالجة الأخطاء وقيم الإرجاع

الدالة مُصرَّح بها كـ noexcept وتُشير إلى النتيجة عبر ara::core::Result<void> [SWS_ANM_01015]. وإذا حدث خطأ أثناء التسجيل – لا سيما إذا تم تمرير معالج غير صالح أو غير قابل للاستدعاء – تفشل العملية وتُرجع رمز الخطأ NmErrc::kInvalidHandler.

التزامن والتفاعل

فيما يتعلق بأمان الخيوط، تم تحديد الواجهة بأنها not thread-safe [SWS_ANM_01015]. لذلك لا يجوز إجراء استدعاءات التسجيل دون حماية وبشكل متزامن من خيوط متعددة على نفس سياق الحالة. وفي النظام المتكامل، تُكمل الدالة الواجهة الأساسية [SWS_ANM_01010] التي تسجل مُخطِراً واحداً كحد أقصى بدون منفذ صريح (Executor). وكتفسير، يُرجَّح أن ينطبق أيضاً على [SWS_ANM_01015] أنه لا يوجد سوى مُخطِر واحد نشط دائماً، وأن الاستدعاء الجديد يستبدل المعالج المحفوظ مسبقاً. سؤال Q-e9a890e004a4f0ea (مفتوح)

تُستخدم الدالة SetNetworkRequestedState لطلب أو تحرير عنقود شبكة فرعية (PNC) أو VLAN أو شبكة مادية عبر ملف الترويسة ara/nm/network_handle.h وفقًا لـ [SWS_ANM_01009]. ويتم تمرير الحالة الهدف المطلوبة networkState من النوع NetworkStateType كمعلمة إدخال. ويُرجَّح تنفيذ الاستدعاء بشكل متزامن، نظرًا لأن الواجهة تُرجع ara::core::Result<void> مباشرةً بدلاً من كائن Future غير متزامن. سؤال Q-38a98cab4ea55704 (مفتوح)

في حالة النجاح، تُرجع الطريقة ara::core::Result<void> فارغًا [SWS_ANM_01009]. وإذا تعذر تعيين الحالة المطلوبة أو لم تكن خدمة إدارة الشبكة جاهزة، تُبلّغ الدالة عن رمز الخطأ المحدد NmErrc::kServiceNotAvailable في كائن النتيجة [SWS_ANM_01009]. ويجب على مكونات البرمجيات المستدعية تقييم كائن الخطأ هذا بشكل صريح للاستجابة بصورة ملائمة للخدمات غير المتاحة.

فيما يتعلق بالتزامن، صُنِّفت العملية صراحةً وفقًا للمواصفة على أنها not thread-safe [SWS_ANM_01009]. لذلك، لا يجوز إجراء استدعاءات متزامنة على نفس المقبض دون مزامنة من جانب التطبيق لتجنب حالات السباق (Race Conditions). بالإضافة إلى ذلك، يضمن التصريح باستخدام noexcept عدم تسرب أي استثناءات ++C إلى الخارج [SWS_ANM_01009].

الاستخدام

تنتمي الدالة UnregisterNetworkRequestedStateChangeNotifier إلى وحدة Network Management التكيفية (anm) ويتم التصريح عنها عبر ملف الرأس ara/nm/network_handle.h [SWS_ANM_01013]. وتتمثل مهمتها في إلغاء الإخطار الخاص بتغييرات حالة الشبكة المطلوبة [SWS_ANM_01013]، وبذلك تساهم في تنفيذ متطلب المنبع RS_Nm_00051.

لا تتوقع الواجهة أي معلمات تمرير ولا تُرجع أي قيمة (void) [SWS_ANM_01013]. تفسير: نظرًا لأن التوقيع لا ينص على نوع نتيجة غير متزامن، يُرجّح أن يتم تنفيذ الاستدعاء بشكل متزامن وأن يسري إلغاء التسجيل فور انتهاء الدالة. سؤال Q-df3005625905440a (مفتوح)

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

تم تحديد الدالة باستخدام noexcept [SWS_ANM_01013]، ومن ثم فهي لا تُطلق أي استثناءات. لا تنص المواصفة على رموز أخطاء أو استجابات أخطاء خاصة للجهة المستدعية.

التزامن والقيود

فيما يتعلق بأمان مؤشرات الترابط، صُنفت الدالة صراحةً على أنها not thread-safe [SWS_ANM_01013]. ولذلك، يتعين على وحدات البرمجيات المستدعية ضمان عدم تنفيذ إلغاء التسجيل بالتزامن مع عمليات وصول أخرى إلى نفس النسخة عبر تدابير مزامنة مناسبة.