IVssEnumObject::Next method (vss.h)

Article
02/22/2024

The Next method returns the specified number of objects from the specified list of enumerated objects.

Syntax

HRESULT Next(
  [in]  ULONG           celt,
  [out] VSS_OBJECT_PROP *rgelt,
  [out] ULONG           *pceltFetched
);

Parameters

[in] celt

The number of elements to be read from the list of enumerated objects into the rgelt buffer.

[out] rgelt

The address of a caller-allocated buffer that receives celtVSS_OBJECT_PROP structures that contain the returned objects. This parameter is required and cannot be NULL.

[out] pceltFetched

The number of elements that were returned in the rgelt buffer.

Return value

The following are the valid return codes for this method.

Value	Meaning
S_OK	The operation was successful.
S_FALSE	The number of returned items is less than the number requested.
E_FAIL	There is an internal error in the enumerator.
E_POINTER	One of the required pointer parameters is NULL.

Remarks

When requesting the return of more than one VSS_OBJECT_PROP object, a return value of S_FALSE indicates that the end of the enumeration list has been reached. If more objects were requested than remained in the list, Next will return all the remaining objects, set the pceltFetched parameter to a nonzero value, and return S_FALSE.

The output rgelt parameter must point to an allocated array containing celt VSS_OBJECT_PROP structures, and cannot be NULL.

It is the caller's responsibility to free system resources returned by IVssEnumObject::Next to the VSS_OBJECT_PROP structure pointed to by the rgelt parameter.

The callers must use CoTaskMemFree for every string value in the VSS_SNAPSHOT_PROP or VSS_PROVIDER_PROP object in the returned VSS_OBJECT_PROP structure.

In the case of VSS_SNAPSHOT_PROP, this can be done manually, or the utility function VssFreeSnapshotProperties can be used.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	vss.h
Library	VssApi.lib