> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# واجهة Win32 API: كيف يكلم برنامجك نظام Windows؟
- URL: https://arabroot.io/articles/واجهة-win32-api-كيف-يكلم-برنامجك-نظام-windows/
- Published: 2026-11-20T11:40:30.000Z
- Updated: 2026-11-20T12:41:22.000Z
- Description: نقرأ واجهة Win32 ببرامج C صغيرة على Windows 11: أين يعيش كود الدوال، ولماذا يتلف الاسم العربي مع نسخة A، وكيف تقرأ GetLastError وHRESULT دون أن يخدعك رقم قديم.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, 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 من الداخل](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D9%8A%D8%B9%D9%85%D9%84-windows-%D9%85%D9%86-%D8%A7%D9%84%D8%AF%D8%A7%D8%AE%D9%84-%D9%88%D8%B6%D8%B9-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D8%AE%D8%AF%D9%85-%D9%88%D8%A7%D9%84%D9%86%D9%88%D8%A7%D8%A9/) الطبقات من البرنامج إلى النواة 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:

[![](https://arabroot.io/content/images/2026/11/win32-first-window-cover-cover.webp)دليلأول برنامج Win32 بلغة C: نافذة وحلقة الرسائلنكتب نافذة Win32 بلغة C ونسجل كل رسالة تصلها، ثم نجعلها عربية بـ WS\_EX\_LAYOUTRTL ونرى لماذا يعلن Windows بعد خمس ثوان أن البرنامج لا يستجيب.](https://arabroot.io/articles/%D8%A7%D9%88%D9%84-%D8%A8%D8%B1%D9%86%D8%A7%D9%85%D8%AC-win32-%D8%A8%D9%84%D8%BA%D8%A9-c-%D9%86%D8%A7%D9%81%D8%B0%D8%A9-%D9%88%D8%AD%D9%84%D9%82%D8%A9-%D8%A7%D9%84%D8%B1%D8%B3%D8%A7%D8%A6%D9%84/)[![](https://arabroot.io/content/images/2026/11/win32-processes-files-cover-cover.webp)دليلWin32 للعمليات والملفات: CreateProcess وCreateFileنشغل برامج أخرى ونقرأ مخرجها ونفتح الملفات بلغة C على Windows 11 بصلاحيات مستخدم عادي، ونرى لماذا تتجمد الأدوات مع الأنابيب ولماذا يبقى الملف مفتوحاً بعد أن تغلقه.](https://arabroot.io/articles/win32-%D9%84%D9%84%D8%B9%D9%85%D9%84%D9%8A%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D9%85%D9%84%D9%81%D8%A7%D8%AA-createprocess-%D9%88createfile/)[![](https://arabroot.io/content/images/2026/11/dll-explained-cover-cover.webp)دليلالمكتبات المشتركة DLL: التحميل وترتيب البحث وDLL Hellنبني مكتبة DLL صغيرة بأنفسنا ونراقب المحمل وهو يقرأ جداولها ويحملها ويستدعي DllMain، ثم نرى من أين جاء جحيم المكتبات وكيف عزله Windows بالنسخ جنباً إلى جنب.](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D9%83%D8%AA%D8%A8%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B4%D8%AA%D8%B1%D9%83%D8%A9-dll-%D8%A7%D9%84%D8%AA%D8%AD%D9%85%D9%8A%D9%84-%D9%88%D8%AA%D8%B1%D8%AA%D9%8A%D8%A8-%D8%A7%D9%84%D8%A8%D8%AD%D8%AB-%D9%88dll-hell/)[![](https://arabroot.io/content/images/2026/11/com-architecture-cover-cover.webp)دليلنموذج المكونات COM من الداخل: الواجهات والتسجيلنبني خادم COM صغيراً بلغة C++ ونسجله للمستخدم الحالي فقط، ونتتبع كل QueryInterface وAddRef وRelease حتى نفهم لماذا يظهر Class not registered وE\_NOINTERFACE.](https://arabroot.io/articles/%D9%86%D9%85%D9%88%D8%B0%D8%AC-%D8%A7%D9%84%D9%85%D9%83%D9%88%D9%86%D8%A7%D8%AA-com-%D9%85%D9%86-%D8%A7%D9%84%D8%AF%D8%A7%D8%AE%D9%84-%D8%A7%D9%84%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%AA%D8%B3%D8%AC%D9%8A%D9%84/)

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

الواجهة البرمجية API، واختصاراً لـ Application Programming Interface، هي مجموعة الدوال والأنواع والثوابت التي يعرضها نظام التشغيل Operating System للبرامج، وWin32 هو اسم هذه الواجهة في Windows. وكل ما يفعله برنامج على Windows، من فتح ملف إلى رسم زر إلى قراءة مفتاح من السجل Registry، يمر في النهاية عبر دالة منها، حتى لو كتبت البرنامج بلغة لا تعرف عن Win32 شيئاً، لأن مكتبة اللغة نفسها هي التي تستدعيها نيابة عنك. ويمكنك أن ترى القائمة الكاملة مرتبة حسب المجالات في صفحة [Windows API index](https://learn.microsoft.com/en-us/windows/win32/apiindex/windows-api-list?ref=arabroot.io) في Microsoft Learn.

والاسم له تاريخ: كانت الواجهة الأولى في Windows 3.x تسمى Win16 لأنها مبنية لمعالجات 16 بت، وعندما صدر Windows NT 3.1 في 1993 ثم Windows 95 جاءت النسخة الجديدة للمعالجات 32 بت فسميت Win32، وقد روينا قصة النواة التي حملتها في [قصة Windows NT وDave Cutler](https://arabroot.io/articles/%D9%82%D8%B5%D8%A9-windows-nt-%D9%88-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](https://arabroot.io/articles/process-explorer-%D9%85%D8%AF%D9%8A%D8%B1-%D8%A7%D9%84%D9%85%D9%87%D8%A7%D9%85-%D9%83%D9%85%D8%A7-%D9%8A%D8%AC%D8%A8-%D8%A7%D9%86-%D9%8A%D9%83%D9%88%D9%86/) التي تعرض لك الأشياء بأسمائها في 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](https://arabroot.io/content/images/2026/11/win32-api-basics-01-layers.webp)

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

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

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

```powershell
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 مع البرنامج، وهذا هو الفرق الذي سوف نقيسه:

```bash
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، وسوف ترى بعد قليل لماذا يهمنا هذا. وهذا هو الجهاز الذي شغلنا عليه المختبر كما يكتبه السكربت:

```text
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، فإنه يتبع التعليمة إلى وجهتها ويسأل مرة أخرى:

```c
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);
}
```

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

```text
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 سطراً لا يرسم شيئاً:

```text
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](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew?ref=arabroot.io)، ومعناه خانة خانة:

![توقيع الدالة CreateFileW مع شرح الحرف W والأنواع وأقواس in وoptional والقيمة المرجعة عند الفشل](https://arabroot.io/content/images/2026/11/win32-api-basics-02-signature.webp)

كل خانة في التوقيع تقول لك شيئاً: النسخة، والأنواع، واتجاه المعاملات، وشكل الفشل.

والأنواع كلها أسماء بديلة Typedefs لأنواع C، وصفحة [Windows Data Types](https://learn.microsoft.com/en-us/windows/win32/winprog/windows-data-types?ref=arabroot.io) تعرف كل واحد منها. والقاعدة التي تريحك من حفظها أن الاسم يقرأ من اليسار كجملة: `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](https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?ref=arabroot.io). وأهم ما تقرؤه في أي صفحة دالة بعد التوقيع هو قسم القيمة المرجعة 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](https://learn.microsoft.com/en-us/windows/win32/intl/conventions-for-function-prototypes?ref=arabroot.io). والسبب تاريخي: كان 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` ويحوله إلى ثلاثة ترميزات، ثم ينشئ الملف ثلاث مرات بثلاث طرق، ويقرأ من القرص ما حفظ فعلاً:

```text
--- 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` في المكتبة، فالاسم بلا حرف موجود في ملفات الترويسة فقط.

وإذا رأيت هذه الحروف اللاتينية الغريبة في اسم ملف أو في قاعدة بيانات فأنت تعرف الآن من أين جاءت، وقد روينا تاريخ هذه المشكلة كاملاً في [قصة الحرف العربي في الحاسب](https://arabroot.io/articles/%D9%82%D8%B5%D8%A9-%D8%A7%D9%84%D8%AD%D8%B1%D9%81-%D8%A7%D9%84%D8%B9%D8%B1%D8%A8%D9%8A-%D9%81%D9%8A-%D8%A7%D9%84%D8%AD%D8%A7%D8%B3%D8%A8-%D9%85%D9%86-%D8%A7%D9%84%D8%AA%D8%B1%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D8%A7%D9%84%D9%82%D8%AF%D9%8A%D9%85%D8%A9-%D8%A7%D9%84%D9%89-unicode/). والصورة التالية تلخص التجربة ومعها التجربة التالية:

![الاسم تقرير.txt بثلاثة ترميزات وما حفظه القرص بلا Manifest ومع Manifest فيه UTF-8](https://arabroot.io/content/images/2026/11/win32-api-basics-04-a-vs-w.webp)

مع صفحة 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](https://learn.microsoft.com/en-us/windows/apps/design/globalizing/use-utf8-code-page?ref=arabroot.io). وهذا هو الملف الذي ضمناه في `unicode-utf8.exe`:

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

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

```text
--- 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](https://learn.microsoft.com/en-us/windows/win32/intl/code-pages?ref=arabroot.io) تشرح لماذا تنصح Microsoft بذلك: صفحة الجهاز قد تختلف بين جهاز المطور وجهاز العميل، وقد تتغير بإعداد واحد.

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

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

![أربع بطاقات للخطأ نفسه: GetLastError يساوي 2 وHRESULT 0x80070002 وNTSTATUS 0xC0000034 وerrno 2](https://arabroot.io/content/images/2026/11/win32-api-basics-03-errors.webp)

ملف مفقود واحد، وأربعة أرقام بحسب الطبقة التي سألتها.

- **BOOL أو HANDLE ثم GetLastError:** أغلب دوال Win32 الكلاسيكية تعيد قيمة تقول «فشلت» فقط، مثل `FALSE` أو `NULL` أو `INVALID_HANDLE_VALUE`، وتحفظ السبب في مكان خاص بالخيط تقرؤه بالدالة [GetLastError](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror?ref=arabroot.io). والأرقام مسرودة في صفحة [System Error Codes](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes?ref=arabroot.io).
- **HRESULT:** رقم من 32 بت تعيده دوال COM وأغلب الواجهات الأحدث مباشرة، وفيه البت الأعلى للفشل، ثم الجهة Facility التي جاء منها، ثم الرمز، كما في صفحة [Structure of COM Error Codes](https://learn.microsoft.com/en-us/windows/win32/com/structure-of-com-error-codes?ref=arabroot.io).
- **NTSTATUS:** نظام النواة و`ntdll.dll` والتعريفات Drivers، وهو الذي تراه في رموز خروج البرامج التي لا تجد مكتبة، مثل `0xC0000135` التي شرحناها في [حالات Sysinternals](https://arabroot.io/articles/%D8%AD%D8%A7%D9%84%D8%A7%D8%AA-sysinternals-%D8%AF%D8%AE%D9%88%D9%84-%D8%A8%D8%B7%D9%8A%D8%A1-%D9%88%D9%85%D8%B9%D8%A7%D9%84%D8%AC-%D9%85%D8%B4%D8%BA%D9%88%D9%84-%D9%88dll-%D9%85%D9%81%D9%82%D9%88%D8%AF/)، والقائمة في [NTSTATUS Values](https://learn.microsoft.com/en-us/openspecs/windows%5Fprotocols/ms-erref/596a1078-e883-4972-9bbc-49e60bebca55?ref=arabroot.io).
- **errno:** نظام مكتبة C القياسية، ولا علاقة له بـ Windows، ولكنه يعيش في البرنامج نفسه إذا استخدمت `fopen` وأخواتها.

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

```c
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 لهذا الرمز:

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

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

```text
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، ثم قرأنا في الأول مرة أخرى:

```text
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، وبطاقة تبين أن الرقم داخل الخيط الواحد يبقى من آخر فشل](https://arabroot.io/content/images/2026/11/win32-api-basics-05-teb.webp)

الرقم خاص بالخيط، ولكنه داخل الخيط يبقى من آخر دالة كتبته، لا من آخر دالة استدعيتها.

⚠️

إذا كتبت دالة مساعدة للتسجيل 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 جديدة:

```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);
'@
```

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

```text
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](https://learn.microsoft.com/en-us/windows/win32/sysinfo/handles-and-objects?ref=arabroot.io) قيمة معتمة Opaque، أي أن البرنامج لا يفترض شيئاً عن معناها. وفي الداخل هو رقم خانة في جدول مقابض Handle Table خاص بالعملية تديره النواة، وكل خانة تشير إلى كائن Object في النواة، ولكن هذا التفصيل له مقال في مرحلة Windows من الداخل، وما يهمنا هنا هو كيف تعامله في كودك. والبرنامج `handles.exe` يجرب أربعة أشياء:

```text
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?](https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443&ref=arabroot.io) في مدونة 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](https://arabroot.io/articles/process-explorer-%D9%85%D8%AF%D9%8A%D8%B1-%D8%A7%D9%84%D9%85%D9%87%D8%A7%D9%85-%D9%83%D9%85%D8%A7-%D9%8A%D8%AC%D8%A8-%D8%A7%D9%86-%D9%8A%D9%83%D9%88%D9%86/)، وهي أول ما تنظر إليه عندما يكبر عمود Handles في مدير المهام يوماً بعد يوم.

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

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

```text
--- 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](https://learn.microsoft.com/en-us/windows/win32/w8cookbook/operating-system-version-changes-in-windows-8-1?ref=arabroot.io): البرنامج الذي لا يقول في ملف البيان إنه يعرف الإصدار الجديد يحصل على رقم Windows 8\. والسبب أن Microsoft وجدت عبر السنين آلاف البرامج تفحص الإصدار بطريقة خاطئة، مثل برنامج يقارن الرقم الثانوي فقط فيظن أن 6.0 أحدث من 10.0، أو برنامج يرفض العمل إذا لم يكن الإصدار في قائمة يعرفها، فيتوقف عند كل إصدار جديد من Windows. فقررت أن تجعل الرقم الحقيقي لمن يطلبه صراحة فقط.

![ثلاث بطاقات: version.exe بلا Manifest يرى 6.2 build 9200، ومع supportedOS يرى 10.0 build 26100، وRtlGetVersion يرى 10.0 في الحالتين](https://arabroot.io/content/images/2026/11/win32-api-basics-06-version.webp)

البرنامج نفسه، والفرق سطر supportedOS في ملف البيان.

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

```xml
<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](https://learn.microsoft.com/en-us/windows/win32/sysinfo/getting-the-system-version?ref=arabroot.io) هي أن تسأل عن الميزة نفسها، مثل أن تحاول تحميل الدالة التي تحتاجها بـ `GetProcAddress`، أو أن تستخدم دوال `IsWindows10OrGreater` وأخواتها التي تعمل بالـ Manifest نفسه. وملفات البيان عموماً، بكل ما يمكن أن تقوله لـ Windows عن برنامجك، موثقة في صفحة [Application manifests](https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests?ref=arabroot.io)، وسوف نعود إليها في مقال النافذة الأولى عند الحديث عن دقة الشاشة DPI.

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

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

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

```text
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

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

```text
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.