OLE DB Programmer's Reference |
Copies trees or subtrees, designated by an array of source URLs, to the locations designated by a corresponding array of destination URLs.
HRESULT Copy ( DBCOUNTITEM cRows, LPCOLESTR rgpwszSourceURLs[ ], LPCOLESTR rgpwszDestURLs[ ], DBCOPYFLAGS dwCopyFlags, IAuthenticate *pAuthenticate, DBSTATUS rgdwStatus[ ], LPOLESTR rgpwszNewURLs[ ], OLECHAR **ppStringsBuffer );
Parameters
Note Some of these flags are similar to the flags used in the Microsoft Windows CopyFileEx file I/O function.
Flag value | Description |
---|---|
DBCOPY_ALLOW_EMULATION | If this flag is set and the attempt to copy the tree or subtree 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 copy using download and upload operations. When moving entities between providers, this may cause increased latency or data loss due to different provider capabilities. |
DBCOPY_ASYNC | The copy operation is performed asynchronously. Progress and notifications are available by using IDBAsynchStatus and IDBAsynchNotify callbacks. Implementations that do not support asynchronous behavior should block and return a warning. |
DBCOPY_ATOMIC | Either all trees or subtrees are copied successfully or none are copied. Whether all parts of an atomic operation are attempted if one part fails is provider-specific. |
DBCOPY_NON_RECURSIVE | If this flag is set, only the root node of the tree is copied; no child nodes are copied. |
DBCOPY_REPLACE_EXISTING | The copy operation succeeds even if a target object already exists at the destination URL. Otherwise, the copy fails if a target object already exists. |
Status field | Description |
---|---|
DBSTATUS_S_OK | Indicates that the tree or subtree was successfully copied. |
DBSTATUS_E_CANCELED | The operation was canceled, and the provider did not complete the copy operation for this resource. |
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 copy 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 copy because an object already exists at the destination URL and the DBCOPY_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 that implement IScopedOperations on a row must at a minimum support IScopedOperations::Copy 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 copied onto themselves. In addition, the destination URL cannot be a descendant of the source URL on a recursive copy; if it were, the operation would recurse. If a provider is unable to perform a copy 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 calling IScopedOperations::Copy, a consumer can request asynchronous processing by setting the DBCOPY_ASYNC bit of dwCopyFlags. For more information on asynchronous processing in OLE DB, see Chapter 17: Asynchronous Processing.
The caller should convert noncanonical URLs to canonical form before calling 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 to 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 copy 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.
1998-2001 Microsoft Corporation. All rights reserved.