3.1.4.4 AddToShadowCopySet (Opnum 3)

  • Article

The AddToShadowCopySet method adds a share to an existing shadow copy set.

 DWORD AddToShadowCopySet(
         [in] handle_t hBinding,
         [in] GUID ClientShadowCopyId,
         [in] GUID ShadowCopySetId,
         [in] [string] LPWSTR ShareName,
         [out] GUID* pShadowCopyId);
 

hBinding:  An RPC binding handle (as defined in [C706]).

ClientShadowCopyId: The GUID for the shadow copy, assigned by the client.<8>

ShadowCopySetId: The GUID of the shadow copy set to which ShareName is to be added. This GUID is assigned by the server.

ShareName: The name of the share, in UNC format, for which a shadow copy is required.

pShadowCopyId: The GUID of the shadow copy associated with the share.

Return Values: The method returns one of the values specified in section 2.2.4. The most common error codes are listed in the following table:

Return value/code

Description

0x80070005

E_ACCESSDENIED

The caller does not have permission to perform the operation.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x8004230C

FSRVP_E_NOT_SUPPORTED

The file store that contains the share to be shadow copied is not supported by the server.

0x80042301

FSRVP_E_BAD_STATE

The method call is invalid because of the state of the server.

0x8004230D

FSRVP_E_OBJECT_ALREADY_EXISTS

The object already exists.

0x80042501

FSRVP_E_SHADOWCOPYSET_ID_MISMATCH

The provided ShadowCopySetId does not exist.

The server MUST verify that the share identified by ShareName exists on the server, in an implementation-specific manner. If the share does not exist, the server MUST fail the call with FSRVP_E_OBJECT_NOT_FOUND.

The server MUST identify the object store on which the ShareName is hosted, in an implementation-defined manner. If the object store contains mount points below the share root directory, or if the object store is not supported by the underlying shadow copy utility, the server MUST fail the call with FSRVP_E_NOT_SUPPORTED.

The server MUST look up the ShadowCopySet from GlobalShadowCopysetTable using the index ShadowCopySetId. If no shadow copy set is found, the server MUST fail the call with FSRVP_E_SHADOWCOPYSET_ID_MISMATCH.

If ShadowCopySet.Status is not "Started" or "Added", the server MUST fail the call with FSRVP_E_BAD_STATE.

The server MUST stop the Message Sequence Timer as specified in section 3.1.2.

The server MUST look up the ShadowCopy in ShadowCopySet.ShadowCopyList where ShadowCopy.VolumeName matches the file store (typically a file system) on which the share identified by ShareName is hosted. If an entry is found, the server MUST fail the call with FSRVP_E_OBJECT_ALREADY_EXISTS and start the Message Sequence Timer as specified in section 3.1.2 with a time-out value of 180 seconds. If no entry is found, the server MUST create a new ShadowCopy object, as specified in section 3.1.1.3, with the following values, and insert it into the ShadowCopySet:

  • ShadowCopyId is set to a unique GUID generated by the server.

  • VolumeName is set to an implementation-specific value identifying the file store on the server that is exposed through the share.

  • CreationTimeStamp is set to the current time.

  • ShareMappingList is set to an empty list.

The server MUST create a new MappedShare object (as specified in section 3.1.1.4) with the following values, and insert it into ShadowCopy.ShareMappingList.

  • ShareName is set to ShareName.

  • ShadowCopyShareName is set to an empty string.

  • IsExposed is set to FALSE.

The server MUST set ShadowCopySet.Status to "Added".

The server MUST set pShadowCopyId to ShadowCopy.ShadowCopyId, start the Message Sequence Timer (as specified in section 3.1.2) with a time-out value of 1800 seconds, and return ZERO to the caller.