Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

InternetConnect (wininet)
 
.
Summary
Opens an FTP, Gopher, or HTTP session for a given site.

    * Returns a valid handle to the FTP, Gopher, or HTTP session if the connection is successful, or NULL otherwise. To get extended error information, call GetLastError. An application can also use InternetGetLastResponseInfo to determine why access to the service was denied.

C# Signature:

const short INTERNET_INVALID_PORT_NUMBER = 0;

const short INTERNET_DEFAULT_FTP_PORT = 21;

const short INTERNET_DEFAULT_GOPHER_PORT = 70;

const short INTERNET_DEFAULT_HTTP_PORT = 80;

const short INTERNET_DEFAULT_HTTPS_PORT = 443;

const short INTERNET_DEFAULT_SOCKS_PORT = 1080;

[DllImport("wininet.dll", SetLastError=true, CharSet=CharSet.Auto)]
static extern IntPtr InternetConnect(
   IntPtr hInternet, string lpszServerName, short nServerPort,
   string lpszUsername, string lpszPassword, int dwService,
   int dwFlags, IntPtr dwContext);

VB Signature:

Declare Auto Function InternetConnect Lib "wininet.dll" (
    ByVal hInternetSession As System.IntPtr,
    ByVal sServerName As String,
    ByVal nServerPort As Integer,
    ByVal sUsername As String,
    ByVal sPassword As String,
    ByVal lService As Int32,
    ByVal lFlags As Int32,
    ByVal lContext As System.IntPtr) As System.IntPtr

User-Defined Types:

hInternetSession

    Handle of the current Internet session. The handle must have been returned by a previous call to InternetOpen.

lpszServerName

    Address of a null-terminated string that contains the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).

nServerPort

    Number of the TCP/IP port on the server to connect to. Can be one of the values in the following list. If this parameter is set to INTERNET_INVALID_PORT_NUMBER, the function uses the default port for the specified service. These values do not cause the function to use this protocol. The value sets the port to be used. A flag must be used to set the service.
    Value     Meaning
    INTERNET_DEFAULT_FTP_PORT     Use the default port for FTP servers (port 21).
    INTERNET_DEFAULT_GOPHER_PORT     Use the default port for Gopher servers (port 70).
    INTERNET_DEFAULT_HTTP_PORT     Use the default port for HTTP servers (port 80).
    INTERNET_DEFAULT_HTTPS_PORT     Use the default port for HTTPS servers (port 443).

lpszUsername

    Address of a null-terminated string that contains the name of the user to log on. If this parameter is NULL, the function uses an appropriate default, except for HTTP. A NULL parameter in HTTP causes the server to return an error. For the FTP protocol, the default is anonymous.

lpszPassword

    Address of a null-terminated string that contains the password to use to log on. If both lpszPassword and lpszUsername are NULL, the function uses the default anonymous password. In the case of FTP, the default anonymous password is the user's e-mail name. If lpszPassword is NULL, but lpszUsername is not NULL, the function uses a blank password. The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword:
    lpszUsername     lpszPassword     User name sent to FTP server     Password sent to FTP server
    NULL     NULL     "anonymous"     User's e-mail name
    Non-NULL string     NULL     lpszUsername     ""
    NULL     Non-NULL string     ERROR     ERROR
    Non-NULL string     Non-NULL string     lpszUsername     lpszPassword

dwService

    Type of service to access. Can be one of these values:
    Value     Meaning
    INTERNET_SERVICE_FTP     FTP service.
    INTERNET_SERVICE_GOPHER     Gopher service.
    INTERNET_SERVICE_HTTP     HTTP service.

dwFlags

    Flags specific to the service used. Can be one of these values:
    If dwService is:     dwFlags supported
    INTERNET_SERVICE_FTP     INTERNET_CONNECT_FLAG_PASSIVE (Use passive mode in all data connections for this FTP session.)

dwContext

    An application-defined value that is used to identify the application context for the returned handle in callbacks.

Notes:

The InternetConnect function is required before communicating with any Internet service.

Having a connect function for all protocols, even those that do not use persistent connections, lets an application communicate common information about several requests using a single function call. In addition, this allows for future versions of Internet protocols that do not require a connection to be established for every client request.

For FTP sites, InternetConnect actually establishes a connection with the server; for others, such as Gopher, the actual connection is not established until the application requests a specific transaction.

For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and avoid calling this function for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect; when the user makes a request to a previously accessed server, that session handle is still available.

An application that needs to display multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve the text.

For FTP connections, if lpszUsername is NULL, InternetConnect sends the string "anonymous" as the user name. If lpszPassword is NULL, InternetConnect attempts to use the user's e-mail name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function disconnects the client from the server and frees all resources associated with the connection.

Tips & Tricks:

Please add some!

Sample Code:

Please add some!

Alternative Managed API:

Do you know one? Please contribute it!

Documentation
Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Edit This Page
Find References
Show Printable Version
Revisions