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
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. |
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:
|
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. |
Return Code
DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.
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.
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.
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.
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.
1998-2001 Microsoft Corporation. All rights reserved.