WinHttpWebSocketQueryCloseStatus function (winhttp.h)

  • Article

The WinHttpWebSocketQueryCloseStatus function retrieves the close status sent by a server.

Syntax

WINHTTPAPI DWORD WinHttpWebSocketQueryCloseStatus(
  [in]  HINTERNET hWebSocket,
  [out] USHORT    *pusStatus,
  [out] PVOID     pvReason,
  [in]  DWORD     dwReasonLength,
  [out] DWORD     *pdwReasonLengthConsumed
);

Parameters

[in] hWebSocket

Type: HINTERNET

Handle to a WebSocket

[out] pusStatus

Type: USHORT*

A pointer to a close status code that will be filled upon return. See WINHTTP_WEB_SOCKET_CLOSE_STATUS for possible values.

[out] pvReason

Type: PVOID

A pointer to a buffer that will receive a close reason on return.

[in] dwReasonLength

Type: DWORD

The length of the pvReason buffer, in bytes.

[out] pdwReasonLengthConsumed

Type: DWORD*

The number of bytes consumed. If pvReason is NULL and dwReasonLength is 0, pdwReasonLengthConsumed will contain the size of the buffer that needs to be allocated by the calling application.

Return value

Type: DWORD

NO_ERROR on success. Otherwise an error code.

Description
ERROR_INSUFFICIENT_BUFFER
 There is not enough space in pvReason to write the whole close reason.
ERROR_INVALID_OPERATION
 No close frame has been received yet.
ERROR_INVALID_PARAMETER
 A parameter is invalid.

Remarks

Call WinHttpWebSocketQueryCloseStatus only after WinHttpWebSocketClose succeeds or if WinHttpWebSocketReceive returns WINHTTP_WEB_SOCKET_CLOSE_BUFFER_TYPE.

pdwReasonLengthConsumed will never be greater than 123, so allocating buffer with at least 123 will guarantee that ERROR_INSUFFICIENT_BUFFER will never be returned.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header winhttp.h
Library Winhttp.lib
DLL Winhttp.dll

See also

WINHTTP_WEB_SOCKET_CLOSE_STATUS

WinHttpWebSocketClose

WinHttpWebSocketReceive