RpcErrorStartEnumeration function (rpcasync.h)

Article
04/02/2021

The RpcErrorStartEnumeration function begins enumeration of extended error information.

Syntax

RPC_STATUS RpcErrorStartEnumeration(
  RPC_ERROR_ENUM_HANDLE *EnumHandle
);

Parameters

EnumHandle

Pointer to the enumeration handle, in the form of an RPC_ERROR_ENUM_HANDLE structure. The structure must be allocated by the caller, and cannot be freed until the operation is complete. All members are ignored on input.

Return value

Successful completion returns RPC_S_OK.

Returns RPC_S_ENTRY_NOT_FOUND if no extended error information is on the thread. If an enumeration is in progress, starting a second enumeration starts from the beginning.

Note For a list of valid error codes, see RPC Return Values.

Remarks

The RpcErrorStartEnumeration function call should be made immediately after the call that returned the error. Otherwise, extended error information may be overwritten by subsequent calls. Enumeration handles must be freed with the RpcErrorEndEnumeration function.

Once RpcErrorStartEnumeration is called, it is safe to use the enumeration handle from a different thread. The RpcErrorStartEnumeration function takes a snapshot of the extended error information, and the returning enumeration handle operates on the snapshot. However, enumeration functions are not synchronized between threads by RPC, and so the caller is responsible for doing so. Subsequent calls to RpcErrorStartEnumeration begins a new enumeration, and does not create a second enumeration for the same extended error information.

The RpcErrorStartEnumeration function may fail if there is not enough memory to begin the enumeration. The enumeration handle can be passed only to RpcError* functions, and cannot be used with other functions, such as DuplicateHandle.

Advancing the enumeration pointer on one enumeration has no effect on independently started enumerations.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	rpcasync.h (include Rpc.h)
Library	Rpcrt4.lib
DLL	Rpcrt4.dll