Passo a passo: Chamando APIs do Windows (Visual Basic)

Artigo
03/05/2024

As APIs do Windows são bibliotecas de vínculo dinâmico (DLLs) que fazem parte do sistema operacional Windows. Você os usa para executar tarefas quando é difícil escrever procedimentos equivalentes por conta própria. Por exemplo, o Windows fornece uma função chamada FlashWindowEx que permite fazer com que a barra de título de um aplicativo alterne entre tons claros e escuros.

A vantagem de usar APIs do Windows em seu código é que elas podem economizar tempo de desenvolvimento porque contêm dezenas de funções úteis que já estão escritas e esperando para serem usadas. A desvantagem é que as APIs do Windows podem ser difíceis de trabalhar e implacáveis quando as coisas dão errado.

As APIs do Windows representam uma categoria especial de interoperabilidade. As APIs do Windows não usam código gerenciado, não têm bibliotecas de tipos internas e usam tipos de dados diferentes daqueles usados com o Visual Studio. Devido a essas diferenças, e porque as APIs do Windows não são objetos COM, a interoperabilidade com APIs do Windows e o .NET Framework é executada usando invocar plataforma ou PInvoke. Platform invoke é um serviço que permite que o código gerenciado chame funções não gerenciadas implementadas em DLLs. Para obter mais informações, consulte Consumindo funções DLL não gerenciadas. Você pode usar PInvoke no Visual Basic usando a Declare instrução ou aplicando o DllImport atributo a um procedimento vazio.

As chamadas de API do Windows eram uma parte importante da programação do Visual Basic no passado, mas raramente são necessárias com o Visual Basic .NET. Sempre que possível, você deve usar o código gerenciado do .NET Framework para executar tarefas, em vez de chamadas de API do Windows. Este passo a passo fornece informações para as situações em que o uso de APIs do Windows é necessário.

Nota

Seu computador pode mostrar nomes ou locais diferentes para alguns dos elementos da interface do usuário do Visual Studio nas instruções a seguir. A edição do Visual Studio que você tem e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Personalizando o IDE.

Chamadas de API usando Declare

A maneira mais comum de chamar APIs do Windows é usando a Declare instrução.

Para declarar um procedimento DLL

Determine o nome da função que você deseja chamar, além de seus argumentos, tipos de argumento e valor de retorno, bem como o nome e o local da DLL que a contém.

Nota

Para obter informações completas sobre as APIs do Windows, consulte a documentação do SDK do Win32 na API do Windows do Platform SDK. Para obter mais informações sobre as constantes que as APIs do Windows usam, examine os arquivos de cabeçalho, como Windows.h, incluídos no Platform SDK.
Abra um novo projeto de aplicativo do Windows clicando em Novo no menu Arquivo e, em seguida, clicando em Projeto. Aparece a caixa de diálogo Novo Projeto.
Selecione Aplicativo do Windows na lista de modelos de projeto do Visual Basic. O novo projeto é exibido.

Adicione a seguinte Declare função à classe ou módulo no qual você deseja usar a 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

Partes da declaração

A Declare declaração inclui os seguintes elementos.

Modificador automático

O Auto modificador instrui o tempo de execução a converter a cadeia de caracteres com base no nome do método de acordo com regras comuns de tempo de execução de linguagem (ou nome de alias, se especificado).

Palavras-chave Lib e Alias

O nome que se segue à Function palavra-chave é o nome que o programa utiliza para aceder à função importada. Pode ser o mesmo que o nome real da função que você está chamando, ou você pode usar qualquer nome de procedimento válido e, em seguida, empregar a Alias palavra-chave para especificar o nome real da função que você está chamando.

Especifique a Lib palavra-chave, seguida pelo nome e local da DLL que contém a função que você está chamando. Não é necessário especificar o caminho para os arquivos localizados nos diretórios do sistema Windows.

Use a Alias palavra-chave se o nome da função que você está chamando não é um nome de procedimento válido do Visual Basic ou entra em conflito com o nome de outros itens em seu aplicativo. Alias Indica o nome verdadeiro da função que está sendo chamada.

Declarações de argumento e tipo de dados

Declare os argumentos e seus tipos de dados. Essa parte pode ser desafiadora porque os tipos de dados que o Windows usa não correspondem aos tipos de dados do Visual Studio. O Visual Basic faz muito do trabalho para você convertendo argumentos em tipos de dados compatíveis, um processo chamado marshaling. Você pode controlar explicitamente como os System.Runtime.InteropServices argumentos são empacotados usando o MarshalAsAttribute atributo definido no namespace.

Nota

Versões anteriores do Visual Basic permitiam que você declarasse parâmetros As Any, o que significa que dados de qualquer tipo de dados poderiam ser usados. Visual Basic requer que você use um tipo de dados específico para todas as Declare instruções.

Constantes de API do Windows

Alguns argumentos são combinações de constantes. Por exemplo, a API mostrada MessageBox neste passo a passo aceita um argumento inteiro chamado Typ que controla como a caixa de mensagem é exibida. Você pode determinar o valor numérico dessas constantes examinando as #define instruções no arquivo WinUser.h. Os valores numéricos são geralmente mostrados em hexadecimal, então você pode querer usar uma calculadora para adicioná-los e convertê-los em decimais. Por exemplo, se você quiser combinar as constantes para o estilo MB_ICONEXCLAMATION de exclamação 0x00000030 e o estilo MB_YESNO Sim/Não 0x00000004, você pode adicionar os números e obter um resultado de 0x00000034 ou 52 decimais. Embora você possa usar o resultado decimal diretamente, é melhor declarar esses valores como constantes em seu aplicativo e combiná-los usando o Or operador .

Para declarar constantes para chamadas de API do Windows

Consulte a documentação da função do Windows que você está chamando. Determine o nome das constantes que ele usa e o nome do arquivo .h que contém os valores numéricos para essas constantes.
Use um editor de texto, como o Bloco de Notas, para exibir o conteúdo do arquivo de cabeçalho (.h) e localizar os valores associados às constantes que você está usando. Por exemplo, a MessageBox API usa a constante MB_ICONQUESTION para mostrar um ponto de interrogação na caixa de mensagem. A definição para MB_ICONQUESTION está em WinUser.h e aparece da seguinte maneira:

#define MB_ICONQUESTION 0x00000020L
Adicione instruções equivalentes Const à sua classe ou módulo para disponibilizar essas constantes para seu aplicativo. Por exemplo:
```
Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7
```

Para chamar o procedimento DLL

Adicione um botão nomeado Button1 ao formulário de inicialização do seu projeto e, em seguida, clique duas vezes nele para exibir seu código. O manipulador de eventos para o botão é exibido.

Adicione código ao Click manipulador de eventos para o botão que você adicionou, para chamar o procedimento e fornecer os argumentos apropriados:

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

Execute o projeto pressionando F5. A caixa de mensagem é exibida com os botões de resposta Sim e Não . Clique em qualquer um deles.

Marshaling de dados

O Visual Basic converte automaticamente os tipos de dados de parâmetros e valores de retorno para chamadas de API do Windows, mas você pode usar o atributo para especificar explicitamente os MarshalAs tipos de dados não gerenciados esperados por uma API. Para obter mais informações sobre interoperabilidade marshaling, consulte Interop Marshaling.

Para usar Declare e MarshalAs em uma chamada de API

Determine o nome da função que você deseja chamar, além de seus argumentos, tipos de dados e valor de retorno.
Para simplificar o MarshalAs acesso ao atributo, adicione uma Imports instrução à parte superior do código da classe ou módulo, como no exemplo a seguir:
```
Imports System.Runtime.InteropServices
```
Adicione um protótipo de função para a função importada à classe ou módulo que você está usando e aplique o MarshalAs atributo aos parâmetros ou valor de retorno. No exemplo a seguir, uma chamada de API que espera o tipo void* é empacotada como AsAny:
```
Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
    ByVal x As Short,
    <MarshalAsAttribute(UnmanagedType.AsAny)>
        ByVal o As Object)
```

Chamadas de API usando DllImport

O DllImport atributo fornece uma segunda maneira de chamar funções em DLLs sem bibliotecas de tipos. DllImport é aproximadamente equivalente ao uso de uma Declare instrução, mas fornece mais controle sobre como as funções são chamadas.

Você pode usar DllImport com a maioria das chamadas de API do Windows, desde que a chamada se refira a um método compartilhado (às vezes chamado estático). Você não pode usar métodos que exigem uma instância de uma classe. Ao contrário Declare das instruções, DllImport as chamadas não podem usar o MarshalAs atributo.

Para chamar uma API do Windows usando o atributo DllImport

Abra um novo projeto de aplicativo do Windows clicando em Novo no menu Arquivo e, em seguida, clicando em Projeto. Aparece a caixa de diálogo Novo Projeto.
Selecione Aplicativo do Windows na lista de modelos de projeto do Visual Basic. O novo projeto é exibido.
Adicione um botão nomeado Button2 ao formulário de inicialização.
Clique duas vezes para abrir o modo de Button2 exibição de código para o formulário.
Para simplificar o acesso ao DllImport, adicione uma Imports instrução à parte superior do código para a classe de formulário de inicialização:
```
Imports System.Runtime.InteropServices
```
Declare uma função vazia que precede a End Class instrução para o formulário e nomeie a função MoveFile.
Aplique os Public modificadores e Shared à declaração de função e defina parâmetros para MoveFile com base nos argumentos que a função de API do Windows usa:
```
Public Shared Function MoveFile(
    ByVal src As String,
    ByVal dst As String) As Boolean
    ' Leave the body of the function empty.
End Function
```
A sua função pode ter qualquer nome de procedimento válido; o DllImport atributo especifica o nome na DLL. Ele também lida com a interoperabilidade marshalling para os parâmetros e valores de retorno, para que você possa escolher tipos de dados do Visual Studio que são semelhantes aos tipos de dados que a API usa.
Aplique o DllImport atributo à função vazia. O primeiro parâmetro é o nome e o local da DLL que contém a função que você está chamando. Não é necessário especificar o caminho para os arquivos localizados nos diretórios do sistema Windows. O segundo parâmetro é um argumento nomeado que especifica o nome da função na API do Windows. Neste exemplo, o atributo força as DllImport chamadas a MoveFile serem encaminhadas para MoveFileW KERNEL32.DLL. O MoveFileW método copia um arquivo do caminho src para o caminho 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
```

Adicione código Button2_Click ao manipulador de eventos para chamar a função:

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

Crie um arquivo chamado Test.txt e coloque-o no diretório C:\Tmp no seu disco rígido. Crie o diretório Tmp, se necessário.
Pressione F5 para iniciar o aplicativo. O formulário principal é exibido.
Clique em Button2. A mensagem "O arquivo foi movido com êxito" é exibida se o arquivo puder ser movido.

Partilhar via