Share via

2.3.1.5 CoauthSubRequestDataType

  • Article

The CoauthSubRequestDataType complex type contains information about data or input parameters used in processing a coauthoring subrequest. The SchemaLockID attribute and the CoauthRequestType attribute specified in the CoauthSubRequestDataOptionalAttributes attribute group MUST both be specified for a coauthoring subrequest. The SchemaLockID attribute and the CoauthRequestType attribute is specified as part of the SubRequestData element associated with a coauthoring SubRequest element. CoauthSubRequestDataOptionalAttributes is defined in section 2.3.3.3. If the CoauthRequestType attribute is not provided, an error code SHOULD<28> be returned. If other attributes are not provided, an "InvalidArgument" error code MUST be returned as part of the SubResponseData element associated with the coauthoring subresponse.

 <xs:complexType name="CoauthSubRequestDataType">
     <xs:attributeGroup ref="tns:CoauthSubRequestDataOptionalAttributes" />
     <xs:attribute name="ClientID" type="xs:string" use="required"/>
     <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="required" />
     <xs:attribute name="Timeout" type="xs:integer" use="optional" />
     <xs:attribute name="ExclusiveLockID" type="xs:string" use="optional"/>
 </xs:complexType>

CoauthSubRequestDataOptionalAttributes: An attribute group that specifies the set of attributes that is provided for a SubRequestData element whose parent SubRequest element’s Type attribute is set to "Coauth". The attributes CoauthSubRequestDataOptionalAttributes is defined in section 2.3.3.3.

ClientID: A string that serves to uniquely identify each client that has access to a shared lock on a coauthorable file. ClientID MUST be specified on all types of coauthoring subrequests. The types of coauthoring subrequest are defined in section 2.3.3.3.

AllowFallbackToExclusive: A Boolean value that specifies to a protocol server whether a coauthoring subrequest is allowed to fall back to an exclusive lock subrequest provided 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 is allowed to fall back to an exclusive lock subrequest.

  • An AllowFallbackToExclusive attribute value set to false indicates that a coauthoring subrequest is not allowed to fall back to an exclusive lock subrequest.

The AllowFallbackToExclusive attribute is specified as part of a coauthoring subrequest of type "Join coauthoring session". The types of coauthoring subrequest are defined in section 2.3.3.3.

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, provided that all of the following conditions are true:

  • The type of coauthoring subrequest is "Convert to an exclusive lock".

  • The conversion to an exclusive lock failed.

When all the preceding conditions are true, the following apply:

  • A ReleaseLockOnConversionToExclusiveFailure attribute set to a value of 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.

  • A ReleaseLockOnConversionToExclusiveFailure attribute MUST be sent only when the coauthoring subrequest type is set to "Convert to exclusive lock". The types of coauthoring subrequest are defined in section 2.3.3.3. The File coauthoring tracker is defined in section 3.1.1.

SchemaLockID: A string that is globally unique and known among all protocol clients that share the same protocol version. The schema lock identifier is used by the protocol server to block other clients with different schema 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 SchemaLockID attribute MUST be sent on all types of coauthoring subrequests. The string "29358EC1-E813-4793-8E70-ED0344E7B73C" has been reserved for use for this attribute.<29>

Timeout: An integer that specifies the time, in seconds, after which the shared lock for that particular file will expire for that specific protocol client. The Timeout attribute MUST be set to a value ranging from 3,600 to 120,000. When the Timeout attribute is set to a value ranging from 60 to 3600, the server also returns success but sets Timeout to an implementation-specific default value. When more than one client is editing the file, the protocol server MUST maintain a separate timeout value for each client in the File coauthoring tracker. The File coauthoring tracker is defined in section 3.1.1. The client’s timeout on a shared lock for a file is refreshed by sending a coauthoring subrequest of type, "Refresh coauthoring session". The Timeout attribute MUST be sent in the following types of coauthoring subrequests:

  • Join coauthoring session

  • Refresh coauthoring session

  • Convert to exclusive lock

The types of coauthoring subrequests are defined in section 2.3.3.3.

ExclusiveLockID: A string that serves as a unique identifier for the exclusive lock on the file when a coauthoring request of type "Convert to exclusive lock" is requested. ExclusiveLockID MUST be sent when the type of the coauthoring subrequest is "Convert to exclusive lock" or "Join coauthoring session" and the AllowFallbackToExclusive attribute is set to true.