WinHttpCloseHandle function (winhttp.h)
The WinHttpCloseHandle function closes a single HINTERNET handle (see HINTERNET Handles in WinHTTP).
Syntax
WINHTTPAPI BOOL WinHttpCloseHandle(
[in] HINTERNET hInternet
);
Parameters
[in] hInternet
A valid HINTERNET handle (see HINTERNET Handles in WinHTTP) to be closed.
Return value
TRUE if the handle is successfully closed, otherwise FALSE. To get extended error information, call GetLastError. Among the error codes returned are the following.
| Error Codes | Description |
|---|---|
|
The WinHTTP function support is being shut down or unloaded. |
|
An internal error has occurred. |
|
Not enough memory was available to complete the requested operation. (Windows error code) |
Remarks
Even when WinHTTP is used in asynchronous mode (that is, when WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates synchronously. The return value indicates success or failure. To get extended error information, call GetLastError.
If there is a status callback registered for the handle being closed and the handle was created with a non-NULL context value, a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING callback is made. This is the last callback made from the handle and indicates that the handle is being destroyed.
An application can terminate an in-progress asynchronous request by closing the HINTERNET request handle using WinHttpCloseHandle. Keep the following points in mind:
- After an application calls WinHttpCloseHandle on a WinHTTP handle, it cannot call any other WinHTTP API functions using that handle from any thread.
- Even after a call to WinHttpCloseHandle returns, the application must still be prepared to receive callbacks for the closed handle, because WinHTTP can tear down the handle asynchronously. If the asynchronous request was not able to complete successfully, the callback receives a WINHTTP_CALLBACK_STATUS_REQUEST_ERROR notification.
- If an application associates a context data structure or object with the handle, it should maintain that binding until the callback function receives a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification. This is the last callback notification WinHTTP sends prior to deleting a handle object from memory. In order to receive the WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING callback notification, the application must enable the WINHTTP_CALLBACK_FLAG_HANDLES flag in the WinHttpSetStatusCallback call.
-
Before calling WinHttpCloseHandle, an application can call WinHttpSetStatusCallback to indicate that no more callbacks should be made:
WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );It might seem that the context data structure could then be freed immediately rather than having to wait for a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification, but this is not the case: WinHTTP does not synchronize WinHttpSetStatusCallback with callbacks originating in worker threads. As a result, a callback could already be in progress from another thread, and the application could receive a callback notification even after having NULL ed-out the callback function pointer and deleted the handle's context data structure. Because of this potential race condition, be conservative in freeing the context structure until after having received the WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP, Windows 2000 Professional with SP3 [desktop apps only] |
| Minimum supported server | Windows Server 2003, Windows 2000 Server with SP3 [desktop apps only] |
| Target Platform | Windows |
| Header | winhttp.h |
| Library | Winhttp.lib |
| DLL | Winhttp.dll |
| Redistributable | WinHTTP 5.0 and Internet Explorer 5.01 or later on Windows XP and Windows 2000. |