RasSecurityDialogReceive function (rasshost.h)

Article
10/13/2021

The RasSecurityDialogReceive function starts an asynchronous operation that receives a remote user's response to a security challenge. The response is the input that the user typed in a terminal window on the remote computer. A third-party RAS security DLL calls this function as part of its authentication of the remote user.

To call this function, first call the LoadLibrary function to load Rasman.dll. Then call the GetProcAddress function to get the DLL's RasSecurityDialogReceive entry point.

Note Windows Server 2008, Windows Server 2003, Windows 2000 Server, and Windows NT Server 4.0 currently provide RAS security host support for serial devices only. Other types of connections, such as Integrated Services Digital Network (ISDN) or virtual private network (VPN) connections, are not supported.

Syntax

DWORD RasSecurityDialogReceive(
  [in] HPORT  hPort,
  [in] PBYTE  pBuffer,
  [in] PWORD  pBufferLength,
  [in] DWORD  Timeout,
  [in] HANDLE hEvent
);

Parameters

[in] hPort

Specifies the port handle that the RAS server passed to the security DLL in the RasSecurityDialogBegin call for this authentication transaction.

[in] pBuffer

Pointer to the receive buffer that was passed to the security DLL in the RasSecurityDialogBegin call. When the asynchronous receive operation has been completed successfully, this buffer specifies the response from the remote user.

[in] pBufferLength

Pointer to a WORD variable. This variable must specify the size, in bytes, of the pBuffer buffer. When the receive operation has been completed, the variable indicates the number of bytes returned in the pBuffer buffer.

[in] Timeout

Specifies a time-out period, in seconds, after which the RAS server sets the hEvent event object to the signaled state.

If this value is zero, there is no time-out period; that is, the RAS server does not signal the event object until the receive operation has been completed.

[in] hEvent

Specifies the handle of an event object created by the CreateEvent function. The RAS server sets the event object to the signaled state when the receive operation has been completed or when the time-out period has elapsed.

Return value

If the function is successful, the return value is PENDING (defined in Raserror.h). This indicates that the receive operation is in progress.

If an error occurs, the return value is one of the error codes defined in Raserror.h or Winerror.h. GetLastError does not provide extended error information.

Remarks

After calling the RasSecurityDialogSend function to send a security challenge to the remote user, the security DLL must call the RasSecurityDialogReceive function to get the user's response.

The RasSecurityDialogReceive function is asynchronous. When the function returns, the security DLL must use one of the wait functions, such as WaitForSingleObject, to wait for the hEvent event object to be signaled. The RAS server signals the event object when the receive operation has been completed or when the time-out interval has elapsed. If the receive operation is successful, the pBuffer buffer contains the response from the remote user, and the pBufferLength parameter indicates the number of bytes received. If the remote user sends more bytes than will fit in the buffer, the RAS server buffers the excess bytes and returns them in the next RasSecurityDialogReceive call.

Use the Timeout parameter to specify a time-out interval. If the time-out elapses, the RAS server signals the event object, and the pBufferLength parameter indicates that zero bytes were transferred. Alternatively, set Timeout to zero, and specify a time-out interval in the wait function used to wait for the event object.

When a security DLL is authenticating a remote user, the connection operation on the remote computer enters a RASCS_Interactive paused state. The message sent by RasSecurityDialogSend is displayed as output in a terminal window on the remote computer. The response received by RasSecurityDialogReceive is the input that the remote user types in the terminal window. The RASCS_Interactive value is defined in the RASCONNSTATE enumeration.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	rasshost.h
DLL	Rasman.dll