Confusions about LARGE_INTEGER

[baier233]

When declaring a native Windows function like SetFilePointerEx, where the second parameter (liDistanceToMove) is an input value typically passed by value in native C/C++:

// Example native function declaration
// liDistanceToMove is the distance to move the file pointer, intended to be passed BY VALUE.
public native boolean SetFilePointerEx(
    HANDLE hFile,
    LARGE_INTEGER liDistanceToMove, // <--- THE PROBLEM IS HERE
    ULONG_PTRByReference lpNewFilePointer,
    int dwMoveMethod
);

I did not think much of it and simply used the base LARGE_INTEGER class for the input parameter. I immediately found that it was incorrectly passed as reference (or address) to the native side!

I am confused about why LARGE_INTEGER, a very common 8-byte structure in Windows APIs, was designed without a corresponding ByValue class. On many calling conventions, small structures like this are passed by value.

Below are my points of view about this issue.

1. Given that this structure is frequently used as a pass-by-value input parameter (as in SetFilePointerEx), why not just adding a static nested ByValue class to LARGE_INTEGER (e.g., LARGE_INTEGER.ByValue)?

2. Since LARGE_INTEGER is semantically equivalent to a 64-bit number, and is designed to represent a single value, how about considering treating it as a numerical type instead of a standard Structure?

[JaredDavis22]

Does long work instead of LARGE_INTEGER?

public native boolean SetFilePointerEx(
HANDLE hFile,
long liDistanceToMove,
ULONG_PTRByReference lpNewFilePointer,
int dwMoveMethod
);

?

[baier233]

Does long work instead of LARGE_INTEGER?

public native boolean SetFilePointerEx( HANDLE hFile, long liDistanceToMove, ULONG_PTRByReference lpNewFilePointer, int dwMoveMethod );

?

I think it dose work(I used UINT_PTR instead). But my purpose of raising this issue is to point out the misleading aspects of LARGE_INTEGER.

[matthiasblaesing]

Adding a LARGE_INTEGER.ByValue subclass would be a compatible and thus doable change. Modifying the implementation of LARGE_INTEGER would break existing uses.

[baier233]

Adding a LARGE_INTEGER.ByValue subclass would be a compatible and thus doable change. Modifying the implementation of LARGE_INTEGER would break existing uses.

I've opened PR #1696 to address this issue. Please take a look.

[matthiasblaesing]

Fixed via #1696