api: change RetrieveProperties to collect results in batches

[dougm]

'RetrieveProperties' is deprecated since 4.1
Use RetrievePropertiesEx + ContinueRetrievePropertiesEx to collect in batches.

[akutz]

The code looks good, but there is no coverage for the change. I will create a test that covers the new code and open a PR against this PR branch.

[akutz]

I opened dougm#2 against this PR to pull in some tests. I will also be honest, one thing has me worried, the documentation around RetrievePropertiesEx's MaxObjects field:

The maximum number of ObjectContent data objects that should be returned in a single result from RetrievePropertiesEx.

An unset value indicates that there is no maximum. In this case PropertyCollector policy may still limit the number of objects. Any remaining objects may be retrieved with ContinueRetrievePropertiesEx.

A positive value causes RetrievePropertiesEx to suspend the retrieval when the count of objects reaches the specified maximum. PropertyCollector policy may still limit the count to something less than maxObjects. Any remaining objects may be retrieved with ContinueRetrievePropertiesEx.

A value less than or equal to 0 is illegal.

Specifically the last line -- A value less than or equal to 0 is illegal. I checked, and neither the options property for RetrievePropertiesEx is nillable, nor is the maxObjects property for the RetrieveOptions struct. Will those notes mean that a zero value is always sent over the wire if no non-empty value is specified?

[akutz]

Lgtm, thanks @dougm !