Implementing Callback Functions

A callback function is code within a managed application that helps an unmanaged DLL function complete a task. Calls to a callback function pass indirectly from a managed application, through a DLL function, and back to the managed implementation. Some of the many DLL functions called with platform invoke require a callback function in managed code to run properly. This topic describes the elements of a callback function, and how to implement and call one from managed code.

Callback Function Basics

To call most DLL functions from managed code, you create a managed definition of the function and then call it. The process is straightforward.

Using a DLL function that requires a callback function has some additional steps. First, you must determine whether the function requires a callback by looking at the documentation for the function. Next, you have to create the callback function in your managed application. Finally, you call the DLL function, passing a pointer to the callback function as an argument. The following illustration summarizes these steps.

Callback function and implementation

Callback functions are ideal for use in situations in which a task is performed repeatedly. Another common usage is with enumeration functions, such as EnumFontFamilies, EnumPrinters, and EnumWindows in the Win32 API. As the example in the next section demonstrates, the EnumWindows function enumerates through all existing windows on your computer, calling the callback function to perform a task on each window.

Implementing a Callback Function

The following process demonstrates how a managed application, using platform invoke, can print the handle value for each window on the local computer. Specifically, the example uses the EnumWindows function to step through the list of windows and a managed callback function (named CallBack) to print the value of the window handle.

To implement a Callback function

1. Look at the signature for the EnumWindows function before going further with the implementation. EnumWindows has the following signature:

   BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam)
   

   One clue that this function requires a callback is the presence of the lpEnumFunc argument. It is common to see the lp (long pointer) prefix combined with the Func suffix in the name of arguments that take a pointer to a callback function. For documentation about Win32 functions, see the Microsoft Platform SDK.

2. Create the managed callback function. The example declares a delegate type, called CallBack, which takes two arguments (hwnd and lparam). The first argument is a handle to the window; the second argument is application-defined. In this release, both arguments must be integers.

   Callback functions generally return nonzero values to indicate success and zero to indicate failure. This example explicitly sets the return value to true to continue the enumeration.

3. Create a delegate and pass it as an argument to the EnumWindows function. Platform invoke converts the delegate to a familiar callback format automatically.

4. Ensure that the garbage collector does not reclaim the delegate before the callback function completes its work. When you pass a delegate as a parameter, or pass a delegate contained as a field in a structure, it remains uncollected for the duration of the call. So, as is the case in the following enumeration example, the callback function completes its work before the call returns and requires no additional action by the managed caller.

   If, however, the callback function can be invoked after the call returns, the managed caller must take steps to ensure that the delegate remains uncollected until the callback function finishes. For detailed information about preventing garbage collection, see Interop Marshaling with Platform Invoke.

Example

Imports System
Imports System.Runtime.InteropServices

Public Delegate Function CallBack( _
hwnd As Integer, lParam As Integer) As Boolean

Public Class EnumReportApp

    Declare Function EnumWindows Lib "user32" ( _
       x As CallBack, y As Integer) As Integer

    Public Shared Sub Main()
        EnumWindows(AddressOf EnumReportApp.Report, 0)
    End Sub 'Main

    Public Shared Function Report(hwnd As Integer, lParam As Integer) _
    As Boolean
        Console.Write("Window handle is ")
        Console.WriteLine(hwnd)
        Return True
    End Function 'Report
End Class 'EnumReportApp
[C#]
using System;
using System.Runtime.InteropServices;

public delegate bool CallBack(int hwnd, int lParam);

public class EnumReportApp {

    [DllImport("user32")]
    public static extern int EnumWindows(CallBack x, int y); 

    public static void Main() 
    {
        CallBack myCallBack = new CallBack(EnumReportApp.Report);
        EnumWindows(myCallBack, 0);
    }

   public static bool Report(int hwnd, int lParam) { 
        Console.Write("Window handle is ");
        Console.WriteLine(hwnd);
        return true;
    }
}
[C++]
using namespace System::Runtime::InteropServices;

// A delegate type.
__delegate bool CallBack(int hwnd, int lParam);

// Managed type with the method to call.
__gc class EnumReport 
{
// Report the window handle.
public:
    bool Report(int hwnd, int lParam) {
       Console::Write(L"Window handle is ");
       Console::WriteLine(hwnd);
       return true;
   }
};

[DllImport("user32")] 
extern "C" int EnumWindows(CallBack* x, int y); 

void main(void) { 
    EnumReport* er = new EnumReport;
    CallBack* myCallBack = new CallBack(er, &EnumReport::Report);
    EnumWindows(myCallBack, 0); 
}

See Also

Calling a DLL Function