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

# XtfGetConsoleFieldValue

> XtfGetConsoleFieldValue

# XtfGetConsoleFieldValue

擷取主機的相關資訊，可以是 Tools IP Address、Console IP Address、AccessKey、Console ID、HostName、Device ID、DevKit Cert type、SystemMajorVersion、SystemMinorVersion、SystemBuildVersion 或 SystemRevisionVersion 其中之一。

<a id="syntaxSection" />

## 語法

```cpp theme={null}
HRESULT XtfGetConsoleFieldValue(
         XtfConsoleInfo hConsoleInfo,
         XtfConsoleFieldId field,
         XtfConsoleFieldType *fieldType,
         BYTE *buffer,
         UINT32 *cbBuffer
)  
```

<a id="ID4EH" />

### 參數

*hConsoleInfo*\
類型: XtfConsoleInfo

\[in] XtfGetConsoleInfoList 所傳回的 XtfConsoleInfo 物件。

*field*\
類型: XtfConsoleFieldId

\[in] 要傳回之值的識別碼，可以是 Tools IP Address、Console IP Address、AccessKey、Console ID、HostName、Device ID、DevKit Cert type、SystemMajorVersion、SystemMinorVersion、SystemBuildVersion 或 SystemRevisionVersion 其中之一。

*fieldType*\
類型: XtfConsoleFieldType \*

\[out] 傳回值的資料類型，可以是 UINT32 或 PWCHAR。

*buffer*\
類型: BYTE \*

\[out] 接收傳回值之緩衝區的指標。若要判斷所需的緩衝區大小，請將此參數設為 nullptr，並將 cbBuffer 參數設為 0。函式傳回時，bufferSize 會設為所需緩衝區的大小 (以位元組為單位)。必要時，此大小會包含結束 null 字元的空間。

*cbBuffer*\
類型: UINT32 \*

\[in, out] 輸入時為緩衝區的大小 (以位元組為單位)。如果傳回值為 PWCHAR，緩衝區大小必須包含結束 null 字元的空間。輸出時為所需的緩衝區長度 (以位元組為單位)。

<a id="ID4EN" />

### 傳回值

類型: HRESULT

傳回值 S\_OK 表示函式成功，且 buffer 和 fieldType 包含值及值的類型。

傳回值 HRESULT\_FROM\_WIN32(ERROR\_MORE\_DATA) 表示為 **buffer** 引數提供的緩衝區不夠大。所需的緩衝區大小包含在 **cbBuffer** 中。

如果在未佈建的開發套件上無法使用該值 (例如 Device ID)，傳回的 HRESULT 會是 0x80070490。

任何其他值都表示發生未預期的錯誤。

<a id="remarks" />

## 備註

使用 [XtfGetConsoleInfoList](/zh-TW/reference/tools/xtf/xtfconsolecontrol/functions/xtfgetconsoleinfolist-xtfconsolecontrol-xbox-microsoft-m) 取得 **XtfConsoleInfo** 物件，然後使用 [XtfGetConsoleFieldValue](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfgetconsolefieldvalue-xbox-microsoft-m) 從該物件擷取值。擷取所需的值之後，使用 [XtfCloseConsoleInfoList](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfcloseconsoleinfolist-xbox-microsoft-m) 釋放與所傳回之 **XtfConsoleInfo** 物件相關聯的資源。

<Note>**XtfGetConsoleInfoList** 會從主機擷取所有資訊。[XtfGetConsoleFieldValue](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfgetconsolefieldvalue-xbox-microsoft-m) 只會逐一查看該擷取的資訊。</Note>

<Note>如果目標主機尚未佈建，**DeviceID** 會傳回空值。</Note>

<a id="ID4E2C" />

```cpp theme={null}
int wmain(int argc, wchar_t **argv)
{
  HRESULT             hr             = S_OK;
  PCWSTR              consoleAddress = L" 190.167.10.18";
  XtfConsoleInfo      hConsoleInfo   = nullptr;
  XtfConsoleFieldType fieldType      = XtfConsoleFieldType::FieldTypeUINT32;
  BYTE *              pValueBuffer   = nullptr;
  UINT32              bufferSize     = 0;

  hr = XtfGetConsoleInfoList(consoleAddress, &hConsoleInfo);
  if (FAILED(hr))
  {
    wprintf(L"\n\n*** XtfGetConsoleInfoList failed 0x%x", hr);
    return hr;
  }

  hr = XtfGetConsoleFieldValue(hConsoleInfo, XtfConsoleFieldId::ConsoleId, &fieldType, nullptr, &bufferSize);
  if (hr != HRESULT_FROM_WIN32(ERROR_MORE_DATA))
  {
    XtfCloseConsoleInfoList(hConsoleInfo);
    wprintf(L"\n\n*** XtfGetConsoleFieldValue failed 0x%x", hr);
    return hr;
  }

  pValueBuffer = new BYTE[bufferSize];

  hr  = XtfGetConsoleFieldValue(hConsoleInfo, XtfConsoleFieldId::ConsoleId, &fieldType, pValueBuffer, &bufferSize);
  if (SUCCEEDED(hr))
  {
    PWCHAR consoleId = (PWCHAR)pValueBuffer;
    wprintf(L"\n\n*** Console ID is %s", consoleId);
  }
  else
  {
    wprintf(L"\n\n*** XtfGetConsoleFieldValue failed 0x%x", hr);
  }

  XtfCloseConsoleInfoList(hConsoleInfo);
  delete[] pValueBuffer;

  return hr;
}  
```

## 需求

**標頭:** xtfapi.h

**程式庫:** XtfApi.lib

**支援的平台:** Windows (適用於 XBOX 主機工具)

## 另請參閱

[XTF 傳輸錯誤 (NDA 主題)](/zh-TW/tools/tools-console/commandlinetools/xtf-transport-errors)\
[其他 Xtf API](/zh-TW/reference/tools/xtf/xtfapi/atoc-xtfapi)


## Related topics

- [XtfConsoleFieldId 列舉](/zh-TW/reference/tools/xtf/xtfapi/enums/xtfconsolefieldid-xbox-windows-t.md)
- [XtfConsoleFieldType 列舉](/zh-TW/reference/tools/xtf/xtfapi/enums/xtfconsolefieldtype-xbox-windows-t.md)
- [XtfGetConsoleInfoList](/zh-TW/reference/tools/xtf/xtfconsolecontrol/functions/xtfgetconsoleinfolist-xtfconsolecontrol-xbox-microsoft-m.md)
- [XtfCloseConsoleInfoList](/zh-TW/reference/tools/xtf/xtfapi/functions/xtfcloseconsoleinfolist-xbox-microsoft-m.md)
- [XtfConsoleCertType 列舉](/zh-TW/reference/tools/xtf/xtfapi/enums/xtfconsolecerttype-xbox-windows-t.md)