SAMPLE: How to Use AsyncHTTP to Call WinInet APIs Asynchronously

Although you can use the WinInet APIs to call functions asynchronously, there are a number of issues that you need to be aware of if you are writing an asynchronous WinInet application. AsyncHTTP is a sample application that demonstrates how to properly call the WinInet API asynchronously.

When you use the WinInet APIs asynchronously, you must be aware of the following issues:

• To make asynchronous WinInet calls, you must first specify a callback function by using InternetSetStatusCallback. You can then set the WININET_API_FLAG_ASYNC flag on a function call and specify a non-zero dwContext parameter. If the function returns a failure condition and GetLastError returns ERROR_IO_PENDING, the call is complete when your callback function is called with the INTERNET_STATUS_REQUEST_COMPLETE notification.
  
  
• By default, if you set dwContext to zero, your callback function is not called. Use a non-zero value for your dwContext parameter or specify the WININET_API_FLAG_USE_CONTEXT option if you must use a zero dwContext.
  
  
• You must preserver the order of the WinInet function calls. For example, if you call HttpSendRequest asynchronously, you must wait until you receive the corresponding INTERNET_STATUS_REQUEST_COMPLETE notification before you can call InternetReadFile.
  
  
• In some instances, you can specify the WININET_API_FLAG_ASYNC flag, and the function returns successfully. You will only receive a INTERNET_STATUS_REQUEST_COMPLETE notification in your callback if the function fails and GetLastError returns ERROR_IO_PENDING. If the function call returns successfully, you do not receive an INTERNET_STATUS_REQUEST_COMPLETE notification.
  
  
• For asynchronous calls that return handles, you must wait for the INTERNET_STATUS_HANDLE_CREATED notification to get the value of the handle that has been created for you. When you receive this notification, save the handle value from the INTERNET_ASYNC_RESULT structure's dwResult member. You cannot use this handle until you have received the INTERNET_STATUS_REQUEST_COMPLETE notification.
  
  
• Do not make assumptions as to whether or not a function returns successfully or whether it fails with GetLastError indicating ERROR_IO_PENDING. Check the return code and act accordingly.
  
  
• Context values are set per WinInet handle. Therefore, after you set the context value for a handle, WinInet continues to use that value even if you specify a different context value for another API that uses the same handle.

The following file is available for download from the Microsoft Download Center:
Release Date: Jan-24-2002

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base: Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file. The Asynchttp.exe file contains the following files: