Instruções passo a passo: chamando APIs do Windows (Visual Basic)

Artigo
06/08/2015

APIs do Windows são bibliotecas de vínculo dinâmico (DLLs) que fazem parte do sistema operacional Windows. Você as usa para executar tarefas quando é difícil escrever procedimentos equivalentes de sua preferência. Por exemplo, o Windows fornece uma função chamada FlashWindowEx que permite que você crie a barra de título para um aplicativo alternativo entre tonalidades claras e escuras.

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

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

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

Dica

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ê possui e as configurações que você usa determinam esses elementos. Para obter mais informações, consulte Personalizando configurações de desenvolvimento no Visual Studio.

Chamadas de API Usando Declare

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

Para declarar um procedimento de DLL

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

Dica

Para obter informações completas sobre as APIs do Windows, consulte a documentação do Win32 SDK na Platform SDK Windows API.Para obter mais informações sobre as constantes que as APIs do Windows usam, examine os arquivos de cabeçalho, como Windows.h incluído no SDK da plataforma.
Abra um novo projeto aplicativo do Windows, clicando em New no menu File e em seguida, clicando em Project . A caixa de diálogo New Project será exibida.
Selecione Aplicativos do Windows a partir da lista de modelos de projeto de Visual Basic. O novo projeto é exibido.

Adicione a seguinte função Declare tanto para a classe quanto 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 de Instrução Declare

A instrução Declare inclui os elementos a seguir.

Modificador automático

O modificador Auto instrui o runtime para converter a sequência de caracteres com base no nome do método de acordo com a regras de tempo de execução de linguagem comum (ou alias se especificado).

Palavras-chave Lib e Alias

O nome após a palavra-chave Function é o nome que seu programa usa para acessar a função importada. Ele pode ser o mesmo que o nome real da função que você está chamando, ou você pode usar qualquer nome válido de procedimento e, em seguida, empregar a palavra-chave Alias para especificar o nome real da função que você está chamando.

Especifique a palavra-chave Lib, seguida do nome e localização do DLL que contém a função que você está chamando. Você não precisa especificar o caminho para arquivos localizados nas pastas de sistema do Windows.

Use o Alias palavra-chave se o nome da função chamada não é válido Visual Basic nome do procedimento ou conflita com o nome de outros itens em seu aplicativo. Aliasindica o verdadeiro nome da função que está sendo chamado.

Declarações de Tipo de Dados e Argumentos

Declare os argumentos e seus tipos de dados. Esta parte pode ser desafiador porque os tipos de dados que o Windows usa não correspondem aos tipos de dados Visual Studio. Visual Basicfaz uma grande parte do trabalho para você, convertendo os argumentos para tipos de dados compatíveis, um processo chamado de empacotamento. Você pode controlar explicitamente como argumentos são empacotados usando o atributo MarshalAsAttribute definido no namespace System.Runtime.InteropServices.

Dica

Versões anteriores do Visual Basic permitia que você declarar parâmetros As Any, que significa que os dados de qualquer dado tipo pode ser usado.Visual Basicexige que você use um tipo de dados específico para todas as Declare instruções.

Constantes API do Windows

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

Para declarar constantes para chamadas API do Windows

Consulte a documentação para a função do Windows que você está chamando. Determine o nome das constantes que são usadas e o nome do arquivo .h que contém os valores numéricos para constantes.
Usar 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 API MessageBox usa a constante MB_ICONQUESTION para mostrar um ponto de interrogação na caixa de mensagem. A definição de MB_ICONQUESTION está na WinUser.h e aparece da seguinte maneira:

#define MB_ICONQUESTION 0x00000020L
Adicione instruções Const equivalentes à sua classe ou módulo para tornar essas constantes disponíveis 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 de DLL

Adicionar um botão chamado Button1 para o formulário de inicialização para 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 para o manipulador de eventos Click para o botão que é adicionado, para chamar o procedimento e forneça 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 ambos os botões de resposta Yes e No. Clique em qualquer um.

Empacotamento de Dados

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

Para usar Declare e MarshalAs em uma chamada de API

Determine o nome da função que você deseja chamar, mais seus argumentos, tipos de dados e valor de retorno.
Para simplificar o acesso ao atributo MarshalAs,adicione uma instrução Imports à parte superior do código para a 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 para a classe ou módulo que estiver usando, e aplique o atributo MarshalAs aos parâmetros ou valor de retorno. No exemplo a seguir, uma chamada de API que espera que 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 API usando DllImport

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

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

Para chamar uma API do Windows usando o atributo DllImport

Abra um novo projeto aplicativo do Windows, clicando em New no menu File e em seguida, clicando em Project . A caixa de diálogo New Project será exibida.
Selecione Aplicativos do Windows a partir da lista de modelos de projeto de Visual Basic. O novo projeto é exibido.
Adicione um botão denominado Button2 para o formulário de inicialização.
Clique duas vezes em Button2 para abrir o modo de exibição de código para o formulário.
Para simplificar o acesso à DllImport,adicione uma instrução Imports à parte superior do código para a classe do formulário de inicialização:
```
Imports System.Runtime.InteropServices
```
Declarar uma função vazia que precede a instrução End Class para o formulário e nomeie a função MoveFile.
Aplicar os modificadores Public e Shared à função de declaração e definir parâmetros para MoveFile baseiados nos argumentos que função 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
```
Sua função pode ter qualquer nome válido de procedimento; o atributo DllImport especifica o nome na DLL. Ele também trata interoperabilidade de empacotamento para os parâmetros e valores de retorno, para que você possa escolher os tipos de dados do Visual Studio que são semelhantes aos tipos de dados que a API usa..
Aplique o atributo DllImport à função vazia. O primeiro parâmetro é o nome e o local da DLL que contém a função que você está chamando. Você não precisa especificar o caminho para arquivos localizados nas pastas de sistema do Windows. O segundo parâmetro é um argumento nomeado que especifica o nome da função na API do Windows. Neste exemplo, o DllImport atributo força chamadas para MoveFile sejam encaminhados para MoveFileW em KERNEL32.DLL. O método MoveFileW 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 para o manipulador de eventos Button2_Click 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

Criar um arquivo chamado Test.txt e coloque-o na pasta C:\Tmp em seu disco rígido. Crie a pasta TMP, se necessário.
Pressione F5 para iniciar o aplicativo. O formulário principal aparece.
Clique em Button2. A mensagem "O arquivo foi movido com êxito" será exibida se o arquivo pode ser movido.

Consulte também

Compartilhar via