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.

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

   
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

See also

Obtaining Extended RPC Error Information

RPC_EE_INFO_PARAM

RPC_ERROR_ENUM_HANDLE

RPC_EXTENDED_ERROR_INFO

RpcErrorAddRecord

RpcErrorClearInformation

RpcErrorEndEnumeration

RpcErrorGetNextRecord

RpcErrorGetNumberOfRecords

RpcErrorLoadErrorInfo

RpcErrorResetEnumeration

RpcErrorSaveErrorInfo