> ## 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](/reference/tools/xtf/xtfconsolecontrol/functions/xtfgetconsoleinfolist-xtfconsolecontrol-xbox-microsoft-m) 获取一个 **XtfConsoleInfo** 对象，然后使用 [XtfGetConsoleFieldValue](/reference/tools/xtf/xtfapi/functions/xtfgetconsolefieldvalue-xbox-microsoft-m) 从该对象中检索值。检索到所需的值后，使用 [XtfCloseConsoleInfoList](/reference/tools/xtf/xtfapi/functions/xtfcloseconsoleinfolist-xbox-microsoft-m) 释放与返回的 **XtfConsoleInfo** 对象关联的资源。

<Note>**XtfGetConsoleInfoList** 会从主机检索所有信息。[XtfGetConsoleFieldValue](/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 主题)](/tools/tools-console/commandlinetools/xtf-transport-errors)\
[其他 Xtf API](/reference/tools/xtf/xtfapi/atoc-xtfapi)


## Related topics

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