WinHTTP WebSocket sample
This sample demonstrates how to use the WinHTTP API to send and receive messages between a client and a server by using the WebSocket protocol.
The sample performs each step required to use the WebSocket connection. First, it creates the session, connection and request handles to open a HTTP connection. It then requests to upgrade the protocol from HTTP to the WebSocket protocol. The WebSocket handshake is performed by sending a request and receiving the appropriate response from the server. Data is then sent and received using the WebSocket protocol, and checks are made to ensure the complete message is transmitted. Finally, the connection is closed, and the close status and reason are confirmed.
To get a copy of Windows, go to Downloads and tools.
To get a copy of Visual Studio, go to Visual Studio Downloads.
For general information about WebSocket connections and how the protocol works, see the IETF's WebSocket Protocol documentation.
Related topics
Windows HTTP Services (WinHTTP)
WinHttpWebSocketCompleteUpgrade
WinHttpWebSocketQueryCloseStatus
Operating system requirements
Client
Windows 8.1
Server
Windows Server 2012 R2
Build the sample
To build the sample using Visual Studio:
- Open Windows Explorer and navigate to the \cpp directory.
- Double-click the icon for the WinhttpWebsocket.sln file to open the file in Visual Studio.
- In the Build menu, select Build Solution. The application will be built in the default \Debug or \Release directory.
Run the sample
This sample requires that a web server that supports WebSockets is available for the app to access for sending and receiving data. The web server must be started before the app is run. The web server must also have a WinHttpWebSocketSample path available. The sample includes a PowerShell script that will install IIS on the local computer, create the WinHttpWebSocketSample folder on the server, and copy a file to this folder.
The easiest way to run the sample is to use the provided PowerShell scripts. Browse to the Server folder in your sample folder to setup and start the web server for WebSockets. There are two options possible.
-
Start PowerShell elevated (Run as administrator) and run the following command:
.\SetupScript.ps1
Note that you may also need to change script execution policy.
-
Start an elevated Command Prompt (Run as administrator) and run following command:
PowerShell.exe -ExecutionPolicy Unrestricted -File SetupServer.ps1
When the web server is not needed anymore, please browse to the Server folder in your sample folder and run one of the following:
-
Start PowerShell elevated (Run as administrator) and run the following command:
.\RemoveScript.ps1
Note that you may also need to change script execution policy.
-
Start an elevated Command Prompt (Run as administrator) and run following command:
PowerShell.exe -ExecutionPolicy Unrestricted -File RemoveScript.ps1
The sample can run using any web server that supports WebSockets, not only the one provided with the sample. In this case, running the previous scripts are not required. However, this requires some special configuration of the server to create the WinHttpWebSocketSample folder and copy a file to this folder. The sample must also be updated if run against a non-localhost web server:
To configure the sample for use with a different web server:
Copy the Server\webSite directory to the WinHttpWebSocketSample folder on the web server and configure the server to support WebSockets.
The target server name should be updated in the sources. This is changed by editing the WinhttpWebsocket.cpp source file so that the pcwszServerName value that contains the hostname or IP address of the web server is substituted for localhost.
Note IIS is not available on ARM builds. Instead, set up the web server on a separate 64-bit or 32-bit computer and follow the steps for using the sample against a non-localhost web server.
To run the sample:
- Run WinhttpWebsocket by clicking Start Without Debugging on the Debug menu.