IMAPITable::QueryPosition

The IMAPITable::QueryPosition method retrieves the current table row position of the cursor, based on a fractional value.

Quick Info

See IMAPITable : IUnknown.

HRESULT QueryPosition(
  ULONG FAR * lpulRow,         
  ULONG FAR * lpulNumerator,   
  ULONG FAR * lpulDenominator  
);

Parameters

lpulRow: [out] Pointer to the number of the current row. The row number is zero-based; the first row in the table is zero.
lpulNumerator: [out] Pointer to the numerator for the fraction identifying the table position.
lpulDenominator: [out] Pointer to the denominator for the fraction identifying the table position. The lpulDenominator parameter cannot be zero.

Return Values

S_OK: The method returned valid values in lpulRow, lpulNumerator, and lpulDenominator.

Remarks

The IMAPITable::QueryPosition method determines the current row position and returns both the number of the current row and a fractional value indicating its relative position to the end of the table. MAPI defines the current row as the next row to be read.

Notes to Implementers

You do not need to return the exact number of rows in the table for the lpulDenominator parameter; it can be an approximation.

If you cannot determine the current row, return a value of 0xFFFFFFFF in lpulRow.

Notes to Callers

You can use QueryPosition to position a scroll box in a scroll bar. For example, in a table containing 100 rows, if QueryPosition returns a value of 75 in the lpulNumerator parameter, 100 in the lpulDenominator parameter, and 75 in the lpulRow parameter, you can position the scroll box 3/4 of the way across the scroll bar.

Do not rely on the value in lpulDenominator being the number of rows in the table. QueryPosition cannot always identify the exact row that the cursor is positioned on.

A call to QueryPosition might involve large amounts of memory, particularly for large categorized tables. If the lpulRow parameter is set to 0xFFFFFFFF, too much memory was required for QueryPosition to determine the current row. Call the IMAPITable::SeekRowApprox method to position the table to the row identified by the lpulNumerator and lpulDenominator parameters. However, do not always expect SeekRowApprox to establish as the current position the same row QueryPosition would have if memory had not been a factor.