CreateTimerQueueTimer arguments differs from WinAPI

Question

I was reading a man page about CreateTimerQueueTimer.

BOOL CreateTimerQueueTimer(
  PHANDLE             phNewTimer,
  HANDLE              TimerQueue,
  WAITORTIMERCALLBACK Callback,
  PVOID               DueTime,
  DWORD               Period,
  DWORD               Flags,
  ULONG               Parameter
);

The doc states:

Period

The period of the timer, in milliseconds. If this parameter is zero, the timer is signaled once.

So I needed to set this to 0 to avoid the callback to be executed periodically. The problem was that modifying the period value has no effect on periodicity. Once loaded in OllyDBG, Olly reconstructed the arguments and the call giving me this function signature :

BOOL CreateTimerQueueTimer(
 PHANDLE             phNewTimer,
 HANDLE              TimerQueue,
 WAITORTIMERCALLBACK Callback,
 ULONG               Parameter,
 PVOID               DueTime,
 DWORD               Period,
 DWORD               Flags
);

Notice that the parameter argument changed position, and thus all my patches was useless. I guess this error might be due to an old version of the API where the Parameter argument was in 4th position, but I can be wrong. Also, I can't find old WinAPIs to confirm my sayings. Am I guessing right or am I missing something?

Answer 1

Yep, I think I've seen a similar case before. It happens very rarely, but because you can do some stunts at the C preprocessor level as well as at the linker level, this happens to work.

In this case I looked it up in the 3790.1830 DDK (Windows 2003 Server) and several newer WDKs and SDKs.

Windows 2000/XP target (3790.1830/inc/w2k/winbase.h and 3790.1830/inc/wxp/winbase.h)

WINBASEAPI
BOOL
WINAPI
CreateTimerQueueTimer(
    PHANDLE phNewTimer,
    HANDLE TimerQueue,
    WAITORTIMERCALLBACK Callback,
    PVOID Parameter,
    DWORD DueTime,
    DWORD Period,
    ULONG Flags
    ) ;  

Windows 2003/Vista/7 target (3790.1830/inc/wnet/winbase.h and 6001.18002/inc/api/WINBASE.H and 7600.16385.1/inc/api/WINBASE.H)

WINBASEAPI
BOOL
WINAPI
CreateTimerQueueTimer(                                                                                                                                                                                             
    __deref_out PHANDLE phNewTimer,
    __in_opt    HANDLE TimerQueue,
    __in        WAITORTIMERCALLBACK Callback,
    __in_opt    PVOID Parameter,
    __in        DWORD DueTime,
    __in        DWORD Period,
    __in        ULONG Flags 
    ) ;   

With the Windows 8.1 SDK ...

... this API moved into another header: Include/um/threadpoollegacyapiset.h (check out this study on API sets).

WINBASEAPI
BOOL
WINAPI
CreateTimerQueueTimer(
    _Outptr_ PHANDLE phNewTimer,
    _In_opt_ HANDLE TimerQueue,
    _In_ WAITORTIMERCALLBACK Callback,
    _In_opt_ PVOID Parameter,
    _In_ DWORD DueTime,
    _In_ DWORD Period,
    _In_ ULONG Flags
    );  

... so no change up until this point (other than adopting SAL2 annotations).

For the Windows 10 SDKs 10.0.10240.0, 10.0.16299.0, 10.0.17134.0, 10.0.17134.0, 10.0.17763.0, 10.0.18362.0 it still has the same order for the arguments as for Windows 8.1. So it stands to reason you ran into a documentation issue rather than an actual change here.

There is no pending or old (and closed) pull request mentioning this function, so you may want to consider sending one.