Panduan: Pemanggilan API Windows (Visual Basic)

Artikel
04/08/2023

API Windows adalah pustaka link dinamis (DLL) yang merupakan bagian dari sistem operasi Windows. Anda menggunakannya untuk melakukan tugas saat sulit untuk menulis prosedur yang setara dengan milik Anda. Misalnya, Windows menyediakan fungsi bernama FlashWindowEx yang memungkinkan Anda membuat bilah judul untuk aplikasi bergantian antara nuansa terang dan gelap.

Keuntungan menggunakan API Windows dalam kode Anda adalah dapat menghemat waktu pengembangan karena berisi puluhan fungsi yang berguna yang sudah ditulis dan menunggu untuk digunakan. Kerugiannya adalah API Windows mungkin sulit untuk digunakan dan tidak toleran saat terjadi kesalahan.

API Windows mewakili kategori interoperabilitas khusus. API Windows tidak menggunakan kode terkendali, tidak memiliki pustaka jenis bawaan, dan menggunakan jenis data yang berbeda dari yang digunakan dengan Visual Studio. Karena perbedaan ini, dan karena API Windows bukan objek COM, interoperabilitas dengan API Windows dan .NET Framework dilakukan menggunakan pemanggilan platform, atau PInvoke. Pemanggilan platform adalah layanan yang memungkinkan kode terkendali untuk memanggil fungsi tidak terkelola yang diterapkan dalam DLL. Untuk informasi selengkapnya, lihat Penggunaan Fungsi DLL Tidak Terkelola. Anda dapat menggunakan PInvoke dalam Visual Basic dengan menggunakan pernyataan Declare atau menerapkan atribut DllImport ke prosedur kosong.

Panggilan API Windows adalah bagian penting dari pemrograman Visual Basic di masa lalu, tetapi jarang diperlukan dengan Visual Basic .NET. Jika memungkinkan, sebaiknya Anda menggunakan kode terkendali dari .NET Framework untuk melakukan tugas, alih-alih panggilan API Windows. Panduan ini memberikan informasi untuk situasi di mana penggunaan API Windows diperlukan.

Catatan

Komputer Anda mungkin memperlihatkan nama atau lokasi yang berbeda untuk beberapa elemen antarmuka pengguna Visual Studio dalam petunjuk berikut. Edisi Visual Studio yang Anda miliki dan setelan yang Anda gunakan menentukan elemen-elemen ini. Untuk informasi selengkapnya, lihat Mempersonalisasi IDE.

Panggilan API Menggunakan Deklarasi

Cara paling umum untuk memanggil API Windows adalah dengan menggunakan pernyataan Declare.

Untuk menyatakan prosedur DLL

Tentukan nama fungsi yang ingin Anda panggil, ditambah argumennya, jenis argumen, dan nilai yang ditampilkan, serta nama dan lokasi DLL yang mengandungnya.

Catatan

Untuk informasi lengkap tentang API Windows, lihat dokumentasi Win32 SDK dalam API Windows Platform SDK. Untuk informasi selengkapnya tentang konstanta yang digunakan API Windows, periksa file header seperti Windows.h yang disertakan dengan Platform SDK.
Buka proyek Aplikasi Windows baru dengan mengeklik Baru pada menu File, lalu klik Proyek. Kotak dialog Proyek Baru muncul.
Pilih Aplikasi Windows dari daftar templat proyek Visual Basic. Proyek baru ditampilkan.

Tambahkan fungsi Declare berikut ke kelas atau modul tempat Anda ingin menggunakan 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

Bagian dari Pernyataan Nyatakan

Pernyataan Declare ini mencakup elemen-elemen berikut.

Pengubah otomatis

Pengubah Auto menginstruksikan runtime untuk mengonversi string berdasarkan nama metode sesuai dengan aturan runtime bahasa umum (atau nama alias jika ditentukan).

Kata kunci Lib dan Alias

Nama yang mengikuti kata kunci Function adalah nama yang digunakan program Anda untuk mengakses fungsi yang diimpor. Ini bisa sama dengan nama asli fungsi yang Anda panggil, atau Anda dapat menggunakan nama prosedur yang valid dan kemudian menggunakan kata kunci Alias untuk menentukan nama asli fungsi yang Anda panggil.

Tentukan kata kunci Lib, diikuti dengan nama dan lokasi DLL yang berisi fungsi yang Anda panggil. Anda tidak perlu menentukan jalur untuk file yang terletak dalam direktori sistem Windows.

Gunakan kata kunci Alias jika nama fungsi yang Anda panggil bukan nama prosedur Visual Basic yang valid, atau berbenturan dengan nama item lain dalam aplikasi Anda. Alias menunjukkan nama sebenarnya dari fungsi yang sedang dipanggil.

Deklarasi Jenis Argumen dan Data

Nyatakan argumen dan jenis datanya. Bagian ini bisa menyulitkan karena jenis data yang Windows gunakan tidak sesuai dengan jenis data Visual Studio. Visual Basic melakukan banyak pekerjaan untuk Anda dengan mengonversi argumen ke jenis data yang kompatibel, sebuah proses yang disebut pengurutan. Anda dapat secara tersurat mengontrol cara argumen diurutkan dengan menggunakan atribut MarshalAsAttribute yang ditentukan dalam namespace System.Runtime.InteropServices.

Catatan

Versi Visual Basic sebelumnya memungkinkan Anda unutk menyatakan parameter As Any, yang berarti data dari jenis data apa pun dapat digunakan. Visual Basic mengharuskan Anda menggunakan jenis data tertentu untuk semua pernyataan Declare.

Konstanta API Windows

Beberapa argumen merupakan kombinasi konstanta. Misalnya, API MessageBox yang ditunjukkan dalam panduan ini menerima argumen bilangan bulat yang disebut Typ yang mengontrol cara kotak pesan ditampilkan. Anda dapat menentukan nilai numerik konstanta ini dengan memeriksa pernyataan #define dalam file WinUser.h. Nilai numerik umumnya ditunjukkan dalam heksadesimal, sehingga Anda mungkin ingin menggunakan kalkulator untuk menambahkannya dan mengonversinya ke desimal. Misalnya, jika Anda ingin menggabungkan konstanta untuk gaya seruan MB_ICONEXCLAMATION 0x00000030 dan gaya Ya/Tidak MB_YESNO 0x00000004, Anda dapat menambahkan angka dan mendapatkan hasil 0x00000034, atau 52 desimal. Meski Anda dapat menggunakan hasil desimal secara langsung, lebih baik menyatakan nilai ini sebagai konstanta dalam aplikasi Anda dan menggabungkannya menggunakan operator Or.

Untuk menyatakan konstanta bagi panggilan API Windows

Lihat dokumentasi untuk fungsi Windows yang Anda panggil. Tentukan nama konstanta yang digunakannya dan nama file .h yang berisi nilai numerik untuk konstanta ini.
Gunakan editor teks, seperti Notepad, untuk melihat konten file header (.h), dan menemukan nilai yang terkait dengan konstanta yang Anda gunakan. Misalnya, API MessageBox menggunakan konstanta MB_ICONQUESTION untuk menunjukkan tanda tanya dalam kotak pesan. Definisi untuk MB_ICONQUESTION berada dalam WinUser.h dan muncul sebagai berikut:

#define MB_ICONQUESTION 0x00000020L
Tambahkan pernyataan Const yang setara ke kelas atau modul Anda untuk membuat konstanta ini tersedia untuk aplikasi Anda. Contohnya:
```
Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7
```

Untuk memanggil prosedur DLL

Tambahkan tombol bernama Button1 ke formulir pengaktifan bagi proyek Anda, lalu klik dua kali untuk menampilkan kodenya. Penanganan aktivitas untuk tombol ditampilkan.

Tambahkan kode ke penanganan aktivitas Click untuk tombol yang Anda tambahkan, untuk memanggil prosedur dan memberikan argumen yang sesuai:

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

Jalankan proyek dengan menekan F5. Kotak pesan ditampilkan dengan tombol respons Ya maupun Tidak. Klik salah satu.

Pengurutan Data

Visual Basic secara otomatis mengonversi jenis data parameter dan nilai tampilan untuk panggilan API Windows, tetapi Anda dapat menggunakan atribut MarshalAs untuk secara tersurat menentukan jenis data tidak terkelola yang diharapkan API. Untuk informasi selengkapnya tentang pengurutan interop, lihat Pengurutan Interop.

Untuk menggunakan Nyatakan dan MarshalAs dalam panggilan API

Tentukan nama fungsi yang ingin Anda panggil, ditambah argumennya, jenis data, dan nilai tampilan.
Untuk menyederhanakan akses ke atribut MarshalAs, tambahkan pernyataan Imports ke bagian atas kode untuk kelas atau modul, seperti dalam contoh berikut:
```
Imports System.Runtime.InteropServices
```
Tambahkan prototipe fungsi untuk fungsi yang diimpor ke kelas atau modul yang Anda gunakan, dan terapkan atribut MarshalAs ke parameter atau nilai tampilan. Dalam contoh berikut, panggilan API yang mengharapkan jenis void* diurutkan sebagai AsAny:
```
Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
    ByVal x As Short,
    <MarshalAsAttribute(UnmanagedType.AsAny)>
        ByVal o As Object)
```

Panggilan API Menggunakan DllImport

Atribut DllImport ini menyediakan cara kedua untuk memanggil fungsi dalam DLL tanpa pustaka jenis. DllImport kira-kira setara dengan penggunaan pernyataan Declare tetapi memberikan kontrol lebih besar terhadap cara fungsi dipanggil.

Anda dapat menggunakan DllImport dengan sebagian besar panggilan API Windows selama panggilan mengacu ke metode bersama (kadang-kadang disebut statik). Anda tidak dapat menggunakan metode yang memerlukan instans kelas. Tidak seperti pernyataan Declare, panggilan DllImport tidak dapat menggunakan atribut MarshalAs.

Untuk memanggil API Windows menggunakan atribut DllImport

Buka proyek Aplikasi Windows baru dengan mengeklik Baru pada menu File, lalu klik Proyek. Kotak dialog Proyek Baru muncul.
Pilih Aplikasi Windows dari daftar templat proyek Visual Basic. Proyek baru ditampilkan.
Tambahkan tombol bernama Button2 ke formulir pengaktifan.
Klik dua kali Button2 untuk membuka tampilan kode bagi formulir.
Untuk menyederhanakan akses ke DllImport, tambahkan pernyataan Imports ke bagian atas kode bagi kelas formulir pengaktifan:
```
Imports System.Runtime.InteropServices
```
Nyatakan fungsi kosong sebelum pernyataan End Class untuk formulir, dan beri nama fungsi MoveFile.
Terapkan pengubah Public dan Shared ke deklarasi fungsi dan atur parameter untuk MoveFile berdasarkan argumen yang digunakan fungsi API Windows:
```
Public Shared Function MoveFile(
    ByVal src As String,
    ByVal dst As String) As Boolean
    ' Leave the body of the function empty.
End Function
```
Fungsi Anda dapat memiliki nama prosedur apa pun yang valid; atribut DllImport menentukan nama dalam DLL. Ia juga menghandel pengurutan interoperabilitas untuk parameter dan nilai tampilan, sehingga Anda dapat memilih jenis data Visual Studio yang mirip dengan jenis data yang digunakan API.
Terapkan atribut DllImport ke fungsi kosong. Parameter pertama adalah nama dan lokasi DLL yang berisi fungsi yang Anda panggil. Anda tidak perlu menentukan jalur untuk file yang terletak dalam direktori sistem Windows. Parameter kedua adalah argumen bernama yang menentukan nama fungsi dalam API Windows. Dalam contoh ini, atribut DllImport memaksa panggilan untuk MoveFile diteruskan ke MoveFileW dalam KERNEL32.DLL. Metode MoveFileW menyalin file dari jalur src hingga jalur 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
```

Tambahkan kode ke penanganan aktivitas Button2_Click untuk memanggil fungsi:

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

Buat file bernama Test.txt dan letakkan dalam direktori C:\Tmp pada hard drive Anda. Buat direktori Tmp jika perlu.
Tekan F5 untuk memulai aplikasi. Formulir utama muncul.
Klik Tombol2. Pesan "File berhasil dipindahkan" ditampilkan jika file dapat dipindahkan.

Bagikan melalui