3.1.4.2 EcDoRpcExt2 Method (Opnum 11)

The EcDoRpcExt2 method passes generic ROP commands to the server for processing within a Session Context. Each call can contain multiple ROP commands. The server returns the results of each ROP command to the client. This call requires an active session context handle returned from the EcDoConnectEx method.

 long __stdcall EcDoRpcExt2(
      [in, out, ref] CXH * pcxh,
      [in, out] unsigned long *pulFlags,
      [in, size_is(cbIn)] unsigned char rgbIn[],
      [in] unsigned long cbIn,
      [out, length_is(*pcbOut), size_is(*pcbOut)] unsigned char rgbOut[],
      [in, out] BIG_RANGE_ULONG *pcbOut,
      [in, size_is(cbAuxIn)] unsigned char rgbAuxIn[],
      [in] unsigned long cbAuxIn,
      [out, length_is(*pcbAuxOut), size_is(*pcbAuxOut)] unsigned char rgbAuxOut[],
      [in, out] SMALL_RANGE_ULONG *pcbAuxOut,
      [out] unsigned long *pulTransTime
 );

pcxh: A session context handle. On input, the client MUST pass a valid session context handle that was created by calling the EcDoConnectEx method. The server uses the session context handle to identify the Session Context to use for this call. On output, the server MUST return the same session context handle on success.

The server can destroy the session context handle by returning a zero session context handle. Reasons for destroying the session context handle are implementation-dependent; following are examples of why the server might destroy the session context handle:

• The server determines that the ROP request payload in the rgbIn buffer is malformed or length parameters are not valid.

• The session context handle that was passed in is not valid.

• An attempt was made to access a mailbox that is in the process of being moved.

• An administrator has blocked a client that has an active connection.

pulFlags: The flags that describe the server output characteristics. On input, this parameter contains flags that tell the server how to build the rgbOut parameter.

For details about how to use these flags, see section 3.1.4.2.1.1.

On output, the server SHOULD<17> set this parameter to 0x00000000. The output flags not in the table are reserved for future use.

rgbIn: The ROP request payload. The ROP request payload is prefixed with an RPC_HEADER_EXT header, as specified in section 2.2.2.1. Information stored in this header determines how to interpret the data following the header. For details about how to access the embedded ROP request payload, see section 3.1.4.2.1. The length of the ROP request payload including the RPC_HEADER_EXT header is contained in the cbIn parameter.

For more information about ROP buffers, see [MS-OXCROPS].

cbIn: The length of the ROP request payload. On input, this parameter contains the length of the ROP request payload passed in the rgbIn parameter. The ROP request payload includes the size of the ROPs plus the size of the RPC_HEADER_EXT structure. The server SHOULD<18> fail with the RPC status code of RPC_X_BAD_STUB_DATA (0x000006F7) if the request buffer is larger than 0x00040000 bytes in size. For more information on returning RPC status codes, see [C706]. If the request buffer is smaller than the size of the RPC_HEADER_EXT structure (0x00000008 bytes), the server SHOULD<19> fail with error code ecRpcFailed (0x80040115).

rgbOut: The ROP response payload. The size of the payload is specified in the pcbOut parameter. Like the ROP request payload, the ROP response payload is also prefixed by a RPC_HEADER_EXT header. For details about how to format the ROP response payload, see section 3.1.4.2.1. The size of the ROP response payload plus the RPC_HEADER_EXT header is returned in the pcbOut parameter.

pcbOut: The maximum size of the rgbOut parameter. On input, this parameter contains the maximum size of the rgbOut parameter. If the value in the pcbOut parameter on input is less than 0x00000008, the server SHOULD<20> fail with error code ecRpcFailed (0x80040115). If the value in the pcbOut parameter on input is larger than 0x00040000, the server MUST fail with the RPC status code of RPC_X_BAD_STUB_DATA (0x000006F7). If the server indicates it supports a larger ROP response payload through the ULTRA_LARGE_PACKED_DOWNLOAD_BUFFERS flag being present in the Flags field of the AUX_SERVER_CAPABILITIES (section 2.2.2.2.19) auxiliary block returned in rgbAuxOut field of the EcDoConnectEx method (section 3.1.4.1), then the server MUST fail only if pcbOut is larger than 0x00100000.

On output, this parameter contains the size of the ROP response payload, including the size of the RPC_HEADER_EXT header in the rgbOut parameter. The server returns 0x00000000 on failure because there is no ROP response payload. The client ignores any data returned on failure.

rgbAuxIn: The auxiliary payload buffer. The auxiliary payload buffer is prefixed by an RPC_HEADER_EXT structure. Information stored in this header determines how to interpret the data following the header. The length of the auxiliary payload buffer including the RPC_HEADER_EXT header is contained in the cbAuxIn parameter.

For details about how to access the embedded auxiliary payload buffer, see section 3.1.4.2.1. For details about how to interpret the auxiliary payload data, see section 3.1.4.2.2.

cbAuxIn: The length of the auxiliary payload buffer. On input, this parameter contains the length of the auxiliary payload buffer passed in the rgbAuxIn parameter. If the request buffer value is larger than 0x00001008 bytes in size, the server SHOULD<21> fail with the RPC status code RPC_X_BAD_STUB_DATA (0x000006F7).<22>

rgbAuxOut: The auxiliary payload buffer. On output, the server MAY<23> return auxiliary payload data to the client. The server MUST include a RPC_HEADER_EXT header before the auxiliary payload data.

pcbAuxOut: The maximum length of the auxiliary payload buffer. On input, this parameter contains the maximum length of the rgbAuxOut parameter. If this value on input is larger than 0x00001008, the server MUST fail with the RPC status code RPC_X_BAD_STUB_DATA (0x000006F7).

On output, this parameter contains the size of the data to be returned in the rgbAuxOut parameter.

pulTransTime: The time it took to execute this method. On output, the server stores the number of milliseconds the call took to execute. This is the total elapsed time from when the call is dispatched on the server to the point in which the server returns the call. This is diagnostic information the client can use to determine the cause of a slow response time from the server. The client can monitor the total elapsed time across the RPC method call and, using this output parameter, can determine whether time was spent transmitting the request/response on the network or processing it on the server.

Return Values: If the method succeeds, the return value is 0. If the method fails, the return value is an implementation-specific error code or the protocol-defined error code listed in the following table.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol as specified in [MS-RPCE].