Пошаговое руководство. Вызов API Windows (Visual Basic)

2023-04-11

API Windows — это библиотеки динамических ссылок (DLL), которые являются частью операционной системы Windows. Вы используете их для выполнения задач, когда сложно писать эквивалентные процедуры самостоятельно. Например, Windows предоставляет функцию с именем FlashWindowEx , которая позволяет сделать заголовок для приложения альтернативным между светлыми и темными оттенками.

Преимущество использования API Windows в коде заключается в том, что они могут сэкономить время разработки, так как они содержат десятки полезных функций, которые уже написаны и ожидают использования. Недостатком является то, что API Windows сложны в работе и не прощают ошибок.

API Windows представляют специальную категорию взаимодействия. API Windows не используют управляемый код, не имеют встроенных библиотек типов и используют типы данных, отличные от используемых в Visual Studio. Из-за этих различий и поскольку API Windows не являются COM-объектами, взаимодействие с API Windows и .NET Framework выполняется с помощью вызова платформы или PInvoke. Вызов платформы — это служба, которая позволяет управляемому коду вызывать неуправляемые функции, реализованные в библиотеках DLL. Дополнительные сведения см. в разделе "Использование неуправляемых функций DLL". Вы можете использовать PInvoke в Visual Basic с помощью Declare инструкции или применения атрибута DllImport к пустой процедуре.

Вызовы API Windows были важной частью программирования Visual Basic в прошлом, но редко необходимы в Visual Basic .NET. По возможности следует использовать управляемый код из .NET Framework для выполнения задач, а не вызовов API Windows. В этом пошаговом руководстве содержатся сведения об этих ситуациях, в которых требуется использование API Windows.

Замечание

На компьютере могут отображаться различные имена или расположения для некоторых элементов пользовательского интерфейса Visual Studio в следующих инструкциях. Выпуск Visual Studio, который у вас есть, и параметры, которые вы используете, определяют эти элементы. Дополнительные сведения см. в разделе Персонализация интегрированной среды разработки.

Вызовы API с помощью декларации

Наиболее распространенным способом вызова API Windows является использование инструкции Declare .

Чтобы объявить процедуру DLL

Определите имя функции, которую вы хотите вызвать, а также его аргументы, типы аргументов и возвращаемое значение, а также имя и расположение библиотеки DLL, содержащей ее.

Замечание

Полные сведения об API Windows см. в документации по API Windows в пакетах SDK Win32 и Platform SDK. Дополнительные сведения о константах, используемых API Windows, см. в файлах заголовков, таких как Windows.h, включенных в пакет SDK для платформы.
Откройте новый проект приложения Windows, нажав кнопку "Создать " в меню "Файл ", а затем щелкните "Проект". Откроется диалоговое окно Создание проекта .
Выберите приложение Windows из списка шаблонов проектов Visual Basic. Отображается новый проект.

Добавьте следующую 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 и Alias

Название, следующее за ключевым словом Function, — это название, которое ваша программа использует для доступа к импортированной функции. Оно может совпадать с реальным именем вызываемой функции или использовать любое допустимое имя процедуры, а затем использовать Alias ключевое слово для указания реального имени вызываемой функции.

Укажите ключевое Lib слово, за которым следует имя и расположение библиотеки DLL, содержащей вызываемую функцию. Не нужно указывать путь к файлам, расположенным в системных каталогах Windows.

Используйте ключевое Alias слово, если имя вызываемой функции не является допустимым именем процедуры Visual Basic или конфликтует с именем других элементов в приложении. Alias указывает истинное имя вызываемой функции.

Объявления типа аргументов и типов данных

Объявите аргументы и их типы данных. Эта часть может быть сложной, так как типы данных, которые использует Windows, не соответствуют типам данных Visual Studio. Visual Basic выполняет большую работу, преобразовав аргументы в совместимые типы данных, процесс, называемый маршалингом. Вы можете явно контролировать, как аргументы маршалируются с помощью атрибута MarshalAsAttribute, определяемого в пространстве имен System.Runtime.InteropServices.

Замечание

Предыдущие версии Visual Basic позволяют объявлять параметры As Any, что означает, что данные любого типа данных могут использоваться. Для всех Declare инструкций Visual Basic требуется использовать определенный тип данных.

Константы API Windows

Некоторые аргументы представляют собой сочетания констант. Например, API, показанный в этом пошаговом руководстве MessageBox, принимает целочисленный аргумент Typ, который управляет тем, как отображается окно сообщения. Вы можете определить числовое значение этих констант, проверив #define утверждения в файле WinUser.h. Числовые значения обычно отображаются в шестнадцатеричном виде, поэтому вы можете использовать калькулятор, чтобы добавить их и преобразовать в десятичное значение. Например, если вы хотите объединить константы для восклицательного стиля MB_ICONEXCLAMATION 0x00000030 и стиля "Да/Нет" MB_YESNO 0x00000004, можно сложить числа и получить результат 0x00000034, или 52 в десятичной системе. Хотя десятичный результат можно использовать напрямую, лучше объявить эти значения как константы в приложении и объединить их с помощью Or оператора.

Объявление констант для вызовов API Windows

Ознакомьтесь с документацией по вызываемой функции Windows. Определите имя используемой константы и имя H-файла, содержащего числовые значения для этих констант.
Используйте текстовый редактор, например Блокнот, для просмотра содержимого файла заголовка (H) и поиска значений, связанных с используемыми константами. Например, MessageBox API использует константу MB_ICONQUESTION для отображения вопросительного знака в поле сообщения. Определение для MB_ICONQUESTION находится в WinUser.h и выглядит следующим образом:

#define MB_ICONQUESTION 0x00000020L
Добавьте эквивалентные Const инструкции в класс или модуль, чтобы сделать эти константы доступными для приложения. Рассмотрим пример.
```
Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7
```

Для вызова процедуры DLL

Добавьте кнопку с именем Button1 в форму запуска проекта, а затем дважды щелкните ее, чтобы просмотреть свой код. Отображается обработчик событий для кнопки.

Добавьте код в обработчик событий для добавленной 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

Запустите проект, нажав клавишу F5. Окно сообщения отображается с кнопками "Да " и "Нет ". Щелкните любой из них.

Маршаллирование данных

Visual Basic автоматически преобразует типы данных параметров и возвращаемые значения для вызовов API Windows, но атрибут можно использовать MarshalAs для явного указания неуправляемых типов данных, ожидаемых API. Дополнительные сведения о маршалинге взаимодействия см. в разделе Interop Marshaling.

Использование Declare и MarshalAs в вызове API

Определите имя функции, которую вы хотите вызвать, а также его аргументы, типы данных и возвращаемое значение.
Чтобы упростить доступ к MarshalAs атрибуту, добавьте Imports инструкцию в начало кода класса или модуля, как показано в следующем примере:
```
Imports System.Runtime.InteropServices
```
Добавьте прототип функции для импортированной функции в класс или модуль, который вы используете, и примените 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, но обеспечивает более точный контроль над вызовом функций.

С большинством вызовов API Windows можно использовать DllImport , если вызов ссылается на общий (иногда называемый статическим) методом. Нельзя использовать методы, требующие экземпляра класса. В отличие от Declare операторов, вызовы DllImport не могут использовать атрибут MarshalAs.

Вызов API Windows с помощью атрибута DllImport

Откройте новый проект приложения Windows, нажав кнопку "Создать " в меню "Файл ", а затем щелкните "Проект". Откроется диалоговое окно Создание проекта .
Выберите приложение Windows из списка шаблонов проектов Visual Basic. Отображается новый проект.
Добавьте кнопку с именем Button2 в форму запуска.
Дважды щелкните Button2 , чтобы открыть представление кода для формы.
Чтобы упростить доступ к DllImport, добавьте Imports инструкцию в начало кода для класса формы запуска:
```
Imports System.Runtime.InteropServices
```
Объявите пустую функцию End Class перед инструкцией формы и присвойите имя функции MoveFile.
Примените модификаторы 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.
Примените DllImport атрибут к пустой функции. Первым параметром является имя и расположение библиотеки DLL, содержащей вызываемую функцию. Не нужно указывать путь к файлам, расположенным в системных каталогах Windows. Второй параметр — это именованный аргумент, указывающий имя функции в API 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
```

Добавьте код в 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

Создайте файл с именем Test.txt и поместите его в каталог C:\Tmp на жестком диске. При необходимости создайте каталог Tmp.
Нажмите клавишу F5, чтобы запустить приложение. Появится основная форма.
Нажмите кнопку 2. Сообщение "Файл был успешно перемещен" отображается, если файл можно переместить.