WinAPI令人困惑的函数参数

Question

The API reference for the function in question: RmStartSession .

The code:

#include <Windows.h>
#include <RestartManager.h>

/*
DWORD WINAPI
RmStartSession(
    _Out_ DWORD *pSessionHandle,
    _Reserved_ DWORD dwSessionFlags,
    _Out_writes_(CCH_RM_SESSION_KEY + 1) WCHAR strSessionKey[]);
*/

int main(int /*argc*/, char** /*argv*/)
{
    WCHAR sessionKey[CCH_RM_SESSION_KEY + 1];

    // 1.
    DWORD *sessionOne = nullptr;
    auto returnCodeOne = RmStartSession(sessionOne, NULL, sessionKey); // = 160 ERROR_BAD_ARGUMENTS

    // 2.
    DWORD sessionTwo = 0xFFFFFFF;
    DWORD *pSessionHandleTwo = &sessionTwo;
    auto returnCodeTwo = RmStartSession(pSessionHandleTwo, NULL, sessionKey); // = 0 ERROR_SUCCESS

    // 3.
    DWORD sessionThree = 0xFFFFFFF;
    auto returnCodeThree = RmStartSession(&sessionThree, NULL, sessionKey); // = 0 ERROR_SUCCESS

    return 0;
}  

Took me a while to realize why 1. was giving me a BAD_ARGUMENTS error, since all of the variations above compiled fine and were legit language constructs.

The problem is that the function actually needs a pointer to a valid object and just uses that pointer to modify the object, does not modify the pointer itself. So if the pointer is nullptr then there's no object to modify, the function does not allocate an object itself.
(Please correct me if my understanding above is wrong)

That being said, why wasn't the function defined to request a reference to a DWORD to make it clear that it cannot be null, is there a specific reason to use a pointer here?
What am I missing?

Answer 1

There are two answers to this question:

1. This is a C api, so references were not available to the API writers.

2. There is a school of thoughts that using references for output value parameters is bad API design, and pointers should always be used, even if it means that passing a nullptr would be a disaster.

The idea is that reference-based output parameters are really confusing at the call site. Look at the following code:

void foo() {
   my_struct val;
   bar(val);
}

void foo_alt() {
   my_struct val;
   bar_alt(&val);
}

At first glance, one would not expect bar to modify val in the first example, but one would suspect it in the second.

Understanding what a function does by only looking at the call site is fundamental to self-documenting code, and mutable references often break that (unless it's really clear in the function name).