Share via

2.2.8.1 SubRequestDataOptionalAttributes

  • Article

The SubRequestDataOptionalAttributes attribute group contains attributes that are used in SubRequestData elements of all types of subrequests. The attributes in SubRequestDataOptionalAttributes are used as input parameters for processing the data associated with subrequests. The definition of the SubRequestDataOptionalAttributes attribute group is as follows:

 <xs:attributeGroup name="SubRequestDataOptionalAttributes">
     <xs:attributeGroup ref="tns:CellSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:CoauthSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:SchemaLockSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:ExclusiveLockSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:EditorsTableSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:FileOperationSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:VersioningSubRequestDataOptionalAttributes"/>
     <xs:attributeGroup ref="tns:PropertiesSubRequestDataOptionalAttributes"/>
     <xs:attribute name="ClientID" type="xs:string" use="optional"/>
     <xs:attribute name="AllowFallbackToExclusive" type="xs:boolean" use="optional" />
     <xs:attribute name="ReleaseLockOnConversionToExclusiveFailure" type="xs:boolean" use="optional"/>
     <xs:attribute name="SchemaLockID" type="xs:string" use="optional" />
     <xs:attribute name="Timeout" type="xs:integer" use="optional" />
     <xs:attribute name="ExclusiveLockID" type="xs:string" use="optional"/>
     <xs:attribute name="BinaryDataSize" type="xs:long" use="optional" />
     <xs:attribute name="AsEditor" type="xs:boolean" use="optional" />
     <xs:attribute name="Key" type="xs:string" use="optional" />
     <xs:attribute name="Value" type="xs:base64Binary" use="optional" /> 
     <xs:attribute name="NewFileName" type="xs:string" use="optional" /> 
     <xs:attribute name="Version" type="tns:FileVersionNumberType" use="optional"/>
     <xs:attribute name="TransitionID" type="tns:guid" use="optional"/>
 </xs:attributeGroup>

CellSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "Cell". This attribute group is defined in section 2.3.3.1.

CoauthSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "Coauth". This attribute group is defined in section 2.3.3.3.

SchemaLockSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "SchemaLock". This attribute group is defined in section 2.3.3.5.

ExclusiveLockSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "ExclusiveLock". This attribute group is defined in section 2.3.3.4.

EditorsTableSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "EditorsTable". This attribute group is defined in section 2.3.3.7.

FileOperationSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "FileOperation". This attribute group is defined in section 2.3.3.8.

VersioningSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "Versioning". This attribute group is defined in section 2.3.3.9.

PropertiesSubRequestDataOptionalAttributes: An attribute group that specifies attributes that MUST be used only for SubRequestData elements whose parent SubRequest element’s Type attribute is set to "Properties". This attribute group is defined in section 2.3.3.10.

ClientID: A string that serves to uniquely identify each client that has access to a shared lock on a coauthorable file.

AllowFallbackToExclusive: A Boolean value that specifies to a protocol server whether a coauthoring subrequest of type "Join coauthoring session" or a schema lock subrequest of type "Get lock" is allowed to fall back to an exclusive lock subrequest when shared locking on the file is not supported. When shared locking on the file is not supported:

  • An AllowFallbackToExclusive attribute value set to true indicates that a coauthoring subrequest of type "Join coauthoring session" or a schema lock subrequest of type "Get lock" is allowed to fall back to an exclusive lock subrequest.

  • An AllowFallbackToExclusive attribute value set to false indicates that a coauthoring subrequest of type "Join coauthoring session" or a schema lock subrequest of type "Get lock" is not allowed to fall back to an exclusive lock subrequest.

ReleaseLockOnConversionToExclusiveFailure: A Boolean value that specifies to the protocol server whether the server is allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker when all of the following conditions are true:

  • Either the type of coauthoring subrequest is "Convert to an exclusive lock" or the type of the schema lock subrequest is "Convert to an Exclusive Lock"

  • The conversion to an exclusive lock failed.

When all the preceding conditions are true:

  • A ReleaseLockOnConversionToExclusiveFailure attribute set to true indicates that the protocol server is allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker.

  • A ReleaseLockOnConversionToExclusiveFailure attribute set to a value of false indicates that the protocol server is not allowed to remove the ClientID entry associated with the current client in the File coauthoring tracker.

SchemaLockID: A string that is globally unique and known among all protocol clients that share the same protocol version. This schema lock identifier is used by the protocol server to block other clients that have different schema lock identifiers. After a protocol client is able to get a shared lock for a file with a specific schema lock identifier, the server MUST allow only other protocol clients that specify the same schema lock identifier to share the file lock. The protocol server ensures that at any instant of time, only clients having the same schema lock identifier can lock the file. After all the protocol clients have released their lock for that file, the protocol server MUST allow a protocol client with a different schema lock identifier to get a shared lock for that file. The string "29358EC1-E813-4793-8E70-ED0344E7B73C" has been reserved for use for this attribute.<24>

Timeout: An integer that specifies the time, in seconds, after which the shared lock or exclusive lock for a specific file expires for a specific protocol client. When more than one client is editing the file, the protocol server MUST maintain a separate timeout value for each client.

ExclusiveLockID: A string that serves as a unique identifier for the exclusive lock on the file.

BinaryDataSize: A long value that specifies the number of bytes of data in the SubRequestData element of a cell subrequest. It MUST be present in the SubRequestData element of a cell subrequest. The BinaryDataSize attribute MUST be set to a value ranging from 1 through 9,223,372,036,854,775,807. It is ignored by the server. The SubRequestData element is defined in section 2.2.3.9.

If text is specified in the SubRequestData element, that text is base64 binary encoded data and indicates if the cell subrequest is for the upload or download of data in a partition. This is passed to the component on the protocol server responsible for implementing the protocols as specified in [MS-FSSHTTPB] section 3.1.4.2 and [MS-FSSHTTPB] section 3.1.4.4. The encoded data is opaque to the protocol.

AsEditor: A Boolean value that specifies to the protocol server whether the protocol client is opening the document as an editor or as a reader. The server MUST NOT allow a user with read-only access to join the editing session as a reader. The AsEditor attribute MUST be specified in all of the following types of editors table subrequests:

  • Join editing session

  • Refresh editing session

The types of editors table subrequests are defined in section 2.3.3.7.

Key: A string that specifies a unique key in an arbitrary key/value pair of the protocol client’s choice. The server stores this key/value pair for that particular file for that specific protocol client. These pairs are visible to other clients editing or reading the same document. The Key attribute MUST be specified in all of the following types of editors table subrequests:

  • Update Editor Metadata

  • Remove Editor Metadata

The types of editors table subrequests are defined in section 2.3.3.7.

Value: A binary value that is associated with a key in an arbitrary key/value pair of the protocol client’s choice. The server stores this key/value pair for that particular file for that specific protocol client. These pairs are visible to other clients editing or reading the same document. The Value attribute MUST be specified in an editors table subrequest type of "Update Editor Metadata".

The types of editors table subrequests are defined in section 2.3.3.7.

NewFileName: This string MUST only contain a valid file name, with no relative path. The NewFileName attribute MUST be sent only when the file operation subrequest has a FileOperationSubRequestType attribute set to "Rename".

Version: A FileVersionNumberType that serves to uniquely identify a version of a file on the server. FileVersionNumberType is defined in section 2.2.5.15. Version MUST be specified when the versioning subrequest has a VersioningSubRequestType attribute set to "RestoreVersion". The types of versioning subrequest are defined in section 2.3.3.9.

TransitionID: A guid that specifies the unique file identifier for that file in the protocol server.