activex.pp DosDateTimeToVariantTime definition problem

[440bx]

Hello,

in activex.pp, DosDateTimeToVariantTime is defined as:

Code: Pascal  [Select][+][-]

1. function DosDateTimeToVariantTime( wDosDate: ushort; wDosTime:ushort;pvtime:pdouble):longint; stdcall; external oleaut32dll name 'DosDateTimeToVariantTime';
2.  

Note the result type of "longint".  This result type is incorrect.

The documentation page:
https://learn.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-dosdatetimetovarianttime

shows the function definition to be:

Code: C  [Select][+][-]

1. INT DosDateTimeToVariantTime(
2.   [in]  USHORT wDosDate,
3.   [in]  USHORT wDosTime,
4.   [out] DOUBLE *pvtime
5. );
6.  

which is also incorrect.

The same page describes the return value:

The function returns TRUE on success and FALSE otherwise.

That's a BOOL (or possibly boolean), not an INT.

To determine which one is correct, inspection of the function's dis-assembly (partial) shows the following:

Code: ASM  [Select][+][-]

1. .text:100169DF                 call    _ErrPackDate@20 ; ErrPackDate(x,x,x,x,x)
2. .text:100169E4                 test    eax, eax
3. .text:100169E6                 jnz     short loc_100169FF
4. .text:100169E8                 fld     [ebp+var_24]
5. .text:100169EB                 inc     eax
6. .text:100169EC                 fstp    qword ptr [ebx]
7. .text:100169EE
8. .text:100169EE loc_100169EE:                           ; CODE XREF: DosDateTimeToVariantTime(x,x,x)+D1↓j
9. .text:100169EE                 mov     ecx, [ebp+var_4]
10. .text:100169F1                 pop     edi
11. .text:100169F2                 pop     esi
12. .text:100169F3                 xor     ecx, ebp        ; StackCookie
13. .text:100169F5                 pop     ebx
14. .text:100169F6                 call    @__security_check_cookie@4 ; __security_check_cookie(x)
15. .text:100169FB                 leave
16. .text:100169FC                 retn    0Ch
17. .text:100169FF ; ---------------------------------------------------------------------------
18. .text:100169FF
19. .text:100169FF loc_100169FF:                           ; CODE XREF: DosDateTimeToVariantTime(x,x,x)+74↑j
20. .text:100169FF                                         ; DosDateTimeToVariantTime(x,x,x)+84↑j ...
21. .text:100169FF                 xor     eax, eax
22. .text:10016A01                 jmp     short loc_100169EE
23. .text:10016A01 _DosDateTimeToVariantTime@12 endp
24. .text:10016A01
25.  

The dis-assembly clearly shows that the function returns 1 when successful and 0 upon failure, this fits a BOOL.

As currently defined, there is room for the result to be misinterpreted depending on how the comparison is done against the "supposed int".

HTH.

[Thaddy]

This stems (both issues) from C(++) compilers interpreting false as zero and anything else a valid true.
Predates compilers with _Bool. As such it was correct at the time as BOOL (Uppercase and without underscore) was a type macro over longint.

[ASerge]

The documentation page: ...
...which is also incorrect.

This is the official documentation, so we need to rely on it, despite the current implementation.
And it's not that hard, instead

Code: Pascal  [Select][+][-]

1. if DosDateTimeToVariantTime(...) then

write it as

Code: Pascal  [Select][+][-]

1. if DosDateTimeToVariantTime(...) <> 0 then

[440bx]

Official or otherwise, it's incorrect.

A longint does not have the semantic properties of a boolean.

In addition to that, the documentation contradicts itself.  In one place it shows the return value as being an int and then it states it is a boolean.

Look at the code to figure out which one is right and boolean is right, int is incorrect and leaves room for an improper comparison that would yield incorrect results.

[PascalDragon]

The documentation page:
https://learn.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-dosdatetimetovarianttime

shows the function definition to be:

Code: C  [Select][+][-]

1. INT DosDateTimeToVariantTime(
2.   [in]  USHORT wDosDate,
3.   [in]  USHORT wDosTime,
4.   [out] DOUBLE *pvtime
5. );
6.  

which is also incorrect.

The actual header OleAuto.h (not the documentation) nevertheless declares it as INT, not as BOOL. It doesn't matter whether the return values are provided using the TRUE and FALSE macros inside DosDateTimeToVariantTime (and its inverse), the decaration is nevertheless INT.

Yes, that could be misinterpreted, but one is supposed to use MSDN when working with the Windows API anyway.

[440bx]

I know all that. 

The header is incorrect. 

An int type isn't a two value type.

Yes, that could be misinterpreted, but one is supposed to use MSDN when working with the Windows API anyway.

In general I completely agree with that _except_ when the stuff is wrong.  Having correct definition is more important than header files and/or msdn.

[nanobit]

In Windows SDK, uppercase FALSE (0), TRUE (1) are integer-constants.

[PascalDragon]

The header is incorrect.

The header files are the official source for the Windows API, not a disassembly of the binary and its the official headers that the API translations are based on.

[440bx]

The header files are the official source for the Windows API, not a disassembly of the binary and its the official headers that the API translations are based on.

In that case Astronomers and Paleontologists should read the bible to get the "official" (not to mention _sacred_) information about Earth's place in the universe and the origin of the species.

Just for fun... here is another definition that, at least in Pascal, is incorrect:

Code: Pascal  [Select][+][-]

1. function ListView_GetItemIndexRect(hwnd:hwnd; plvii:PLVITEMINDEX; iSubItem:clong; code:clong; prc:LPRECT) :BOOL;
2.  

It's incorrect because it is a faithful translation of the C macro.

The documentation defines the macro as:

Code: C  [Select][+][-]

1. BOOL ListView_GetItemIndexRect(
2.   [in]      HWND        hwnd,
3.   [in]      LVITEMINDEX *plvii,
4.   [in]      LONG        iSubItem,
5.   [in]      LONG        code,
6.   [in, out] LPRECT      prc
7. );
8.  

and states the following about the last parameter "prc"

[in, out] prc

Type: LPRECT

A pointer to a RECT structure to receive the coordinates. The caller is responsible for allocating this structure. prc must not be NULL.

Emphasis mine.  It "kinda" makes sense for the last parameter not to be NULL/nil given that the purpose of the macro/function is to retrieve the rectangle values (it would be "difficult" to get the rect if passing nil as the place to store it.)

The C definition is "correct" because C does not have the means to enforce the condition that the parameter must not be nil but, Pascal does.  The Pascal definition is incorrect, it should specify "var" for the last parameter.

Official, sacred... etc, don't make things right.

[marcov]

Commctrls was semi automated translated with various bits of Pascal code back then.

Anyway, I fully agree with PascalDragon.

And in this particular case, while it might be semantically closer, it breaks 1:1 converting existing (example) code.

[440bx]

It's quite obvious that most of the API definitions were automatically generated to some extent, e.g, the use of MS disturbingly poor parameter names.  That's very obvious because there is no attempt whatsoever to cleanup MS' definition mess, e.g, close to a dozen superfluous type names for the same data type and, type names that have no business existing in Pascal, e.g, tagSomeName.

It really makes no sense to protect mistakes and gross deficiencies.  Definitions that are incorrect should be corrected.  Things should be improved. 

If making it correct breaks some code then that code should be corrected too.

Another case like that is WriteFile, the current definition is incorrect but, I know that's another one that is not going to change and, _all_ the definitions that use untyped parameters are semantically incorrect because there is no such thing nor equivalent in C nor C++.  I'm not the only programmer who has written perfectly good code that ended up causing access violations because of those incorrect definitions (which are unfortunately here to stay.)

I know, this situation isn't going to change.  Somehow some mistakes are sacred and must be preserved. 

Anyway, I'll keep reporting the mistakes as a courtesy.  I have to admit that I'm still not used to seeing mistakes defended and preserved.