Declare Statement | VB.NET Language in a Nutshell

Declare Statement

Syntax

Syntax for subroutines:

 [   accessmodifier   ] Declare [AnsiUnicodeAuto] Sub   name   Lib "   libname   " _     [Alias "aliasname"] [([   arglist   ])]

Syntax for functions:

 [   accessmodifier   ] Declare [AnsiUnicodeAuto] Function   name _   Lib "   libname   " [Alias "aliasname"] [([arglist])] [As type]

accessmodifier (optional; Keyword)

accessmodifier can be any one of the following: Public , Private , Protected , Friend , or Protected Friend . The following table describes the effects of the various access modifiers. Note that Direct Access refers to accessing the member without any qualification, as in:

 classvariable = 100

and Class/Object Access refers to accessing the member through qualification, either with the class name or the name of an object of that class.

	Direct Access scope	Class/Object Access scope
Private	Declaring class	Declaring class
Protected	All derived classes	Declaring class
Friend	Derived in-project classes	Declaring project
Protected Friend	All derived classes	Declaring project
Public	All derived classes	All projects

For more information, see Section 4.7 in Chapter 4.

Ansi (optional; Keyword)

Converts all strings to ANSI values.

Unicode (optional; Keyword)

Converts all strings to Unicode values.

Auto (optional; Keyword)

Converts the strings according to .NET rules based on the name of the method (or the alias name, if specified). If no modifier is specified, Auto is the default.

name (required; String literal)

Any valid procedure name. Note that DLL entry points 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 name of the routine as found in the DLL.

Lib (required; Keyword)

Indicates that a DLL or code resource contains the procedure being declared.

libname (required; String literal)

Name of the DLL or code resource that contains the declared procedure.

Alias (optional; Keyword)

Indicates that the procedure being called has another name in the DLL. This is useful when the external procedure name is the same as a keyword. You can also use Alias when a DLL procedure has the same name as a public variable, constant, or any other procedure in the same scope. Alias is also useful if any characters in the DLL procedure name aren't allowed by VB.NET naming conventions.

aliasname (optional; String literal)

Name of the procedure in the DLL or code resource. If the first character is not a number sign ( # ), aliasname is the name of the procedure's entry point in the DLL. If # is the first character, all characters that follow must indicate the ordinal number of the procedure's entry point.

arglist (optional)

List of variables representing arguments that are passed to the procedure when it is called.

type (optional; Keyword)

Data type of the value returned by a Function procedure; may be Byte , Boolean , Char , Short , Integer , Long , Single , Double , Decimal , Date , String , Object , or any user -defined type. Arrays of any type cannot be returned, but an Object containing an array can.

Description

Used at module level to declare references to external procedures in a dynamic- link library (DLL)

Rules at a Glance

arglist is optional and has the following syntax:
```
 [ByVal  ByRef]   varname   [( )] [As   type   ] 
```
ByVal (optional; Keyword)

The argument is passed by value; that is, a local copy of the variable is assigned the value of the argument. ByVal is the default method of passing arguments.

ByRef (optional; Keyword)

The argument is passed by reference; that is, the local variable is simply a reference to the argument being passed. All changes made to the local variable are reflected in the calling argument.

varname (required; String literal)

The name of the local variable containing either the reference or value of the argument.

type (optional; Keyword)

The data type of the argument. Can be Byte, Boolean, Char, Short, Integer, Long, Single, Double, Decimal, Date, String, Object, or any user- defined type, object type, or data type defined in the BCL.
The number and type of arguments included in arglist are checked each time the procedure is called.
The data type you use in the As clause following arglist must match that returned by the function.

Example

The following example retrieves the handle of a window from its title bar caption. This is done using the FindWindow API function.

 Declare Function FindWindow Lib "user32" Alias "FindWindowA" ( _         ByVal lpClassName As String, _         ByVal lpWindowName As String _     ) As Integer Private Sub GetWindowHandle(  )     MsgBox(FindWindow(vbNullString, "Document - WordPad")) End Sub

Programming Tips and Gotchas

Using an Alias is useful when the name of an external procedure conflicts with a Visual Basic keyword or with the name of a procedure within your project, or when the name of the procedure in the code library is not allowed by Visual Basic naming conventions. In addition, aliasname is frequently used with functions in the Win32 API that have string parameters, where the "official" documented name of the function is used in code to call either of two "real" functions one an ANSI and the other a Unicode version. For example:
```
 Declare Function ExpandEnvironmentStrings _    Lib "kernel32" Alias "ExpandEnvironmentStringsA" _    (ByVal lpSrc As String, ByVal lpDst As String, _    ByVal nSize As Long) As Long 
```
defines the documented Win32 function ExpandEnvironmentStrings to a VB application. However, although calls to the function take the form:
```
 lngBytes = ExpandEnvironmentStrings(strOriginal, _            strCopy, len(strCopy)) 
```
the actual name of the function as it exists in Kernel32.dll is ExpandEnvironmentStringsA . ( Windows . API functions ending in "A" are the ANSI string versions, and those ending in "W" (for Wide) are the Unicode string versions.)
You can use the # symbol at the beginning of aliasname to denote that aliasname is in fact the ordinal number of a procedure within the DLL or code library. In this case, all characters following the # sign and composing the aliasname argument must be numeric. For example:
```
 Declare Function GetForegroundWindow Lib "user32" _         Alias "#237" (  ) As Long 
```
Remember that DLL entry points are case sensitive. In other words, either name or aliasname (if it is present and does not represent a routine's ordinal position) must correspond in case exactly to the routine as it is defined in the external DLL. Otherwise, VB displays runtime error 453, "Specified DLL function not found." 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 by default 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 Advapi32.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 1999).
In addition to the standard VB data types, you can also include BCL data types that are not wrapped by VB in arglist . Most useful are the unsigned integers, UShort, UInt16, and UInt32.
In many cases, you can use routines available in the .NET Base Class Library or Framework Class Library instead of calling the Win32 API.

VB.NET/VB 6 Differences

In VB 6, it is possible to declare the data type of an argument as Any , which suspends typechecking by the VB runtime engine. In VB.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 VB.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 VB.NET, this usage is not permitted.
The size of the integer data types in VB 6 and VB.NET are different, making it necessary to rewrite any arglist that has a data type of Integer or Long in VB 6. The VB 6 Integer data type is equivalent to the VB.NET Short data type. The VB 6 Long data type is equivalent to the VB.NET Integer data type.
VB 6 lacks a signed 8-bit integer data type and unsigned data types to correspond to the Integer and Long types. In the .NET platform, unsigned data types are available for 16-bit integers (UInt16), 32-bit integers (UInt32), and 64-bit integers (UInt64). A signed byte data type (SByte) is also available. All are BCL classes not wrapped by VB.NET.