3.1.4.5 CopyKey (Opnum 7)

  • Article

The CopyKey method copies or moves a node, including its subnodes and data, to a specified destination. The copied or moved node becomes a subnode of the destination node.

 HRESULT CopyKey(
   [in] METADATA_HANDLE hMDSourceHandle,
   [unique, in, string] LPCWSTR pszMDSourcePath,
   [in] METADATA_HANDLE hMDDestHandle,
   [unique, in, string] LPCWSTR pszMDDestPath,
   [in] BOOL bMDOverwriteFlag,
   [in] BOOL bMDCopyFlag
 );

hMDSourceHandle: An unsigned 32-bit integer value containing an open metabase handle specifying the source node to be copied or moved.

pszMDSourcePath: A pointer to a Unicode string that contains the path of the node to be copied or moved relative to the path of the hMDSourceHandle parameter.

hMDDestHandle: An unsigned 32-bit integer value containing an open metabase handle specifying the destination node of the moved or copied metabase key.

pszMDDestPath: A pointer to a string that contains the path of the new or moved node, relative to the hMDDestHandle parameter.

bMDOverwriteFlag: A Boolean value that determine the behavior if a node with the same name as source is already a child of destination node. If TRUE, the existing node and all its data and children are deleted prior to copying or moving the source. If FALSE, the existing node, data, and children remain, and the source is merged with that data. In cases of data conflicts, the source data overwrites the destination data.

bMDCopyFlag: A Boolean value that specifies whether to copy or move the specified node. If TRUE, the node is copied. If FALSE, the node is moved, and the source node is deleted from its original location.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it failed. If the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a Win32 error code in the lower 16 bits. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF].

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070003

ERROR_PATH_NOT_FOUND

The system cannot find the path specified.

0x80070005

E_ACCESSDENIED

General access denied error.

0x80070006

ERROR_INVALID_HANDLE

The handle is invalid.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

The opnum field value for this method is 7.

When processing this call, the server MUST do the following:

  • Check the source handle parameter. This handle is valid if it is either the master root handle or a handle returned from a previous OpenKey call. If the handle is invalid, return ERROR_INVALID_HANDLE.

  • Check the destination handle parameter. This handle is valid if it is either the master root handle or a handle returned from a previous OpenKey call. If the handle is invalid, return ERROR_INVALID_HANDLE.

  • The server SHOULD check whether the source and destination handles are opened with the correct access mask. The destination handle, hMDDestHandle, SHOULD be opened with write access. If bMDCopyFlag is TRUE the source handle, hMDSourceHandle, SHOULD be opened with write access, otherwise it SHOULD be opened with read access. If the handles were not opened with the correct access, return E_ACCESSDENIED.<5>

  • Check whether the source relative path points to the existing node. If not, return ERROR_PATH_NOT_FOUND.

  • Check whether the destination relative path has the right syntax and length. If not, return an error.

  • Check if the destination node exists. If it is true, check whether the overwrite parameter is set to TRUE. If it is FALSE, then merge destination data with source data. When there is a conflict in this merge, take the source data.

  • If the destination node does not exist, add a new node to the tree that has the resultant path as a combined path of destination parent node and destination relative path. If any intermediate nodes are required, the server creates these nodes. Copy all data from the source path to the destination path.

  • If the copy flag is set to FALSE, delete the source node.