RpcErrorStartEnumeration function (rpcasync.h)
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.
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 |