3.1.4.20 OpenWorkbook

This operation is used to open a session (2) giving access to a workbook on the protocol server.

 <wsdl:operation name="OpenWorkbook">
     <wsdl:input message="OpenWorkbookSoapIn" />
     <wsdl:output message="OpenWorkbookSoapOut" />
 </wsdl:operation>

The protocol client sends an OpenWorkbookSoapIn request message, and the protocol server responds with an OpenWorkbookSoapOut response message, as follows:

  1. The workbook file, specified by url, is specified as follows:

    • It SHOULD be in a format specified by [MS-XLSB] or [ECMA-376] but MAY be in any other format. If it is in the [ECMA-376] format, the following apply:

      • It MAY<32> contain any valid SpreadsheetML records in that format.

      • If an odcFile attribute of a connection (2) element ( [ECMA-376], Part 4, Section 3.13.1) is present it SHOULD be the path of a file in the format specified by [MS-ODCFF].

      • If a connection (2) attribute of dbPr element ([ECMA-376], Part 4, Section 3.13.3]) is present it SHOULD be in the format specified by [MS-ODBCSTR] or [MS-OLEDBSTR].

    • If it is in the [MS-XLSB] format, the following apply:

      • It MAY<33> contain any valid records in that format.

      • If a brtBeginExternalConnection record is present and it has the stConnectionFile field present, the stConnectionFile SHOULD be the path of a file in the format specified by [MS-ODCFF].

      • If a BrtBeginECDbProps record  is present, its stConn field SHOULD be in the format specified by [MS-ODBCSTR] or [MS-OLEDBSTR].

    • If a file in [MS-ODCFF] is referenced by the workbook file, the following apply:

      • SourceFile element of OfficeDataConnection ([MS-ODCFF] section 2.7.1.1) MUST NOT be present.

      • Parameter elements of CT_Connection [MS-ODCFF] section 2.2.1) MUST be ignored.

  2. If the operation succeeds, the protocol server MUST return the session (2) identifier of the newly created session (2) in the response message, to be used in any future operations against the newly created session (2).

  3. hasOpenItemPermission MUST be true if the user has the Open Item permission on the workbook file that was opened by the operation, otherwise hasOpenItemPermission MUST be false.

In the event of an application error on the protocol server during this operation, the protocol server MUST return an ExcelServerMessage as specified in section 2.2.9.2. The id element of the ExcelServerMessage MUST be one of the values specified in section 2.2.9.4, and SHOULD<34> be one of the following values.

Id

Description

InvalidOrTimedOutSession

See section 2.2.9.5.

RetryError

See section 2.2.9.5.

OperationCanceled

See section 2.2.9.5.

InternalError

See section 2.2.9.5.

MultipleRequestsOnSession

See section 2.2.9.5.

MaxRequestDurationExceeded

See section 2.2.9.5.

FileOpenNotFound

The specified workbook file could not be found.

FileOpenAccessDenied

Access to the workbook file was denied by either the file-server supplying access to the file, or because the protocol server has determined that the user should not have access.

FileCorrupt

The workbook file is not following any of the file formats supported by the protocol server implementation.