Visual Studio 2010 - Visual Basic Walkthrough: Calling Windows APIs (Visual Basic) Windows APIs are dynamic-link libraries (DLLs) that are part of the Windows operating system. You use them to perform tasks when it is difficult to write equivalent procedures of your own. For example, Windows provides a function named FlashWindowEx that lets you make the title bar for an application alternate between light and dark shades. The advantage of using Windows APIs in your code is that they can save development time because they contain dozens of useful functions that are already written and waiting to be used. The disadvantage is that Windows APIs can be difficult to work with and unforgiving when things go wrong. Windows APIs represent a special category of interoperability. Windows APIs do not use managed code, do not have built-in type libraries, and use data types that are different than those used with Visual Studio. Because of these differences, and because Windows APIs are not COM objects, interoperability with Windows APIs and the .NET Framework is performed using platform invoke, or PInvoke. Platform invoke is a service that enables managed code to call unmanaged functions implemented in DLLs. For more information, see Consuming Unmanaged DLL Functions. You can use PInvoke in Visual Basic by using either the Declare statement or applying the DllImport attribute to an empty procedure. Windows API calls were an important part of Visual Basic programming in the past, but are seldom necessary with Visual Basic 2005. Whenever possible, you should use managed code from the .NET Framework to perform tasks, instead of Windows API calls. This walkthrough provides information for those situations in which using Windows APIs is necessary.
.gif) Note |
|---|
|
Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.
|
API Calls Using Declare
The most common way to call Windows APIs is by using the Declare statement. To declare a DLL procedureDetermine the name of the function you want to call, plus its arguments, argument types, and return value, as well as the name and location of the DLL that contains it. | Note |
|---|
For complete information about the Windows APIs, see the Win32 SDK documentation in the Platform SDK Windows API. For more information about the constants that Windows APIs use, examine the header files such as Windows.h included with the Platform SDK. |
Open a new Windows Application project by clicking New on the File menu, and then clicking Project. The New Project dialog box appears. Select Windows Application from the list of Visual Basic project templates. The new project is displayed. Add the following Declare function either to the class or module in which you want to use the 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
Parts of the Declare StatementThe Declare statement includes the following elements. Auto modifierThe Auto modifier instructs the runtime to convert the string based on the method name according to common language runtime rules (or alias name if specified). Lib and Alias keywordsThe name following the Function keyword is the name your program uses to access the imported function. It can be the same as the real name of the function you are calling, or you can use any valid procedure name and then employ the Alias keyword to specify the real name of the function you are calling. Specify the Lib keyword, followed by the name and location of the DLL that contains the function you are calling. You do not need to specify the path for files located in the Windows system directories. Use the Alias keyword if the name of the function you are calling is not a valid Visual Basic procedure name, or conflicts with the name of other items in your application. Alias indicates the true name of the function being called. Argument and Data Type DeclarationsDeclare the arguments and their data types. This part can be challenging because the data types that Windows uses do not correspond to Visual Studio data types. Visual Basic does a lot of the work for you by converting arguments to compatible data types, a process called marshaling. You can explicitly control how arguments are marshaled by using the MarshalAsAttribute attribute defined in the System.Runtime.InteropServices namespace. | Note |
|---|
Previous versions of Visual Basic allowed you to declare parameters As Any, meaning that data of any data type could be used. Visual Basic requires that you use a specific data type for all Declare statements. |
Windows API ConstantsSome arguments are combinations of constants. For example, the MessageBox API shown in this walkthrough accepts an integer argument called Typ that controls how the message box is displayed. You can determine the numeric value of these constants by examining the #define statements in the file WinUser.h. The numeric values are generally shown in hexadecimal, so you may want to use a calculator to add them and convert to decimal. For example, if you want to combine the constants for the exclamation style MB_ICONEXCLAMATION 0x00000030 and the Yes/No style MB_YESNO 0x00000004, you can add the numbers and get a result of 0x00000034, or 52 decimal. Although you can use the decimal result directly, it is better to declare these values as constants in your application and combine them using the Or operator. To declare constants for Windows API callsConsult the documentation for the Windows function you are calling. Determine the name of the constants it uses and the name of the .h file that contains the numeric values for these constants. Use a text editor, such as Notepad, to view the contents of the header (.h) file, and find the values associated with the constants you are using. For example, the MessageBox API uses the constant MB_ICONQUESTION to show a question mark in the message box. The definition for MB_ICONQUESTION is in WinUser.h and appears as follows: #define MB_ICONQUESTION 0x00000020L Add equivalent Const statements to your class or module to make these constants available to your application. For example:
Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7
To call the DLL procedureAdd a button named Button1 to the startup form for your project, and then double-click it to view its code. The event handler for the button is displayed. Add code to the Click event handler for the button you added, to call the procedure and provide the appropriate arguments:
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
Run the project by pressing F5. The message box is displayed with both Yes and No response buttons. Click either one.
Data MarshalingVisual Basic automatically converts the data types of parameters and return values for Windows API calls, but you can use the MarshalAs attribute to explicitly specify unmanaged data types that an API expects. For more information about interop marshaling, see Interop Marshaling. To use Declare and MarshalAs in an API callDetermine the name of the function you want to call, plus its arguments, data types, and return value. To simplify access to the MarshalAs attribute, add an Imports statement to the top of the code for the class or module, as in the following example:
Imports System.Runtime.InteropServices
Add a function prototype for the imported function to the class or module you are using, and apply the MarshalAs attribute to the parameters or return value. In the following example, an API call that expects the type void* is marshaled as AsAny:
Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
ByVal x As Short,
<MarshalAsAttribute(UnmanagedType.AsAny)>
ByVal o As Object)
API Calls Using DllImport
The DllImport attribute provides a second way to call functions in DLLs without type libraries. DllImport is roughly equivalent to using a Declare statement but provides more control over how functions are called. You can use DllImport with most Windows API calls as long as the call refers to a shared (sometimes called static) method. You cannot use methods that require an instance of a class. Unlike Declare statements, DllImport calls cannot use the MarshalAs attribute. To call a Windows API using the DllImport attributeOpen a new Windows Application project by clicking New on the File menu, and then clicking Project. The New Project dialog box appears. Select Windows Application from the list of Visual Basic project templates. The new project is displayed. Add a button named Button2 to the startup form. Double-click Button2 to open the code view for the form. To simplify access to DllImport, add an Imports statement to the top of the code for the startup form class:
Imports System.Runtime.InteropServices
Declare an empty function preceding the End Class statement for the form, and name the function MoveFile. Apply the Public and Shared modifiers to the function declaration and set parameters for MoveFile based on the arguments the Windows API function uses:
Public Shared Function MoveFile(
ByVal src As String,
ByVal dst As String) As Boolean
' Leave the body of the function empty.
End Function
Your function can have any valid procedure name; the DllImport attribute specifies the name in the DLL. It also handles interoperability marshaling for the parameters and return values, so you can choose Visual Studio data types that are similar to the data types the API uses. Apply the DllImport attribute to the empty function. The first parameter is the name and location of the DLL containing the function you are calling. You do not need to specify the path for files located in the Windows system directories. The second parameter is a named argument that specifies the name of the function in the Windows API. In this example, the DllImport attribute forces calls to MoveFile to be forwarded to MoveFileW in KERNEL32.DLL. The MoveFileW method copies a file from the path src to the path 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
Add code to the Button2_Click event handler to call the function:
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
Create a file named Test.txt and place it in the C:\Tmp directory on your hard drive. Create the Tmp directory if necessary. Press F5 to start the application. The main form appears. Click Button2. The message "The file was moved successfully" is displayed if the file can be moved.
See Also
ReferenceConceptsOther Resources
|
Visual Studio 2010 - Visual Basic Tutorial: Llamar a las API de Windows (Visual Basic) Las API de Windows son bibliotecas de vínculos dinámicos (DLL) que forman parte del sistema operativo Windows. Se utilizan para realizar tareas cuando resulta difícil escribir procedimientos equivalentes. Por ejemplo, Windows proporciona una función denominada FlashWindowEx que permite que la barra de título de una aplicación alterne entre un sombreado claro y otro oscuro. La ventaja de utilizar las API de Windows en el código es que pueden ahorrar tiempo porque contienen numerosas funciones útiles ya escritas y listas para utilizar. La desventaja es que puede resultar difícil trabajar con las API de Windows y pueden ser implacables cuando las cosas van mal. Las API de Windows representan una categoría especial de interoperabilidad. Las API de Windows no utilizan código administrado, no tienen bibliotecas de tipos integradas y utilizan tipos de datos que son diferentes a los que se utilizan en Visual Studio. Debido a estas diferencias y a que las API de Windows no son objetos COM, la interoperabilidad con las API de Windows y .NET Framework se lleva a cabo mediante la invocación de la plataforma o PInvoke. Invocación de la plataforma es un servicio que permite al código administrado llamar a funciones no administradas implementadas en archivos DLL. Para obtener más información, vea Consumir funciones DLL no administradas. Puede utilizar PInvoke en Visual Basic mediante la instrucción Declare o aplicando el atributo DllImport a un procedimiento vacío. Las llamadas API de Windows constituían en el pasado una parte importante de la programación de Visual Basic, pero en Visual Basic 2005 pocas veces resultan necesarias. Siempre que sea posible, debe utilizar código administrado en .NET Framework para llevar a cabo tareas en lugar de utilizar llamadas API de Windows. Este tutorial proporciona información sobre aquellas situaciones en las que es necesario utilizar las API de Windows.
| Nota |
|---|
|
Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio incluidos en las instrucciones siguientes. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para obtener más información, vea Valores de configuración de Visual Studio.
|
Llamadas API usando Declare
El modo más común de llamar a las API de Windows es utilizar la instrucción Declare. Para declarar un procedimiento de DLLDetermine el nombre de la función que desea llamar y sus argumentos, los tipos de argumento y el valor devuelto, así como el nombre y la ubicación de la DLL que la contiene. | Nota |
|---|
Para obtener información completa sobre las API de Windows, consulte la documentación Win32 SDK relacionada con la API de Windows de Platform SDK. Para obtener más información sobre las constantes que utilizan las API de Windows, vea los archivos de encabezado, como Windows.h, que se incluyen en el SDK de la plataforma. |
En el menú Archivo, haga clic en Nuevo para abrir un nuevo proyecto de aplicación para Windows y, a continuación, haga clic en Proyecto. Aparecerá el cuadro de diálogo Nuevo proyecto. Seleccione Aplicación Windows en la lista de plantillas de proyecto de Visual Basic. Aparecerá el proyecto nuevo. Agregue la función Declare siguiente a la clase o al módulo en el que desea utilizar el archivo 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 la instrucción DeclareLa instrucción Declare incluye los siguientes elementos. Modificador AutoEl modificador Auto indica al motor en tiempo de ejecución que convierta la cadena basada en el nombre del método de acuerdo con las reglas de Common Language Runtime (o el alias, si se ha especificado). Palabras clave Lib y AliasEl nombre que sigue a la palabra clave Function es el nombre que utiliza el programa para tener acceso a la función importada. Puede ser igual que el nombre real de la función a la que llama; o bien, puede utilizar cualquier nombre de procedimiento válido y utilizar después la palabra clave Alias para especificar el nombre real de la función a la que llama. Especifique la palabra clave Lib seguida del nombre y la ubicación de la DLL que contiene la función a la que se está llamando. No es necesario que especifique la ruta de acceso de los archivos ubicados en los directorios del sistema de Windows. Utilice la palabra clave Alias si el nombre de la función a la que llama no es un nombre de procedimiento válido de Visual Basic o si está en conflicto con el nombre de otros elementos de la aplicación. Alias indica el nombre real de la función a la que se llama. Declaraciones de argumentos y tipos de datosDeclare los argumentos y sus tipos de datos. Esta parte puede suponer un reto porque los tipos de datos que Windows usa no corresponden a los tipos de datos de Visual Studio. Visual Basic se encarga de gran parte del trabajo ya que convierte los argumentos en tipos de datos compatibles; este proceso se denomina cálculo de referencias. Puede controlar explícitamente el modo en que se calculan las referencias de los argumentos mediante el atributo MarshalAsAttribute definido en el espacio de nombres System.Runtime.InteropServices. | Nota |
|---|
Las versiones anteriores de Visual Basic permitían declarar parámetros As Any, lo que significa que se podían utilizar datos de cualquier tipo. Visual Basic requiere que se utilice un tipo de datos específico en todas las instrucciones Declare. |
Constantes de las API de WindowsAlgunos argumentos son combinaciones de constantes. Por ejemplo, la API MessageBox que se muestra en este tutorial acepta un argumento Integer denominado Typ que controla cómo se muestra el cuadro de mensaje. Puede determinar el valor numérico de estas constantes examinando las instrucciones #define en el archivo WinUser.h. Los valores numéricos se muestran generalmente en hexadecimal, de modo que se puede utilizar una calculadora para agregarlos y convertirlos a decimal. Por ejemplo, si desea combinar las constantes del estilo de exclamación MB_ICONEXCLAMATION 0x00000030 y el estilo sí/no MB_YESNO 0x00000004, puede sumar los números y obtener el resultado de 0x00000034, o 52 en el sistema decimal. Aunque puede utilizar el resultado decimal directamente, es mejor declarar estos valores como constantes en la aplicación y combinarlos utilizando el operador Or. Para declarar constantes para las llamadas a API de WindowsConsulte la documentación de la función de Windows a la que está llamando. Determine el nombre de las constantes que utiliza y el nombre del archivo .h que contiene los valores numéricos de estas constantes. Utilice un editor de texto, como el Bloc de notas, para ver el contenido del archivo de encabezado .h y busque los valores asociados con las constantes que está utilizando. Por ejemplo, la API MessageBox utiliza la constante MB_ICONQUESTION para mostrar un signo de interrogación en el cuadro de mensaje. La definición para MB_ICONQUESTION está en WinUser.h y aparece como sigue: #define MB_ICONQUESTION 0x00000020L Agregue instrucciones Const equivalentes en la clase o el módulo para que estas constantes estén disponibles para la aplicación. Por ejemplo:
Const MB_ICONQUESTION As Integer = &H20
Const MB_YESNO As Integer = &H4
Const IDYES As Integer = 6
Const IDNO As Integer = 7
Para llamar al procedimiento de DLLAgregue un botón denominado Button1 al formulario de inicio del proyecto y haga doble clic en él para ver su código. Aparecerá el controlador de eventos del botón. Agregue código al controlador de eventos Click del botón que ha agregado para llamar al procedimiento, y proporcione los argumentos correspondientes:
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
Presione F5 para ejecutar el proyecto. El cuadro de mensaje aparecerá con dos botones de respuesta Sí y No. Haga clic en alguno de ellos.
Cálculo de referencias de datosVisual Basic convierte automáticamente los tipos de datos de parámetros y valores devueltos para las llamadas API de Windows, aunque se puede utilizar el atributo MarshalAs para especificar de manera explícita los tipos de datos no administrados que espera una API. Para obtener más información sobre el cálculo de referencias de interoperabilidad, vea Cálculo de referencias de interoperabilidad. Para utilizar Declare y MarshalAs en una llamada a una APIDetermine el nombre de la función a la que desea llamar y sus argumentos, tipos de datos y valor devuelto. Para simplificar el acceso al atributo MarshalAs, agregue una instrucción Imports en la parte superior del código de la clase o módulo, como en el siguiente ejemplo:
Imports System.Runtime.InteropServices
Agregue el prototipo de la función importada en la clase o módulo que está utilizando y aplique el atributo MarshalAs a los parámetros o al valor devuelto. En el siguiente ejemplo, se calculan las referencias de una llamada a una API que espera el tipo void* como AsAny:
Declare Sub SetData Lib "..\LIB\UnmgdLib.dll" (
ByVal x As Short,
<MarshalAsAttribute(UnmanagedType.AsAny)>
ByVal o As Object)
Llamadas a API utilizando DllImport
El atributo DllImport proporciona una alternativa para llamar a las funciones de DLL sin bibliotecas de tipos. El atributo DllImport es prácticamente equivalente a la instrucción Declare pero proporciona un mayor control sobre la forma en que se llama a las funciones. Puede utilizar DllImport con la mayoría de las llamadas a API de Windows siempre y cuando la llamada haga referencia a un método compartido (a veces denominado static). No puede utilizar métodos que requieran una instancia de una clase. A diferencia de las instrucciones Declare, las llamadas a DllImport no pueden utilizar el atributo MarshalAs. Para llamar a una API de Windows utilizando el atributo DllImportEn el menú Archivo, haga clic en Nuevo para abrir un nuevo proyecto de aplicación para Windows y, a continuación, haga clic en Proyecto. Aparecerá el cuadro de diálogo Nuevo proyecto. Seleccione Aplicación Windows en la lista de plantillas de proyecto de Visual Basic. Aparecerá el proyecto nuevo. Agregue un botón denominado Button2 al formulario de inicio. Haga doble clic en Button2 para abrir la vista de código del formulario. Para simplificar el acceso a DllImport, agregue una instrucción Imports a la parte superior del código para la clase del formulario de inicio:
Imports System.Runtime.InteropServices
Declare una función vacía que preceda a la instrucción End Class para el formulario y dé a la función el nombre MoveFile. Aplique los modificadores Public y Shared a la declaración de la función y establezca parámetros para MoveFile de acuerdo con los argumentos que utiliza la función de la API de Windows:
Public Shared Function MoveFile(
ByVal src As String,
ByVal dst As String) As Boolean
' Leave the body of the function empty.
End Function
La función puede tener cualquier nombre de procedimiento válido; el atributo DllImport especifica el nombre de la DLL. También controla el cálculo de referencia de interoperabilidad de los parámetros y los valores devueltos, de manera que puede elegir tipos de datos de Visual Studio que sean similares a los tipos de datos que utiliza la API. Aplique el atributo DllImport a la función vacía. El primer parámetro es el nombre y la ubicación de la DLL que contiene la función a la que llama. No es necesario que especifique la ruta de acceso de los archivos ubicados en los directorios del sistema de Windows. El segundo parámetro es un argumento con nombre que especifica el nombre de la función de la API de Windows. En este ejemplo, el atributo DllImport hace que las llamadas a MoveFile se reenvíen a MoveFileW en KERNEL32.DLL. El método MoveFileW copia un archivo de la ruta de acceso src a la ruta de acceso 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
Agregue el código al controlador de eventos Button2_Click para llamar a la función:
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
Cree un archivo con el nombre Test.txt y sitúelo en el directorio C:\Tmp del disco duro. Cree el directorio Tmp si es necesario. Presione F5 para iniciar la aplicación. Aparecerá el formulario principal. Haga clic en Button2. Aparecerá el mensaje "El archivo se ha movido correctamente" si se puede mover el archivo.
Vea también
ReferenciaConceptosOtros recursos
|