3 Protocol Details

SharePoint

In the following sections, the schema definition might differ from the processing rules imposed by the protocol. The WSDL in this specification matches the WSDL that shipped with the product and provides a base description of the schema. The text that introduces the WSDL might specify differences that reflect actual Microsoft product behavior. For example, the schema definition might allow for an element to be empty, null, or not present but the behavior of the protocol as specified restricts the same elements to being non-empty, not null, and present.

The client side of this protocol is simply a pass-through. That is, no additional timers or other state is required on the client side of this protocol. Calls made by the higher-layer protocol or application are passed directly to the transport, and the results returned by the transport are passed directly back to the higher-layer protocol or application.

Except where specified, protocol clients SHOULD interpret HTTP status codes returned by the protocol server as specified in [RFC2616] section 10.

This protocol allows protocol servers to perform implementation-specific authorization checks and notify protocol clients of authorization faults as specified previously in this section.

This protocol allows protocol servers to perform implementation-specific localization of text in various messages. Except where specified, the localization of this text is an implementation-specific behavior of the protocol server and not significant for interoperability.

The following high-level sequence diagram illustrates the operation of the protocol.

High-level sequence of operations between protocol client and protocol server

Figure 3: High-level sequence of operations between protocol client and protocol server

Session behavior: A session (2) MUST be created on a successful OpenWorkbook request. A session (2) MUST stop responding to operations after a successful call to the CloseWorkbook operation or after the session (2) has timed out.

Request behavior: A request is created when a Web service operation starts running on the protocol server, and ends when the Web service operation finishes, when it is successfully cancelled by a CancelRequest call, or after the request has timed out.

Types of operation: The common behavior of each operation is determined by the set of categories it falls under. The following table specifies the possible categories.

Category

Meaning

Concurrent

The operation does not change session (2) state on the protocol server. The protocol server MUST allow multiple concurrent operations to execute at the same time as long as there is no NonConcurrent operation executing at the same time.

NonConcurrent

The operation is an exclusive operation on the session (2) in the protocol server, and the protocol server can only process one of such operations on a session (2) at the same time.

If the protocol client issues an operation of this category or of the concurrent category on a given session (2) while the protocol server is processing another operation of this category on the same session (2), then the protocol server MUST return an ExcelServerMessage as specified in section 2.2.9.2, with the value of the id element of the ExcelServerMessage set to MultipleRequestsOnSession.

If the protocol client issues an operation of this category on a given session (2) while the protocol server is processing one or more operations of the concurrent category on the same session (2), then the protocol server MAY<7> immediately return an ExcelServerMessage as specified in section 2.2.9.2, with the value of the id element of the ExcelServerMessage set to MultipleRequestsOnSession.

ChangesState

The operation is a session (2)'s state changing operation on the protocol server.

The protocol server MUST increment the session (2)'s state identifier.

Out of Band

The operation can be processed on the protocol server regardless of the current  state of the session (2), or whether there are other operations from any category currently being processed by the protocol server on the session (2).

The following table specifies the combination of the categories per protocol server operation.

Operation

Concurrent

NonConcurrent

ChangesState

Out of Band

ApplyItemFilter

X

X

ApplyPivotFilter

X

X

ApplyPivotSort

X

X

ApplyPivotTop10Filter

X

X

ApplyTop10Filter

X

X

CancelRequest

X

CloseWorkbook

X

ConnectAndGetPivotFilterItemList

X

X

ExpandCollapseOutline

X

X

FindRange

X

GetAutoFilterItemList

X

GetImage

X

GetPivotFilterItemList

X

GetPivotMenu

X

GetRange

X

GetRangeValues

X

GetRangeValuesA1

X

GetSessionInformation

X

GetWorkbook

X

OpenWorkbook

X

X

Recalc

X

X

RecalcA1

X

X

RecalcAll

X

X

Refresh

X

X

RefreshAll

X

X

RemovePivotFilter

X

X

SetParameters

X

X

SetRange

X

X

SetRangeA1

X

X

SortFilterColumn

X

X

TogglePivotDrill

X

X

Show: