Working with common WinInet APIs

This article has two parts. First part is the introduction to WinInet APIs required using InternetOpenUrl and second part is sample code. Sample code is a dialog base VC++/MFC application that is attached as Url.zip.

Before talking about InternetOpenUrl, we need to look into InternetOpen API.

InternetOpen

This function is root of all WinInet functions, and must be called before any WinInet function. The InternetOpen function initializes WinInet environment and prepares to call other WinInet functions. Basically this function starts a new Internet session. The WinInet is based on hierarchy so next level function will require the handle returned by InternetOpen. Here is syntax of InternetOpen function:

HINTERNET InternetOpen( IN LPCSTR lpszAgent, IN WORD dwAccessType, IN LPCSTR lpszProxyName, IN LPCSTR lpszProxyBypass, IN WORD dwFlags );

Where, lpszAgent - String containing the name of the application. dwAccessType specifies how this internet session should attempt to access the Internet.

lpszProxyName and lpszProxyBypass parameters are valid only you use INTERNET_OPEN_TYPE_PROXY as second parameter.  lpszProxyName is the name of proxy server, and lpszProxyBypass is list of proxy servers. You can specify more than one proxy in lpszProxyName parameter. lpszProxyBypass parameter allows to specify an IP address to bypass a proxy server. The fourth parameter, dwFlags, allows controlling the Internet session behavior. Value of this parameter is either INTERNET_FLAG_OFFLINE, puts Internet session in offline mode, or INTERNET_FLAG_ASYNC, which foreces that all operations should b asynchronous. Here is an example,

HINTERNET hInternet = InternetOpen( "TestApp", INTERNET_OPEN_TYPE_PROXY, "prxy.server.com", 158.55.255.251, INTERNET_FLAG_ASYNC );

We will see this in more details in our example later.

After initializing WinInet, there are two ways to work with Internet. Either URL related requirement, or protocol related requirement. InternetConnect function is followed by protocol related functions and InternetOpenUrl is related to URLs.

Here is when to choose what?

InternetOpenUrl - Download a web page, downoad an image via HTTP, download a file via FTP, or download a file via Gopher.

InternetConnect - HTTP POST/GET headers to send and retrieve data, work with FTP such as create, rename, delete directories or upload/download  file, use gopher locators.

InternetConnect

InternetConnect is responsible for starting new HTTP, FTP, or Gopher session after establishing a connection using InternetOpen. A single application can have multiple InternetConnect objects, depends on the requirement of the application.

HINTERNET InternetConnect(IN HINTERNET hInternetSession, IN LPCSTR lpszServerName,IN INTERNET_PORT nServerPort, IN LPCSTR lpszUsername, IN LPCSTR lpszPassword,IN DWORD dwService, IN DWORD dwFlags, IN DWORD dwContext);

Opens an FTP, Gopher, or HTTP session for a given site. 

InternetCloseHandle

BOOL InternetCloseHandle (IN HINTERNET hInet );

This function closes opened Internet connection and terminates any pending operations on the handle and discards any outstanding data. 

Here is an example of InterrnetConnect:

HINTERNET InternetOpen( IN LPCSTR lpszAgent, IN WORD dwAccessType, IN LPCSTR lpszProxyName, IN LPCSTR lpszProxyBypass, IN WORD dwFlags );
 
Working with URLs

InternetOpenUrl is the main function required to work with URLs after InternetOpen. Other functions are helper functions.

InternetOpenUrl

HINTERNET InternetOpenUrl(IN HINTERNET hInternetSession, IN LPCSTR lpszUrl,
IN LPCSTR lpszHeaders, IN DWORD dwHeadersLength, IN DWORD dwFlags,
IN DWORD dwContext );

This is a general function that an application can use to retrieve data over any of the protocols that the Win32 Internet functions support. This function is particularly useful when the application does not need to access the particulars of a protocol, but only requires the data corresponding to a URL. The InternetOpenUrl function parses the URL string, establishes a connection to the server, and prepares to download the data identified by the URL. The application can then use InternetReadFile (for files) or InternetFindNextFile (for directories) to retrieve the URL data. It is not necessary to call InternetConnect before InternetOpenUrl.

Sample: Using InternetOpenUrl to download a URL

Downloading a web page's contents is pretty simple using InternetOpenUrl. Here are few simple steps:

• Create a dialog based application with two buttons and two edit boxes. Set content edit box's as multiline.
  
  
  
  
  
• Add two variables using Class wizard, m_strURL and m_strContents, for each edit boxes.  
• Include <wininet.h> in your stdafx.h and link to wininet.lib in your project settings. WinInet.lib is in your Lib directory of Visual Studio. 
• And Add a handler for Download button using Class Wizard and add this piece of code:
  
  void COpenUrlDlg::OnOk()
  {
  UpdateData(TRUE);
  if ( m_strURL.IsEmpty() )
  return;
  HINTERNET hINet, hFile;
  hINet = InternetOpen("InetURL/1.0", INTERNET_OPEN_TYPE_PRECONFIG, NULL, NULL, 0 );
  if ( !hINet )
  {
  AfxMessageBox("InternetOpen Failed");
  return;
  }
  hFile = InternetOpenUrl( hINet, m_strURL, NULL, 0, 0, 0 ) ;
  if ( hFile )
  {
  CHAR buffer[1024];
  DWORD dwRead;
  while ( InternetReadFile( hFile, buffer, 1023, &dwRead ) )
  {
  if ( dwRead == 0 )
  break;
  buffer[dwRead] = 0;
  m_strURL += buffer;
  }
  InternetCloseHandle( hFile );
  }
  InternetCloseHandle( hINet );
  UpdateData(FALSE);}
• Now run your program, type URL with http and hit Download. You will see source code of the URL you have entered. 
• Don't forget to include wininet.h #include <wininet.h> in your stdafx.h.
  NOTE: Here is attached project. Url.zip 94 KB.

Other URL functions

• Introduction to WinInet. 
• WinInet APIs for HTTP and FTP with sample examples.
• WinInet MFC classes with sample examples. 
• Advanced WinInet and Security Issues.