ICreateRow::CreateRow

OLE DB Programmer's Reference

Creates and binds to an object named by a URL and returns the requested interface pointer.

HRESULT CreateRow(    IUnknown *            pUnkOuter,    LPCOLESTR             pwszURL,    DBBINDURLFLAG         dwBindURLFlags,    REFGUID               rguid,    REFIID                riid,    IAuthenticate *       pAuthenticate,    DBIMPLICITSESSION *   pImplSession,    DBBINDURLSTATUS *     pdwBindStatus,    LPOLESTR *            ppwszNewURL,    IUnknown **           ppUnk );

Parameters

pUnkOuter

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

pwszURL

[in]
The canonical URL naming the object to be created. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this string defines the path to the new object and the provider will generate the URL suffix.

dwBindURLFlags

[in]
Bitmask of bind flags that control how the object is to be bound. For more information, see the dwBindURLFlags value table in the reference entry for IBindResource::Bind.

Note   Creating a row requires DBBINDURLFLAG_WRITE be set. This is independent of whether a row, rowset, or stream view of the resource is requested.

The flag values listed in the following table are also available on ICreateRow::CreateRow, in addition to the bind flags defined in IBindResource::Bind.

Flags	Meaning
DBBINDURLFLAG_COLLECTION	Creates the object as a collection.
DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT	Creates the object as a structured document.
DBBINDURLFLAG_OPENIFEXISTS	If the resource exists and is not a collection, it is opened and S_OK is returned. If it exists and is a collection, DB_E_RESOURCEEXISTS is returned. If the resource does not exist, it is created. This flag may not be used with DBBINDURLFLAG_OVERWRITE. Note   All implementers of ICreateRow must support this flag.
DBBINDURLFLAG_OVERWRITE	Deletes and re-creates a named object if it exists. This flag may not be used with DBBINDURLFLAG_OPENIFEXISTS.
DBBINDURLFLAG_COLLECTION | DBBINDURLFLAG_OPENIFEXISTS	If the resource is not a collection, DB_E_NOTCOLLECTION is returned. If the resource exists and is a collection, it is opened and S_OK is returned. If the resource does not exist, it is created.

Not all bind flags may be used with all object types (as specified in the rguid parameter). The following table describes the restrictions. If a client does not adhere to these restrictions, the bind will fail with E_INVALIDARG.

Object type	Restrictions
DBGUID_ROW	All flags are allowed. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together.
DBGUID_ROWSET	DBBINDURLFLAG_COLLECTION must be specified. DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In addition, the following flags are disallowed: DBBINDURLFLAG_DELAYFETCHCOLUMNS DBBINDURLFLAG_DELAYFETCHSTREAM
DBGUID_STREAM	DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE may not be used together. In addition, the following flags are disallowed: DBBINDURLFLAG_DELAYFETCHCOLUMNS DBBINDURLFLAG_DELAYFETCHSTREAM

rguid

[in]
A pointer to a GUID indicating the type of OLE DB object to be returned. The GUID must be set to one of the following values:

DBGUID_ROW
DBGUID_ROWSET
DBGUID_STREAM

Note   DBGUID_ROWSET can be requested only if the row represents a collection (that is, dwBindURLFlags set to DBBINDURLFLAG_COLLECTION).

riid

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

pAuthenticate

[in]
Optional pointer to the caller's IAuthenticatei nterface. If supplied, it is provider-specific whether the IAuthenticate credentials are used before or after anonymous or default login credentials are used.

pImplSession

[in/out]
A pointer to a DBIMPLICITSESSION structure used to request and return aggregation information for the implicit session object. The DBIMPLICITSESSION structure is defined in the reference entry for IBindResource::Bind. If ICreateRow::CreateRow fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL.

Note   ICreateRow::CreateRow uses pImplSession only when implemented on a binder object and binding to a row, rowset, or stream object (rguid is DBGUID_ROW, DBGUID_ROWSET, or DBGUID_STREAM). If implemented on any other object (for example, a session or row object), the provider ignores pImplSession because the existing object already has a session context.

pdwBindStatus

[out]
A pointer to memory in which to return a bitmask that describes warning status for requested bind flags. If pdwBindStatus is a null pointer, no status is returned. The bind status values are listed in the table for pdwBindStatus for IBindResource::Bind. This parameter should be set to NULL if an error code is returned.

ppwszNewURL

[out]
A pointer to memory in which to return a string containing a provider-generated canonical URL that names the created row. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, callers are required to pass this pointer. If DBPROP_GENERATEURL is DBPROPVAL_GU_NOTSUPPORTED and the caller passes a null value, the provider does not return the absolute URL of the created row. If the caller passes this pointer, the provider must return the absolute URL of the created row. The provider allocates the memory for this string. The consumer should free the memory with IMalloc::Free. If ICreateRow::CreateRow fails and ppwszNewURL is not a null pointer, *ppwszNewURL is set to NULL.

ppUnk

[out]
A pointer to memory in which to return an interface pointer on the requested object. If ICreateRow::CreateRow fails, *ppUnk is set to a null pointer.

Return Code

S_OK

The method succeeded, the object named by the URL was created and bound, and the requested interface pointer was returned.

E_INVALIDARG

pwszURL or ppUnk was a null pointer.

rguid was DBGUID_ROWSET, but the DBBINDURLFLAG_COLLECTION bit of dwBindURLFlags was not set.

pImplSession was not a null pointer, and pImplSession->piid was a null pointer.

dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the dwBindURLFlags value table in the reference entry for IBindResource::Bind but did not contain the flag to be modified.

dwBindURLFlags contained both DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE.

The provider does not support one or more values of dwBindURLFlags.

One of more of the bind flags in dwBindURLFlags are either not supported by the provider or disallowed for the object type denoted by rguid. For flags allowed for each object type, see the table in the reference entry for IBindResource::Bind.

DB_S_ASYNCHRONOUS

The method has initiated asynchronous creation of an object. The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until asynchronous processing is complete, the object is not populated.

DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.

DB_S_ERRORSOCCURRED

The bind succeeded, but some bind flags or properties were not satisfied. The consumer should examine the bind status returned in *pdwBindStatus.

DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop.

DB_E_OBJECTMISMATCH

The object named by rguid does not represent the resource named by pwszURL.

DB_E_OBJECTOPEN

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

DB_E_RESOURCELOCKED

One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by this URL. IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of the users who have the object locked.

DB_E_RESOURCENOTSUPPORTED

The consumer attempted to create a type of row not supported by the provider. For example, DBBINDURLFLAG_ISSTRUCTUREDDOCUMENT was set but the provider does not support structured documents.

DB_E_RESOURCEOUTOFSCOPE

ICreateRow is implemented on a session or row object, and the caller tried to bind to an object that is not within the scope of this session or row object, respectively.

DB_SEC_E_PERMISSIONDENIED

The caller's authentication context does not permit access to the object. IErrorInfo::GetDescription returns the default error string.

DB_SEC_E_SAFEMODE_DENIED

The provider was called within a safe mode or context, and pwszURL specified an unsafe URL.

DB_E_READONLY

The caller requested write access to a read-only object.

DB_E_ASYNCNOTSUPPORTED

The provider does not support asynchronous binding.

DB_E_CANNOTCONNECT

The provider could not connect to the server for this object.

DB_E_NOAGGREGATION

pUnkOuter was not a null pointer, and the object being created does not support aggregation.

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

pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and pImplSession->piid did not point to IID_IUnknown.

pImplSession was not a null pointer, pImplSession->pUnkOuter was not a null pointer, and the object being created does not support aggregation.

DB_E_OUTOFSPACE

The provider was unable to create an object at this URL using ICreateRow::CreateRow because the server was out of physical storage.

DB_E_NOTCOLLECTION

The provider was unable to create an object with the specified URL because the parent URL is not a collection.

DB_E_NOTFOUND

The provider was unable to create an object with the specified URL because the parent URL does not exist.

DB_E_NOTSUPPORTED

The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid.

DB_E_TIMEOUT

The attempt to bind to the object timed out.

DB_E_RESOURCEEXISTS

The provider was unable to create an object at this URL because an object named by this URL already exists and either the caller did not specify OPENIFEXISTS or OVERWRITE or the provider does not support this behavior on object creation.

REGDB_E_CLASSNOTREG

The root binder was unable to instantiate the provider binder object.

E_FAIL

A provider-specific error occurred.

E_NOINTERFACE

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

The provider does not allow the creation of resources via ICreateRow.

E_UNEXPECTED

ICreateRow::CreateRow is implemented on a row object, ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

ICreateRow::CreateRow provides the ability to create a new object named by a URL and bind it directly to a row, to a rowset, or to a row and a default stream object. If a consumer calls CreateRow on a URL that does not exist and rguid is set to DBGUID_STREAM, both a row and a default stream object are created. Only the stream object may be aggregated. The provider returns the requested interface pointer on the stream object.

The created row object "inherits" the default columns of its container's class. The provider determines what these default columns are. Whether or not to allow creation of a root row object with no inherited columns is provider-specific. For "document source" providers (that is, providers for which the value of DBPROP_DATASOURCE_TYPE is DBPROPVAL_DST_DOCSOURCE), the default columns are the columns of the resource rowset. For example, a new document inherits the default columns of its folder's class, which are the columns of the resource rowset.

Columns may be added by calling IRowSchemaChange::AddColumns. Column values may also be set with IRowChange::SetColumns.

The provider determines what the container, or parent row, is for its hierarchy. Atomic rows (for example, simple documents) are leaf nodes in a hierarchy. Collections are root nodes or intermediate nodes in a hierarchy. For example, a document's container is a folder. Given a row object, a consumer can obtain the parent by obtaining the parent URL and binding to it.

The DBBINDURLFLAG_OPENIFEXISTS and DBBINDURLFLAG_OVERWRITE bind flags may be used to specify behavior when the URL denotes an existing row. If a consumer calls ICreateRow::CreateRow on a URL that exists and does not specify DBBINDURLFLAG_OPENIFEXISTS or DBBINDURLFLAG_OVERWRITE, the provider must return DB_E_RESOURCEEXISTS. The result does not depend on the value of rguid. (The value of rguid could be DBGUID_ROW or DBGUID_STREAM.) Providers are not required to support these flags. If these flags are not supported and the consumer uses them to open a resource, the provider returns DB_E_RESOURCEEXISTS (the same error that is returned if the flag is not specified). These flags are disallowed on IBindResource::Bind. The following table outlines the behavior with and without these two flags.

Method, bind flag	Row exists	Row does not exist
Bind	Open	Fail
CreateRow	Fail	Create
CreateRow, DBBINDURLFLAG_OPENIFEXISTS	Open	Create
CreateRow, DBBINDURLFLAG_OVERWRITE	Create	Create

If the object was created and no warnings are issued, the provider returns S_OK. If the object was created with warnings, the provider returns DB_S_ERRORSOCCURRED. *pdwBindStatus contains any warning flags.

Binding semantics, except where noted, are identical to those of IBindResource::Bind. See the reference entry for IBindResource::Bind for a full discussion of bind flags and additional binding properties.

The scope of the session object associated with the object obtained in this call to ICreateRow::CreateRow is defined by the URL that was requested in the bind call. For more information, see "Direct Binding" in Chapter 8: Binder Objects and Direct Binding, as well as the "Comments" section of the reference entry for IBindResource::Bind.

Note   "Provider Binder Objects" in Chapter 8 discusses case-sensitivity issues for URL-to-provider mapping.

Row creation and binding operations can be performed asynchronously. For more information on asynchronous processing in OLE DB, see Chapter 17: Asynchronous Processing.

The consumer may also support and register the IAuthenticate interface via pAuthenticate to provide information to authenticate the user. If the client registers an IAuthenticate pointer, it will be called if access to the requested resource is denied. The initial attempt to access the resource uses anonymous credentials or the default logged-in credentials. For more information, see IAuthenticate in the MSDN Library documentation.

The caller should convert noncanonical URLs to canonical form before invoking this method. Providers must return URLs in canonical form. For more information, see the Win32 Internet API function InternetCanonicalizeUrl in the Site Builder Network (SBN) Workshop documentation at http://msdn.microsoft.com/workshop/networking/default.asp.

If returning a result code that indicates success, the provider must return it in the following order of precedence:

• If an asynchronous operation was requested, the provider returns DB_S_ASYNCHRONOUS.
• If the creation was successful but at least one warning was issued, the provider returns DB_S_ERRORSOCCURRED.
• Otherwise, the provider returns S_OK.

Providers may own the responsibility for determining the suffix portion of the new URL. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, the caller specifies the path of the new URL in *pwszURL. The provider generates the URL suffix and returns the entire URL in **ppwszNewURL.

1998-2001 Microsoft Corporation. All rights reserved.