IRow::Open

Returns an interface pointer to be used to access an object-valued column. IRow::Open will generally return a rowset, row, or stream object, allowing the provider to create the appropriate object for tabular columns and streams. The returned object inherits the access privileges from the original flags used for binding to the row. IRow::Open also can return an interface pointer to a child rowset when called on a chapter-valued column.

HRESULT Open(
   IUnknown     *pUnkOuter,
   DBID         *pColumnID,
   REFGUID       rguidColumnType,
   DWORD         dwFlags,
   REFIID        riid,
   Iunknown    **ppUnk
);

Parameters

pUnkOuter

[in]
The controlling IUnknown if the returned interface is to be aggregated; otherwise, a null pointer.

pColumnID

[in]
A pointer to a DBID containing the name of the column to open. Must not be a null pointer. When a chapter-valued column, rguidColumnType must be DBGUID_ROWSET and riid should be a rowset interface.

rguidColumnType

[in]
A pointer to a GUID that identifies the type of object to be opened from this column. If the GUID does not match the column type, DB_E_OBJECTMISMATCH is returned. Possible values are described in the following table.

Object type	Description
DBGUID_STREAM	Column contains a stream of binary data. Use IStream or ISequentialStream.
DBGUID_ROW	Column contains a nested collection of columns. Use IRow.
DBGUID_ROWSET	Column contains a nested rowset. Use IRowset.
GUID_NULL	Column contains a COM object. Open the object as its native type, and return the interface specified by riid.

dwFlags

[in]
Reserved for flags to control the open operation. Must be zero.

riid

[in]
Interface ID of the interface pointer to be returned.

ppUnk

[out]
A pointer to memory in which to return the requested interface pointer. If an error code is returned and ppUnk is not a null pointer, *ppUnk should be set to NULL.

Return Code

S_OK

The object was successfully opened. The caller becomes responsible for releasing the returned interface pointer.

DB_E_BADCOLUMNID

pColumnID was an invalid DBID or a shortcut DBID, such as DBROWCOL_DEFAULTSTREAM, that does not exist on this row.

Note   For more information about DBROWCOL_DEFAULTSTREAM, see "Special Row Column DBIDs" in Chapter 9: Row and Stream Objects.

DB_E_COLUMNUNAVAILABLE

Requested column is valid, but could not be retrieved. The caller should check that the DBPROP_ACCESSORDER property is compatible with this operation.

DB_E_DELETEDROW

The row is either a pending delete row or a row for which a deletion had already been transmitted to the data store.

DB_E_NOAGGREGATION

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

The provider does not support aggregation.

The object has already been created.

DB_E_NOTFOUND

The data value of this column is NULL.

DB_E_OBJECTMISMATCH

rguidColumnType pointed to a GUID that did not match the object type of this column.

pcolumnID is a chapter-valued column, and rguidColumnType is not DBGUID_ROWSET.

DB_E_OBJECTOPEN

The provider can support only a single open storage object at a time (DBPROP_MULTIPLESTORAGEOBJECTS = VARIANT_FALSE) and already has a storage object open.

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

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pColumnID or ppUnk was a null pointer.

E_NOINTERFACE

The object does not support the interface requested in riid, or riid was IID_NULL.

E_UNEXPECTED

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

Comments

IRow::Open is a synchronous operation.

The DBBINDURLFLAG_* flags used in IBindResource for read and write access to open the row are carried through to the access privileges for columns. For example, a row opened with DBBINDURLFLAG_READ will not allow a column to be updated.

Note   For more information about DBBINDURLFLAG_* flags, see the reference entry for IBindResource::Bind.

For columns that are themselves rowsets, it is suggested that the object returned has a well-known list of supported interfaces. IRowset, IRowsetInfo, IRowsetChange (only for write access), IAccessor, and IColumnsInfo are the supported interfaces.

If pColumnID specifies a shortcut data type identifier (DBID) such as DBROWCOL_DEFAULTSTREAM or DBROWCOL_URL and the row object does not contain these columns, the provider returns DB_E_BADCOLUMNID.