Share via

3.6.4.2 SendRTMessage (Opnum 3)

  • Article

The SendRTMessage method determines whether roundtrip communication works between two network addresses.

The server SHOULD fail this method if the server Initialization State is FALSE.

 HRESULT SendRTMessage(
   [in] BSTR SourceIPAddress,
   [in] BSTR DestIPAddress,
   [in] unsigned short DestPort,
   [in] unsigned short AddressFamily,
   [in] unsigned long MessageSize,
   [in] unsigned long Timeout,
   [out] unsigned long* RTElapsedTime
 );

SourceIPAddress: The address from which to send the network request. IPv4 addresses MUST be represented in dotted decimal notation. IPv6 addresses MUST be represented in the form specified by [RFC1924].<25>

DestIPAddress: The address to which to send the network request. The address is in the same representation as SourceIPAddress.

DestPort: This server MUST ignore this value.

AddressFamily: The address type of the SourceIPAddress and DestIPAddress parameters.

Value

Meaning

AF_INET

0x0002

The addresses are in IPv4 format.

AF_INET6

0x0017

The addresses are in IPv6 format.

MessageSize: The server MUST ignore this value.

Timeout: An implementation-specific value<26> indicating the maximum amount of time to wait for a response from the destination address.

RTElapsedTime: The elapsed time (in milliseconds) between when the server sends the message from the SourceIPAddress to DestIPAddress and when it receives a reply from the destination address.

Return Values: A signed 32-bit value that indicates return status. If the method returns a negative value, it has failed. Zero or positive values indicate success, with the lower 16 bits in positive nonzero values containing warnings or flags defined in the method implementation. For more information about Win32 error codes and HRESULT values, see [MS-ERREF] sections 2.2 and 2.1.

Return value/code

Description

0x00000000

S_OK

The call was successful.

For any other condition, this method MUST return a value that is not one of the values listed in the preceding table. The client MUST behave in one consistent, identical manner for all values that are not listed in the preceding table.

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

The opnum field value for this method is 3.

When processing this call, the server MUST do the following:

  • Initialize the Round-Trip Message Timer to 1000 milliseconds.

  • Use an implementation-specific mechanism to send a network message from SourceIPAddress to DestIPAddress, such that a reply message is sent back from DestIPAddress to the SourceIPAddress.

    Note While performing the round-trip message operation, use an implementation-specific mechanism to determine the elapsed time. For example, prior to sending the message, observe the current time of day in millisecond granularity. Upon receipt of the reply, again observe the current time of day. The elapsed time can be calculated by subtracting the first observed value from the second.

  • If the Round-Trip Message Timer (section 3.6.2.1) expires before receiving the reply, the server MUST return an error code.

Return the following information to the client:

  • The elapsed time (in milliseconds) between when the server sends the message from the SourceIPAddress to DestIPAddress and when it receives a reply from the destination address.