> ## 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.

# XGameUiShowWebAuthenticationWithOptionsAsync

> XGameUiShowWebAuthenticationWithOptionsAsync

# XGameUiShowWebAuthenticationWithOptionsAsync

開始非同步驗證要求，該要求會顯示網頁 UI (可能為全螢幕)，讓使用者能將存取權委派給外部網站和服務，而不需要直接向執行中的遊戲提供其認證。

## 語法

```cpp theme={null}
STDAPI XGameUiShowWebAuthenticationWithOptionsAsync(
    _In_ XAsyncBlock* async,
    _In_ XUserHandle requestingUser,
    _In_z_ const char* requestUri,
    _In_z_ const char* completionUri,
    _In_ XGameUiWebAuthenticationOptions options
    ) noexcept;
)  
```

### 參數

*async*   \_In\_\
類型：[XAsyncBlock\*](/zh-TW/reference/system/xasync/structs/xasyncblock)

指向傳遞給 [XAsyncRun](/zh-TW/reference/system/xasync/functions/xasyncrun) 之 [XAsyncBlock](/zh-TW/reference/system/xasync/structs/xasyncblock) 的指標。

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

要求網頁驗證之使用者的控制代碼。

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

呈現給使用者之網頁檢視的初始 URI (可能包含讓使用者向服務進行驗證的欄位)。要求 URI 必須是安全的 HTTPS 位址。

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

表示代表網頁驗證程序成功完成的 URI。當網頁檢視巡覽至符合 *completionUri* 的 URI 時，網頁檢視會關閉，並將控制權交還給呼叫的遊戲。

*options* \&nbps; \_In\_
類型：[XGameUiWebAuthenticationOptions](/zh-TW/reference/system/xgameui/enums/xgameuiwebauthenticationoptions)

表示是否嘗試以全螢幕顯示 UI 的旗標。在 PC 上會忽略此旗標。PC 不支援全螢幕
選項。

### 傳回值

類型：HRESULT

非同步呼叫的 HRESULT 成功或錯誤碼。

若要取得結果，請在 *AsyncBlock* 回呼內或 *AsyncBlock* 完成之後，呼叫 [xgameuishowwebauthenticationresultsize](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationresultsize) 和 [xgameuishowwebauthenticationresult](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationresult)。

## 備註

當此非同步工作執行時，系統會向使用者呈現網頁檢視 (覆蓋在目前的應用程式上)，使用者可以與其互動，或按下返回來關閉它。這可讓使用者使用 OAuth 將授權權限授與外部網站和服務。這可用於下列情境：驗證遊戲以在社群媒體上分享遊戲內精彩片段、向外部提供者要求使用者資料等。

驗證要求的結果會儲存在 [XGameUiWebAuthenticationResultData](/zh-TW/reference/system/xgameui/structs/xgameuiwebauthenticationresultdata) 物件中，該物件是由 [XGameUiShowWebAuthenticationResult](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationresult) 方法傳回。

如果網頁檢視因巡覽至 *completionUri* 而關閉，則結果資料結構的 *responseStatus* 欄位會是 `S_OK`。

如果使用者取消或以其他方式手動關閉網頁檢視，則結果資料結構的 *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(XGameUiShowWebAuthenticationWithOptionsAsync(
    block,
    currentUser,
    requestUri,
    completionUri,
    XGameUiWebAuthenticationOptions::PreferFullscreen
    ));
```

## 需求

**標頭：** XGameUI.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[XGameUI](/zh-TW/reference/system/xgameui/xgameui_members)
[XGameUiShowWebAuthenticationAsync](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationasync)\
[XGameUiShowWebAuthenticationResultSize](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationresultsize)\
[XGameUiShowWebAuthenticationResult](/zh-TW/reference/system/xgameui/functions/xgameuishowwebauthenticationresult)\
[XGameUiWebAuthenticationResultData](/zh-TW/reference/system/xgameui/structs/xgameuiwebauthenticationresultdata)\
[非同步程式設計模型](/zh-TW/build/core-features/common/async/async-programming-model)


## Related topics

- [XGameUiShowWebAuthenticationWithOptionsAsync](/reference/system/xgameui/functions/xgameuishowwebauthenticationwithoptionsasync.md)
- [XGameUiWebAuthenticationOptions](/reference/system/xgameui/enums/xgameuiwebauthenticationoptions.md)
- [XGameUiShowWebAuthenticationAsync](/reference/system/xgameui/functions/xgameuishowwebauthenticationasync.md)
- [XGameUI](/reference/system/xgameui/xgameui_members.md)
- [XGameUiShowWebAuthenticationResult](/reference/system/xgameui/functions/xgameuishowwebauthenticationresult.md)