Share via

3.1.4.2 CopyIntoItems

  • Article

The CopyIntoItems operation copies a file to the destination server. This operation can be used when the destination server is different from the source location.

 <wsdl:operation name="CopyIntoItems">
     <wsdl:input message="tns:CopyIntoItemsSoapIn" />
     <wsdl:output message="tns:CopyIntoItemsSoapOut" />
 </wsdl:operation>

The protocol client sends a CopyIntoItemsSoapIn request message (section 3.1.4.2.1.1) and the protocol server responds with a CopyIntoItemsSoapOut response message (section 3.1.4.2.1.2 ) as follows.

The protocol client prepares a request that contains the content of the file, the file metadata as a collection of fields, the source location from which the file is being copied, and the collection of destination locations on the destination server to which the file is to be copied.

The destination server proceeds with the operation by attempting to create new files or to update existing files at all of the locations that are specified in the destination locations collection.

The protocol server MUST report the status of the operation inside the Results collection (see section 3.1.4.2.2.2) for each destination location that is passed. The CopyResult element in the Results collection MUST be in the same order as the items in the destination locations collection. The DestinationUrl attribute of the CopyResult element (section 2.2.4.2) that corresponds to the destination location MUST be set to the value of the destination location.

If the protocol server detects a Value attribute that is not one of the valid values of the FieldInformation elements of the Fields collection (see section 3.1.4.2.2.1), the protocol server MUST report a failure of the operation by setting the ErrorCode attribute to "Unknown" for each CopyResult element, and provide a string value that denotes the error in the ErrorMessage attribute. The validity of the value of a field is derived from the Type attribute value and varies according to the base type of the field. Base field types are defined in [MS-WSSTS] section 2.3.1.

  • If the value of a field is empty and the base field type is "Integer", "Number", "Boolean", or "DateTime", the Value attribute MUST NOT be present.

  • If the value of a field is empty and the base field type is something other than "Integer", "Number", "Boolean", or "DateTime", the Value attribute MUST either be present and have an empty value, or not be present. A protocol server MUST accept both choices as an empty value.

  • If the field is not empty, the Value attribute MUST be present and contain a non-empty Unicode string that represents the value of the field.

  • If the type is "DateTime", the value MUST be a UTC value.

The protocol server MUST attempt to copy the file to all destination locations that are specified in the request.

If the file on the protocol server is checked out and cannot be updated, the protocol server MUST report a failure of the copy operation by setting the value of the ErrorCode attribute of the corresponding CopyResult element to "DestinationCheckedOut", and provide a string value that specifies the error in the ErrorMessage attribute.

If the destination location is part of a Meeting Workspace site, the protocol server MUST report a failure of the copy operation by setting the value of the ErrorCode attribute of the corresponding CopyResult element to "DestinationMWS", and provide a string value that specifies the error in the ErrorMessage attribute. The protocol server MAY proceed with the copy operation to the destination location.

The file that is created or updated as a result of the operation MUST have the same content as specified in the Stream element of the CopyIntoItemsSoapIn message. If the file cannot be created at the given destination location or the content of the file cannot be set to the value specified in the Stream element based on permission settings for example, the protocol server MUST report a failure for this destination location by setting the ErrorCode attribute of the corresponding CopyResult element to "Unknown" and provide a string value that describes the error in the ErrorMessage attribute.

The protocol server MUST attempt to update the metadata of the file that is created or updated as a result of the operation to match the metadata that is passed in the Fields element of the CopyIntoItemsSoapIn message. The field for the source location MUST be set to the value of SourceUrl element. Failure to set or update some or all of the fields MUST NOT be treated as a failure to copy the file and MUST be reported as success for the given destination location.<4>

For the CopyIntoItemsLocal method, see section 3.1.4.3.