IBindResource::Bind

Article
05/03/2017

Binds to an object named by a URL. When implemented on a row object, binds to a tree-structured namespace, such as a file system directory, named by the URL. Returns a data source, session, rowset, row, command, or stream object.

HRESULT Bind(   
   IUnknown *            pUnkOuter,
   LPCOLESTR             pwszURL,
   DBBINDURLFLAG         dwBindURLFlags,
   REFGUID               rguid,
   REFIID                riid,
   IAuthenticate *       pAuthenticate,
   DBIMPLICITSESSION *   pImplSession,
   DBBINDURLSTATUS *     pdwBindStatus,
   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.

Note

When IBindResource is implemented on an object other than a binder and Bind is requesting a data source or session object, pUnkOuter must be a null pointer because the data source and session objects have already been created.
pwszURL
[in] The canonical URL of the object for which an OLE DB object is to be returned.

dwBindURLFlags
[in] Bitmask of bind flags that control how the OLE DB object is opened.

Flag	Meaning
DBBINDURLFLAG_READ	Open object for reading only. Note At least one of DBBINDURLFLAG_READ and DBBINDURLFLAG_WRITE must be set, either by setting the appropriate bits on dwBindURLFlags or by setting the corresponding bits of DBPROP_INIT_MODE.
DBBINDURLFLAG_WRITE	Open object for writing only. See note above for DBBINDURLFLAG_READ.
DBBINDURLFLAG_READWRITE	Open object for reading and writing. See note above for DBBINDURLFLAG_READ.
DBBINDURLFLAG_SHARE_DENY_READ	Deny others read access. Note Not all providers support all types of DENY semantics. If the provider does not support this type of DENY semantics, the bind will succeed but return DB_S_ERRORSOCCURRED and a status of DBBINDURLSTATUS_S_DENYTYPENOTSUPPORTED. If the provider does not support any type of DENY semantics, the bind will succeed but return DB_S_ERRORSOCCURRED and a status of DBBINDURLSTATUS_S_DENYNOTSUPPORTED.
DBBINDURLFLAG_SHARE_DENY_WRITE	Deny others write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not support this type of DENY semantics.
DBBINDURLFLAG_SHARE_EXCLUSIVE	Deny others read and write access. See the notes for SHARE_DENY_READ for information about the behavior of providers that do not support this type of DENY semantics.
DBBINDURLFLAG_SHARE_DENY_NONE	Do not deny others read or write access (equivalent to the omission of SHARE_DENY_READ and SHARE_DENY_WRITE).
DBBINDURLFLAG_RECURSIVE	Modifies DBBINDURLFLAG_SHARE_*. Propagate sharing restrictions to all objects in the subtree. Has no effect when binding to leaf nodes. Specifying this flag with only DBBINDURLFLAG_SHARE_DENY_NONE (or equivalently, with no SHARE_DENY flags) will result in E_INVALIDARG.
DBBINDURLFLAG_OUTPUT	Bind to the resource's executed output rather than its source. For example, this will retrieve the HTML generated by an ASP file rather than its source. This flag is ignored on binds to collections.
DBBINDURLFLAG_ASYNCHRONOUS	Return immediately and perform the binding on a separate thread. If DBBINDURLFLAG_WAITFORINIT is not specified, this flag affects the behavior of the IBindResource::Bind or ICreateRow::CreateRow call. If DBBINDURLFLAG_WAITFORINIT is specified, this flag affects the behavior of the IDBInitialize::Initialize call. For more information, see the "Comments" section below.
DBBINDURLFLAG_WAITFORINIT	Return an interface supported on an uninitialized object, but do not initiate the bind. Used in the following cases: The object supports IDBInitialize, and the caller must use IDBInitialize::Initialize to initiate the bind. The caller intends to register callback interfaces by querying from the returned interface to IConnectionPointContainer. To poll for status or cancel an operation, the caller requests an IDBAsynchStatus interface. The consumer may ask only for interfaces supported on uninitialized objects. The provider returns E_NOINTERFACE if any other interface is requested. Note When IBindResource is implemented on an object other than a binder (for example, when it is implemented on a session or row object as IScopedOperations, which is derived from IBindResource), this flag is disallowed because the data source object is already initialized.
DBBINDURLFLAG_DELAYFETCHSTREAM	On a bind to a row, overrides the consumer's intent to immediately open the default stream. Absence of this flag is a hint to the provider to instantiate the default stream object and prefetch its contents.
DBBINDURLFLAG_DELAYFETCHCOLUMNS	On a bind to a row, this flag overrides the consumer's intent to immediately access the row's columns. Absence of this flag is a hint to the provider to download or prefetch the row's columns.

Most of the options specified by these flags can also be specified by setting DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS initialization properties. (See "IBindResource::Bind Flags and Initialization Property Flags" below.) If any flags are specified in dwBindURLFlags (that is, dwBindURLFlags does not equal zero), this set of flags overrides any flags that are specified in DBPROP_INIT_MODE or DBPROP_INIT_BINDFLAGS. If dwBindURLFlags is zero, the flags specified in DBPROP_INIT_MODE and DBPROP_INIT_BINDFLAGS are used instead.

If dwBindURLFlags is zero and DBPROP_INIT_MODE is not explicitly set on the bind, the provider returns E_INVALIDARG because one of DBBINDURLFLAG_READ or DBBINDURLFLAG_WRITE was not set. If dwBindURLFlags is zero and DBPROP_INIT_BINDFLAGS is not explicitly set, DBPROP_INIT_BINDFLAGS defaults to zero (no options set).

Note

The sets of flags that can be specified in DBPROP_INIT_MODE and DBPROP_INIT_BINDFLAGS are deliberately disjoint so that flags from both sets can be used in the same call to IBindResource::Bind. Nevertheless, the division of flags between the two properties specified below in "IBindResource::Bind Flags and Initialization Property Flags" must be honored. If the client specifies flags from DBPROP_INIT_MODE in the DBPROP_INIT_BINDFLAGS property, or vice versa, they will be ignored.

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_DSO	Only the following flags may be used: DBBINDURLFLAG_ASYNCHRONOUS DBBINDURLFLAG_READ DBBINDURLFLAG_WAITFORINIT
DBGUID_SESSION	Only the following flag may be used: DBBINDURLFLAG_READ
DBGUID_COMMAND	Only the following flags may be used: DBBINDURLFLAG_READ DBBINDURLFLAG_WAITFORINIT
DBGUID_ROW	No restrictions. All flags are allowed.
DBGUID_ROWSET	The following flags are disallowed: DBBINDURLFLAG_DELAYFETCHCOLUMNS DBBINDURLFLAG_DELAYFETCHSTREAM A consumer may bind to a rowset object, but the behavior is provider-specific.
DBGUID_STREAM	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 one of the following values:
- DBGUID_DSO
- DBGUID_SESSION
- DBGUID_COMMAND
- DBGUID_ROW
- DBGUID_ROWSET
- DBGUID_STREAM
Note

When implemented on a row object, the GUID must be set to one of the following values:

DBGUID_ROW

DBGUID_ROWSET (can be requested only if the row represents a collection)

DBGUID_STREAM
riid
[in] Interface ID of the interface pointer to be returned.
pAuthenticate
[in] Optional pointer to the caller's IAuthenticate interface. 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. If the bind fails and pImplSession is not a null pointer, pImplSession->pSession should be set to NULL. The DBIMPLICITSESSION structure is defined as follows:

typedef struct tagDBIMPLICITSESSION {
   IUnknown   *pUnkOuter;    // [in] Controlling IUnknown
                           //  for session object
   IID *        piid,      // [in] Interface requested
                           //  on session
   IUnknown *   pSession   // [out] The returned session object.
} DBIMPLICITSESSION;

Element	Description
pUnkOuter	If the implicit session object is to be aggregated, pUnkOuter is an interface pointer to the controlling IUnknown. Otherwise, it is a null pointer.
piid	A pointer to the IID of the interface (on the implicit session) on which to return a pointer. Cannot be NULL. If pUnkOuter is not a null pointer, this IID must be IID_IUnknown.
pSession	An interface pointer to the implicit session object returned by the provider. If the session object is aggregated, this is a pointer to the IUnknown interface of the inner object.

Note

IBindResource::Bind 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). When binding to a data source or session object (rguid is DBGUID_DSO or DBGUID_SESSION), the provider ignores pImplSession because no recursive backing session is created. 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 containing warning status values for the requested bind flags. If pdwBindStatus is a null pointer, no status values are returned. If IBindResource::Bind returns a result other than DB_S_ERRORSOCCURRED and pdwBindStatus is not a null pointer, the provider returns DBBINDURLSTATUS_S_OK. The values described in the following table may be returned.

Status value	Description
DBBINDURLSTATUS_S_ DENYNOTSUPPORTED	The bind succeeded, but the provider does not support any DENY semantics. No lock was obtained. If the consumer requires the lock, it should release the object and report that a lock could not be obtained.
DBBINDURLSTATUS_S_ DENYTYPENOTSUPPORTED	The bind succeeded, but the provider does not support the requested kind of DENY semantics. For example, the provider may support only DENY_WRITE or DENY_EXCLUSIVE. No lock was obtained. If the consumer requires the lock type, it should release the object and report that the type of lock could not be obtained.
DBBINDURLSTATUS_S_REDIRECTED	The bind was successful, but the server for the object indicated that its URL has changed. The client should query the RESOURCE_ABSOLUTEPARSENAME column on the returned object to determine the new URL. This column is available on the resource rowset, so this status should be used only by document source providers. (DBPROP_DATASOURCE_TYPE is DBPROPVAL_DST_DOCSOURCE.)
DBBINDURLSTATUS_S_OK	The bind was successful and the status is reported as OK, because the provider returned a result other than DB_S_ERRORSOCCURRED and pdwBindStatus was not a null pointer.

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

Return Code

S_OK
The bind succeeded.
DB_S_ASYNCHRONOUS
The call to IBindResource::Bind has initiated asynchronous binding to the data source, rowset, or row. The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until asynchronous processing completes, the data source, rowset, row, or stream object remains in an uninitialized state.

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 reported 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_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.

IBindResource was implemented on an object other than a binder, rguid was DBGUID_DSO or DBGUID_SESSION, and pUnkOuter was not a null pointer.
DB_E_NOTCOLLECTION
The client requested an object type that is valid only for a collection (such as a rowset), but the resource at the specified URL is not a collection.
DB_E_NOTFOUND
The provider was unable to locate an object named by the specified URL.
DB_E_NOTSUPPORTED
The provider supports direct binding to OLE DB objects but does not support the object type requested in rguid.
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_READONLY
The caller requested write access to a read-only object.
DB_E_RESOURCELOCKED
One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the OLE DB object represented by this URL. If a provider supports extended error information, 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_RESOURCEOUTOFSCOPE
IBindResource is implemented on a session object, and the caller tried to bind to a URL that is not within the scope of this session.
DB_E_TIMEOUT
The attempt to bind to the object timed out.
DB_SEC_E_PERMISSIONDENIED
The caller's authentication context does not permit access to the object.
DB_SEC_E_SAFEMODE_DENIED
The provider was called within a safe mode or context, and pwszURL specified an unsafe URL.
REGDB_E_CLASSNOTREG
The root binder was unable to instantiate the provider binder.
E_FAIL
A provider-specific error occurred.
E_INVALIDARG
pwszURL or ppUnk was null.

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

dwBindURLFlags contained a flag labeled "Modifies DBBINDURLFLAG_*" in the table above but did not contain the flag to be modified.

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.
E_NOINTERFACE
The object did not support the interface specified in riid, or riid was IID_NULL.

The provider binder did not implement IBindResource.
E_UNEXPECTED
IBindResource::Bind is implemented on a row object; ITransaction::Commit or ITransaction::Abort was called; and the object is in a zombie state.

Comments

If the caller binds to a URL in the namespace serviced by a provider but sets rguid to DBGUID_DSO or DBGUID_SESSION, no row or rowset is instantiated or bound. Even if the URL does not name an existing resource, the provider instantiates its data source or session object if needed, sets **ppUnk to the requested interface on the data source or session object, and returns S_OK.

The caller must bind again and set rguid to DBGUID_ROW or DBGUID_ROWSET to obtain the row or rowset, respectively. When binding to a data source object, the returned data source object is initialized using properties as described in "OLE DB Properties and Binding" below. When implemented on the session object, the consumer may bind to the data source or session object, but the existing data source or session object is returned, and the provider ignores pImplSession.

The scope of the session object associated with the object obtained in this call to IBindResource::Bind is defined by the URL that was requested in the bind call. For more information, see Direct Binding in Binder Objects and Direct Binding.

Note

Provider Binder Objects discusses case-sensitivity issues for URL-to-provider mapping.

If the caller binds to a stream (rguid is DBGUID_STREAM), no implicit row is created. To obtain the row object in order to access other columns besides the default stream, the caller must bind again and request the row.

Updatability of the row obtained by this method (whether or not the row exposes IRowChange) depends on the bits of dwBindURLFlags.

To execute a script and open the results of the script, the results must be opened read-only because the contents cannot be changed. If the results are opened for write access, the Bind call will fail with DB_E_READONLY.

When IBindResource is implemented on a provider binder object and a data source object is requested (rguid is DBGUID_DSO), the provider returns an initialized data source unless the DBBINDURLFLAG_WAITFORINIT is set. Providers are required to support DBBINDURLFLAG_WAITFORINIT as a way to obtain an uninitialized data source.

Bind operations can be performed asynchronously. For more information on asynchronous processing in OLE DB, see Asynchronous Processing.

To provide information to authenticate the user, the consumer may also support and register the IAuthenticate interface via pAuthenticate. 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. This can be done by calling the InternetCanonicalizeUrl Win32? Internet API function. For more information, see the discussion of the Win32 Internet API function InternetCanonicalizeUrl in the article "Handling Uniform Resource Locators" in the MSDN Library.

When supporting direct binding to commands, providers are free to return a command in one of the following states:

Initial A command on which no command text has been set, no properties have been set, and which is unprepared.
Unprepared If the provider is able to determine a specific command syntax from the URL (by mapping a URL to an instance, or by encoding the command within the URL), a command on which the command text has been set.

The consumer can infer the state of the command object by calling IColumnsInfo::GetColumnInfo and evaluating the return code. (see Command States in Commands (OLE DB).)

The consumer can view the command text by using ICommandText::GetCommandText.

OLE DB Properties and Binding

The IBindResource interface allows specification of the most common binding options. Additional binding options may be specified by setting OLE DB properties on an IDBBinderProperties pointer associated with the object implementing IBindResource. If a provider does not support a binding option, the provider returns an error on the call to IBindResource::Bind, whether the binding option was set on properties via IDBBinderProperties or was specified as a bind flag on the call to Bind. The root binder does not raise an error when a property is set via IDBBinderProperties.

Two new initialization properties, DBPROP_INIT_LOCKOWNER and DBPROP_INIT_BINDFLAGS, have been added to cover binding semantics that were introduced in OLE DB 2.5. These properties are described in Appendix C: OLE DB Properties. In addition, some existing initialization properties have been modified to accommodate OLE DB 2.5 providers.