Everything3 SDK: undocumented "unavailable" sentinel values for property getters (e.g. Everything3_GetResultRunCount)

[avi]

Hi, thanks for the great work on the 1.5 SDK — the pipe-based API is a big improvement.

I ran into (indirectly, via a downstream client — Flow Launcher's Explorer plugin) an issue that seems to stem from a documentation gap rather than a functional bug.

The legacy `Everything_GetResultRunCount` function (1.4 SDK) is clearly documented: "The function returns 0 if the run count information is unavailable" (https://www.voidtools.com/support/every ... truncount/).

The new `Everything3_GetResultRunCount` function (1.5 SDK) appears to behave differently: when the run-count property is unavailable for a result, it seems to return a MAX sentinel value (e.g. `UINT32_MAX`/`0xFFFFFFFF`) instead of `0`. I found this confirmed indirectly in another project's (EverythingToolbar) source code, which explicitly checks for `EVERYTHING3_UINT64_MAX` when reading a 64-bit property and resets it to 0 — implying the same MAX-sentinel pattern applies across the new property-based API.

This difference from the documented 1.4 behavior isn't mentioned anywhere I could find in the 1.5 SDK docs/forum thread (viewtopic.php?t=15853), and at least one client (Flow Launcher) didn't account for it, causing a crash (`OverflowException` when naively converting the returned `uint` to a smaller signed type) rather than a graceful "no data" result.

Would it be possible to:
1. Document explicitly, for each `Everything3_Get*` property getter, what "unavailable" looks like (e.g. "returns UINT32_MAX for DWORD properties, UINT64_MAX for 64-bit properties" or similar)?
2. Optionally, expose a small helper (e.g. `Everything3_IsPropertyValueValid(...)`) so client authors don't need to know the exact sentinel per property type?

Thanks again!

[void]

Thank you for your feedback avi,

The run count is never unknown.
Everything3_GetResultRunCount returns 0 if the run count is not set.
Everything3_GetResultRunCount returns DWORD_MAX if an error occurs or if the run count is DWORD_MAX. To get extended error information, call Everything3_GetLastError. If the property value is really DWORD_MAX, Everything3_GetLastError returns 0.

What is the value from Everything3_GetLastError when Everything3_GetResultRunCount returns UINT32_MAX?
EVERYTHING3_ERROR_INVALID_PARAMETER = Please double check the result index is in range when calling Everything3_GetResultRunCount.
EVERYTHING3_ERROR_PROPERTY_NOT_FOUND = Please make sure you request the run count property before calling Everything3_Search with:

Everything3_AddSearchPropertyRequest(search_state,EVERYTHING3_PROPERTY_ID_RUN_COUNT);

1. Document explicitly, for each `Everything3_Get*` property getter, what "unavailable" looks like (e.g. "returns UINT32_MAX for DWORD properties, UINT64_MAX for 64-bit properties" or similar)?

I have updated the documentation.
However, run count is never "unknown" or "unavailable".

2. Optionally, expose a small helper (e.g. `Everything3_IsPropertyValueValid(...)`) so client authors don't need to know the exact sentinel per property type?

I will consider a

BOOL Everything3_IsResultPropertyValueValid(EVERYTHING3_RESULT_LIST *result_list,SIZE_T result_index,DWORD property_id)

function.
Thank you for the suggestion.

[avi]

Thank you very much for the detailed and clear explanation — this makes complete sense now.

Following your explanation, I went back and checked the Flow Launcher source code, and confirmed the exact issue: the run count property is only conditionally requested via Everything3_AddSearchPropertyRequest (only when a specific "run counter" setting is enabled), but the result-parsing code unconditionally tries to read Everything3_GetResultRunCount for every result regardless — without checking Everything3_GetLastError. So exactly as you described: EVERYTHING3_ERROR_PROPERTY_NOT_FOUND was the real cause.

I've reported this back to the Flow Launcher developers with these specifics https://github.com/Flow-Launcher/Flow.L ... ssues/4603, so this should get fixed on their end. Thanks again for taking the time to dig into this, and for updating the documentation — much appreciated!