GBIC: Windows API
The following is reprinted for archival purposes from Gary Beene's Information Center, with permission from Mr. Beene himself.
'API - Application Programming Interface
'When Microsoft wrote Windows they put a huge amount of code into procedure libraries
'which programmers can access. No matter which language you're using (VB, C++, ...) you
'can use these files (called the Windows Application Programming Interface, or API) to
access the pre - written code To expand the power of your application.
'Windows has hundreds of files you can access, but the three most often used files are:
'- user32.dll controls the visible objects that you see on the screen
'- gdi32 home of most graphics oriented API
'- kernel32.dll provides access to low level operating system features
'Using procedures from other files is almost exactly the same as using procedures from within
'your own program. The one big difference is that you must tell your application which file the
'procedure is contained in. You must do this for each external procedure you plan to use.
'Telling VB about the procedure you want to use is known as "declaring" the procedure and
'the code to declare a procedure is as follows:
Declare Function ExitWindowsEx Lib "user32" ( ByVal uFlags As Long , ByVal dwReserved As Long ) As Long
'Let's take apart the declaration statement:
- Declare
'This is reserved word that VB uses to begin a declaration. There is no alternative - you have to use it.
- Function
'Also a reserved word, but in this case it distinguishes between a SUB procedured and a FUNCTION
'procedure. The API use Function procedures so that they can return a value to indicate the results
'of the action. Although you can discard the returned value, it's also possible to check the return value
'to determine that the action was successfully completed. completed. alternative - you have to use it.
- ExitWindowsEx
'Inside each DLL is a list of the procedures that it contains. Normally, in a VB declaration statement you
'simply type in the name of the procedure just as it is named in the DLL. Sometimes, the DLL true name
'of the procedure may be a name that is illegal in VB. For those cases, VB allows you to put in the text
'string "Alias NewProcedurename" right behind the filename. In this example, VB would make a call to
'the procedure by using the name "NewProcedureName".
- Lib 'user32'
'Here's where you tell VB which file the procedure is in. Normally you would put "user32.dll", showing the
'extension of the procedure library. For the special case of the three Windows system DLLs listed above,
'the API will recognize the files when simply named "user32", "kernel32", and "gdi32" - without the DLL
'extensions shown. In most other cases you must give the complete file name. Unless the file is in the
'system PATH, you must also give the complete path to the file.
- ( ByVal uFlags As Long ...)
'Exactly like VB procedures, Windows API functions can have a list of arguments. However, while your
'VB procedures often use arguments passed by reference (i.e., their values can be changed), most
'Windows API require that the arguments be passed by value (i.e, a copy of the argument is passed
'to the DLL and the originial variable cannot be changed).
'Also, you'll note that a constant or variable is normally used as the argument for an API call. It's
'technically acceptable to simply use a number for an argument but it is common practice among
'experienced programmers to create constants (or variables) whose name is easy to remember and
'then to use those in the argument list. When you're reading or debugging your code later, the use
'of these easy to read constant/variable names makes it much easier to figure out what went wrong!
- As Long
'This is exactly like the code you use to create your own functions. Windows API are functions which
'return values and you must define what type of variable is returned.
'Concerns
'Because the API code executes outside the VB program itself, your own program is susceptable to error
' in the external procedure. If the external procedure crashes, then your own program will crash as well. It
'is not un-common for an API problem to freeze your system and force a reboot - casuing loss of data
And/ Or code.
'Here are several issues/comments about using API which you will want to be aware of:
'Declare
'- DECLARE in standard module are PUBLIC by default and be used anywhere in your app
'- DECLARE in any other module are PRIVATE to that module and MUST BE marked PRIVATE
'- Procedure names for API are CASE-SENSITIVE
'ALIAS
'- Is the "real" name of the procedure as found in the DLL
'- If the API uses string, you MUST use ALIAS with "A" to specify the correct character set (A=ANSI W=UNICODE)
'- WinNT supports W, but Win95/Win98 do not
'- Some DLLs have illegal VB names, so you must use ALIAS to rename the procedure
'- Can also be the ordinal number of the procedure
'Variable Type
'- Very few DLLs recognize VARIANT
'- ByRef is VB default
'- Most DLLs expect ByVal
'- In C documentation, C passes all arguments except arrays by value
'- AS ANY can be used but it turns off all type checking
'Strings
'- API generally require fixed length strings
'- Pass string ByVal means passing pointer to first data byte in the string
'- Pass string ByRef means passing memory address to another memory addresss which refers to first data byte in the string
'- Most DLLs expect LPSTR (ASCIIZ) strings (end in a null character), which point to the first data byte
'- VB Strings should be passed ByVal (in general)
'- VB uses BSTR strings (header + data bytes) - BSTR is passed as a pointer to the header
'- DLL can modify data in a string variable that it receives as an argument - WARNING: if returned value is longer than passed value, system error occurs!
'- Generally, API do not expect string buffers longer than 255 characters
'- C & VB both treat a string array as an array of pointers to string data
'- Most API require you to pass the length of the string and to fill the string wih spaces
'Arrays
'- Pass entire array by passing the first element of the array ByRef
'- Pass individual elements of array just like any other variable
'- If pass pass binary data to DLL, use array of Byte characters
'Passing a null value
'- To pass a null value - zero-length string ("") will not work
'- To pass a null value - use vbNullString
'- To pass a null value - change Type to Long and then use 0&
'Window Handle
'- A handle is simply a number assigned by Windows to each window
'- In VB, the handle is the same as the property hWnd
'- Handles are always Long variable types
'Callbacks
'- Some API can run one of you own VB functions. Your VB function is called a "Callback"
'- Callback functions must be in a module. They cannot be in a form.
'- Use AddressOf to pass a user-defined function that the DLL procedure can use
'- Must have specific set of arguments, AS DEFINED by the API procedure
'- Passed procedure must be As Any or As Long
'Subclassing
'- All windows work by processing messages from the Windows operating system
'- You can change how a window responds to a message by intercepting the message
'- To intercept a message, use the API SetWindowsLong
'Miscellaneous
'- Control properties MUST be passed by value (use intermediate value to pass ByRef)
'- Handles - always declare as ByVal Long
'- Variant - to pass Variant to argument that is not a Variant type, pass the Variant data ByVal
'- UDT - cannot be passed except as ByRef
Loading Comments ...
Comments
No comments have been added for this post.
You must be logged in to make a comment.