MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Interfaces

IBindResource::Bind

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.

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.

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
DBGUID_STREAM

Note   DBGUID_ROWSET can be requested only if the row represents a collection.

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;

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.

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_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 Chapter 8, "Binder Objects and Direct Binding."

Note   "Provider Binder Objects" in Chapter 8 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 Chapter 17, "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 Win32 Internet API function InternetCanonicalizeUrl in the Site Builder Network (SBN) Workshop documentation at http://msdn.microsoft.com/workshop/networking/default.asp.

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 Chapter 3, "Commands.")

The consumer can check 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 are new in OLE DB 2.5. These new properties are described in Appendix C, "OLE DB Properties." In addition, some existing initialization properties have slightly different meanings for OLE DB 2.5 providers than for traditional OLE DB providers.

IBindResource::Bind Flags and Initialization Property Flags

The following table shows the mapping between flags in the IBindResource::Bind call and flags in the DBPROP_INIT_MODE and DBPROP_INIT_BINDFLAGS initialization properties.

If a consumer sets the DBPROP_INIT_MODE and/or DBPROP_INIT_BINDFLAGS properties when using IBindResource::Bind, the flag values specified in the Bind call override those specified in the properties.