Syntax [accessModifier] [Shadows] Declare [Ansi | Unicode | Auto] _ {Sub | Function} name Lib "libname" [Alias "aliasname"] _ [([arglist])] [As type]
accessModifier (optional) Specifies the scope and accessibility of the declaration. One of the following access levels: Access level | Description |
|---|
Public | The declaration is publicly accessible anywhere, both inside and outside of the project. | Private | The declaration is accessible only within the defining type. | Protected | The declaration is accessible only to the code in the defining type or to one of its derived types. | Friend | The declaration is accessible only within the project that contains the declaration definition. | Protected Friend | Combines the access features of Protected and Friend. |
If omitted, the Public access level is used.
Shadows (optional) Indicates that the declaration shadows an identically named element in a base class.
Ansi (optional) Converts all strings to ANSI values. This is the default if none of the string translation modifiers are used.
Unicode (optional) Converts all strings to Unicode values.
Auto (optional) Converts the strings according to .NET rules based on the name of the method (or the alias name, if specified).
name (required) Any valid procedure name. Dynamic-link library (DLL) procedure and function names are case-sensitive. If the aliasname argument is used, name represents the name by which the function or procedure is referenced in your code, while aliasname represents the true name of the routine as found in the DLL.
libname (required; String) The name of the DLL or code resource that contains the declared procedure.
aliasname (optional; String) Indicates the true name of the procedure or function in the DLL, as opposed to the local name identified through name. If the true procedure or function name conflicts with a Visual Basic or .NET keyword or reserved word, use this feature to supply a nonconflicting name.
arglist (optional) A comma-delimited list of parameters defined by the DLL function or procedure. Each comma-delimited parameter includes a parameter name and a data type. arglist uses the following syntax and parts: [ByVal | ByRef] varname[( )] [As argtype]
ByVal (optional) The argument is passed by value to the DLL. ByVal is the default method of passing variables.
ByRef (optional) The argument is passed by reference to the DLL. All changes made to the argument in the DLL procedure will be reflected in the original variable.
varname (required) The name of the argument, although it may vary from the parameter name given by the designer of the DLL.
argtype (optional; Type) The data type of the argument. Any valid .NET data type can be used. Visual Basic does not examine the DLL at compile time to see if this data type is correct.
type (optional; Type) Data type of the value returned by a DLL function. Arrays cannot be returned, but an Object containing an array is valid.
Description The Declare statement is used at the module level to declare references to external procedures in DLLs. Usage at a Glance The data type of each parameter, and also the data type of the return value, may differ in name between .NET and the DLL. For instance, 16-bit signed integers may be known as "Integer" in the DLL, but they should be declared as Short in the Declare parameter list. The number and type of arguments included in arglist are checked each time the procedure is called. You can use the # symbol at the beginning of aliasname to denote that aliasname is, in fact, the ordinal position of a procedure within the DLL or code library. In this case, all characters following the # sign must be numeric. For example: Friend Declare Function GetForegroundWindow Lib "user32" _ Alias "#237" ( ) As Long
DLL entry points are case-sensitive. Either name or aliasname (whichever one represents the true name of the DLL procedure) must correspond in case exactly to the routine as it is defined in the external DLL. If you aren't sure how the routine name appears in the DLL, use the DumpBin.exe utility to view its export table. For instance, the following command displays the export table of advapi32.dll, one of the Windows system files: dumpbin /exports c:\windows\system32\advapi32.dll
libname can include an optional path that identifies precisely where the external library is located. If the path is not included along with the library name, VB searches the current directory, the Windows directory, the Windows system directory, and the directories in the path, in that order. If the external library is one of the major Windows system DLLs (such as Kernel32.dll or User32.dll), libname can consist of only the root filename, rather than the complete filename and extension. One of the most common uses of the Declare statement is to make routines in the Win32 API accessible to your programs. For more on this topic, see Win32 API Programming with Visual Basic by Steven Roman (O'Reilly Media). The .NET Framework also defines a <DllImport> attribute that provides similar functionality. In many cases, you can use routines available in the .NET Base Class Library or Framework Class Library instead of calling procedures in the Win32 API.
Example The following example retrieves the handle of a window from its title bar caption. This is done using the FindWindow API function. Friend Declare Function FindWindow Lib "user32" _ Alias "FindWindowA" (ByVal lpClassName As String, _ ByVal lpWindowName As String) As Integer Private Sub ShowWindowHandle( ) MsgBox(FindWindow(vbNullString, "Document - WordPad")) End Sub
Version Differences In VB 6, it is possible to declare the data type of an argument as Any, which suspends type checking by the VB runtime engine. In .NET, this usage is not supported. In VB 6, if ByVal or ByRef is not specified, an argument is passed to the calling procedure by reference. In .NET, arguments are passed by value, by default. In VB 6, it is possible to override the method in which an argument is passed to an external function within the call itself by specifying either ByVal or ByRef before the argument. In .NET, this usage is not permitted. Due to data-type changes between VB 6 and VB under .NET, some data-type changes may be required in the Declare statement. For instance, parameters declared as Integer in VB 6 are declared as Short in .NET.
|
