IScopedOperations::Delete | Microsoft OLE DB 2.0 Programmers Reference and Data Access SDK (Microsoft Professional Editions)

OLE DB Programmer's Reference

Deletes the trees or subtrees named by an array of URLs. The URLs must all be within the scope of the current row object.

HRESULT Delete (    DBCOUNTITEM     cRows,    LPCOLESTR       rgpwszURLs[ ],    DBDELETEFLAGS   dwDeleteFlags,    DBSTATUS        rgdwStatus[ ] );

Parameters

cRows

[in]
Count of trees and subtrees named by the rgpwszURLs array. If cRows is zero, all other arguments are ignored and the method returns S_OK.

rgpwszURLs

[in]
Array of canonical URLs naming the trees or subtrees to be deleted. If cRows is greater than zero and an element of rgpwszURLs is an empty string (L""), the current row object is deleted.

dwDeleteFlags

[in]
A bitmask of flags that control additional semantics for the delete operation, as described in the following table.

Flag value	Description
DBDELETE_ASYNC	The delete operation is performed asynchronously. Progress and notifications are available via IDBAsynchStatus and IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. If DBDELETE_ASYNC is not specified, the operation is synchronous. A value of 0 is allowed.
DBDELETE_ATOMIC	Either all trees and subtrees are deleted or none are deleted. Whether all parts of an atomic operation are attempted if one part fails is provider-specific. If DBDELETE_ATOMIC is not specified, the operation is non-atomic. A value of 0 is allowed.

rgdwStatus

[out]
Array of DBSTATUS status fields indicating, for each element of rgpwszURLs, whether the tree or subtree named by that element was deleted. Whether the status fields are set for return codes other than DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED is provider-specific. The status fields described in the following table apply.

Status field	Description
DBSTATUS_S_OK	Indicates that the tree or subtree was deleted.
DBSTATUS_E_CANCELED	The operation was canceled, and the provider did not complete the delete operation for this resource.
DBSTATUS_E_DOESNOTEXIST	Indicates that the tree or subtree named by this URL did not exist.
DBSTATUS_E_INVALIDURL	A URL string contained invalid characters.
DBSTATUS_E_PERMISSIONDENIED	Unable to access a tree or subtree due to a permissions failure.
DBSTATUS_E_RESOURCELOCKED	One or more other processes using the DBBINDURLFLAG_SHARE_* flag have locked the object named by this URL. If supported, IErrorInfo::GetDescription returns a string consisting of user names separated by semicolons. These are the names of the users who have the object locked.
DBSTATUS_E_RESOURCEOUTOFSCOPE	A URL to be deleted is outside the scope of the current row object.
DBSTATUS_E_UNAVAILABLE	An atomic operation failed to complete, and status was unavailable for this part of the operation.
DBSTATUS_E_VOLUMENOTFOUND	The provider is unable to locate the storage volume named by a URL.

Return Code

S_OK: All requested deletions succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK.
DB_S_ASYNCHRONOUS: The method has initiated an asynchronous delete operation. The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing.
DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.
DB_S_ERRORSOCCURRED: DBDELETE_ATOMIC was not set, and the provider failed to delete one or more URLs. The caller should examine rgdwStatus to determine which URLs were not deleted and why.
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 deletions.
DB_E_CANCELED: The operation was called synchronously and, before it completed, was canceled by a call to IDBAsynchStatus::Abort. The consumer can examine rgdwStatus for a status of DBSTATUS_E_CANCELED to determine whether an individual URL was deleted.
DB_E_ERRORSOCCURRED: DBDELETE_ATOMIC was set, and the provider failed to delete one or more URLs. The caller should examine rgdwStatus to determine which URLs were not deleted and why.
DB_E_NOTSUPPORTED: The provider does not support the value of dwDeleteFlags.
DB_SEC_E_SAFEMODE_DENIED: The provider was called within a safe mode or context, and one of the URLs specified was unsafe.

Note When failing one of multiple operations, the status of the failing operation is DBSTATUS_E_CANNOTCOMPLETE and the status of any remaining, uncompleted operations is DBSTATUS_E_UNAVAILABLE.

E_FAIL: A provider-specific error occurred.
E_INVALIDARG: cRows is not zero, and rgpwszURLs or rgdwStatus is a null pointer.
cRows is not zero, and an element of rgpwszURLs is a null pointer.
E_OUTOFMEMORY: The provider did not have enough memory to complete the operation.
E_UNEXPECTED: ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

When the current row object is deleted, it enters a zombie state, and the provider should return E_UNEXPECTED for any other method call on the row object other than Release.

Providers that implement IScopedOperations on a row must at a minimum support Delete for URLs within the tree rooted at the row. It is provider-specific whether URLs outside the scope of this row can be operated on.

If IScopedOperations::Delete is called with an empty string for the URL or for the absolute URL of the object that is bound, the object is deleted. The only operation the consumer may then perform on the object is IUnknown::Release. All other methods on all other interfaces might return E_UNEXPECTED. (The exact behavior is provider-dependent.)

IScopedOperations::Delete can affect currently open rowset and row objects when the underlying object is deleted. Binding to a URL that has been deleted or moved will result in DB_E_NOTFOUND. Other methods that cause the provider to access the underlying data store will result in similar errors or DB_E_DELETEDROW. Refer to the return codes for each method.

When calling IScopedOperations::Delete, a consumer can request asynchronous processing by setting the DELETE_ASYNC bit of dwDeleteFlags. For more information on asynchronous processing in OLE DB, see Chapter 17: Asynchronous Processing.

The caller should convert noncanonical URLs to canonical form before invoking this method. 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.