ARCRequest

4/8/2010

This function is implemented by the Authentication Reset Component (ARC). It may perform any desired functionality in order to determine if the Authentication Reset process is allowed.

Syntax

HRESULT ARCRequest(
  HWND hWndParent,
  const BYTE* pbRequestData,
  DWORD cbRequestData,
  LPBYTE* ppbResetData,
  LPDWORD pcbResetData
);

Parameters

• hWndParent
  [in] Handle to the parent window. Can be NULL.

• pbRequestData
  [in] Pointer to the Request Data. To successfully complete Authentication Reset, this must be the same data returned by a successful call to ARCSetup. The meaning, size, and contents of the Request Data are defined by the Authentication Reset Component (ARC).

• cbRequestData
  [in] Size in bytes of the buffer pointed to by pbRequestData.

• ppbResetData
  [out] Pointer to a BYTE array that contains the Reset Data set during a call to ARCSetup, if available. The caller should verify that the contents of this buffer match the originally supplied Reset Data before continuing Authentication Reset steps. The buffer for the BYTE array will be allocated by this function. The caller is responsible to free this buffer using LocalFree. If no Reset Data are available, this argument will point to NULL.

• pcbResetData
  [out] Size in bytes of the ppbResetData buffer. If no Reset Data are available, pcbResetData will equal zero.

Annotated Function Declaration

HRESULT ARCRequest(__in_opt HWND hWndParent, __in_bcount(cbResetData) const BYTE* pbRequestData, DWORD cbRequestData, __deref_out_bcount_opt(*pcbResetData) LPBYTE* ppbResetData, __out LPDWORD pcbResetData);

Return Value

Returns S_OK if Authentication Reset is allowed to proceed. In this case, pbRequestData must have been verified and ppbResetData must contain the originally-supplied Reset Data. If Authentication Reset cannot proceed, an error code is returned. The error code must be HRESULT(ERROR_PRIVILEGE_NOT_HELD) if the request is denied, but may contain more specific error information. Examples:

• HRESULT(ERROR_PRIVILEGE_NOT_HELD)
  The Authentication Reset request is denied.

• HRESULT(WAIT_TIMEOUT)
  The wait timeout has been exceeded.

• E_PENDING
  The Authentication Reset could not be completed at this time. The user may be requested to wait or perform some action, then try again.

• E_ACCESSDENIED
  The caller is not trusted.

• E_POINTER
  Invalid pointer. Either ppbResetData is NULL or pcbResetData is NULL. Valid pointers for these arguments are required.

• E_INVALIDARG
  Invalid argument. pbRequestData is NULL or cbResetData is 0. Non-zero values for these arguments are required.

• E_ABORT
  The user canceled the process.

• E_OUTOFMEMORY
  The device is out of memory.

• E_FAIL
  Unspecified error.

Remarks

This function is called by the Shell in response to a request from a LAP to reset the user's authentication. LAPs must not call this function directly, they should use AuthResetRequest.

Buffers returned from this function must be allocated using LocalAlloc.

The Authentication Reset component may display user interface and may take any amount of time to complete this function. If user interface is displayed, the implementation must provide a way for the user to cancel or provide a mechanism to place emergency phone calls (on phone devices). All windows must have the WS_EX_ABOVESTARTUP exstyle set. If the user cancels, this function should return E_ABORT.

Requirements

See Also

Reference

Authentication Reset System Functions
Authentication Reset System Reference

Concepts

Authentication Reset System