DOCUMENT:Q171729 11-JAN-2001 [vbwin] TITLE :HOWTO: Do Generic Callbacks Using a Helper DLL PRODUCT :Microsoft Visual Basic for Windows PROD/VER: OPER/SYS: KEYWORDS:kbGrpDSVB ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Learning Edition for Windows, version 6.0 - Microsoft Visual Basic Professional Edition for Windows, version 6.0 - Microsoft Visual Basic Enterprise Edition for Windows, version 6.0 - Microsoft Visual Basic Control Creation Edition for Windows, version 5.0 - Microsoft Visual Basic Learning Edition for Windows, version 5.0 - Microsoft Visual Basic Professional Edition for Windows, version 5.0 - Microsoft Visual Basic Enterprise Edition for Windows, version 5.0 ------------------------------------------------------------------------------- SUMMARY ======= The new AddressOF operator allows you to pass the Address of a Visual Basic procedure to a DLL for the purposes of providing a Callback function. However, Visual Basic does not let you make the callback directly from within BASIC code. This article provides a helper DLL that makes generic callback functionality available to BASIC. MORE INFORMATION ================ The usual way to use the callback mechanism is to write separate DLL functions for each BASIC function prototype. This article details two Visual C++ functions that provide a generic callback mechanism for any BASIC function prototype. The functions work by manipulating the stack, thus passing the parameters directly to the called function. WARNING: ANY USE BY YOU OF THE CODE PROVIDED IN THIS ARTICLE IS AT YOUR OWN RISK. Microsoft provides this code "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. Visual C++ Code --------------- The following code was compiled using Microsoft Visual C++ 4.0 but should work with other compilers. This is in a standard DLL project with multi- threaded DLL libraries. The calling convention has no prolog code. If you're unsure, have the compiler generate an .ASM file, examine the output, and choose a different calling convention. You can ignore epilog code because it will never get executed. NOTE: This code is specific to the INTEL platform only. Callback.DEF ------------ LIBRARY VB5Callback EXPORTS Callback Callback2 Callback.CPP ------------ __declspec(naked) void Callback() { /* For procedures with return values of 8 bytes or less */ /* Get address to be called and fix-up return address */ _asm pop eax; // save return address _asm pop ecx; // get address to JMP to _asm push eax; // restore return address _asm jmp ecx; // Jump to callback function.... } __declspec(naked) void Callback2() { /* For procedures with return values of more than 8 bytes */ /* Get address to be called and fix-up return address */ _asm pop eax; // save return address _asm pop edx; // save parameter 0 _asm pop ecx; // get address to JMP to _asm push edx; // restore parameter 0 _asm push eax; // restore return address _asm jmp ecx; // Jump to callback function.... } Visual Basic Code ----------------- The function prototypes in BASIC are achieved by using the DECLARE statement because the BASIC compiler does no type checking on the DLL functions. The first argument needs to be a LONG with which to pass the address of the function to be called. Subsequent arguments and the function return type should match the callback function exactly. Sample Callback Function Declarations: -------------------------------------- The callback functions must reside in a standard .BAS module. They cannot reside in a Form or Class module: Sub Message() Function Calc(ByVal X As Long, Y As Long) As Long Function StrPrt(ByVal S As String) As String Function RetVariant() As Variant Sample Declare Statements ------------------------- The declare statements can be anywhere. If in a Form or Class module, they need to be declared using Private Declare ...: Declare Sub CallMessage Lib "Callback.dll" Alias "Callback" _ (ByVal Addr As Long) Declare Function CallCalc Lib "Callback.dll" Alias "Callback" _ (ByVal Addr As Long, ByVal X As Long, Y As Long) As Long Declare Function CallStrPrt Lib "Callback.dll" Alias "Callback" _ (ByVal Addr As Long, ByVal S As String) As String Declare Function CallRetVariant Lib "Callback.dll" Alias "Callback2" _ (ByVal Addr As Long) As Variant The use of "Callback" or "Callback2" depends on the function return type as explained in the Return Type table (below). Sample Usage ------------ The callback functions can be called from anywhere in scope of the prototype Declare statement: CallMessage AddressOf Message iResult = CallCalc(AddressOf Calc, 6, iNum) S$ = CallStrPrt(AddressOf StrPrt, "The moon is rising over Toledo") Debug.Print CallRetVariant(AddressOf RetVariant) Return-type Table ----------------- The following table indicates which return types should use Callback and which should use Callback2 in their Declare statements. Two versions of the function are required. The first is for Sub routines and all Function prototypes whose return type occupies 8 bytes or less, including all object types and String. The second is for Function prototypes whose return argument is greater than 8 bytes, namely all Variants and those User-Defined Types whose length is greater than 8 bytes. The reason for this dichotomy is that Visual Basic can't return these large data types in a register. It passes the address of a pre-allocated structure as an implicit parameter on the stack, which the second callback function takes into account. Return Type DLL Function ---------------------------- -------------------- All Sub routines Callback Byte Callback Integer Callback Boolean Callback Long Callback Single Callback Double Callback Currency Callback Date Callback String Callback Variant Callback2 Any object type Callback User-defined type (8-bytes or less) Callback User-defined Type (more than 8 bytes) Callback2 If you're unsure about which function to use with your user-defined type, you may have to try both functions and see which one works. The example below illustrates Types requiring both Callback and Callback2: Type Size8 ' functions returning this type require Callback A As Long ' 4 bytes B As String ' 4-byte pointer - note String discussion below End Type Type Size12 ' functions returning this type require Callback2 A As Long ' 4 bytes B As Double ' 8 bytes End Type A Note About Strings -------------------- Because BASIC is calling a DLL, it will convert string parameters from UNICODE to ANSI when calling, and back to UNICODE when returning. If the function returns a String, it undergoes the ANSI to UNICODE conversion process also. The callback function receives the converted (ANSI) string, which can present problems. This also applies to Strings in User-Defined types. There are several ways to deal with this problem: 1. Use the StrConv() function in the callback function to do the appropriate conversions upon entry and exit. 2. Use Byte arrays. These don't undergo conversion. 3. Use Variant. These don't undergo conversion and can be used as function return, whereas Byte arrays cannot. It is recommended that you use a Variant to pass strings as the most simple and flexible option. NOTE: You don't have to use the Callback2 function unless you return a Variant or large User-Defined Type as the function result. Using Variants and User-defined types as function arguments has no bearing on which DLL function to use in your Declare statement. Other Notes ----------- In many cases, you can get similar functionality completely in BASIC by using a SELECT CASE statement to call multiple implementations of the same prototype, or by using callback objects. The main area where the all-BASIC solution won't apply is using components that require calling back into your code and that need to call a function rather than an object. (c) Microsoft Corporation 1997. All Rights Reserved. Contributions by Malcolm Stewart, Microsoft Corporation (c) Microsoft Corporation 1997. All Rights Reserved. Contributions by Richard Ault, Microsoft Corporation Additional query words: kbVBp500 kbVBp600 kbVBp kbdsd kbDSupport kbNoKeyWord ====================================================================== Keywords : kbGrpDSVB Technology : kbVBSearch kbAudDeveloper kbZNotKeyword6 kbZNotKeyword2 kbVB500Search kbVB600Search kbVBA500Search kbVBA500 kbVBA600 kbVB500 kbVB600 kbZNotKeyword3 Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2001.