IGetRow::GetRowFromHROW

  • Article

Creates a new row object from a row in a rowset and returns an interface pointer on the newly created row object.

Syntax

HRESULT GetRowFromHROW(
   IUnknown     **pUnkOuter,
   HROW          hRow,
   REFIID        riid,
   IUnknown    **ppUnk);
}

Parameters

  • pUnkOuter
    [in] If the row object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, it is a null pointer.

  • hRow
    [in] The handle of the row from which the row object is to be created.

    Warning

    The consumer must ensure that hRow contains a valid row handle because the provider might not validate hRow before using it. The result of passing the handle of a deleted row is provider-specific, although the provider must not terminate abnormally. For example, the provider might return DB_E_BADROWHANDLE or DB_E_DELETEDROW, or it might get data from a different row. The result of passing an invalid row handle in hRow is undefined.

  • riid
    [in] The IID of the interface for which to return a pointer on the newly created row object.

  • ppUnk
    [out] A pointer to memory in which to return an interface pointer on the row object. If IGetRow::GetRowFromHROW fails, the provider must attempt to set *ppUnk to a null pointer.

Return Code

  • S_OK
    The row object was created, and the interface pointer was successfully returned.

  • DB_S_NOROWSPECIFICCOLUMNS
    The row object does not contain any row-specific columns. Providers are encouraged (but not required) to return this warning as a performance hint to consumers. As a result, the consumer can avoid the overhead of calling IColumnsInfo::GetColumnInfo for each row and allocating column access structures for row columns.

  • E_FAIL
    A provider-specific error occurred.

  • E_INVALIDARG
    ppUnk was a null pointer.

  • E_NOINTERFACE
    The row object did not support the interface specified in riid, or riid was IID_NULL.

  • DB_E_BADROWHANDLE
    hRow was invalid. Providers are not required to check for this condition, because doing so might slow the method significantly.

  • DB_E_NOAGGREGATION
    pUnkOuter was not a null pointer, and riid was not IID_IUnknown.

  • DB_E_DELETEDROW
    hRow referred to a pending delete row or to a row for which a deletion had already been transmitted to the data store.

  • DB_E_OBJECTOPEN
    The provider would have to open a new connection to support the operation, and DBPROP_MULTIPLECONNECTIONS is set to VARIANT_FALSE.

  • E_UNEXPECTED
    ITransaction::Commit or ITransaction::Abort was called, and the row object is in a zombie state.

Comments

IGetRow::GetRowFromHROW is a synchronous operation that instantiates a new row object. If multiple row objects have been created from the same row in a rowset, the visibility of changes made to one of these row objects as seen by the others is governed by properties of the source rowset. For more information, see Visibility of Changes.

If a row is obtained from a source rowset using this method, the updatability of the row is inherited from the source rowset.

Providers that implement IGetRow::GetRowFromHROW are allowed to implement the row object on the same data structure that implements the source rowset, instead of on a separately cached data structure. In this case, the provider should increment the reference count of the row handle in the rowset when returning the corresponding row object with IGetRow::GetRowFromHROW. Consumers may then receive DB_E_ROWSNOTRELEASED on IRowset::GetNextRows, and must release the row object before obtaining additional rows.