3.2.6.2.2 TsProxySetupReceivePipe (Opnum 8)

  • Article

The TsProxySetupReceivePipe method is used for data transfer from the RDG server to the RDG client. The RDG server MUST create an RPC out pipe upon receiving this method call from the RDG client. This call bypasses the NDR and hence, the RPC runtime MUST NOT perform a strict NDR data consistency check for this method. Refer to section 3.6.5 for details on NDR-bypassing. Section 3.6.5.4 and section 3.6.5.5 give details on wire representation of data for responses to TsProxySetupReceivePipe. The out pipe MUST be created by the RDG server in the same manner as NDR creates it for a call.<49> The RDG server MUST use this out pipe and Stub Data field in RPC response PDUs to send all data from the target server to the RDG client on the channel. The RDG client MUST use this out pipe to pull data from the target server on the channel. On connection disconnect, the RDG server MUST send the following on the pipe: A DWORD return code in an RPC response PDU and set the PFC_LAST_FRAG bit in the pfc_flags field of the RPC response PDU. The pipe close is indicated when the PFC_LAST_FRAG bit is set in the pfc_flags field of the RPC response PDU. When the RDG client sees that the PFC_LAST_FRAG bit is set in the pfc_flags field of the RPC response PDU, it MUST interpret the 4 bytes Stub Data as the return code of TsProxySetupReceivePipe. For a description of RPC response PDU, pfc_flags, PFC_LAST_FRAG, and Stub Data, refer to sections 12.6.2 and 12.6.4.10 in [C706]. The RDG client and RDG server MUST negotiate a separate out pipe for each channel. Out pipes MUST NOT be used or shared across channels.<50>

As long as the channel is not closed, the RPC and Transport layer guarantee that any data that is sent by the RDG server reaches the RDG client. RPC and Transport layer also ensure that the data is delivered to the RDG client in the order it was sent by the RDG server.

After the call reaches the RDG server, the connection MUST transition to Pipe Created state after setting up the out pipe.

Prerequisites: The connection MUST be in Channel Created state. If this is called in any other state, then the behavior is undefined.

Sequential Processing Rules:

  1. If some unexpected error occurs in the following process, the RDG server MUST return HRESULT_CODE(E_PROXY_INTERNALERROR).

  2. If the RDG server is implementing the Connection Timer, then if TsProxySetupReceivePipe is called after the Connection Timer has expired, the RDG server MUST return ERROR_OPERATION_ABORTED; otherwise, the Connection Timer MUST be stopped.

  3. The RDG server MUST extract the channel context handle from pRpcMessage parameter. For the pRpcMessage format, refer to RDG Client to RDG Server Packet Format (section 2.2.9.4.1).

  4. The RDG server MUST verify that the channel context handle is not NULL. Otherwise, it MUST return ERROR_ACCESS_DENIED.

  5. If the RDG server is configured such that the connections are allowed only to a resource that allows policy exchanges between the RDG server and the target server, and the target server does not support the same, then the RDG server MUST return HRESULT_CODE(E_PROXY_SDR_NOT_SUPPORTED_BY_TS).

  6. If connection to the target server is not set up in TsProxyCreateChannel call, then the RDG server MUST try to connect to the target server by each name in the Target server names array until it succeeds or until the array is traversed completely. If connection fails for all target server names, it MUST return HRESULT_CODE(E_PROXY_TS_CONNECTFAILED).<51>

  7. The RDG server MUST set up an out pipe to send data received from the target server to the RDG client.

  8. The connection MUST transition to Pipe Created state.

  9. The RDG server MUST start receiving data from the target server and stream the same to the RDG client. This process MUST be continued until one of the following events occurs.

    1. If the Session Timeout Timer expires and the TimeoutAction ADM element is set to "disconnect on session timeout" RDG server:

      1. If the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the session by sending the final response of the TsProxySetupReceivePipe method with the HRESULT_CODE(E_PROXY_SESSIONTIMEOUT) error code.

      2. If the ADM element Negotiated Capabilities does not contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the session by sending the final response of the TsProxySetupReceivePipe method with the HRESULT_CODE(E_PROXY_CONNECTIONABORTED) error code.

    2. If the session timeout timer expires and the TimeoutAction ADM element is set to "reauthentication on session timeout", the RDG server initiates a reauthentication with the client and starts the reauthentication timer, as explained in section 3.2.7.1. After the reauthentication timer expires, the RDG server MUST check the value of Reauthentication Status ADM element.

      • If the ADM element Reauthentication Status is set to NONE:

        1. If the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_REAUTH_AUTHN_FAILED).

        2. If the ADM element Negotiated Capabilities does not contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_CONNECTIONABORTED).

      • If the ADM element Reauthentication Status is set to AuthenticationCompleted:

        1. If the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_REAUTH_CAP_FAILED).

        2. If the ADM element Negotiated Capabilities does not contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_CONNECTIONABORTED).

      • If the ADM element Reauthentication Status is set to UserAuthorizationCompletedButQurantineFailed:

        1. If the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_REAUTH_NAP_FAILED).

        2. If the ADM element Negotiated Capabilities does not contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_CONNECTIONABORTED).

      • If the ADM element Reauthentication Status is set to UserAuthorizationCompleted:

        1. If the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_REAUTH_RAP_FAILED).

        2. If the ADM element Negotiated Capabilities does not contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT, then the RDG server MUST disconnect the connection with HRESULT_CODE(E_PROXY_CONNECTIONABORTED).

      • If the ADM element Reauthentication Status is set to ResourceAuthorizationCompleted, the RDG server MUST start the Session Timeout Timer and MUST reset the ADM element Reauthentication Status to NONE.

    3. If the target server unexpectedly closes the connection between the RDG server and the target server, the RDG server MUST return ERROR_BAD_ARGUMENTS.

    4. If the RDG server administrator forcefully disconnects the connection, the RDG server MUST return HRESULT_CODE(E_PROXY_CONNECTIONABORTED).

    5. If the connection gets disconnected either by the RDG client or the RDG server, or by an unknown error, the RDG server MUST send the corresponding error code to the RDG client in the final response, as specified in RDG Server to RDG Client Packet Format for Final Response (section 2.2.9.4.3).

     DWORD TsProxySetupReceivePipe(
   [in, max_is(32767)] byte pRpcMessage[]
 );

pRpcMessage: The protocol data between RDG client and RDG server MUST be decoded as specified in section 2.2.9.4. RPC stub information is specified in [MS-RPCE] sections 1.1 and 1.5.

Return Values: The method MUST return ERROR_GRACEFUL_DISCONNECT on success, that is, if the RDG client gracefully disconnects the connection by calling TsProxyCloseChannel. Other failures MUST be one of the codes listed. The client MAY interpret failures in any way it deems appropriate. See section 2.2.6 for details on these errors.

The error DWORD value is always sent, when the receive pipe closes down. The receive pipe will always close down when a disconnect takes place.

Return value

State transition

Description

ERROR_ACCESS_DENIED (0x00000005)

The connection MUST transition to Tunnel Close Pending state.

Returned either if this method is called before TsProxyCreateChannel or if the Channel Context Handle ADM element is NULL. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_INTERNALERROR) (0x000059D8)

The connection MUST transition to Tunnel Close Pending state.

Returned when an unexpected error occurs in TsProxySetupReceivePipe. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_TS_CONNECTFAILED) (0x000059DD)

The connection MUST transition to Tunnel Close Pending state.

Returned when the RDG server fails to connect to target server. It is returned in an rpc_fault packet.<52> The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_SESSIONTIMEOUT) (0x000059F6)

The connection MUST transition to Tunnel Close Pending state.

Returned by RDG server if a session timeout occurs and "disconnect on session timeout" is configured at the RDG server and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_REAUTH_AUTHN_FAILED) (0x000059FA)

The connection MUST transition to Tunnel Close Pending state.

Returned when a reauthentication attempt by the client has failed because the user credentials are no longer valid and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_REAUTH_CAP_FAILED) (0x000059FB)

The connection MUST transition to Tunnel Close Pending state.

Returned when a reauthentication attempt by the client has failed because the user is not authorized to connect through the RDG server anymore and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_REAUTH_RAP_FAILED) (0x000059FC)

The connection MUST transition to Tunnel Close Pending state.

Returned when a reauthentication attempt by the client has failed because the user is not authorized to connect to the given end resource anymore and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_CONNECTIONABORTED) (0x000004D4)

The connection MUST transition to Tunnel Close Pending state.

Returned when the following happens:

  1. The RDG server administrator forcefully disconnects the connection.

  2. Or when the ADM element Negotiated Capabilities doesn't contain TSG_NAP_CAPABILITY_IDLE_TIMEOUT and any one of the following happens:

    1. Session timeout occurs and disconnect on session timeout is configured at the RDG server.

    2. Reauthentication attempt by the client has failed because the user credentials are no longer valid.

    3. Reauthentication attempt by the client has failed because the user is not authorized to connect through the RDG server anymore.

    4. Reauthentication attempt by the client has failed because the user is not authorized to connect to the given end resource anymore.

    5. Reauthentication attempt by the RDG client has failed because the health of the user's computer is no longer compliant with the RDG server configuration.

The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_SDR_NOT_SUPPORTED_BY_TS) (0x000059FD)

The connection MUST transition to Tunnel Close Pending state.

The RDG server is capable of exchanging policies with some target servers. The RDG server MAY be configured to allow connections to only target servers that are capable of policy exchange. If such a setting is configured and the target server is not capable of exchanging policies with the RDG server, this error will be returned. The RDG client MUST end the protocol when this error is received.

ERROR_GRACEFUL_DISCONNECT (0x000004CA)

The connection MUST transition to Tunnel Close Pending state.

Returned when the connection is disconnected gracefully by the RDG client calling TsProxyCloseChannel.

HRESULT_CODE(E_PROXY_REAUTH_NAP_FAILED) (0x00005A00)

The connection MUST transition to Tunnel Close Pending state.

Returned when a reauthentication attempt by the RDG client has failed because the user's computer's health is no longer compliant with the RDG server configuration and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_IDLE_TIMEOUT. The RDG client MUST end the protocol when this error is received.

ERROR_OPERATION_ABORTED(0x000003E3)

The connection MUST transition to Tunnel Close Pending state.

Returned when the call to TsProxySetupReceivePipe is received after the Connection Timer has expired.

ERROR_BAD_ARGUMENTS(0x000000A0)

The connection MUST transition to Tunnel Close Pending state.

Returned when the target server unexpectedly closes the connection between the RDG server and the target server.