XtfGetConsoleInfoList

Article
06/22/2023

Returns an XtfConsoleInfo object that contains information about a console.

Syntax

HRESULT XtfGetConsoleInfoList(
         PCWSTR address,
         XtfConsoleInfo *hConsoleInfo
)

Parameters

address
Type: PCWSTR

[in] The address of the console.

hConsoleInfo
Type: XtfConsoleInfo*

[out] A pointer to be used with the XtfGetConsoleFieldValue function to retrieve information about a console.

Return value

Type: HRESULT

Returns S_OK if the function succeeded and XtfGetConsoleFieldValue can be used to retrieve values from hConsoleInfo; otherwise, returns an HRESULT error code.

Remarks

To retrieve information about a console, first use this function to get an XtfConsoleInfo pointer, and then use XtfGetConsoleFieldValue to retrieve information about the console from that pointer. After you retrieve the information you need, use XtfCloseConsoleInfoList to free resources associated with the returned XtfConsoleInfo pointer.

Note

XtfGetConsoleInfoList retrieves all of the information from the console and provides a pointer to that information. XtfGetConsoleFieldValue only iterates that retrieved information. You must use both functions together to retrieve information about a console.

Note

If the target console specified in address for this function has not been provisioned, the XtfGetConsoleFieldValue function returns an empty value if XtfConsoleFieldId::DeviceID is specified in field.

The following code sample demonstrates how to use the XtfGetConsoleInfoList and XtfGetConsoleFieldValue functions together to retrieve the console ID of a development console.

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;
}

Requirements

Header: xtfapi.h

Library: XtfApi.lib

Supported platforms: Windows (for Xbox console tools)

Share via