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

OLE DB Programmer's Reference

Moves trees or subtrees that are represented by OLE DB row objects. The trees or subtrees are designated by an array of source URLs and are moved to the locations designated by a corresponding array of destination URLs.

HRESULT Move (    DBCOUNTITEM       cRows,    LPCOLESTR         rgpwszSourceURLs[ ],    LPCOLESTR         rgpwszDestURLs[ ],    DBMOVEFLAGS       dwMoveFlags,    IAuthenticate    *pAuthenticate,    DBSTATUS          rgdwStatus[ ],    LPOLESTR          rgpwszNewURLs[ ],    OLECHAR         **ppStringsBuffer );

Parameters

cRows

[in]
Count of rows named by the rgpwszSourceURLs and rgpwszDestURLs arrays. If cRows is zero, all other arguments are ignored and the method returns S_OK.

rgpwszSourceURLs

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

rgpwszDestURLs

[in]
Array of canonical URLs naming the destination to which the trees or subtrees are to be moved. The elements of rgpwszDestURLs correspond to the elements of rgpwszSourceURLs. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, this array contains URL paths and the provider generates the URL suffixes. If DBPROP_GENERATEURL is DBPROPVAL_GU_NOTSUPPORTED and the caller passes a null value, the provider does not return the absolute URLs of the moved URLs.

dwMoveFlags

[in]
Flags describing additional semantics for the move operation as described in the following table.

Flag value	Description
DBMOVE_ALLOW_EMULATION	If the attempt to move the row fails because the destination URL is on a different server or serviced by a different provider than the source, the provider is requested to attempt to simulate the move using download, upload, and delete operations. When moving resources between providers, this may cause increased latency or data loss due to different provider capabilities.
DBMOVE_ASYNC	The move 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.
DBMOVE_ATOMIC	Either all sources are moved successfully or no sources are moved. Whether all parts of an atomic operation are attempted if one part fails is provider-specific.
DBMOVE_DONT_UPDATE_LINKS	Request the server not to update links contained in an object on a move. If this flag is not specified, the default behavior is to do what the server specifies. By default, IScopedOperations::Move will update links if the server is capable and if the option is turned on. If the server does not have the ability to fix up links or if the option is turned off, this call will still return S_OK.
DBMOVE_REPLACE_EXISTING	The move operation succeeds, even if a target object exists. Without this value, the move will fail if the target object already exists.

pAuthenticate

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

rgdwStatus

[out]
Array of DBSTATUS status fields indicating whether each element of rgpwszSourceURLs was moved to rgpwszDestURLs. 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 to the move operations.

Status field	Description
DBSTATUS_S_OK	Indicates that a tree or subtree was successfully moved.
DBSTATUS_E_CANCELED	The operation was canceled, and the provider did not complete the move operation for this resource.
DBSTATUS_S_CANNOTDELETESOURCE	A tree or subtree was moved to a new location, but the source tree or subtree could not be deleted.
DBSTATUS_E_CANNOTCOMPLETE	The server that owns the source URL cannot complete the operation. The provider may return this error for one of the following reasons: The server cannot service a destination URL, and the caller did not specify the DBMOVE_ALLOW_EMULATION flag. The caller specified the DBMOVE_ALLOW_EMULATION flag, but some portion of the emulated operation failed. The source and destination URLs overlap. The consumer called IDBAsyncStatus::Abort in the middle of the operation.
DBSTATUS_E_DOESNOTEXIST	Indicates that either the source URL or the parent of the destination URL does not exist.
DBSTATUS_E_INVALIDURL	A source or destination URL string contains invalid characters.
DBSTATUS_E_NOTCOLLECTION	The destination URL contained in rgpwszDestURLs did not specify a path or collection as required by the operation.
DBSTATUS_E_OUTOFSPACE	The provider is unable to obtain enough storage space to complete the move operation.
DBSTATUS_E_PERMISSIONDENIED	Unable to access a tree or subtree because of a permissions failure.
DBSTATUS_E_RESOURCEEXISTS	The provider was unable to perform the move because an object already exists at the destination URL and the DBMOVE_REPLACE_EXISTING flag was not set.
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 source or destination URL 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 indicated by a URL.

rgpwszNewURLs

[in/out]
Optional consumer-allocated array of cRows pointers to the provider-assigned and allocated canonical destination URLs. The caller may pass a null value to indicate it does not want the provider to return destination URLs. This parameter should be set to NULL if an error code is returned.

ppStringsBuffer

[out]
A pointer to memory in which to return a pointer to storage for all generated URL strings within a single allocation block. When it is finished working with the URLs, the consumer should free this buffer. Each of the individual string values stored in this buffer is terminated by a null character. If cRows is zero or this method terminates due to an error, the provider sets ppStringsBuffer to a null pointer. If rgpwszNewURLs is a null pointer, the consumer must set ppStringsBuffer to NULL as well.

Return Code

S_OK: All requested move operations succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK.
DB_S_ASYNCHRONOUS: The method has initiated an asynchronous move 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_BUFFERFULL: All move operations succeeded, but the provider was unable to allocate ppStringsBuffer.
DB_S_ERRORSOCCURRED: DBMOVE_ATOMIC was not set, and the provider failed to move one or more source URLs. The caller should examine rgdwStatus to determine which source URLs were not copied from 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 moves.
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 moved.
DB_E_ERRORSOCCURRED: DBMOVE_ATOMIC was set, and the provider failed to move one or more source URLs. The caller should examine rgdwStatus to determine which URLs were not moved and why.
DB_E_NOTSUPPORTED: The provider does not support the value of dwMoveFlags.
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 rgpwszSourceURLs, rgpwszDestURLs, or rgdwStatus is a null pointer.

cRows is not zero, and one of rgpwszNewURLs and ppStringsBuffer, but not both, are null pointers.

cRows is not zero, and an element of rgpwszSourceURLs or rgpwszDestURLs is a null pointer.

E_OUTOFMEMORY

The provider did not have enough memory to complete the operation.

E_UNEXPECTED

ITransaction::Commit, ITransaction::Abort, or IScopedOperations::Delete (on this row) was called, and the object is in a zombie state..

Comments

Providers implementing IScopedOperations on a row must at a minimum support IScopedOperations::Move for source and destination URLs within the tree rooted at the row. It is provider-specific whether source and destination URLs outside the scope of this row can be operated on.

Rows cannot be moved onto themselves. In addition, the destination URL cannot be a descendant of the source URL on a recursive move; if it were, the operation would recurse. If a provider is unable to perform a move operation because the source and destination trees overlap, it returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, as appropriate, and sets the corresponding element of rgdwStatus to DBSTATUS_E_CANNOTCOMPLETE.

When invoking IScopedOperations::Move, a consumer can request asynchronous processing by setting the DBMOVE_ASYNC bit of dwMoveFlags. 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. 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.

Providers may own the responsibility of determining the suffix portion of the destination URLs. If DBPROP_GENERATEURL is DBPROPVAL_GU_SUFFIX, the caller specifies the path of each destination URL in rgpwszDestURLs. The provider generates the URL suffix. If DBPROP_GENERATEURL is DBPROPVAL_GU_NOTSUPPORTED, the provider does not generate destination URLs. The consumer must pass all destination URLs in rgpwszDestURLs. The provider ignores rgpwszNewURLs. In either case, if the caller passes pointers in rgpwszNewURLs and ppStringsBuffer, the provider returns the pointers to the absolute URLs and the URL strings using these arguments. If the consumer does not wish to receive the destination URLs, even if they were generated by a provider who supports DBPROP_GENERATEURL as DBPROPVAL_GU_SUFFIX, the consumer should set both rgpwszNewURLs and ppStringsBuffer to NULL.

If all move operations succeed but the provider is unable to allocate ppStringsBuffer, the provider should return DB_S_BUFFERFULL and set the output arguments rgpwszNewURLs and ppStringsBuffer to NULL.

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