3.2.6.1.4 TsProxyCreateChannel (Opnum 4)

  • Article

The TsProxyCreateChannel method is used to create a channel between the RDG client and the RDG server.<44> The RDG server SHOULD connect to the target server during this call to start communication between the RDG client and target server. If connection to the target server cannot be done, the RDG server MUST return HRESULT_CODE(E_PROXY_TS_CONNECTFAILED) as noted in the Return Values section.<45> The RDG server MUST return a representation of the channel to the RDG client. After this method call has successfully been completed, a channel shutdown can be performed by using the TsProxyCloseChannel method. Please refer to section 3.1.1 for a state transition diagram.

Prerequisites: The tunnel MUST be authorized; otherwise, the error ERROR_ACCESS_DENIED is returned.

Sequential Processing Rules:

  1. If some unexpected error occurs during the following process, the RDG server MUST return E_PROXY_INTERNALERROR.

  2. The RDG server MUST verify that the tunnel has been authorized. Otherwise, it MUST return ERROR_ACCESS_DENIED.

  3. The RDG server MUST verify that the tsEndPointInfo parameter is not NULL and tsEndPointInfo->numResources is not zero. Otherwise, it MUST return ERROR_ACCESS_DENIED.

  4. The RDG server MUST initialize the ADM element Target server names with combined array of the resourceName and alternateResourceNames members of the tsEndPointInfo parameter.

  5. The RDG server MUST do the resource authorization as per policies configured at the RDG server. If the resource is not authorized, then it MUST return E_PROXY_RAP_ACCESSDENIED.<46>

  6. If Reauthentication Connection is TRUE:

    1. The RDG server MUST find the original connection that has initiated the reauthentication using Reauthentication Tunnel Context and MUST set its ADM element Reauthentication Status to ResourceAuthorizationCompleted.

    2. Return ERROR_SUCCESS.

  7. The RDG server SHOULD 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) in rpc_fault packet.

  8. The RDG server MUST create the channelId and channelContext RPC content handles and MUST initialize the corresponding ADM elements.

  9. The RDG server MUST also start the Session Timeout Timer (section 3.1.2.1), if the session timeout is configured at the RDG server.

  10. If the RDG server is implementing the Connection Timer, the RDG server MUST start the Connection Timer.

  11. The RDG server MUST return ERROR_SUCCESS.

     HRESULT TsProxyCreateChannel(
   [in] PTUNNEL_CONTEXT_HANDLE_NOSERIALIZE tunnelContext,
   [in, ref] PTSENDPOINTINFO tsEndPointInfo,
   [out] PCHANNEL_CONTEXT_HANDLE_SERIALIZE* channelContext,
   [out] unsigned long* channelId
 );

tunnelContext: The RDG client MUST provide the RDG server with the same context handle it received from the TsProxyCreateTunnel method call. The RDG server SHOULD throw an exception if the RPC validation and verification fails.

tsEndPointInfo: Pointer to the TSENDPOINTINFO structure. The RDG client MUST provide a non-NULL pointer to the RDG server for this structure. The RDG server initializes the ADM element Target server names with an array of resourceName and alternateResourceNames members of TSENDPOINTINFO structure. The RDG server SHOULD try to connect to the target server by each name in the array until it succeeds or until the array is traversed completely. If connection fails for all target server names, HRESULT_CODE(E_PROXY_TS_CONNECTFAILED) (0x000059DD) is returned.<47> The rules for determining a valid server name are specified in section 2.2.1.1.

channelContext: A RPC context handle that represents context-specific information for the channel. The RDG server MUST provide a non-NULL value. The RDG client MUST save and use this context handle on all subsequent method calls on the channel. Specifically, these methods are TsProxySendToServer, TsProxySetupReceivePipe, and TsProxyCloseChannel.

channelId: An unsigned long identifying the channel. The RDG server MUST provide this value to the RDG client. The RDG client MUST save the returned channel ID for future use in the ADM element Channel id (section 3.5.1). This channel ID is not required on any future method calls.

Return Values: The method MUST return ERROR_SUCCESS on success. 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.

Return value

State transition

Description

ERROR_SUCCESS (0x00000000)

The connection MUST transition to Channel Created state.

Returned when a call to the TsProxyCreateChannel method succeeds.

ERROR_ACCESS_DENIED (0x00000005)

The connection MUST NOT transition its state.

Returned either if tunnelContext parameter is NULL, if this method is called on a tunnel which is not authorized, if the tsEndPointInfo parameter is NULL, or if the numResourceNames member of the tsEndPointInfo parameter is zero.

E_PROXY_RAP_ACCESSDENIED (0x800759DA)

The connection MUST NOT transition its state.

Returned when an attempt to resolve or access a target server is blocked by RDG server policies.

E_PROXY_INTERNALERROR (0x800759D8)

The connection MUST NOT transition its state.

Returned when the server encounters an unexpected error while creating the channel.

HRESULT_CODE(E_PROXY_TS_CONNECTFAILED) (0x000059DD)

The connection MUST NOT transition its state.

This error is returned in rpc_fault packet when the RDG server fails to connect to any of the target server names, as specified in the members of tsEndPointInfo.

The error ERROR_ACCESS_DENIED is returned when this call is made on a tunnel which is not authorized.