مشاركة عبر

الإرشادات التفصيلية: استدعاء Windows API

  • مقالة

واجهات برمجة تطبيقات ال Windows هي مكتبات ارتباط ديناميكي (DLL) وهي جزء من نظام تشغيل ال Windows . تـستخدامها لتنفيذ مهام عندما يكون من الصعب كتابة إجراءات مكافئة خاصة بك. على سبيل المثال، يوفر Windows دالة باسم FlashWindowEx الذي يسمح لك بإجراء شريط عنوان لتطبيق للتبديل بين ظلال فاتحة و داكنة.

الميزة باستخدام واجهات برمجة تطبيقات Windows في التعليمات البرمجية هو توفير وقت التطوير لأنها تحتوي على العشرات من الدالات المفيدة التي تمت كتابتها مسبقاً و في انتظار ليتم استخدامها. من مساوؤها هو أن واجهات برمجة تطبيقات Windows يمكن أن تكون صعب العَمَل معها و عديمة الرحمة عند حدوث خطأ.

واجهات برمجة تطبيقات Windows تمثل فئة خاصة لإمكانية التشغيل التفاعلي. لا تستخدم واجهات برمجة تطبيقات Windows التعليمات البرمجية, لا تحتوي على مكتبات الأنواع المضمنة, و تقوم باستخدام أنواع بيانات مختلفة عن تلك التي يتم استخدامها مع ‏‫Visual Studio. نتيجة لهذه الاختلافات و لأن Windows API ليست كائنات COM , و إمكانية التشغيل التفاعلي مع واجهات برمجة تطبيقات Windows و .NET Framework يتم تنفيذها باستخدام استدعاء النظام الأساسي, أو PInvoke. استدعاء النظام الأساسي هي خدمة تمكّنُ التعليمات البرمجية المدارة استدعاء الدالات غير مدارة مطبقة في مكتبات الارتباط الديناميكي (DLL). لمزيد من المعلومات، راجع التي تستخدم دالات DLL غير المُدارة. يمكنك استخدام PInvoke في Visual Basic إما باستخدام Declare الكشف أو تطبيق DllImport السمة إلى لإجراء فارغ.

Windows API كانت جزء هام من Visual Basic البرمجة في الماضي, ولكن نادراً ضرورية مع Visual Basic 2005. عند الإمكان، يجب استخدام تعليمات برمجية مدارة من .NET Framework لتنفيذ المهام بدلاً من استدعاءات API Windows. توفر هذه المعاينة معلومات لهذه المواقف حيث يكون استخدام واجهات برمجة تطبيقات Windows ضرورية.

ملاحظة

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

استدعاءات API باستخدام الإعلان

الطريقة الأكثر شيوعا لاستدعاء واجهات برمجة تطبيقات Windows باستخدام كشف Declare.

لـتعريف إجراء مكتبة الارتباط الديناميكية (DLL)

  1. قم بـتحديد اسم الدالة التي تريد استدعاءها, بالإضافة إلى الوسيطات الخاصة بها, أنواع الوسيطة و القيمة المرجعة ، بالإضافة إلى اسم وموقع ملف DLL الذي يحتوي عليه.

    ملاحظة

    للحصول على معلومات كاملة حول Windows API s راجع وثائق SDK Win32 في النظام الأساسي SDK Windows API. لمزيد من المعلومات حول الثوابت التي تستخدمها APIs Windows, قم بفحص ملفات العنوان مثل Windows.h المضمنة مع للنظام الأساسي أدوات تطوير البرامج SDK.

  2. افتح مشروع تطبيقات Windows جديد بالنقر فوق جديدعلى ملف قائمة, ثم انقر فوقالمشروع. يظهر مربع الحوار مشروع جديد.

  3. قم بتحديدتطبيق لـ Windowsمن القائمةVisual Basic قوالب المشروع. الـمشروع الجديد. معروض

  4. قم بـإضافة دالة Declare التالية إما لفئة أو لوحدة نمطية حيث تريد استخدام مكتبة الارتباط الحيوي (DLL):

    Declare Auto Function MBox Lib "user32.dll" Alias "MessageBox" (
    ByVal hWnd As Integer,
    ByVal txt As String,
    ByVal caption As String,
    ByVal Typ As Integer) As Integer

أجزاء من كشف التعريف

كشف Declare يتضمن العناصر التالية.

معدّل تلقائي

المعدّل Auto يرشد وقت التشغيل لتحويل السلسلة استناداً إلى ‏‏اسم الأسلوب تبعا إلى القواعد وقت تشغيل اللغة العامة (أو اسم مستعار في حالة تحديده).

الكلمات الأساسية lib و الاسم المستعار

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

قم بتحديد الكلمة الأساسية Lib، متبوعة باسم وموقع ملف DLL الذي يحتوي على دالة التي تقوم بطلبها. لا تحتاج إلى تحديد مسار الملفات الموجودة في دلائل نظام Windows.

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

تعريفات نوع البيانات و الوسيطة

قم بتعريف الوسيطات و أنواع البيانات الخاصة بها. يمكن أن يكون هذا الجزء فيه تحدي لأن أنواع البيانات التي يستخدمها Windows لا تتوافق مع أنواع بيانات ‏‫Visual Studio. Visual Basic يقوم بكثير من العمل لك بواسطة تحويل الوسائط إلى أنواع بيانات متوافقة, عملية تسمى التنظيم والإرسال. يمكنك بوضوح التحكم في كيفية تنظيم الوسائط باستخدام MarshalAsAttribute السمة المعرفة في System.Runtime.InteropServices مساحة الاسم.

ملاحظة

الإصدارات السابقة من Visual Basic سمحت لك بتصريح المعلمات As Any، بمعنى بيانات لأي نوع بيانات يمكن استخدامها. Visual Basic يتطلب استخدام نوع بيانات محدد لكافة كشوف Declare.

ثوابت Windows API

تعتبر بعض الوسيطات تركيبة من الثوابت. على سبيل المثال، API ال MessageBox الموضح في هذه المعاينة يقبل وسيطة عدد صحيح تسمى Typ التي تتحكم في كيفية عرض مربع الرسالة. يمكنك تحديد القيمة رقمية لهذه الثوابت عن طريق فحص كشوف #define في ملف WinUser.h. عادةً يتم عرض القيم الرقمية بالنظام السداسى , لذلك قد ترغب في استخدام حاسبة لإضافتهم وتحويلهم إلى النظام العشري. على سبيل المثال، إذا كنت تريد جمع ثوابت لنمط علامة تعجب MB_ICONEXCLAMATION 0x00000030 و نمط Yes/NoMB_YESNO 0x00000004, يمكنك إضافة الأرقام و الحصول على النتيجة 0x00000034 أو 52 العشرية. على الرغم من أنه يمكنك استخدام النتيجة عشرية مباشرة من الأفضل أن تقوم بتعريف هذه القيم كثوابت في التطبيق الخاص بك ودمجها باستخدام عامل التشغيل Or.

لـإعلان الثوابت لنداءات Windows API

  1. استشر الوثائق لدالة Windows الذي تقوم بطلبها. تحدد اسم الثوابت التي يستخدمها و اسم ملف .h الذي يحتوي على القيم الرقمية لهذه الثوابت.

  2. استخدم محرر النص مثل المفكرة, لعرض محتويات ملف (.h) العنوان ، ثم ابحث عن القيم المقترنة بالثوابت التي تستخدمها. على سبيل المثال، واجهة برمجة التطبيقات (API) MessageBox يستخدم الثابت MB_ICONQUESTION لإظهار علامة الاستفهام في مربع الرسالة. تعريفMB_ICONQUESTION يكون في WinUser.h و يظهر كما يلي:

    #define MB_ICONQUESTION 0x00000020L

  3. إضافة المكافئ كشوف Const للفئة أو الوحدة النمطية الخاصة بك لتوفير هذه الثوابت للتطبيق الخاص بك. فعلى سبيل المثال:

    Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7

للاتصال بإجراء مكتبة الارتباط الديناميكي (DLL)

  1. قم بـإضافة زر باسم Button1 لنموذج بدء التشغيل للمشروع الخاص بك ثم انقر نقرا مزدوج فوقه لعرض التعليمات البرمجية الخاصة به. معالج الحدث للزر يتم عرضة.

  2. قم بإضافة التعليمات البرمجية إلى معالج الأحداث Click للزر الذي تمت إضافته, لاستدعاء الإجراء وتوفير الوسائط المناسبة:

    Private Sub Button1_Click(ByVal sender As System.Object,
    ByVal e As System.EventArgs) Handles Button1.Click

    ' Stores the return value.
    Dim RetVal As Integer
    RetVal = MBox(0, "Declare DLL Test", "Windows API MessageBox",
        MB_ICONQUESTION Or MB_YESNO)

    ' Check the return value.
    If RetVal = IDYES Then
        MsgBox("You chose Yes")
    Else
        MsgBox("You chose No")
    End If
End Sub

  3. شغل المشروع بالضغط على F5. يتم عرض مربع رسالة مع كلا نعم و لا أزرار الاستجابة. انقر فوق أي منهما.

تنظيم وإرسال البيانات

Visual Basic تلقائياً يقوم بتحويل أنواع البيانات للمعلمات و قيم الإرجاع لنداءات Windows API ولكن يمكن استخدام MarshalAs السمة لتحديد أنواع البيانات الغير المُدارة بشكل واضح التي يتوقعها API. لمزيد من المعلومات حول interop marshaling, راجعتنظيم إمكانية التشغيل المتداخل.

لاستخدام Declare وMarshalAs في نداء API

  1. تحديد اسم الدالة التي تريد استدعاءها مع الوسيطات الخاصة بها, أنواع بيانات و القيمة المرجعة.

  2. لتبسيط الوصول إلى سمة MarshalAs قم بإضافة كشف Imports إلى أعلى التعليمات البرمجية للفئة أو الوحدة النمطية كما هو موضح في المثال التالي:

    Imports System.Runtime.InteropServices

  3. قم بـإضافة تعريف دالة لدالة تم استيرادها للفئة أو للوحدة النمطية التي تستخدمها وقم بتطبيق MarshalAs السمة للمعلمات أو قيمة الإرجاع. في المثال التالي نداء API الذي يتوقع النوع void* يتم تنظيمه كـ AsAny:

    Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
    ByVal x As Short,
    <MarshalAsAttribute(UnmanagedType.AsAny)>
        ByVal o As Object)

نداءات ال API باستخدام DllImport

سمة ال DllImport توفر طريقة ثانية لاستدعاء دالات في DLL بدون مكتبات الأنواع. DllImport يكافئ تقريباً ل باستخدام Declare الكشف لكنه يوفر المزيد من التحكم في كيفية يتم استدعاء الدالات.

يمكنك استخدام DllImport مع معظم نداءات واجهة برمجة تطبيقات Windows لطالما يشير إلى الأسلوب المشترك (أحياناً يسمى الـثابت) . لا يمكنك استخدام الأساليب التي تتطلب مثيل فئة. بعكس كشوف Declare ، DllImport النداءات لا يمكنها استخدام MarshalAs السمة.

لـاستدعاء Windows API باستخدام سمة DllImport

  1. افتح مشروع تطبيقات Windows جديد بالنقر فوق جديدعلى ملف قائمة, ثم انقر فوقالمشروع. يظهر مربع الحوار مشروع جديد.

  2. قم بتحديدتطبيق لـ Windowsمن القائمةVisual Basic قوالب المشروع. الـمشروع الجديد. معروض

  3. قم بـإضافة زر باسم Button2 إلى نموذج بدء التشغيل.

  4. انقر مزودجا Button2 لفتح طريقة عرض التعليمات البرمجية للنموذج.

  5. لتبسيط الوصول إلى DllImport، قم بإضافة كشف Imports لأعلى التعليمات البرمجية لفئة نموذج بدء التشغيل:

    Imports System.Runtime.InteropServices

  6. قم بتعريف دالة فارغة سابقة لكشف End Class للنموذج، و اسم الدالة MoveFile.

  7. قم بتطبيقPublic و Shared المعدّلات لتعريف الدالة ثم قم بتعيين المعلمات ل MoveFile استناداً إلى الوسائط التي يستخدمها Windows API:

    Public Shared Function MoveFile(
    ByVal src As String,
    ByVal dst As String) As Boolean
    ' Leave the body of the function empty.
End Function

    يمكن أن يكون لدى الدالة أي اسم إجراء صحيح; السمة DllImport تحدد الاسم في مكتبة الارتباط الديناميكي (DLL). يتعامل أيضاً مع تنظيم وإرسال إمكانية التشغيل التفاعلي للمعلمات وقيم الرجوع، بحيث يمكنك اختيار أنواع بيانات ‏‫Visual Studio المشابهة لأنواع البيانات التي يستخدمها واجهة برمجة التطبيقات (API).

  8. تـطبيق سمةDllImport إلى الدالة الفارغة. الـمعلمة الأولى هي اسم وموقع مكتبة الارتباط الديناميكي (DLL) الذي يحتوي على الدالة التي تتصل بها. لا تحتاج إلى تحديد مسار الملفات الموجودة في دلائل نظام Windows. الـمعلمة الثانية هي وسيطة مسماة التي تحدد اسم الدالة في واجهة برمجة تطبيقات Windows. في هذا المثال، DllImport السمة تفرض الاستدعاءات الى MoveFile لإعادة توجيهها إلى MoveFileW في KERNEL32.DLL. أسلوب MoveFileW يقوم بنسخ ملف من المسار src إلى المسار dst.

    <DllImport("KERNEL32.DLL", EntryPoint:="MoveFileW", SetLastError:=True,
    CharSet:=CharSet.Unicode, ExactSpelling:=True,
    CallingConvention:=CallingConvention.StdCall)>
Public Shared Function MoveFile(
    ByVal src As String,
    ByVal dst As String) As Boolean
    ' Leave the body of the function empty.
End Function

  9. قم بإضافة التعليمات البرمجية إلى معالج الحدث Button2_Click لاستدعاء الدالة.

    Private Sub Button2_Click(ByVal sender As System.Object,
    ByVal e As System.EventArgs) Handles Button2.Click

    Dim RetVal As Boolean = MoveFile("c:\tmp\Test.txt", "c:\Test.txt")
    If RetVal = True Then
        MsgBox("The file was moved successfully.")
    Else
        MsgBox("The file could not be moved.")
    End If
End Sub

  10. قم بإنشاء ملف يسمى Test.txt وضعه في الدليل C:\Tmp على محرك القرص الثابت. قم بـإنشاء دليل Tmp إذا لزم الأمر.

  11. اضغط على المفتاح F5 لبدء تشغيل التطبيق. يظهر النموذج الرئيسي.

  12. انقر فوقButton2. الرسالة "الملف تم نقله بنجاح" يتم عرضها اذا كان بمكن نقل الملف.

راجع أيضًا:

المرجع

عبارة التعريف

DllImportAttribute

MarshalAsAttribute

تلقائي (Visual Basic)

عبارة الاسم المستعار في (Visual Basic)

المبادئ

إنشاء النماذج الأولية في التعليمات البرمجية المدارة

نموذج رد الاتصال

موارد أخرى

توافق COM