3.1 Lists Soap Server Details
3.1.4 Message Processing Events and Sequencing Rules
3.1.4.30 UpdateList
The UpdateList operation is used to update list properties and add, remove, or update fields.
<wsdl:operation name="UpdateList">
<wsdl:input message="UpdateListSoapIn" />
<wsdl:output message="UpdateListSoapOut" />
</wsdl:operation>
The protocol client sends an UpdateListSoapIn request message (section 3.1.4.30.1.1), and the server MUST respond with an UpdateListSoapOut response message (section 3.1.4.30.1.2), as follows:
1. If the specified listName is a valid GUID and corresponds to the identification of a list on the site, use that list.
2. If the specified listName is not a valid GUID or does not correspond to the identification of a list on the site, check if the listName corresponds to the list title of a list on the site and if so, use that list.
3. If listName does not correspond to a list from either of these checks, the protocol server SHOULD<78> return a SOAP fault with error code 0x82000006. This indicates that the list does not exist or might have been deleted by another user.
4. If the listVersion is null, the list MUST be updated and the protocol server MUST return an UpdateListResponse element.
5. If the listVersion string cannot be converted to an integer, the protocol server MUST return a SOAP fault. There is no error code for this fault.
6. If the listVersion string is numeric but not within the range of an unsigned 32-bit integer, this operation MUST return a SOAP fault. There is no error code for this fault.
7. If the listVersion does not match the version of the list, the protocol server MUST return a SOAP fault with error code 0x81020015. This indicates that the list changes are in conflict with those made by another user.
3.1.4.30.1 Messages
The following table summarizes the set of WSDL message definitions that are specific to this operation.
Message Description
UpdateListSoapIn The request to update list properties and add, remove, or update fields.
UpdateListSoapOut The response to a request to update list properties and add, remove, or update fields.
3.1.4.30.1.1 UpdateListSoapIn
The UpdateListSoapIn message is the request that contains required parameters for the UpdateList operation (section 3.1.4.30).
The SOAP action value of the message is defined as follows:
http://schemas.microsoft.com/sharepoint/soap/UpdateList
The SOAP body contains an UpdateList element (section 3.1.4.30.2.1).
3.1.4.30.1.2 UpdateListSoapOut
The UpdateListSoapOut message is the response that contains the results returned by the UpdateList operation (section 3.1.4.30).
The SOAP action value of the message is defined as follows:
http://schemas.microsoft.com/sharepoint/soap/UpdateList
The SOAP body contains an UpdateListResponse element (section 3.1.4.30.2.2).
3.1.4.30.2 Elements
The following table summarizes the XML schema element definitions that are specific to this operation.
Element Description
UpdateList The request to update list properties and add, remove, or update fields.
UpdateListResponse Contains the response to a request to update list properties and add, remove, or update fields.
3.1.4.30.2.1 UpdateList
The UpdateList element specifies the details for updating list properties and adding, removing, or updating fields.
<s:element name="UpdateList"> <s:complexType>
<s:sequence>
<s:element name="listName" type="s:string" minOccurs="0"/>
<s:element name="listProperties" minOccurs="0">
<s:complexType mixed="true">
<s:sequence>
<s:element name="List" minOccurs="0">
<s:complexType>
<s:sequence>
<s:element name="Validation"
minOccurs="0">
<s:complexType>
<s:attribute name="Message" type="s:string" use="optional" />
</s:complexType>
</s:element>
</s:sequence>
<s:attribute name="AllowMultiResponses" type="core:TRUEFALSE" />
<s:attribute name="Description" type="s:string" />
<s:attribute name="Direction" type="s:string" />
<s:attribute name="EnableAssignToEmail" type="core:TRUEFALSE" />
<s:attribute name="EnableAttachments" type="core:TRUEFALSE" />
<s:attribute name="EnableModeration" type="core:TRUEFALSE" />
<s:attribute name="EnableVersioning" type="core:TRUEFALSE" />
<s:attribute name="EnforceDataValidation" type="core:TRUEFALSE"
use="optional"/>
<s:attribute name="Hidden" type="core:TRUEFALSE" />
<s:attribute name="MultipleDataList" type="core:TRUEFALSE" />
<s:attribute name="Ordered" type="core:TRUEFALSE" />
<s:attribute name="PreserveEmptyValues" type="core:TRUEFALSE" />
<s:attribute name="ShowUser" type="core:TRUEFALSE" />
<s:attribute name="StrictTypeCoercion" type="core:TRUEFALSE" />
<s:attribute name="Title" type="s:string" />
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
<s:element name="newFields" type="tns:UpdateListFieldsRequest"
minOccurs="0" />
<s:element name="updateFields" type="tns:UpdateListFieldsRequest"
minOccurs="0" />
<s:element name="deleteFields" type="tns:UpdateListFieldsRequest"
minOccurs="0" />
<s:element name="listVersion" type="s:string" minOccurs="0"/>
</s:sequence>
</s:complexType>
</s:element>
listName: The GUID, or the list title, of the list from which to update properties and fields.
listProperties: The properties of the specified list.
Validation: An expression, as specified by [MS-WSSTS] section 2.9. Each data-reference in the expression MUST correspond to a valid DisplayName attribute of a field (2) in the current list. If present, it MUST not be longer than 1024 characters.
Validation.Message: A message used to indicate that validation was not satisfied. If present, it MUST not be longer than 1024 characters.
Attribute Description
AllowMultiResponses Specifies whether multiple responses are allowed for a given user when the list is a survey list. The value MUST be ignored when the list is not a survey list.
Description A string that contains the description for the list.
Direction A string that MUST contain one of the following values: "LTR" if the reading order is left-to-right, "RTL" if it is right-to-left, or "None". If
"None", the default value is taken from the list template.
EnableAssignedToEmail TRUE to enable assigned-to e-mail for a list of type issues list.
EnableAttachments TRUE to enable attachments to items in the list. Does not apply to document libraries.
EnableModeration TRUE to enable content approval for the list.
EnableVersioning TRUE to enable version control for the list.
EnforceDataValidation TRUE if the protocol server SHOULD enforce the field properties that limit the data values that can be stored in that field.
Attribute Description
Hidden TRUE to hide the list so that it does not appear on the Documents and Lists page, Quick Launch bar, Modify Site Content page, or Add Column page as an option for lookup fields.
MultipleDataList TRUE to specify that the list in a meeting workspace site contains data for multiple meeting instances within the site.
Ordered TRUE to specify that the option to allow users to reorder items in the list is available on the edit view page for the list.
PreserveEmptyValues TRUE if Null values are preserved for expression evaluation. FALSE if there are no special requirements on how the protocol server treats Null values.<79>
ShowUser TRUE to specify whether to show the survey respondent's name in the survey results.
StrictTypeCoercion TRUE if expressions anywhere in the list that include invalid type casts such as casting a date to a string SHOULD return an error instead of attempting to perform the cast.<80>
Title A string that contains the title of the list.
newFields: An UpdateFieldsRequest object that defines the new fields to be added to the list.
updateFields: An UpdateFieldsRequest object that defines the fields to be updated in the list.
deleteFields: An UpdateFieldsRequest object that defines the fields to be deleted from the list.
listVersion: A string representation of an integer value that specifies the current version of the list.
This is used to determine if the protocol client is working off of the same version of the schema that is currently maintained by the protocol server. The ListVersion is set to the value of Version retrieved from a previous GetListItemChangesSinceToken call (section 3.1.4.22) with no changeToken parameter included, or a GetListItemChangesWithKnowledge call (section 3.1.4.23) with no knowledge parameter included or where the schema on the protocol server changed or from a call to the GetList (section 3.1.4.15) or GetListAndView (section 3.1.4.16) operations. If the listVersion value sent up in the UpdateList request does not match the current version, the protocol server MUST respond with a SOAP fault with error code 0x81020015. This indicates that the changes being requested via UpdateList will conflict with whatever changes have already been made to this list that resulted in the protocol server listVersion being higher than the one sent by the protocol client.
3.1.4.30.2.2 UpdateListResponse
The UpdateListResponse element contains the response to the request to update list properties and add, delete, or update fields.
<s:element name="UpdateListResponse"> <s:complexType>
<s:sequence>
<s:element name="UpdateListResult" minOccurs="0">
<s:complexType mixed="true">
<s:sequence>
<s:element name="Results">
<s:complexType mixed="true">
<s:sequence>
<s:element name="NewFields" type="tns:UpdateListFieldResults" />
<s:element name="UpdateFields"
type="tns:UpdateListFieldResults" />
<s:element name="DeleteFields"
type="tns:UpdateListFieldResults" />
<s:element name="ListProperties" type="tns:ListDefinitionCT" />
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
UpdateListResult: The results of the UpdateList request.
Results: The container element for the result categories.
NewFields: The container element for the results of any add field requests. See section 2.2.4.14.
DeleteFields: The container element for the results of any delete field requests. See section 2.2.4.14.
UpdateFields: The container element for the results of any update field requests. See section 2.2.4.14.
ListProperties: The container element for the results of any content type requests.