In this article

Implementing Callback Functions

10/17/2014

3 minutes to read

In this article

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

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.

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.

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

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.