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

IScopedOperations::Copy

Copies trees or subtrees, designated by an array of source URLs, to the locations designated by a corresponding array of destination URLs.

HRESULT Copy (
   ULONG             cRows,
   LPCOLESTR         rgpwszSourceURLs[ ],
   LPCOLESTR         rgpwszDestURLs[ ],
   DBCOPYFLAGS       dwCopyFlags,
   IAuthenticate *   pAuthenticate,
   DBSTATUS          rgdwStatus[ ],
   LPOLESTR          rgpwszNewURLs[ ],
   OLECHAR **        ppStringsBuffer
);

Parameters

cRows

[in]
Count of trees and subtrees 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 source trees or subtrees to be copied. If cRows is greater than zero and an element of rgpwszSourceURLs is an empty string (L""), the current row object is copied.

rgpwszDestURLs

[in]
Array of canonical URLs naming the destination trees or subtrees. 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.

dwCopyFlags

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

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.

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.

rgdwStatus

[out]
Array of DBSTATUS status fields indicating whether each element of rgpwszSourceURLs was copied 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.

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: The server cannot service a destination URL, and the caller did not specify the DBCOPY_ALLOW_EMULATION flag. The caller specified the DBCOPY_ALLOW_EMULATION flag, but some portion of the emulated operation failed. The source and destination URLs overlap. The consumer called IDBAsynchStatus::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 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.

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 copy operations succeeded. All elements of rgdwStatus passed to the method are set to DBPROPSTATUS_OK.

DB_S_ASYNCHRONOUS

The method has initiated an asynchronous copy 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 copy operations succeeded, but the provider was unable to allocate ppStringsBuffer.

DB_S_ERRORSOCCURRED

DBCOPY_ATOMIC was not set, and the provider failed to copy from one or more source URL. The caller should examine rgdwStatus to determine which source URLs were not copied 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 copy operations.

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 copied.

DB_E_ERRORSOCCURRED

DBCOPY_ATOMIC was set, and the provider failed to copy one or more source URLs. The caller should examine rgdwStatus to determine which URLs were not copied and why.

DB_E_NOTSUPPORTED

The provider does not support the value of dwCopyFlags.

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 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.