Windows للمسؤولين والمطورين الأدلة التقنية

واجهة Win32 API: كيف يكلم برنامجك نظام Windows؟

نقرأ واجهة Win32 ببرامج C صغيرة على Windows 11: أين يعيش كود الدوال، ولماذا يتلف الاسم العربي مع نسخة A، وكيف تقرأ GetLastError وHRESULT دون أن يخدعك رقم قديم.

واجهة Win32 API: كيف يكلم برنامجك نظام Windows؟

إذا كتبت برنامجاً على Windows بأي لغة، سواءً كانت C# أو Python أو Go أو Java، فهناك لحظة لا تراها يتحول فيها سطرك البسيط مثل open("report.txt") إلى استدعاء دالة اسمها CreateFileW في مكتبة اسمها kernel32.dll. وهذه الدالة وأخواتها، وهي بالآلاف، هي واجهة Win32 API التي يكلم بها كل برنامج نظام Windows منذ أكثر من ثلاثين سنة. ولذلك عندما يظهر لك في أي لغة الخطأ «The system cannot find the file specified»، فأنت تقرأ نصاً كتبته Microsoft لرمز الخطأ رقم 2 في Win32، ولم تكتبه مكتبة لغتك. وعندما يعمل برنامجك عندك ويطبع أسماء الملفات العربية علامات استفهام عند زميلك، فالسبب غالباً في حرف واحد في آخر اسم دالة: A أو W.

وقد شرحنا في مقال كيف يعمل Windows من الداخل الطبقات من البرنامج إلى النواة Kernel، وكيف ينزل طلب الكتابة في ملف عبر kernelbase.dll وntdll.dll ثم استدعاء النظام System Call. وهذا المقال يقف في الطبقة التي يكتب لها المطور فعلاً: كيف تقرأ دالة من Win32، وكيف تعرف أنها فشلت ولماذا، وما قصة النسختين A وW، وما هو المقبض Handle، ولماذا يقول Windows لبرنامج بلا ملف Manifest إن رقم إصداره 6.2. وكل ذلك ببرامج صغيرة بلغة C نبنيها ونشغلها على جهاز Windows 11 حقيقي، وبحساب مستخدم عادي Standard User.

وسوف نتناول في هذا المقال ما يلي:

  • ما هي Win32 API، ولماذا ما زال اسمها 32 على أنظمة 64 بت.
  • المكتبات التي تحمل الدوال، ولماذا يعيش كود CreateFileW في مكتبة غير التي توثقها Microsoft.
  • كيف تقرأ توقيع دالة في Microsoft Learn: الأنواع Types، وتعليقات SAL، والقيمة المرجعة.
  • النسختان A وW، وما يحدث لاسم ملف عربي في كل واحدة، ومعهما خيار UTF-8 في ملف Manifest.
  • أربعة أنظمة للأخطاء: GetLastError وHRESULT وNTSTATUS وerrno، وكيف تحول الرقم إلى نص بالدالة FormatMessageW.
  • المقابض Handles، والقيمتان اللتان تعني كل منهما «فشل».
  • لماذا يكذب Windows على برنامجك في رقم الإصدار، ومن أين تعرف الرقم الحقيقي.

وهذا المقال أول مقالات مرحلة «Windows للمطورين»، وبعده نبني نافذة حقيقية بحلقة الرسائل، ثم العمليات والملفات، ثم المكتبات المشتركة DLL ونموذج المكونات COM:

دليلأول برنامج Win32 بلغة C: نافذة وحلقة الرسائلنكتب نافذة Win32 بلغة C ونسجل كل رسالة تصلها، ثم نجعلها عربية بـ WS_EX_LAYOUTRTL ونرى لماذا يعلن Windows بعد خمس ثوان أن البرنامج لا يستجيب.دليلWin32 للعمليات والملفات: CreateProcess وCreateFileنشغل برامج أخرى ونقرأ مخرجها ونفتح الملفات بلغة C على Windows 11 بصلاحيات مستخدم عادي، ونرى لماذا تتجمد الأدوات مع الأنابيب ولماذا يبقى الملف مفتوحاً بعد أن تغلقه.دليلالمكتبات المشتركة DLL: التحميل وترتيب البحث وDLL Hellنبني مكتبة DLL صغيرة بأنفسنا ونراقب المحمل وهو يقرأ جداولها ويحملها ويستدعي DllMain، ثم نرى من أين جاء جحيم المكتبات وكيف عزله Windows بالنسخ جنباً إلى جنب.دليلنموذج المكونات COM من الداخل: الواجهات والتسجيلنبني خادم COM صغيراً بلغة C++ ونسجله للمستخدم الحالي فقط، ونتتبع كل QueryInterface وAddRef وRelease حتى نفهم لماذا يظهر Class not registered وE_NOINTERFACE.

ما هي Win32 API، ولماذا ما زال اسمها 32؟

الواجهة البرمجية API، واختصاراً لـ Application Programming Interface، هي مجموعة الدوال والأنواع والثوابت التي يعرضها نظام التشغيل Operating System للبرامج، وWin32 هو اسم هذه الواجهة في Windows. وكل ما يفعله برنامج على Windows، من فتح ملف إلى رسم زر إلى قراءة مفتاح من السجل Registry، يمر في النهاية عبر دالة منها، حتى لو كتبت البرنامج بلغة لا تعرف عن Win32 شيئاً، لأن مكتبة اللغة نفسها هي التي تستدعيها نيابة عنك. ويمكنك أن ترى القائمة الكاملة مرتبة حسب المجالات في صفحة Windows API index في Microsoft Learn.

والاسم له تاريخ: كانت الواجهة الأولى في Windows 3.x تسمى Win16 لأنها مبنية لمعالجات 16 بت، وعندما صدر Windows NT 3.1 في 1993 ثم Windows 95 جاءت النسخة الجديدة للمعالجات 32 بت فسميت Win32، وقد روينا قصة النواة التي حملتها في قصة Windows NT وDave Cutler. وعندما انتقل Windows إلى معالجات 64 بت لم تغير Microsoft الاسم، وإنما بنت الواجهة نفسها بمؤشرات Pointers من 64 بت، فبقي اسمها الرسمي Windows API واسمها الشائع Win32، وبقيت المكتبة الأساسية تسمى kernel32.dll وهي ملف 64 بت في مجلد System32، والمجلد الذي فيه الملفات 32 بت اسمه SysWOW64. وهذه من الأمور التي تربك كل من يبدأ مع Windows، والسبب واحد: Microsoft تحافظ على الأسماء القديمة لأن آلاف البرامج تكتبها حرفياً في كودها.

وقد يتساءل البعض: إذا كانت هناك واجهات أحدث مثل .NET وWinRT، فلماذا يتعلم المطور Win32 اليوم؟ والإجابة أن كل هذه الطبقات تقف فوقها، فعندما تفتح ملفاً في C# بالكلاس FileStream فإن .NET يستدعي CreateFileW، وعندما يفشل الفتح فإن الاستثناء Exception الذي تراه يحمل رقم الخطأ نفسه الذي أعادته Win32. ولذلك فإن من يعرف هذه الطبقة يقرأ الأخطاء في أي لغة، ويعرف ما الذي تستطيع اللغة أن تفعله وما الذي لا تستطيعه، ويفهم أدوات مثل Process Explorer التي تعرض لك الأشياء بأسمائها في Win32.

أين تعيش الدوال؟ المكتبات التي يكلمها برنامجك

الدوال موزعة على مكتبات مشتركة DLL، واختصاراً لـ Dynamic-Link Library، وكل صفحة دالة في Microsoft Learn تذكر في آخرها اسم المكتبة التي تصدرها Export وملف الترويسة Header الذي فيه تعريفها. والمكتبات التي سوف تقابلها في أغلب البرامج هي:

  • kernel32.dll وkernelbase.dll: الملفات والعمليات Processes والخيوط Threads والذاكرة والمزامنة Synchronization، أي كل ما ليس نافذة ولا رسماً.
  • user32.dll: النوافذ Windows والرسائل Messages ولوحة المفاتيح والفأرة، وهي موضوع المقال القادم.
  • gdi32.dll: واجهة الرسم القديمة GDI، واختصاراً لـ Graphics Device Interface، للخطوط والأشكال والصور على الشاشة والطابعة.
  • advapi32.dll: الخدمات «المتقدمة» كما سمتها Microsoft في التسعينات: السجل Registry، والأمان Security، والخدمات Services، وسجل الأحداث Event Log.
  • shell32.dll وole32.dll وcombase.dll: واجهة سطح المكتب Shell ونموذج المكونات COM.
  • ntdll.dll: آخر طبقة في وضع المستخدم User Mode، وأغلب دوالها غير موثقة للاستخدام المباشر.

ولكن هناك تفصيل لا تقوله صفحات التوثيق صراحة: المكتبة التي توثقها الصفحة ليست دائماً المكتبة التي فيها الكود. ففي Windows 7 بدأت Microsoft مشروعاً لتفكيك المكتبات الكبيرة إلى أجزاء أصغر، ونقلت أغلب كود kernel32.dll وجزءاً من advapi32.dll إلى مكتبة جديدة اسمها kernelbase.dll، وبقيت الأسماء القديمة كواجهة رقيقة حتى لا يتوقف أي برنامج قديم يربط Link مع kernel32.dll. ولكي نرى هذا بأعيننا لا أن نقرأه، كتبنا برنامجاً صغيراً يسأل عن عنوان كل دالة من مكتبتها الموثقة، ثم يسأل Windows من يملك هذا العنوان.

جدول يبين المكتبة الموثقة لكل دالة والمكتبة التي يوجد فيها الكود فعلاً مثل KERNELBASE.dll وntdll.dll
البرنامج يستدعي الاسم الموثق، والكود قد يكون في مكتبة أخرى بعد تعليمة jmp أو توجيه.

تجهيز المختبر Lab

المختبر مجلد lab مع المقال، وفيه خمسة برامج صغيرة بلغة C وسكربت PowerShell صغير، ونبني البرامج بالمترجم MinGW-w64 داخل Container من Alpine Linux حتى لا نثبت أي مترجم Compiler على Windows نفسه، ثم نشغلها على Windows بسكربت PowerShell يحفظ مخرج كل برنامج في ملف out-NN-*.txt. ولا يحتاج أي شيء في المختبر صلاحيات المسؤول Administrator، ولا يغير أي إعداد في الجهاز، والبرامج تعمل في مجلد مؤقت يحذفه السكربت في آخره.

cd lab
docker run --rm -v "%cd%:/src" -w /src alpine:3.22 sh build.sh
powershell -NoProfile -ExecutionPolicy Bypass -File run.ps1

والملف build.sh يثبت المترجم داخل الـ Container ثم يبني البرامج، ولاحظ أنه يبني unicode.exe وversion.exe مرتين: مرة بلا ملف Manifest ومرة مع ملف يغير سلوك Windows مع البرنامج، وهذا هو الفرق الذي سوف نقيسه:

CC="x86_64-w64-mingw32-gcc -O1 -municode -Wall"
mkdir -p build
$CC -o build/errors.exe 01-errors.c
$CC -o build/unicode.exe 02-unicode.c
x86_64-w64-mingw32-windres utf8.rc -O coff -o build/utf8.res
$CC -o build/unicode-utf8.exe 02-unicode.c build/utf8.res
$CC -o build/layers.exe 03-layers.c -lpsapi
$CC -o build/handles.exe 04-handles.c
$CC -o build/version.exe 05-version.c
x86_64-w64-mingw32-windres win10.rc -O coff -o build/win10.res
$CC -o build/version-win10.exe 05-version.c build/win10.res

والخيار -municode يجعل نقطة الدخول Entry Point هي wmain بدل main، أي أن البرنامج يستلم معاملات سطر الأوامر نصوصاً عريضة Wide Strings، وسوف ترى بعد قليل لماذا يهمنا هذا. وهذا هو الجهاز الذي شغلنا عليه المختبر كما يكتبه السكربت:

OS        : Microsoft Windows 11 Pro 24H2 (build 26100.9711)
UI lang   : en-US, installed MUI languages: en-US
PowerShell: 5.1.26100.9711
Elevated  : False

لاحظ السطرين الأخيرين: الحساب غير مرفوع الصلاحيات Not Elevated، ولغة واجهة Windows الوحيدة المثبتة هي الإنجليزية، وهذا التفصيل الثاني سوف يظهر لنا في رسائل الأخطاء.

التجربة الأولى: من يملك كود الدالة؟

البرنامج layers.exe يأخذ عنوان كل دالة بالدالة GetProcAddress من المكتبة التي توثقها Microsoft، ثم يسأل GetModuleHandleExW عن المكتبة التي يقع فيها هذا العنوان. وإذا كانت أول تعليمة عند العنوان تعليمة تحويل غير مباشرة jmp [rip+x]، أي أن الدالة مجرد ممر Stub، فإنه يتبع التعليمة إلى وجهتها ويسأل مرة أخرى:

static void where(const wchar_t *dll, const char *fn) {
    const BYTE *p = (const BYTE *)GetProcAddress(LoadLibraryW(dll), fn);
    wchar_t chain[512]; int n = _snwprintf(chain, 512, L"%ls", owner(p));
    for (int i = 0; i < 4; i++) {
        const BYTE *q = p; if (q[0] == 0x48 && q[1] == 0xFF && q[2] == 0x25) q++;
        if (!(q[0] == 0xFF && q[1] == 0x25)) break;
        p = *(const BYTE **)(q + 6 + *(const INT32 *)(q + 2));
        n += _snwprintf(chain + n, 512 - n, L" (jmp) -> %ls", owner(p));
    }
    out(L"   %-13ls %-17hs -> %ls\n", dll, fn, chain);
}

والمخرج سوف يكون كما يلي:

1) GetProcAddress from the documented DLL, then the module that owns that address
   kernel32.dll  CreateFileW       -> KERNEL32.DLL (jmp) -> KERNELBASE.dll
   kernel32.dll  GetLastError      -> KERNEL32.DLL
   kernel32.dll  HeapAlloc         -> ntdll.dll
   kernel32.dll  Sleep             -> KERNEL32.DLL (jmp) -> KERNELBASE.dll
   user32.dll    MessageBoxW       -> user32.dll
   gdi32.dll     TextOutW          -> GDI32.dll (jmp) -> GDI32.dll
   advapi32.dll  RegOpenKeyExW     -> advapi32.dll (jmp) -> KERNELBASE.dll
   advapi32.dll  OpenProcessToken  -> advapi32.dll (jmp) -> KERNELBASE.dll

وفي المخرج أعلاه لاحظ التالي:

  • CreateFileW وSleep: العنوان الذي أعادته GetProcAddress داخل KERNEL32.DLL فعلاً، ولكن أول تعليمة فيه تعليمة jmp تحول التنفيذ إلى KERNELBASE.dll، أي أن kernel32.dll هنا مجرد لافتة على الباب، والكود الحقيقي في الغرفة المجاورة.
  • HeapAlloc: لم يعد العنوان داخل kernel32.dll أصلاً، وإنما داخل ntdll.dll، لأن المكتبة تصدر الاسم بطريقة التوجيه Forwarding: جدول التصدير Export Table يقول للمحمل Loader إن هذا الاسم موجود في مكتبة أخرى باسم آخر، فيعطيك المحمل العنوان النهائي مباشرة، وهو هنا دالة الكومة Heap في ntdll.dll.
  • RegOpenKeyExW وOpenProcessToken: دوال السجل والأمان التي توثقها Microsoft في advapi32.dll تحول التنفيذ هي أيضاً إلى KERNELBASE.dll، ولذلك إذا رأيت في مكدس الاستدعاءات Call Stack اسم KERNELBASE وأنت تظن أنك استدعيت advapi32، فلا يوجد خطأ في الأداة.
  • TextOutW: وجهة التعليمة بقيت داخل GDI32.dll نفسها، أي أن المكتبة تمرر الطلب داخلياً إلى جزء آخر منها، ولم نتتبع أبعد من ذلك.
  • GetLastError وMessageBoxW: الكود في المكتبة الموثقة نفسها.

والدرس العملي من هذا: اكتب كودك دائماً للمكتبة التي توثقها Microsoft، أي اربط مع kernel32 وadvapi32 كما تقول الصفحة، ولا تربط مع kernelbase.dll مباشرة، لأن مكان الكود تفصيل داخلي غيرته Microsoft من إصدار إلى آخر وقد تغيره مرة أخرى، والاسم الموثق هو العقد الذي تلتزم به. وفي القسم الثالث من المخرج نفسه يطبع البرنامج كل المكتبات المحملة في عمليته، وهو برنامج من 30 سطراً لا يرسم شيئاً:

3) DLLs loaded in this process now (EnumProcessModules)
   layers.exe
   ntdll.dll
   KERNEL32.DLL
   KERNELBASE.dll
   ucrtbase.dll
   user32.dll
   win32u.dll
   GDI32.dll
   gdi32full.dll
   msvcp_win.dll
   IMM32.DLL
   advapi32.dll
   msvcrt.dll
   sechost.dll
   RPCRT4.dll

وهنا لاحظ أن user32.dll وGDI32.dll محملتان رغم أن البرنامج لا ينشئ نافذة، والسبب أن البرنامج نفسه طلبهما بالدالة LoadLibraryW في التجربة، ومع user32.dll جاءت win32u.dll، وهي المقابل لـ ntdll.dll لدوال النوافذ والرسم، فمنها تعبر الطلبات إلى الجزء win32k.sys في النواة. وأما تفاصيل تحميل المكتبات وترتيب البحث عنها فلها مقال مستقل في هذه المرحلة.

كيف تقرأ توقيع دالة في Microsoft Learn؟

أول ما يقابله المطور في توثيق Win32 هو التوقيع Signature، وهو مكتوب بأنواع لا تشبه C العادية: HANDLE وDWORD وLPCWSTR. والصورة التالية تبين توقيع CreateFileW كما في صفحتها في Microsoft Learn، ومعناه خانة خانة:

توقيع الدالة CreateFileW مع شرح الحرف W والأنواع وأقواس in وoptional والقيمة المرجعة عند الفشل
كل خانة في التوقيع تقول لك شيئاً: النسخة، والأنواع، واتجاه المعاملات، وشكل الفشل.

والأنواع كلها أسماء بديلة Typedefs لأنواع C، وصفحة Windows Data Types تعرف كل واحد منها. والقاعدة التي تريحك من حفظها أن الاسم يقرأ من اليسار كجملة: LP تعني مؤشراً Long Pointer، وC تعني ثابتاً Const، وW تعني عريضاً Wide، وSTR تعني نصاً. فالنوع LPCWSTR هو «مؤشر إلى نص عريض ثابت»، أي const wchar_t *. وكلمة Long في LP بقيت من أيام Win16، حيث كان هناك مؤشر قريب Near ومؤشر بعيد Far، واليوم لا يوجد فرق، ولكن الاسم بقي لنفس السبب الذي بقي فيه رقم 32 في kernel32.

أما الأقواس [in] و[out] و[optional] فهي ترجمة التوثيق لتعليقات SAL، واختصاراً لـ Source Annotation Language، وهي علامات مثل _In_ و_Out_opt_ مكتوبة في ملفات الترويسة نفسها، يقرؤها محلل الكود Code Analysis في Visual Studio ليحذرك إذا مررت NULL لمعامل لا يقبله، أو أعطيت مخزناً Buffer أصغر من الحجم الذي تقول إنه لديك. وتشرحها صفحة Understanding SAL. وأهم ما تقرؤه في أي صفحة دالة بعد التوقيع هو قسم القيمة المرجعة Return Value، لأنه يقول لك بالضبط كيف تعرف الفشل، وهذا يختلف من دالة إلى أخرى أكثر مما تتوقع، كما سوف نرى.

وفي التوقيع الحقيقي في ملف الترويسة كلمة لا تظهر في الصفحة هي WINAPI، وهي اصطلاح الاستدعاء Calling Convention: من ينظف المكدس Stack بعد الاستدعاء، وفي أي ترتيب توضع المعاملات. وكانت هذه الكلمة مهمة جداً في برامج 32 بت، لأن WINAPI تعني __stdcall بينما الدوال العادية في C تستخدم __cdecl، والخلط بينهما يفسد المكدس. أما في برامج x64 فهناك اصطلاح واحد للجميع، أول أربعة معاملات في المسجلات Registers والباقي في المكدس، ولذلك لا تفعل الكلمة شيئاً هناك، ولكن اكتبها دائماً في الدوال التي يستدعيها Windows، مثل دالة النافذة ودالة الخيط، حتى يبقى كودك صحيحاً إذا بنيته يوماً لـ 32 بت.

A وW: لماذا توجد كل دالة مرتين؟

إذا بحثت في ملفات الترويسة عن CreateFile فلن تجد دالة بهذا الاسم، وإنما ماكرو Macro يتحول إلى CreateFileW إذا كان الثابت UNICODE معرفاً، وإلى CreateFileA إذا لم يكن، والقاعدة موثقة في صفحة Conventions for Function Prototypes. والسبب تاريخي: كان Windows 95 يعمل بالنصوص بايتاً لكل حرف، بصفحة ترميز Code Page تختلف من بلد إلى آخر، فالعربية في الصفحة 1256 والإنجليزية الغربية في 1252، بينما بني Windows NT من البداية على Unicode بوحدات من 16 بت. فاحتاجت Microsoft أن يعمل الكود نفسه على النظامين، فجعلت لكل دالة تأخذ نصاً نسختين: A، واختصاراً لـ ANSI، تأخذ بايتات بصفحة الترميز الحالية للنظام، وW، واختصاراً لـ Wide، تأخذ UTF-16.

واليوم لم يبق Windows 95، وكل نسخ Windows تعمل داخلياً بـ UTF-16، فالدالة CreateFileA لا تفعل أكثر من تحويل الاسم الذي أعطيته إلى UTF-16 بصفحة الترميز الحالية، ثم استدعاء CreateFileW. والسؤال المهم إذاً: ما هي صفحة الترميز الحالية؟ والإجابة أنها إعداد على مستوى الجهاز كله اسمه لغة البرامج غير Unicode، ويختاره المسؤول من إعدادات المنطقة Region، وعلى الجهاز الذي شغلنا عليه المختبر هي 1252، أي صفحة اللغات الغربية التي لا يوجد فيها حرف عربي واحد. ولكي نرى ما يحدث عملياً، كتبنا البرنامج unicode.exe الذي يأخذ الاسم تقرير.txt ويحوله إلى ثلاثة ترميزات، ثم ينشئ الملف ثلاث مرات بثلاث طرق، ويقرأ من القرص ما حفظ فعلاً:

--- unicode.exe (no manifest)
code pages: ANSI (GetACP) = 1252, OEM (GetOEMCP) = 437

1) UTF-16 (9 code units): 062A 0642 0631 064A 0631 002E 0074 0078 0074

2) the same name as bytes
   code page 1256  ( 9 bytes): CA DE D1 ED D1 2E 74 78 74
   UTF-8 (65001)   (14 bytes): D8 AA D9 82 D8 B1 D9 8A D8 B1 2E 74 78 74
   CP_ACP          ( 9 bytes): 3F 3F 3F 3F 3F 2E 74 78 74
   characters lost in CP_ACP: yes

3) CreateFileW (UTF-16 name)          -> ok
   CreateFileA (code page 1256 bytes) -> ok
   CreateFileA (UTF-8 bytes)          -> ok

   files on disk now (FindFirstFileW):
   ÊÞÑíÑ.txt      00CA 00DE 00D1 00ED 00D1 002E 0074 0078 0074
   تقرير.txt 00D8 00AA 00D9 201A 00D8 00B1 00D9 0160 00D8 00B1 002E 0074 0078 0074
   تقرير.txt      062A 0642 0631 064A 0631 002E 0074 0078 0074

4) exports in kernel32.dll: CreateFileA yes, CreateFileW yes, CreateFile no

وفي المخرج أعلاه لاحظ التالي:

  • السطر الأول: صفحة الترميز للبرامج غير Unicode هي 1252، وصفحة الطرفية Console القديمة OEM هي 437، أي صفحة IBM PC الأصلية من الثمانينات.
  • UTF-16: الاسم تسع وحدات، كل حرف عربي وحدة واحدة مثل 062A للتاء، وهذا ما تأخذه CreateFileW كما هو.
  • CP_ACP: عندما طلبنا التحويل بصفحة النظام الحالية ظهر كل حرف عربي بالبايت 3F، وهو علامة الاستفهام، وقالت الدالة WideCharToMultiByte إن هناك حروفاً ضاعت. وهذا بالضبط ما يحدث لأي برنامج يحول نصاً عربياً إلى A على جهاز إعداده 1252: يرى المستخدم ?????.txt.
  • الملفات الثلاثة على القرص: كل استدعاء من الثلاثة قال ok، ولكن فقط CreateFileW أنشأ الاسم الصحيح. فبايتات 1256 قرأتها CreateFileA بصفحة 1252 فصارت ÊÞÑíÑ.txt، وبايتات UTF-8 صارت تقرير.txt. وهذا أخطر ما في القصة: لا توجد رسالة خطأ، والدالة نجحت، والملف أنشئ باسم تالف.
  • الصادرات Exports: لا توجد دالة اسمها CreateFile في المكتبة، فالاسم بلا حرف موجود في ملفات الترويسة فقط.

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

الاسم تقرير.txt بثلاثة ترميزات وما حفظه القرص بلا Manifest ومع Manifest فيه UTF-8
مع صفحة 1252 لا ينجو إلا الاسم الذي مر عبر W، ومع UTF-8 في الـ Manifest تنجو UTF-8 وتتلف 1256.

ماذا يحدث إذا قال البرنامج إن صفحته UTF-8؟

منذ Windows 10 الإصدار 1903 يستطيع البرنامج أن يطلب لنفسه صفحة UTF-8 للدوال A، دون أن يغير المسؤول إعداد الجهاز كله، وذلك بسطر في ملف البيان Manifest، وهو ملف XML يضمن داخل الملف التنفيذي ويقرؤه Windows قبل تشغيل البرنامج، والطريقة موثقة في صفحة Use UTF-8 code pages in Windows apps. وهذا هو الملف الذي ضمناه في unicode-utf8.exe:

<application xmlns="urn:schemas-microsoft-com:asm.v3">
  <windowsSettings>
    <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
  </windowsSettings>
</application>

والبرنامج هو نفسه حرفاً بحرف، والمخرج سوف يكون كما يلي:

--- unicode-utf8.exe (activeCodePage UTF-8 in its manifest)
code pages: ANSI (GetACP) = 65001, OEM (GetOEMCP) = 65001
...
   CP_ACP          (14 bytes): D8 AA D9 82 D8 B1 D9 8A D8 B1 2E 74 78 74
   characters lost in CP_ACP: no

3) CreateFileW (UTF-16 name)          -> ok
   CreateFileA (code page 1256 bytes) -> ok
   CreateFileA (UTF-8 bytes)          -> ok

   files on disk now (FindFirstFileW):
   تقرير.txt      062A 0642 0631 064A 0631 002E 0074 0078 0074
   �����.txt      FFFD FFFD FFFD FFFD FFFD 002E 0074 0078 0074

صارت صفحة البرنامج 65001، أي UTF-8، على الجهاز نفسه الذي إعداده 1252، فكتبت CreateFileA ببايتات UTF-8 الملف الصحيح نفسه الذي كتبته CreateFileW، ولذلك لا ترى في القائمة إلا ملفين. أما بايتات 1256 فهي ليست UTF-8 صالحة، فاستبدل Windows كل حرف منها بحرف الاستبدال U+FFFD. والخلاصة أن الـ Manifest لا يصلح كل شيء، وإنما يجعل البرنامج يتكلم ترميزاً واحداً معروفاً بدل ترميز يختلف من جهاز إلى آخر، وهذا يكفي لمكتبات كتبت لـ Linux وتعمل بـ char * وUTF-8 في كل مكان.

وقد يتساءل البعض: أيهما أفضل إذاً، W في كل مكان أم A مع UTF-8؟ والإجابة أن Microsoft نفسها توصي في الصفحة نفسها بـ W للكود الجديد الخاص بـ Windows، وبـ UTF-8 للكود المشترك بين الأنظمة. والقاعدة البسيطة التي ننصح بها هي التالية: داخل برنامجك احفظ النصوص بالترميز الذي تريده، وعند حدود Win32 استدعي دائماً نسخة W، وحول بنفسك بالدالتين MultiByteToWideChar وWideCharToMultiByte وأنت تعرف من أي ترميز إلى أي ترميز، ولا تترك Windows يخمن بصفحة الجهاز. وصفحة Code Pages تشرح لماذا تنصح Microsoft بذلك: صفحة الجهاز قد تختلف بين جهاز المطور وجهاز العميل، وقد تتغير بإعداد واحد.

كيف تعرف أن الدالة فشلت؟ أربعة أنظمة للأخطاء

هنا يأتي أكثر ما يربك من يكتب لـ Windows أول مرة: لا يوجد نظام واحد للأخطاء، وإنما أربعة، لأن الواجهات بنيت في أزمنة مختلفة. والصورة التالية تبين الملف المفقود نفسه كما يظهر في كل نظام:

أربع بطاقات للخطأ نفسه: GetLastError يساوي 2 وHRESULT 0x80070002 وNTSTATUS 0xC0000034 وerrno 2
ملف مفقود واحد، وأربعة أرقام بحسب الطبقة التي سألتها.
  • BOOL أو HANDLE ثم GetLastError: أغلب دوال Win32 الكلاسيكية تعيد قيمة تقول «فشلت» فقط، مثل FALSE أو NULL أو INVALID_HANDLE_VALUE، وتحفظ السبب في مكان خاص بالخيط تقرؤه بالدالة GetLastError. والأرقام مسرودة في صفحة System Error Codes.
  • HRESULT: رقم من 32 بت تعيده دوال COM وأغلب الواجهات الأحدث مباشرة، وفيه البت الأعلى للفشل، ثم الجهة Facility التي جاء منها، ثم الرمز، كما في صفحة Structure of COM Error Codes.
  • NTSTATUS: نظام النواة وntdll.dll والتعريفات Drivers، وهو الذي تراه في رموز خروج البرامج التي لا تجد مكتبة، مثل 0xC0000135 التي شرحناها في حالات Sysinternals، والقائمة في NTSTATUS Values.
  • errno: نظام مكتبة C القياسية، ولا علاقة له بـ Windows، ولكنه يعيش في البرنامج نفسه إذا استخدمت fopen وأخواتها.

والبرنامج errors.exe يطلب الملف المفقود نفسه بكل طريقة، وهذا أوله:

HANDLE h = CreateFileW(L"no-such-file.txt", GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, 0, NULL);
DWORD e = GetLastError();
out(L"1) CreateFileW on a missing file\n   handle = %p  (INVALID_HANDLE_VALUE = %p)\n   GetLastError = %lu  \"%ls\"\n\n", h, INVALID_HANDLE_VALUE, e, msg(e, 0));

والدالة msg في الملف out.h تستدعي FormatMessageW لتحول الرقم إلى النص الذي يكتبه Windows لهذا الرمز:

DWORD n = FormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, code, lang, buf, 512, NULL);

والمخرج سوف يكون كما يلي:

1) CreateFileW on a missing file
   handle = FFFFFFFFFFFFFFFF  (INVALID_HANDLE_VALUE = FFFFFFFFFFFFFFFF)
   GetLastError = 2  "The system cannot find the file specified."

2) FormatMessageW for code 2 in other languages
   en-US: The system cannot find the file specified.
   ar-SA: (FormatMessageW failed, GetLastError = 15100)

3) CreateFileW(OPEN_ALWAYS) succeeds twice
   first call : GetLastError = 0  "The operation completed successfully."
   second call: GetLastError = 183  "Cannot create a file when that file already exists."

4) GetLastError read after another successful call: 2  "The system cannot find the file specified."

5) HRESULT_FROM_WIN32(2) = 0x80070002  severity=1 facility=7 code=2
   text: The system cannot find the file specified.
   NTSTATUS 0xC0000034 (from ntdll.dll): Object Name not found.
      RtlNtStatusToDosError -> 2
   NTSTATUS 0xC0000135 (from ntdll.dll): The code execution cannot proceed because %hs was not found. Reinstalling the program may fix this problem.
      RtlNtStatusToDosError -> 126

6) errno from the C runtime is a third, separate number:
   _wfopen -> 0000000000000000, errno = 2 (No such file or directory), GetLastError = 2

وكل قسم من هذا المخرج درس مستقل، لذلك نأخذها واحداً واحداً.

النص من FormatMessageW، وبأي لغة؟

القسم الأول هو ما تتوقعه: المقبض يساوي INVALID_HANDLE_VALUE، وهي القيمة -1 التي تظهر في x64 كـ FFFFFFFFFFFFFFFF، والسبب 2 ونصه المعروف. والقسم الثاني أكثر فائدة: طلبنا النص نفسه بالعربية، ففشلت FormatMessageW نفسها بالرمز 15100، وهو ERROR_MUI_FILE_NOT_FOUND، أي أن ملف اللغة العربية لرسائل النظام غير مثبت، لأن الجهاز لا يحمل إلا واجهة إنجليزية كما رأينا في سطر MUI languages. والدرس هنا مهم لمن يعرض رسائل Windows للمستخدم: النص يأتي من ملفات اللغات المثبتة على جهاز المستخدم، لا على جهازك، وإذا طلبت لغة بعينها فقد لا تجدها، لذلك مرر صفراً في معامل اللغة ليختار Windows بترتيبه الافتراضي، وتعامل مع فشل الدالة نفسها، ولا تكتب النص الإنجليزي في الكود كأنه ثابت، لأن المستخدم الذي واجهته عربية سوف يرى نصاً عربياً.

ولاحظ أيضاً أن FormatMessageW هي نفسها دالة Win32، ففشلها يقرأ بـ GetLastError مثل أي دالة أخرى، وهذا ما فعله البرنامج حين كتب 15100. وفي ملف out.h ستجد أن دالة الطباعة نفسها تحفظ آخر خطأ وتعيده بعد أن تطبع، لأن الطباعة تستدعي WriteFile، وهي دالة قد تغير القيمة، وهذا يقودنا إلى أهم قاعدة في المقال.

GetLastError: متى تقرؤه، ومتى يكذب؟

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

  • نجاح يكتب رقماً: في القسم 3 فتحنا الملف بالخيار OPEN_ALWAYS مرتين، ونجحت الدالة في المرتين، ولكنها في المرة الثانية كتبت 183، وهو ERROR_ALREADY_EXISTS، لأن صفحة CreateFileW توثق أنها تخبرك بهذه الطريقة أن الملف كان موجوداً. فلو كان كودك يفحص GetLastError() != 0 ليعرف الفشل، لظن أن الفتح فشل وهو ناجح.
  • نجاح لا يمسح الرقم: في القسم 4 فشل الفتح فكتب 2، ثم نجحت GetCurrentDirectoryW، ثم قرأنا GetLastError فوجدنا 2. فالدوال الناجحة لا تعيد القيمة إلى صفر في الغالب، والرقم الذي تقرؤه قد يكون من دالة فشلت قبل عشرين سطراً، فإذا قرأته دون أن تعرف أن آخر دالة فشلت، فقد تكتب في سجلك سبباً لا علاقة له بما حدث.

والسؤال الطبيعي هنا: أين يحفظ هذا الرقم؟ وهل يتأثر بالخيوط الأخرى في البرنامج نفسه؟ والإجابة في القسم الثاني من مخرج layers.exe، حيث كتبنا 2 في الخيط الأول، ثم أنشأنا خيطاً ثانياً كتب 5، ثم قرأنا في الأول مرة أخرى:

2) the last error is a field of the thread (TEB), not a global
   thread 1: SetLastError(2), GetLastError() = 2, TEB+0x68 = 2
   thread 2: SetLastError(5), GetLastError() = 5
   thread 1 after thread 2 ran: GetLastError() = 2

الرقم يعيش في بنية اسمها TEB، واختصاراً لـ Thread Environment Block، ولكل خيط بنيته، وقرأنا الحقل بأنفسنا من الإزاحة 0x68 فوجدناه 2 كما قالت GetLastError. وهذه الإزاحة تفصيل داخلي لـ x64 قرأناه للتعلم فقط، فلا تكتبه في كود حقيقي. والنتيجة العملية أن الخيوط لا تفسد أرقام بعضها، ولكن داخل الخيط الواحد كل دالة تستدعيها بين الفشل والقراءة قد تفسد الرقم، ومن هذه الدوال ما لا تتوقعه: الطباعة إلى السجل، وتحرير الذاكرة، وأي دالة في مكتبة خارجية.

خيطان لكل منهما بنية TEB فيها LastErrorValue، وبطاقة تبين أن الرقم داخل الخيط الواحد يبقى من آخر فشل
الرقم خاص بالخيط، ولكنه داخل الخيط يبقى من آخر دالة كتبته، لا من آخر دالة استدعيتها.
⚠️
إذا كتبت دالة مساعدة للتسجيل Logging أو الطباعة، فاحفظ آخر خطأ في أولها وأعده في آخرها بـ SetLastError، كما في out.h في المختبر، والسبب أن من يستدعيها قد يقرأ GetLastError بعدها وهو يظن أن الرقم ما زال للدالة التي فشلت قبلها.

HRESULT وNTSTATUS: الرقم نفسه بلباس آخر

القسم 5 من المخرج يبين العلاقة بين الأنظمة. فالماكرو HRESULT_FROM_WIN32(2) أعطى 0x80070002، والبرنامج فككه: البت الأعلى 1 يعني فشلاً، والجهة 7 هي FACILITY_WIN32، والرمز 2. ولذلك إذا رأيت في أي رسالة خطأ من .NET أو PowerShell أو Windows Update رقماً يبدأ بـ 0x8007، فاقرأ آخر أربع خانات بالنظام الست عشري وستجد رمز Win32 العادي، فـ 0x80070005 هو 5، أي ERROR_ACCESS_DENIED، و0x80070002 هو الملف المفقود. وهذه أنفع حيلة في المقال لمسؤول الأنظمة، لأن هذه الأرقام تظهر له كل يوم في سجلات التحديثات.

أما NTSTATUS فلا يحمل رمز Win32 داخله، وإنما له أرقامه الخاصة، فالملف المفقود عند النواة هو 0xC0000034 واسمه STATUS_OBJECT_NAME_NOT_FOUND، ونصه نقرؤه من جدول الرسائل في ntdll.dll نفسها بالخيار FORMAT_MESSAGE_FROM_HMODULE. والدالة RtlNtStatusToDosError هي التي تترجمه إلى 2، وهي الترجمة نفسها التي تفعلها kernelbase.dll قبل أن تكتب الرقم في الخيط. ولاحظ نص 0xC0000135: فيه %hs لأن النظام يضع اسم المكتبة المفقودة في هذا المكان عندما يعرض الرسالة، ونحن طلبنا النص بالخيار FORMAT_MESSAGE_IGNORE_INSERTS فبقي كما هو، ولو نسيت هذا الخيار مع رسالة فيها إدراجات Inserts ولم تعطها قيماً، فقد تقرأ FormatMessageW من ذاكرة لا تملكها، ولذلك تنصح صفحتها بالخيار نفسه عند قراءة رسائل النظام.

والقسم 6 يكمل الصورة: _wfopen من مكتبة C فشلت فكتبت errno = 2، وفي الوقت نفسه بقي GetLastError يساوي 2، لأن مكتبة C استدعت CreateFileW في الداخل. والرقمان هنا متساويان بالصدفة، فالقيمة 2 في errno هي ENOENT في معيار C، والقيمة 2 في Win32 هي ERROR_FILE_NOT_FOUND، وفي أخطاء أخرى لا يتطابقان، فإذا استخدمت مكتبة C فاقرأ errno، وإذا استدعيت Win32 مباشرة فاقرأ GetLastError، ولا تخلط بينهما في رسالة واحدة.

والقاعدة نفسها من PowerShell وC#

قد يظن مطور .NET أن هذا كله لا يخصه، ولكن عندما تستدعي دالة Win32 بنفسك من C# أو PowerShell عبر P/Invoke، واختصاراً لـ Platform Invoke، فأنت تقف على الحد نفسه. والمشكلة أن .NET Runtime يستدعي بنفسه دوال Win32 كثيرة بين سطر وآخر من كودك، فإذا لم تطلب منه أن يحفظ آخر خطأ لحظة رجوع دالتك، فإن الرقم الذي تقرؤه بعدها قد يكون من أي دالة استدعاها هو. والسكربت 06-pinvoke.ps1 في المختبر يعرف CreateFileW مرتين، مرة بالخيار SetLastError = true ومرة بدونه، ويستدعي التي بدونه أولاً في عملية PowerShell جديدة:

Add-Type -Namespace Lab -Name P -MemberDefinition @'
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true, EntryPoint = "CreateFileW")]
public static extern IntPtr CreateFileKeep(string name, uint access, uint share, IntPtr sa, uint disp, uint flags, IntPtr tmpl);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, EntryPoint = "CreateFileW")]
public static extern IntPtr CreateFileLose(string name, uint access, uint share, IntPtr sa, uint disp, uint flags, IntPtr tmpl);
'@

والمخرج سوف يكون كما يلي:

SetLastError = false: handle = -1, GetLastWin32Error = 203 (The system could not find the environment option that was entered)
SetLastError = true : handle = -1, GetLastWin32Error = 2 (The system cannot find the file specified)
[IO.File]::OpenRead : System.IO.FileNotFoundException, HResult = 0x80070002

الاستدعاء الأول فشل كما يجب، ولكن الرقم الذي قرأناه بعده 203، أي ERROR_ENVVAR_NOT_FOUND، وهو رقم لا علاقة له بالملف، وإنما بقي من دالة استدعاها PowerShell قبل ذلك وهو يقرأ متغيرات البيئة Environment Variables. ولو كتبت هذا الرقم في سجل الأخطاء لأرسلت زميلك يبحث عن متغير بيئة مفقود والمشكلة ملف غير موجود. أما مع SetLastError = true فقد حفظ .NET القيمة لحظة رجوع الدالة، فقرأنا 2 الصحيحة بالدالة Marshal.GetLastWin32Error. والسطر الثالث يكمل الصورة من الجهة الأخرى: الكلاس File في .NET استدعى CreateFileW بنفسه، ثم حول الرمز 2 إلى استثناء FileNotFoundException وحفظ معه HRESULT هو 0x80070002، أي الرمز نفسه في الثوب الذي رأيناه قبل قليل. ولذلك عندما ترى رقم HRESULT في استثناء من .NET فأنت تقرأ رمز Win32 الذي بدأ كل شيء.

المقابض Handles: رقم لا تقرأ ما بداخله

المقبض Handle قيمة تعطيك إياها دالة عندما تفتح شيئاً: ملفاً أو حدثاً Event أو عملية أو مفتاح سجل، ثم تمرره إلى كل دالة تعمل على هذا الشيء، وتغلقه في النهاية بـ CloseHandle. وتسميه Microsoft في صفحة Handles and Objects قيمة معتمة Opaque، أي أن البرنامج لا يفترض شيئاً عن معناها. وفي الداخل هو رقم خانة في جدول مقابض Handle Table خاص بالعملية تديره النواة، وكل خانة تشير إلى كائن Object في النواة، ولكن هذا التفصيل له مقال في مرحلة Windows من الداخل، وما يهمنا هنا هو كيف تعامله في كودك. والبرنامج handles.exe يجرب أربعة أشياء:

1) CreateFileW failed: handle = FFFFFFFFFFFFFFFF
   if (!h)                       -> success (wrong!)
   if (h == INVALID_HANDLE_VALUE) -> failed

2) CreateEventW with a bad name: handle = 0000000000000000, GetLastError = 3 "The system cannot find the path specified."
   if (h == INVALID_HANDLE_VALUE) -> success (wrong!)

3) handle values are small numbers, multiples of 4, private to this process:
   event 1 -> 00000000000000DC
   event 2 -> 00000000000000E0
   event 3 -> 00000000000000E4
   event 4 -> 00000000000000E8
   pseudo handles: GetCurrentProcess() = FFFFFFFFFFFFFFFF, GetCurrentThread() = FFFFFFFFFFFFFFFE

4) CloseHandle on a handle that is already closed: FALSE, GetLastError = 6 "The handle is invalid."

وفي المخرج أعلاه لاحظ التالي:

  • قيمتان للفشل: CreateFileW تعيد عند الفشل INVALID_HANDLE_VALUE، بينما CreateEventW تعيد NULL. فالفحص if (!h) بعد CreateFileW يقول «نجح» والملف غير موجود، والفحص بـ INVALID_HANDLE_VALUE بعد CreateEventW يقول «نجح» والحدث غير موجود. وهذا الخطأ من أكثر الأخطاء شيوعاً في كود Win32، وقد شرح Raymond Chen سببه التاريخي في مقاله Why are HANDLE return values so inconsistent? في مدونة The Old New Thing: الدوال التي ورثت سلوكها من MS-DOS، حيث كان الصفر مقبضاً صالحاً، تعيد -1، والدوال الجديدة تعيد NULL. والحل الوحيد أن تقرأ قسم القيمة المرجعة في صفحة كل دالة، ولا تعمم.
  • المقابض أرقام صغيرة: أربعة أحداث متتالية أخذت DC ثم E0 ثم E4 ثم E8، مضاعفات 4 لأن البتين الأدنيين يستخدمهما النظام لأغراض أخرى. والرقم DC في عمليتك قد يشير إلى ملف، والرقم نفسه في عملية أخرى يشير إلى شيء مختلف تماماً، فلا تحاول أن ترسل مقبضاً إلى برنامج آخر كرقم، فهناك دالة خاصة لذلك هي DuplicateHandle.
  • المقابض الوهمية Pseudo Handles: GetCurrentProcess() تعيد -1، وهي القيمة نفسها التي تساوي INVALID_HANDLE_VALUE، وGetCurrentThread() تعيد -2. وهذه ليست خانات في الجدول، وإنما أرقام خاصة تعني «العملية الحالية» و«الخيط الحالي» ولا تحتاج إغلاقاً. والتطابق مع INVALID_HANDLE_VALUE مقصود في التصميم القديم، ويعني أن مقارنة مقبض عملية بها لا تكفي لتعرف أن شيئاً فشل.
  • الإغلاق مرتين: الإغلاق الثاني فشل بالرمز 6، وهذه هي الحالة الجيدة. الحالة السيئة أن يعيد النظام استخدام الرقم نفسه لشيء فتحته بعد الإغلاق الأول، فيغلق الإغلاق الثاني شيئاً آخر تماماً دون أي خطأ، ولذلك اجعل المتغير NULL أو INVALID_HANDLE_VALUE فور إغلاقه.

وإذا نسيت إغلاق المقابض في برنامج يعمل طويلاً، كخدمة أو سيرفر، فإن عددها يكبر حتى تنفد موارد العملية، ويمكنك أن ترى هذا العدد وأنواع المقابض بعينك في تبويب المقابض في Process Explorer، وهي أول ما تنظر إليه عندما يكبر عمود Handles في مدير المهام يوماً بعد يوم.

لماذا يكذب Windows على برنامجك في رقم الإصدار؟

لنفرض أن برنامجك يحتاج ميزة Feature صدرت في Windows 10، فتسأل النظام عن إصداره قبل أن تستخدمها. والطريقة التي ستجدها في أغلب الأمثلة القديمة هي الدالة GetVersionExW، وهذا ما أعادته على جهاز Windows 11 في المختبر:

--- version.exe (no manifest)
GetVersionExW : 6.2 build 9200
RtlGetVersion : 10.0 build 26100
GetVersionExW with dwOSVersionInfoSize = 0: FALSE, GetLastError = 122 "The data area passed to a system call is too small."

--- version-win10.exe (supportedOS Windows 10 in its manifest)
GetVersionExW : 10.0 build 26100
RtlGetVersion : 10.0 build 26100
GetVersionExW with dwOSVersionInfoSize = 0: FALSE, GetLastError = 122 "The data area passed to a system call is too small."

البرنامج بلا Manifest سمع أن النظام هو 6.2 بناء 9200، أي Windows 8 الصادر في 2012، وهو يعمل على Windows 11 بناء 26100. وهذا ليس خطأ، وإنما سلوك موثق بدأ في Windows 8.1، وتشرحه صفحة Operating system version changes in Windows 8.1: البرنامج الذي لا يقول في ملف البيان إنه يعرف الإصدار الجديد يحصل على رقم Windows 8. والسبب أن Microsoft وجدت عبر السنين آلاف البرامج تفحص الإصدار بطريقة خاطئة، مثل برنامج يقارن الرقم الثانوي فقط فيظن أن 6.0 أحدث من 10.0، أو برنامج يرفض العمل إذا لم يكن الإصدار في قائمة يعرفها، فيتوقف عند كل إصدار جديد من Windows. فقررت أن تجعل الرقم الحقيقي لمن يطلبه صراحة فقط.

ثلاث بطاقات: version.exe بلا Manifest يرى 6.2 build 9200، ومع supportedOS يرى 10.0 build 26100، وRtlGetVersion يرى 10.0 في الحالتين
البرنامج نفسه، والفرق سطر supportedOS في ملف البيان.

والطلب الصريح هو قسم التوافق Compatibility في ملف البيان، حيث يذكر البرنامج معرفات GUID للأنظمة التي اختبر عليها، وهذا ما ضمناه في version-win10.exe:

<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
  <application>
    <!-- Windows 10 and Windows 11 -->
    <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
  </application>
</compatibility>

ومع هذا السطر رأى البرنامج 10.0 بناء 26100. ولاحظ أن Windows 11 لا يملك معرفاً خاصاً به، فالمعرف نفسه لـ Windows 10 و11، والفرق بينهما في رقم البناء فقط، وأي بناء من 22000 فما فوق هو Windows 11. أما RtlGetVersion من ntdll.dll فأعادت الرقم الحقيقي في الحالتين لأنها لا تمر على طبقة التوافق، ولكن لا تتخذها طريقاً للالتفاف على النظام، فالطريقة التي توصي بها Microsoft في صفحة Getting the System Version هي أن تسأل عن الميزة نفسها، مثل أن تحاول تحميل الدالة التي تحتاجها بـ GetProcAddress، أو أن تستخدم دوال IsWindows10OrGreater وأخواتها التي تعمل بالـ Manifest نفسه. وملفات البيان عموماً، بكل ما يمكن أن تقوله لـ Windows عن برنامجك، موثقة في صفحة Application manifests، وسوف نعود إليها في مقال النافذة الأولى عند الحديث عن دقة الشاشة DPI.

والسطر الأخير في المخرج يبين نمطاً تكرره Win32 في عشرات البنى Structures: أول حقل في البنية هو حجمها، وعليك أن تملأه قبل الاستدعاء. وعندما تركناه صفراً رفضت الدالة البنية بالرمز 122، أي ERROR_INSUFFICIENT_BUFFER. والسبب أن الحجم هو طريقة Microsoft في إضافة حقول جديدة للبنية في إصدارات لاحقة دون أن تفسد البرامج القديمة، فالدالة تعرف من الحجم أي نسخة من البنية أعطيتها، ولذلك فإن نسيان cbSize أو dwOSVersionInfoSize خطأ صامت في بعض الدوال وصريح في غيرها، فاملأه دائماً بـ sizeof.

مشكلة قابلتنا أثناء كتابة المختبر

في أول تشغيل للبرنامج errors.exe ظهر القسم الثالث هكذا:

3) CreateFileW(OPEN_ALWAYS) succeeds twice
   first call : GetLastError = 0  "The operation completed successfully."
   second call: GetLastError = 183  "The operation completed successfully."

الرقم 183 صحيح، ولكن نصه نص الرقم صفر، فهل أخطأت FormatMessageW؟ لا، والسبب في الكود الذي كتبناه: الدالة المساعدة msg تكتب النص في مخزن ثابت Static Buffer واحد وتعيد مؤشراً إليه، وكنا نستدعيها مرتين في سطر طباعة واحد، فكتبت المرة الثانية فوق الأولى قبل أن يطبع السطر، وطبع المؤشران النص نفسه. وهذا النمط بالضبط موجود في دوال قديمة في مكتبة C نفسها مثل strerror وasctime، ولذلك فصلنا السطر إلى استدعاءين كما ترى في الكود الآن. والدرس العام: عندما تقرأ نصاً عرضته دالة تعيد مؤشراً إلى ذاكرتها هي، فانسخه قبل أن تستدعيها مرة أخرى، وفي الكود الجديد اجعل المتصل هو من يعطي المخزن، كما تفعل FormatMessageW نفسها.

والمفاجأة الثانية كانت في layers.exe: في النسخة الأولى سألنا فقط عن مالك العنوان الذي تعيده GetProcAddress، فقال إن CreateFileW في KERNEL32.DLL، وهذا يناقض ما نعرفه عن kernelbase.dll. ولم تتضح الصورة حتى قرأنا أول بايتات في العنوان ووجدنا تعليمة jmp ببايتاتها FF 25، فأضفنا تتبعها. فالأداة التي تسأل «من يملك هذا العنوان» تقول الحقيقة عن العنوان، ولكن العنوان نفسه قد يكون مجرد ممر.

والمشكلة الثالثة كانت في سكربت PowerShell: كتبنا الثابت GENERIC_READ كما في ملفات الترويسة، أي 0x80000000، فرفض PowerShell 5.1 الاستدعاء برسالة Cannot convert value "-2147483648" to type "System.UInt32". والسبب أن PowerShell يقرأ الرقم الست عشري الذي يملأ 32 بتاً كعدد بإشارة Int32، فيصير سالباً لأن البت الأعلى مفعل، ثم يرفض تحويله إلى uint الذي يطلبه التوقيع. والحل أن تكتب القيمة بنوعها صراحة، كما في السطر $GENERIC_READ = [uint32]2147483648 في السكربت. وستقابل هذا مع كل ثابت في Win32 يبدأ بـ 0x8، وهي كثيرة لأن أغلب الأعلام Flags تستخدم البت الأعلى.

أخطاء شائعة Common Mistakes

  • فحص GetLastError بدل القيمة المرجعة: كما رأينا مع OPEN_ALWAYS، الدالة الناجحة قد تكتب رقماً. افحص القيمة المرجعة أولاً، واقرأ GetLastError فقط عند الفشل.
  • قراءة GetLastError متأخراً: أي دالة بين الفشل والقراءة قد تغيره، حتى سطر التسجيل في السجل. اقرأه في السطر التالي مباشرة واحفظه في متغير.
  • P/Invoke دون SetLastError: في C# وPowerShell يقرأ Marshal.GetLastWin32Error رقماً قديماً إذا لم تكتب SetLastError = true في DllImport، كما رأينا مع الرقم 203.
  • مقارنة كل المقابض بـ NULL: CreateFileW وFindFirstFileW وغيرهما تعيد INVALID_HANDLE_VALUE عند الفشل. اقرأ صفحة كل دالة.
  • استدعاء نسخة A مع نص عربي: على جهاز صفحته 1252 يتحول كل حرف إلى علامة استفهام دون خطأ. استخدم W، أو UTF-8 في ملف البيان مع A.
  • كتابة نص الخطأ الإنجليزي في الكود: النص يأتي من لغات جهاز المستخدم. خذه من FormatMessageW واحفظ الرقم معه في السجل، لأن الرقم لا يتغير بتغير اللغة.
  • الثقة في رقم الإصدار من GetVersionExW: بلا Manifest يعيد 6.2 على كل إصدار حديث. اسأل عن الميزة نفسها، أو أضف supportedOS.
  • نسيان حقل الحجم في البنى: املأ cbSize وأخواته بـ sizeof قبل كل استدعاء.
  • الربط مع kernelbase.dll مباشرة: مكان الكود تفصيل داخلي. اربط مع المكتبة التي توثقها صفحة الدالة.

أين تبحث عندما…؟

ترىابحث فيالمعنى غالباً
رقماً يبدأ بـ 0x8007آخر أربع خانات، ثم System Error Codesرمز Win32 داخل HRESULT
رقماً يبدأ بـ 0xC000قائمة NTSTATUSرمز من النواة أو المحمل
أسماء ملفات بحروف مثل اهل استدعيت A ببايتات UTF-8؟UTF-8 قرئت بصفحة 1252
علامات استفهام مكان العربيةنسخة A وصفحة الجهازالحروف غير موجودة في الصفحة
البرنامج يقول إن Windows هو 6.2قسم compatibility في ملف البيانلا يوجد supportedOS
«نجح» والملف غير موجودفحص المقبض بعد CreateFileWمقارنة بـ NULL بدل INVALID_HANDLE_VALUE
عدد Handles يكبر كل يومتبويب المقابض في Process Explorerمقابض لا تغلق

تدريب عملي Practice

  1. غير في 01-errors.c اسم الملف إلى مسار في مجلد غير موجود، مثل no-dir\\x.txt، وشغل البرنامج: أي رقم يظهر بدل 2، وما نصه؟
  2. جرب CreateFileW على ملف في C:\Windows للكتابة بحسابك العادي، واقرأ الرقم، ثم حوله إلى HRESULT وقارنه بأي رقم 0x8007... رأيته في Windows Update.
  3. أضف إلى 02-unicode.c طباعة نتيجة GetACP() في برنامج مبني مع ملفي البيان معاً، أي UTF-8 وsupportedOS في ملف واحد، وتحقق أن الاثنين يعملان.
  4. افتح Process Explorer واختر عملية PowerShell، وانظر في تبويب المكتبات DLLs هل تجد kernelbase.dll وwin32u.dll، ثم ابحث عن مقبض الملف الذي يكتب فيه السكربت.

حذف المختبر Cleanup

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

lab folder left: False

ولحذف المترجم لا تحتاج شيئاً، لأن الـ Container الذي بنى البرامج يحذف نفسه بالخيار --rm، وتبقى Image الخاصة بـ alpine:3.22 إذا لم تكن لديك من قبل، فاحذفها بـ docker rmi alpine:3.22 إذا لم تحتجها.

الخلاصة Summary

  • Win32 هي الطبقة التي تنتهي إليها كل لغة على Windows، والاسم بقي 32 لأن الأسماء القديمة جزء من العقد مع البرامج.
  • المكتبة التي توثقها Microsoft هي العقد، والكود قد يعيش في kernelbase.dll أو ntdll.dll، فاكتب للاسم الموثق.
  • استدع نسخة W دائماً، أو اجعل صفحة برنامجك UTF-8 بملف البيان، ولا تترك تحويل النص العربي لصفحة الجهاز.
  • افحص القيمة المرجعة كما تقول صفحة الدالة، ثم اقرأ GetLastError فوراً وعند الفشل فقط، وتذكر أن الرقم خاص بالخيط.
  • 0x8007XXXX هو رمز Win32 داخل HRESULT، و0xC000XXXX هو NTSTATUS، وFormatMessageW تعطيك النص بلغة الجهاز إذا كانت مثبتة.
  • بلا Manifest يرى برنامجك Windows 8، فاسأل عن الميزة لا عن الرقم.

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

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال، وتشغيل المختبر على Windows 11 Pro 24H2 (البناء 26100.9711) بـ Windows PowerShell 5.1 وصلاحيات مستخدم عادي، والبرامج مبنية بـ MinGW-w64 GCC 14.2.0 في Container من alpine:3.22.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.