3.2.6.1.3 TsProxyMakeTunnelCall (Opnum 3)

  • Article

The TsProxyMakeTunnelCall method is designed to be used as a general purpose API. If both the client and the server support the administrative message, the client MAY request the same from the RDG server. If the RDG server has any administrative messages, it SHOULD complete the pending call at this point in time. After a call to TsProxyMakeTunnelCall returns, the RDG client SHOULD queue up another request at this point in time. During the shutdown sequence, the client MUST make this call, if a request is pending on the RDG server, to cancel the administrative message request.

Prerequisites: The connection MUST be in Authorized state or Channel Created state or Pipe Created state or Channel Close Pending state or Tunnel Close Pending state. If this call is made in any other state, the error ERROR_ACCESS_DENIED is returned.

Sequential Processing Rules:

  1. The RDG server MUST verify that the procId parameter is either TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST or TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST. Otherwise, it MUST return ERROR_ACCESS_DENIED.

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

  3. The RDG server MUST verify that the ADM element Reauthentication Connection is FALSE. Otherwise, it MUST return ERROR_ACCESS_DENIED. TsProxyMakeTunnelCall is not valid on reauthentication tunnels.

  4. If procId is TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST:

    1. If a TsProxyMakeTunnelCall has already been made and not yet returned, the RDG server MUST return ERROR_ACCESS_DENIED.

    2. If there is already a pending administrative message or reauthentication message to the RDG client, the RDG server MUST fill TSGPacketResponse and return ERROR_SUCCESS.

    3. If there is no pending administrative message or a reauthentication message, the RDG server MUST wait until one of the following events occurs:

      • Reauthentication starts because the session timeout timer expires.

      • The RDG server administrator sets the administrative message.

      • The RDG client cancels the call.

      • The connection shutdown sequence is initiated.

        If any of the preceding events occurs, then the following steps MUST be performed:

      1. If reauthentication is started because of session timeout timer expiration, then the RDG server MUST return the TsProxyMakeTunnelCall as explained in section 3.2.7.1.

      2. Or else, if the RDG administrator has set the administrative message, then the RDG server MUST do the following:

        1. The RDG server MUST set the packetId member of the TSGPacketResponse out parameter of TsProxyMakeTunnelCall to TSG_PACKET_TYPE_MESSAGE_PACKET.

        2. The RDG server MUST set TSGPacketResponse->packetMsgResponse->msgType to TSG_ASYNC_MESSAGE_SERVICE_MESSAGE.

        3. The RDG server MUST initialize TSGPacketResponse->packetMsgResponse->messagePacket.serviceMessage->isDisplayMandatory to TRUE.

        4. The RDG server MUST initialize TSGPacketResponse->packetMsgResponse->messagePacket.serviceMessage->isConsentMandatory to FALSE.

        5. The RDG server MUST initialize TSGPacketResponse->packetMsgResponse->messagePacket.serviceMessage->msgBuffer with the administrative message.

        6. The RDG server MUST initialize TSGPacketResponse->packetMsgResponse->messagePacket.serviceMessage->msgBytes with the number of characters in TSGPacketResponse->packetMsgResponse->messagePacket.serviceMessage->msgBuffer.

        7. The RDG server MUST complete the TsProxyMakeTunnelCall with error code ERROR_SUCCESS.

      3. Or else, if the RDG client cancels the call by calling another TsProxyMakeTunnelCall with procId TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST, then the RDG server MUST return HRESULT_FROM_WIN32(RPC_S_CALL_CANCELLED).

      4. Or else, if the connection shutdown sequence is initiated, then the RDG server MUST return HRESULT_FROM_WIN32(RPC_S_CALL_CANCELLED).

  5. If procId is TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST:

    1. If there is no unreturned TsProxyMakeTunnelCall call which is called with the procId value TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST, the RDG server MUST return ERROR_ACCESS_DENIED.

    2. Otherwise, the RDG server MUST notify the waiting TsProxyMakeTunnelCall call, which is called with the procId value TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST, that the RDG client is canceling the call.

    3. The RDG server MUST return ERROR_SUCCESS.

     HRESULT TsProxyMakeTunnelCall(
   [in] PTUNNEL_CONTEXT_HANDLE_NOSERIALIZE tunnelContext,
   [in] unsigned long procId,
   [in, ref] PTSG_PACKET TSGPacket,
   [out, ref] PTSG_PACKET* TSGPacketResponse
 );

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 fail.

procId: This field identifies the work that is performed by the API. This field can have the following values.

Value

Meaning

TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST

0x00000001

Used to request an administrative message when the same is available on the server.

TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST

0x00000002

Used to cancel a pending administrative message request.

TSGPacket: Pointer to the TSG_PACKET structure. The value of the packetId field MUST be set to TSG_PACKET_TYPE_MSGREQUEST_PACKET. The packetMsgRequest field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_MSG_REQUEST structure.

TSGPacketResponse: Pointer to the TSG_PACKET structure. If procId is TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST or if the return value is HRESULT_FROM_WIN32(RPC_S_CALL_CANCELLED), *TSGPacketResponse MUST be set to NULL. Otherwise, the value of the packetId field MUST be TSG_PACKET_TYPE_MESSAGE_PACKET. The packetMsgResponse field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_MSG_RESPONSE structure.

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. The connection MUST NOT transition its state after completing the TsProxyMakeTunnelCall.

Return value

State transition

Description

ERROR_SUCCESS (0x00000000)

The connection MUST NOT transition its state.

Returned when a call to the TsProxyMakeTunnelCall method succeeds.

ERROR_ACCESS_DENIED (0x00000005)

The connection MUST NOT transition its state.

Returned in the following cases.

  • When the call is made in any state other than Authorized, Channel Created, Pipe Created, Channel Close Pending, or Tunnel Close Pending.

  • If procId is neither TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST nor TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST.

  • If procId is TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST and there is already a call to TsProxyMakeTunnelCall made earlier with procId TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST and it is not yet returned.

  • If procId is TSG_TUNNEL_CANCEL_ASYNC_MSG_REQUEST  and there is no call to TsProxyMakeTunnelCall made earlier with procId TSG_TUNNEL_CALL_ASYNC_MSG_REQUEST that is not yet returned.

  • If the tunnelContext parameter is NULL.

  • If the tunnel is not authorized.

  • If the Reauthentication Connection ADM element is TRUE.

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

HRESULT_FROM_WIN32(RPC_S_CALL_CANCELLED)(0x8007071A)

The connection MUST not transition its state.

Returned when the call is canceled by the RDG client or the call is canceled because a shutdown sequence is initiated.