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

Recupera informações sobre um console: Tools IP Address, Console IP Address, AccessKey, Console ID, HostName, Device ID, DevKit Cert type, SystemMajorVersion, SystemMinorVersion, SystemBuildVersion ou SystemRevisionVersion.

<a id="syntaxSection" />

## Sintaxe

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

<a id="ID4EH" />

### Parâmetros

*hConsoleInfo*\
Tipo: XtfConsoleInfo

\[in] Objeto XtfConsoleInfo retornado por XtfGetConsoleInfoList.

*field*\
Tipo: XtfConsoleFieldId

\[in] Identificador do valor a ser retornado: Tools IP Address, Console IP Address, AccessKey, Console ID, HostName, Device ID, DevKit Cert type, SystemMajorVersion, SystemMinorVersion, SystemBuildVersion ou SystemRevisionVersion.

*fieldType*\
Tipo: XtfConsoleFieldType \*

\[out] O tipo de dados do valor retornado, UINT32 ou PWCHAR.

*buffer*\
Tipo: BYTE \*

\[out] Um ponteiro para o buffer que recebe o valor retornado. Para determinar o tamanho de buffer necessário, defina esse parâmetro como nullptr e o parâmetro cbBuffer como 0. Quando a função retornar, bufferSize será definido como o tamanho do buffer necessário, em bytes. Esse tamanho incluirá espaço para o caractere nulo de terminação, se necessário.

*cbBuffer*\
Tipo: UINT32 \*

\[in, out] Na entrada, o tamanho do buffer em bytes. O tamanho do buffer deve incluir espaço para um caractere nulo de terminação se o valor retornado for um PWCHAR. Na saída, o comprimento necessário do buffer em bytes.

<a id="ID4EN" />

### Valor de retorno

Tipo: HRESULT

Um valor de retorno S\_OK indica que a função foi bem-sucedida e que buffer e fieldType contêm o valor e o tipo do valor.

Um valor de retorno HRESULT\_FROM\_WIN32(ERROR\_MORE\_DATA) indica que o buffer fornecido para o argumento **buffer** não era grande o suficiente. O tamanho de buffer necessário está contido em **cbBuffer**.

Se o valor não estiver disponível (por exemplo, Device ID) em um devkit não provisionado, o HRESULT retornado será 0x80070490.

Qualquer outro valor indica que ocorreu um erro inesperado.

<a id="remarks" />

## Comentários

Use [XtfGetConsoleInfoList](/pt-BR/reference/tools/xtf/xtfconsolecontrol/functions/xtfgetconsoleinfolist-xtfconsolecontrol-xbox-microsoft-m) para obter um objeto **XtfConsoleInfo** e, em seguida, use [XtfGetConsoleFieldValue](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfgetconsolefieldvalue-xbox-microsoft-m) para recuperar os valores desse objeto. Depois de recuperar os valores necessários, use [XtfCloseConsoleInfoList](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfcloseconsoleinfolist-xbox-microsoft-m) para liberar os recursos associados ao objeto **XtfConsoleInfo** retornado.

<Note>**XtfGetConsoleInfoList** recupera todas as informações do console. [XtfGetConsoleFieldValue](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfgetconsolefieldvalue-xbox-microsoft-m) simplesmente itera sobre essas informações recuperadas.</Note>

<Note>Se o console de destino não tiver sido provisionado, **DeviceID** retornará um valor vazio.</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;
}  
```

## Requisitos

**Cabeçalho:** xtfapi.h

**Biblioteca:** XtfApi.lib

**Plataformas com suporte:** Windows (para ferramentas de console XBOX)

## Confira também

[Erros de transporte do XTF (tópico sob NDA)](/pt-BR/tools/tools-console/commandlinetools/xtf-transport-errors)\
[APIs adicionais do Xtf](/pt-BR/reference/tools/xtf/xtfapi/atoc-xtfapi)


## Related topics

- [XtfGetConsoleInfoList](/pt-BR/reference/tools/xtf/xtfconsolecontrol/functions/xtfgetconsoleinfolist-xtfconsolecontrol-xbox-microsoft-m.md)
- [Enumeração XtfConsoleFieldId](/pt-BR/reference/tools/xtf/xtfapi/enums/xtfconsolefieldid-xbox-windows-t.md)
- [Enumeração XtfConsoleFieldType](/pt-BR/reference/tools/xtf/xtfapi/enums/xtfconsolefieldtype-xbox-windows-t.md)
- [XtfCloseConsoleInfoList](/pt-BR/reference/tools/xtf/xtfapi/functions/xtfcloseconsoleinfolist-xbox-microsoft-m.md)
- [Enumeração XtfConsoleCertType](/pt-BR/reference/tools/xtf/xtfapi/enums/xtfconsolecerttype-xbox-windows-t.md)