IDataTable Interface

Interface

IDataTable

Represents a tabular data structure within the Windows data access framework. This interface defines the contract for objects that manage and expose data in a row and column format, similar to a database table.

The IDataTable interface provides methods for accessing metadata about the table, retrieving rows, and performing basic data manipulation.

Methods

HRESULT GetRowCount( _Out_ ULONG* pRowCount)

Retrieves the total number of rows in the table.

Parameters:

  • pRowCount: [out] A pointer to a ULONG that receives the number of rows.

Return Value:

  • Returns S_OK if the operation succeeds.
  • Returns an error code otherwise.
HRESULT GetColumnCount( _Out_ ULONG* pColumnCount)

Retrieves the total number of columns in the table.

Parameters:

  • pColumnCount: [out] A pointer to a ULONG that receives the number of columns.

Return Value:

  • Returns S_OK if the operation succeeds.
  • Returns an error code otherwise.
HRESULT GetColumnName( _In_ ULONG columnIndex, _Out_ LPWSTR* ppColumnName)

Retrieves the name of a column at a specified index.

Parameters:

  • columnIndex: [in] The zero-based index of the column.
  • ppColumnName: [out] A pointer to a pointer to a null-terminated wide character string that receives the column name. The caller is responsible for freeing this memory.

Return Value:

  • Returns S_OK if the operation succeeds.
  • Returns E_INVALIDARG if columnIndex is out of bounds.
  • Returns an error code otherwise.
HRESULT GetRow( _In_ ULONG rowIndex, _Out_ IDataRow** ppRow)

Retrieves a specific row from the table by its index.

Parameters:

  • rowIndex: [in] The zero-based index of the row to retrieve.
  • ppRow: [out] A pointer to a pointer to an IDataRow interface. The caller is responsible for releasing this interface.

Return Value:

  • Returns S_OK if the operation succeeds.
  • Returns E_INVALIDARG if rowIndex is out of bounds.
  • Returns an error code otherwise.

Remarks

The IDataTable interface is a fundamental component for working with structured data in Windows applications. It allows for efficient access to data presented in a two-dimensional grid.

Implementations of this interface should ensure thread safety and proper memory management, especially when returning string data or interface pointers.

Requirements:

Header Include
Windows Data Access API <windowsdata.h>

Example Usage

The following C++ code snippet demonstrates how to retrieve the number of rows and columns from an IDataTable object:


#include <windowsdata.h>
#include <iostream>

// Assume pDataTable is a valid pointer to an IDataTable interface
// IDataTable* pDataTable = ...;

ULONG rowCount = 0;
ULONG colCount = 0;

HRESULT hr = pDataTable->GetRowCount(&rowCount);
if (SUCCEEDED(hr)) {
    hr = pDataTable->GetColumnCount(&colCount);
    if (SUCCEEDED(hr)) {
        std::wcout << L"Table has " << rowCount << L" rows and " << colCount << L" columns." << std::endl;
    } else {
        std::wcerr << L"Failed to get column count." << std::endl;
    }
} else {
    std::wcerr << L"Failed to get row count." << std::endl;
}

// Remember to release the IDataTable interface when done
// if (pDataTable) {
//     pDataTable->Release();
// }