> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XGameUiShowWebAuthenticationAsync

> XGameUiShowWebAuthenticationAsync

# XGameUiShowWebAuthenticationAsync

启动异步身份验证请求，显示一个 Web UI，允许用户委托访问外部网站和服务，而无需直接向正在运行的游戏提供其凭据。

## 语法

```cpp theme={null}
HRESULT XGameUiShowWebAuthenticationAsync(  
         XAsyncBlock* async,  
         XUserHandle requestingUser,  
         const char* requestUri,  
         const char* completionUri  
)  
```

### 参数

*async*   \_In\_\
类型：[XAsyncBlock\*](/reference/system/xasync/structs/xasyncblock)

指向传递给 [XAsyncRun](/reference/system/xasync/functions/xasyncrun) 的 [XAsyncBlock](/reference/system/xasync/structs/xasyncblock) 的指针。

*requestingUser*   \_In\_\
类型：XUserHandle

请求进行 Web 身份验证的用户的句柄。

*requestUri*   \_In\_z\_\
类型：char\*

向用户呈现的 Web 视图的初始 URI（可能包含用于用户向服务进行身份验证的字段）。请求 URI 必须是安全的 HTTPS 地址。

*completionUri*   \_In\_z\_\
类型：char\*

表示 Web 身份验证过程成功完成的 URI。当 Web 视图导航到与 *completionUri* 匹配的 uri 时，Web 视图将关闭，控制权返回给调用游戏。

### 返回值

类型：HRESULT

异步调用的 HRESULT 成功或错误代码。

若要获取结果，请在 *AsyncBlock* 回调中或 *AsyncBlock* 完成后调用 [xgameuishowwebauthenticationresultsize](/reference/system/xgameui/functions/xgameuishowwebauthenticationresultsize) 和 [xgameuishowwebauthenticationresult](/reference/system/xgameui/functions/xgameuishowwebauthenticationresult)。

## 备注

当此异步任务运行时，系统会向用户呈现一个 Web 视图（覆盖在当前应用程序之上），用户可以与之交互，或按“返回”将其关闭。这样一来，用户可以使用 OAuth 向外部网站和服务授予访问权限。这可用于诸如让游戏进行身份验证以在社交媒体上分享游戏亮点、向外部提供程序请求用户数据等场景。

身份验证请求的结果存储在 [XGameUiWebAuthenticationResultData](/reference/system/xgameui/structs/xgameuiwebauthenticationresultdata) 对象中，该对象由 [XGameUiShowWebAuthenticationResult](/reference/system/xgameui/functions/xgameuishowwebauthenticationresult) 方法返回。

如果 Web 视图因导航到 *completionUri* 而关闭，则结果数据结构的 *responseStatus* 字段将为 `S_OK`。

如果用户取消或以其他方式手动关闭 Web 视图，则结果数据结构的 *responseStatus* 字段将为 `E_CANCELLED`。

## 示例

以下代码示例演示了如何使用 Facebook 执行 OAuth。为了使代码简洁，此示例未包含内存分配错误处理。

```cpp theme={null}
// Use Facebook example for OAuth; client_id should correspond to your registered application.
const char completionUri[] = "https://www.facebook.com/connect/login_success.html"; 
const char requestUri[] =
    "https://www.facebook.com/dialog/oauth?"
    "client_id=000000000000000&"
    "redirect_uri=https%3A%2F%2Fwww.facebook.com%2Fconnect%2Flogin_success.html&"
    "response_type=token&"
    "sdk=xboxone";

// Allocate and initialize XAsyncBlock for asynchronous authentication operation.
XAsyncBlock* block = new XAsyncBlock();
ZeroMemory(block, sizeof(XAsyncBlock));
block->callback = [](XAsyncBlock* block)
{
    // Query required size and allocate buffer for authentication result data.
    uint32_t bufferSize = 0;
    FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationResultSize(block, &bufferSize));
    uint8_t* buffer = new uint8_t[bufferSize];

    // The currentUser is initialized with user to authenticate for.
    XGameUiWebAuthenticationResultData* resultData = nullptr;
    FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationResult(
        block,
        bufferSize,
        buffer,
        &resultData,
        nullptr
        ));

    //
    // Use the result data here. If resultData->responseStatus is S_OK, then web authentication was successful.
    //

    // Free allocated buffer and XAsyncBlock.
    delete[] buffer;
    delete block;
};

//  Begin asynchronous authentication operation.
XUserHandle currentUser = GetCurrentUserForAuthentication();
FAIL_FAST_IF_FAILED(XGameUiShowWebAuthenticationAsync(
    block,
    currentUser,
    requestUri,
    completionUri
    ));
```

## 要求

**标头：** XGameUI.h

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 请参阅

[XGameUI](/reference/system/xgameui/xgameui_members)
[XGameUiShowWebAuthenticationWithOptionsAsync](/reference/system/xgameui/functions/xgameuishowwebauthenticationwithoptionsasync)
[XGameUiShowWebAuthenticationResultSize](/reference/system/xgameui/functions/xgameuishowwebauthenticationresultsize)\
[XGameUiShowWebAuthenticationResult](/reference/system/xgameui/functions/xgameuishowwebauthenticationresult)\
[XGameUiWebAuthenticationResultData](/reference/system/xgameui/structs/xgameuiwebauthenticationresultdata)\
[异步编程模型](/build/core-features/common/async/async-programming-model)


## Related topics

- [XGameUiShowWebAuthenticationResultSize](/zh-CN/reference/system/xgameui/functions/xgameuishowwebauthenticationresultsize.md)
- [XGameUiShowWebAuthenticationWithOptionsAsync](/zh-CN/reference/system/xgameui/functions/xgameuishowwebauthenticationwithoptionsasync.md)
- [XGameUiShowWebAuthenticationResult](/zh-CN/reference/system/xgameui/functions/xgameuishowwebauthenticationresult.md)
- [XGameUiWebAuthenticationResultData](/zh-CN/reference/system/xgameui/structs/xgameuiwebauthenticationresultdata.md)
- [XGameUI](/zh-CN/reference/system/xgameui/xgameui_members.md)