IEnumExplorerCommand::Next return values

Question

IEnumExplorerCommand::Next return values

Kai 6

Hello,

I want to implement the IEnumExplorerCommand interface to provide a custom entry in the explorer context menu.
Sccording to the documentation IEnumExplorerCommand::Next returns S_OK if the method returns, regardless of whether the specified number of elements could be fetched or not.
Other IEnum*::Next methods return S_OK only if the full count of requested items are successfully retrieved, and S_FALSE if more items were requested than remained in the enumeration.
Shouldn't this also be the case for IEnumExplorerCommand ?

Xiaopo Yang - MSFT 12,736 Reputation points Microsoft External Staff

2022-03-21T01:39:35.673+00:00

Is that really necessary? Even IEnumExplorerCommand::Skip is Not currently implemented.
Kai 6 Reputation points

2022-03-21T18:19:06.553+00:00

Sorry, I don't understand the question.
What exactly do you think is not necessary?
Xiaopo Yang - MSFT 12,736 Reputation points Microsoft External Staff

2022-03-22T01:12:15.307+00:00

IEnumExplorerCommand::Next returns S_OK only if the full count of requested items are successfully retrieved, and S_FALSE if more items were requested than remained in the enumeration that is not necessary otherwise similarly IEnumExplorerCommand::Skip needs to Skips the specified number of elements in the enumeration sequence. Perhaps you need to implement the interface.
Kai 6 Reputation points

2022-03-22T10:02:19.17+00:00

Thanks, that's what I thought, too.
But that should also be stated in the documentation, right?

1 answer

Your answer

Xiaopo Yang - MSFT 12,736 Reputation points Microsoft External Staff

2022-03-21T01:39:35.673+00:00

Is that really necessary? Even IEnumExplorerCommand::Skip is Not currently implemented.
Kai 6 Reputation points

2022-03-21T18:19:06.553+00:00

Sorry, I don't understand the question.
What exactly do you think is not necessary?
Xiaopo Yang - MSFT 12,736 Reputation points Microsoft External Staff

2022-03-22T01:12:15.307+00:00

IEnumExplorerCommand::Next returns S_OK only if the full count of requested items are successfully retrieved, and S_FALSE if more items were requested than remained in the enumeration that is not necessary otherwise similarly IEnumExplorerCommand::Skip needs to Skips the specified number of elements in the enumeration sequence. Perhaps you need to implement the interface.
Kai 6 Reputation points

2022-03-22T10:02:19.17+00:00

Thanks, that's what I thought, too.
But that should also be stated in the documentation, right?

Answer 1

RLWA32 52,571

Although it is a common pattern for an enumerator to return S_FALSE it is not a requirement. There are other instances besides IEnumExplorerCommand (e.g., IEnumAssocHandlers, IEnumResources) that are documented to deviate from the pattern.

Kai 6 Reputation points

2022-03-21T18:12:41.197+00:00

Thank you for your response!

So does that mean that IEnumExplorerCommand::Next should return an error ( E_FAIL ?) in case the enumeration is exhausted?
RLWA32 52,571 Reputation points

2022-03-21T18:30:01.497+00:00

I don't know what the interface method would return in that situation. Don't forget that S_FALSE is a success code. Even if the method did return S_OK I presume you could check the value used to indicate the number of items returned.
Kai 6 Reputation points

2022-03-22T00:23:36.02+00:00

Sorry, I realize I didn't make that clear, but I actually want to implement the interface myself and therefore need to know what behavior the explorer expects.
RLWA32 52,571 Reputation points

2022-03-22T00:35:59.12+00:00

There is a sample implementation of IEnumExplorerCommand at https://github.com/microsoft/Windows-classic-samples/blob/main/Samples/Win7Samples/winui/shell/shellextensibility/explorerdataprovider/FVCommands.cpp.
Kai 6 Reputation points

2022-03-22T09:57:49.627+00:00

Thanks, that example is very helpful!
But if I understand correctly, Next indeed returns S_FALSE if the enumeration is exhausted, wouldn't that mean that the documentation (or the sample) is incorrect?
RLWA32 52,571 Reputation points

2022-03-22T10:19:50.9+00:00

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Well, this isn't the first time that Microsoft documentation has been confusing to say the least. You might also say that the documentation is incomplete since it completely ignores the result of returning fewer items than requested. Another possibility is that the sample code is not compliant. Only Microsoft knows for sure.

In any event, your implementation can test the consequences of returning S_OK instead of S_FALSE. Again, neither of these are considered errors.
Xiaopo Yang - MSFT 12,736 Reputation points Microsoft External Staff

2022-04-01T07:28:44.093+00:00

@Kai Any updates about this?
Kai 6 Reputation points

2022-04-01T23:40:56.863+00:00

Yes, using the S_FALSE return code seems to work correctly, while S_OK crashes the explorer.

Thanks again for your help!
RLWA32 52,571 Reputation points

2022-04-01T23:54:06.057+00:00

All things considered, a bug report should probably be filed against the documentation.

Share via

IEnumExplorerCommand::Next return values

1 answer

Your answer