Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

SetWindowsHookEx (user32)
 
.
Summary
Installs a hook to monitor certain types of events.

C# Signature:

/// <summary>
///     Installs an application-defined hook procedure into a hook chain. You would install a hook procedure to monitor the
///     system for certain types of events. These events are associated either with a specific thread or with all threads
///     in the same desktop as the calling thread.
///     <para>See https://msdn.microsoft.com/en-us/library/windows/desktop/ms644990%28v=vs.85%29.aspx for more information</para>
/// </summary>
/// <param name="hookType">
///     C++ ( idHook [in]. Type: int )<br />The type of hook procedure to be installed. This parameter can be one of the
///     following values.
///     <list type="table">
///     <listheader>
///         <term>Possible Hook Types</term>
///     </listheader>
///     <item>
///         <term>WH_CALLWNDPROC (4)</term>
///         <description>
///         Installs a hook procedure that monitors messages before the system sends them to the
///         destination window procedure. For more information, see the CallWndProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_CALLWNDPROCRET (12)</term>
///         <description>
///         Installs a hook procedure that monitors messages after they have been processed by the
///         destination window procedure. For more information, see the CallWndRetProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_CBT (5)</term>
///         <description>
///         Installs a hook procedure that receives notifications useful to a CBT application. For more
///         information, see the CBTProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_DEBUG (9)</term>
///         <description>
///         Installs a hook procedure useful for debugging other hook procedures. For more information,
///         see the DebugProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_FOREGROUNDIDLE (11)</term>
///         <description>
///         Installs a hook procedure that will be called when the application's foreground thread is
///         about to become idle. This hook is useful for performing low priority tasks during idle time. For more
///         information, see the ForegroundIdleProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_GETMESSAGE (3)</term>
///         <description>
///         Installs a hook procedure that monitors messages posted to a message queue. For more
///         information, see the GetMsgProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_JOURNALPLAYBACK (1)</term>
///         <description>
///         Installs a hook procedure that posts messages previously recorded by a WH_JOURNALRECORD hook
///         procedure. For more information, see the JournalPlaybackProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_JOURNALRECORD (0)</term>
///         <description>
///         Installs a hook procedure that records input messages posted to the system message queue. This
///         hook is useful for recording macros. For more information, see the JournalRecordProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_KEYBOARD (2)</term>
///         <description>
///         Installs a hook procedure that monitors keystroke messages. For more information, see the
///         KeyboardProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_KEYBOARD_LL (13)</term>
///         <description>
///         Installs a hook procedure that monitors low-level keyboard input events. For more information,
///         see the LowLevelKeyboardProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_MOUSE (7)</term>
///         <description>
///         Installs a hook procedure that monitors mouse messages. For more information, see the
///         MouseProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_MOUSE_LL (14)</term>
///         <description>
///         Installs a hook procedure that monitors low-level mouse input events. For more information,
///         see the LowLevelMouseProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_MSGFILTER (-1)</term>
///         <description>
///         Installs a hook procedure that monitors messages generated as a result of an input event in a
///         dialog box, message box, menu, or scroll bar. For more information, see the MessageProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_SHELL (10)</term>
///         <description>
///         Installs a hook procedure that receives notifications useful to shell applications. For more
///         information, see the ShellProc hook procedure.
///         </description>
///     </item>
///     <item>
///         <term>WH_SYSMSGFILTER (6)</term><description></description>
///     </item>
///     </list>
/// </param>
/// <param name="lpfn">
///     C++ ( lpfn [in]. Type: HOOKPROC )<br />A pointer to the hook procedure. If the dwThreadId parameter
///     is zero or specifies the identifier of a thread created by a different process, the lpfn parameter must point to a
///     hook procedure in a DLL. Otherwise, lpfn can point to a hook procedure in the code associated with the current
///     process.
/// </param>
/// <param name="hMod">
///     C++ ( hMod [in]. Type: HINSTANCE )<br />A handle to the DLL containing the hook procedure pointed to
///     by the lpfn parameter. The hMod parameter must be set to NULL if the dwThreadId parameter specifies a thread
///     created by the current process and if the hook procedure is within the code associated with the current process.
/// </param>
/// <param name="dwThreadId">
///     C++ ( dwThreadId [in]. Type: DWORD )<br />The identifier of the thread with which the hook
///     procedure is to be associated. For desktop apps, if this parameter is zero, the hook procedure is associated with
///     all existing threads running in the same desktop as the calling thread. For Windows Store apps, see the Remarks
///     section.
/// </param>
/// <returns>
///     C++ ( Type: HHOOK )<br />If the function succeeds, the return value is the handle to the hook procedure. If
///     the function fails, the return value is NULL.
///     <para>To get extended error information, call GetLastError.</para>
/// </returns>
/// <remarks>
///     <para>
///     SetWindowsHookEx can be used to inject a DLL into another process. A 32-bit DLL cannot be injected into a
///     64-bit process, and a 64-bit DLL cannot be injected into a 32-bit process. If an application requires the use
///     of hooks in other processes, it is required that a 32-bit application call SetWindowsHookEx to inject a 32-bit
///     DLL into 32-bit processes, and a 64-bit application call SetWindowsHookEx to inject a 64-bit DLL into 64-bit
///     processes. The 32-bit and 64-bit DLLs must have different names.
///     </para>
///     <para>
///     Because hooks run in the context of an application, they must match the "bitness" of the application. If a
///     32-bit application installs a global hook on 64-bit Windows, the 32-bit hook is injected into each 32-bit
///     process (the usual security boundaries apply). In a 64-bit process, the threads are still marked as "hooked."
///     However, because a 32-bit application must run the hook code, the system executes the hook in the hooking app's
///     context; specifically, on the thread that called SetWindowsHookEx. This means that the hooking application must
///     continue to pump messages or it might block the normal functioning of the 64-bit processes.
///     </para>
///     <para>
///     If a 64-bit application installs a global hook on 64-bit Windows, the 64-bit hook is injected into each
///     64-bit process, while all 32-bit processes use a callback to the hooking application.
///     </para>
///     <para>
///     To hook all applications on the desktop of a 64-bit Windows installation, install a 32-bit global hook and a
///     64-bit global hook, each from appropriate processes, and be sure to keep pumping messages in the hooking
///     application to avoid blocking normal functioning. If you already have a 32-bit global hooking application and
///     it doesn't need to run in each application's context, you may not need to create a 64-bit version.
///     </para>
///     <para>
///     An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the
///     identifier of a thread created by another process.
///     </para>
///     <para>
///     Calling the CallNextHookEx function to chain to the next hook procedure is optional, but it is highly
///     recommended; otherwise, other applications that have installed hooks will not receive hook notifications and
///     may behave incorrectly as a result. You should call CallNextHookEx unless you absolutely need to prevent the
///     notification from being seen by other applications.
///     </para>
///     <para>
///     Before terminating, an application must call the UnhookWindowsHookEx function to free system resources
///     associated with the hook.
///     </para>
///     <para>
///     The scope of a hook depends on the hook type. Some hooks can be set only with global scope; others can also
///     be set for only a specific thread, as shown in the following table.
///     </para>
///     <list type="table">
///     <listheader>
///         <term>Possible Hook Types</term>
///     </listheader>
///     <item>
///         <term>WH_CALLWNDPROC (4)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_CALLWNDPROCRET (12)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_CBT (5)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_DEBUG (9)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_FOREGROUNDIDLE (11)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_GETMESSAGE (3)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_JOURNALPLAYBACK (1)</term>
///         <description>Global only</description>
///     </item>
///     <item>
///         <term>WH_JOURNALRECORD (0)</term>
///         <description>Global only</description>
///     </item>
///     <item>
///         <term>WH_KEYBOARD (2)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_KEYBOARD_LL (13)</term>
///         <description>Global only</description>
///     </item>
///     <item>
///         <term>WH_MOUSE (7)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_MOUSE_LL (14)</term>
///         <description>Global only</description>
///     </item>
///     <item>
///         <term>WH_MSGFILTER (-1)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_SHELL (10)</term>
///         <description>Thread or global</description>
///     </item>
///     <item>
///         <term>WH_SYSMSGFILTER (6)</term>
///         <description>Global only</description>
///     </item>
///     </list>
///     <para>
///     For a specified hook type, thread hooks are called first, then global hooks. Be aware that the WH_MOUSE,
///     WH_KEYBOARD, WH_JOURNAL*, WH_SHELL, and low-level hooks can be called on the thread that installed the hook
///     rather than the thread processing the hook. For these hooks, it is possible that both the 32-bit and 64-bit
///     hooks will be called if a 32-bit hook is ahead of a 64-bit hook in the hook chain.
///     </para>
///     <para>
///     The global hooks are a shared resource, and installing one affects all applications in the same desktop as
///     the calling thread. All global hook functions must be in libraries. Global hooks should be restricted to
///     special-purpose applications or to use as a development aid during application debugging. Libraries that no
///     longer need a hook should remove its hook procedure.
///     </para>
///     <para>
///     Windows Store app development If dwThreadId is zero, then window hook DLLs are not loaded in-process for the
///     Windows Store app processes and the Windows Runtime broker process unless they are installed by either UIAccess
///     processes (accessibility tools). The notification is delivered on the installer's thread for these hooks:
///     </para>
///     <list type="bullet">
///     <item>
///         <term>WH_JOURNALPLAYBACK</term>
///     </item>
///     <item>
///         <term>WH_JOURNALRECORD </term>
///     </item>
///     <item>
///         <term>WH_KEYBOARD </term>
///     </item>
///     <item>
///         <term>WH_KEYBOARD_LL </term>
///     </item>
///     <item>
///         <term>WH_MOUSE </term>
///     </item>
///     <item>
///         <term>WH_MOUSE_LL </term>
///     </item>
///     </list>
///     <para>
///     This behavior is similar to what happens when there is an architecture mismatch between the hook DLL and the
///     target application process, for example, when the hook DLL is 32-bit and the application process 64-bit.
///     </para>
///     <para>
///     For an example, see Installing and
///     <see
///         cref="!:https://msdn.microsoft.com/en-us/library/windows/desktop/ms644960%28v=vs.85%29.aspx#installing_releasing">
///         Releasing
///         Hook Procedures.
///     </see>
///     [
///     https://msdn.microsoft.com/en-us/library/windows/desktop/ms644960%28v=vs.85%29.aspx#installing_releasing ]
///     </para>
/// </remarks>
[DllImport("user32.dll", SetLastError = true)]
static extern IntPtr SetWindowsHookEx(HookType hookType, HookProc lpfn, IntPtr hMod, uint dwThreadId);

VB.NET Signature:

<DllImport("user32.dll", SetLastError:=True)> _
Private Shared Function SetWindowsHookEx(ByVal hookType As HookType, ByVal lpfn As HookProc, ByVal hMod As IntPtr, ByVal dwThreadId As UInteger) As IntPtr
End Function

User-Defined Types:

A HookType constant specifying the type of hook to install. Used as the value passed into idHook.

A HookProc delegate representing the hook procedure method. Used as the value passed into lpfn (long pointer to function).

Notes:

This will enable you to install application hooks. However, you cannot implement global hooks in Microsoft .NET Framework except low level hooks. To install a global hook, a hook must have a native dynamic-link library (DLL) export to inject itself in another process that requires a valid, consistent function to call into. This requires a DLL export, which .NET Framework does not support. Managed code has no concept of a consistent value for a function pointer because these function pointers are proxies that are built dynamically.

AppDomain.GetCurrentThreadId is marked as deprecated in favour of Thread.ManagedThreadId but this will not to work with unmanaged API.

You can use the GetCurrentThreadId API as well:

To hook low level events use:

IntPtr hHook;

using (Process process = Process.GetCurrentProcess())
using (ProcessModule module = process.MainModule)
{
    IntPtr hModule = GetModuleHandle(module.ModuleName);

    hHook = SetWindowsHookEx(HookType.WH_KEYBOARD_LL, hook, hModule, 0);
}

Tips & Tricks:

Remember to keep the HookProc delegate alive manually, such as using a class member as shown in the example below, otherwise the garbage collector will clean up your hook delegate eventually, resulting in your code throwing a System.NullReferenceException.

Remember to call CallNextHookEx in your callback delegate.

Remember to call UnhookWindowsHookEx using the handle returned by SetWindowsHookEx

Note how you can import the same function several times with different overloaded signatures to handle the common case where one parameter is an opaque pointer pointing to a struct that depends on another parameter.

Sample Code:

// this sample installs a keyboard hook

using System.Windows.Forms;
public class MyClass
{
     private HookProc myCallbackDelegate = null;

     public MyClass()
     {
     // initialize our delegate
     this.myCallbackDelegate = new HookProc(this.MyCallbackFunction);

     // setup a keyboard hook
     SetWindowsHookEx(HookType.WH_KEYBOARD, this.myCallbackDelegate, IntPtr.Zero, AppDomain.GetCurrentThreadId());
     }

     [DllImport("user32.dll")]
     protected static extern IntPtr SetWindowsHookEx(HookType code, HookProc func, IntPtr hInstance, int threadID);

     [DllImport("user32.dll")]
     static extern int CallNextHookEx(IntPtr hhk, int nCode, IntPtr wParam, IntPtr lParam);

     private int MyCallbackFunction(int code, IntPtr wParam, IntPtr lParam)
     {
    if (code < 0) {
        //you need to call CallNextHookEx without further processing
        //and return the value returned by CallNextHookEx
        return CallNextHookEx(IntPtr.Zero, code, wParam, lParam);
    }
     // we can convert the 2nd parameter (the key code) to a System.Windows.Forms.Keys enum constant
     Keys keyPressed = (Keys)wParam.ToInt32();
     Console.WriteLine(keyPressed);
    //return the value returned by CallNextHookEx
    return CallNextHookEx(IntPtr.Zero, code, wParam, lParam);
     }
}

VB.NET:

' My sample installs a keyboard hook
Imports System.Windows.Forms
Imports System.Runtime.InteropServices

Public Class MyClass1
    Delegate Function HookProc(ByVal code As Integer, ByVal wParam As IntPtr, ByVal lParam As IntPtr) As Integer

    Private myCallbackDelegate As HookProc = Nothing

    Public Sub New()
    ' initialize our delegate
    Me.myCallbackDelegate = New HookProc(AddressOf Me.MyCallbackFunction)

    ' setup a keyboard hook
    SetWindowsHookEx(HookType.WH_KEYBOARD, Me.myCallbackDelegate, IntPtr.Zero, AppDomain.GetCurrentThreadId())
    End Sub

    <DllImport("user32.dll")> _
    Friend Shared Function SetWindowsHookEx(ByVal idHook As Integer, ByVal lpfn As HookProc, ByVal hInstance As IntPtr, ByVal threadId As Integer) As Integer
    End Function

    <DllImport("user32.dll")> _
    Friend Shared Function CallNextHookEx(ByVal hhk As intptr, ByVal nCode As Integer, ByVal wParam As intptr, ByVal lParam As intptr) As Integer
    End Function

    Private Function MyCallbackFunction(ByVal code As Integer, ByVal wParam As intptr, ByVal lParam As intptr) As Integer
    If (code < 0) Then
        'you need to call CallNextHookEx without further processing
        'and return the value returned by CallNextHookEx
        Return CallNextHookEx(IntPtr.Zero, code, wParam, lParam)    'unt
    End If
    ' we can convert the 2nd parameter (the key code) to a System.Windows.Forms.Keys enum constant
    Dim keyPressed As Keys = CType(wParam.ToInt32, Keys)
    Console.WriteLine(keyPressed)
    'return the value returned by CallNextHookEx
    Return CallNextHookEx(IntPtr.Zero, code, wParam, lParam)
    End Function
End Class

Alternative Managed API:

The ManagedWindowsApi project (http://mwinapi.sourceforge.net) provides a Hook class and subclasses for Journal hooks, Message hooks and Low-Level hooks.

Documentation

SetWindowsHookEx on MSDN

MSDN example of a mouse hook in C#: http://support.microsoft.com/default.aspx?scid=kb;en-us;318804#3

MSDN article on hooks in .NET: http://msdn.microsoft.com/msdnmag/issues/02/10/CuttingEdge/

MSDN article on KeyboardProc: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/windowsuserinterface/windowing/hooks/hookreference/hookfunctions/keyboardproc.asp

Stephen Toub entry on low-level keyboard hook in C#: http://blogs.msdn.com/toub/archive/2006/05/03/589423.aspx

Stephen Toub entry on low-level mouse hook on C#: http://blogs.msdn.com/toub/archive/2006/05/03/589468.aspx

.

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions