WNetAddConnection3

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function makes a connection to a network resource and can specify a local name for the resource.

Syntax

DWORD WNetAddConnection3(
  HWND hwndOwner, 
  LPNETRESOURCE lpNetResource, 
  LPTSTR lpPassword, 
  LPTSTR lpUserName, 
  DWORD dwFlags 
);

Parameters

• hwndOwner
  [in] Handle to a window that the provider of network resources can use as an owner window for dialog boxes.

  The hwndOwner parameter may be NULL.

• lpNetResource
  [in] Long pointer to a NETRESOURCE data structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

  You must specify the following members of the NETRESOURCE structure.

  Value	Description
  dwType	Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
  lpLocalName	Long pointer to a null-terminated string that specifies the name of a local device to be redirected, such as "MyDevice" or "LocalShare". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without assigning a local name.
  lpRemoteName	Long pointer to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length. The string must follow the network provider's naming conventions.
  lpProvider	Long pointer the network provider to connect to. Applications should set this to NULL because the Microsoft® Windows® Network is the only provider supported.

  The WNetAddConnection3 function ignores the other members of the NETRESOURCE structure.

• lpPassword
  [in] Long pointer to a null-terminated string that specifies a password to be used in making the network connection.

  If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

  If lpPassword points to an empty string, the function does not use a password.

• lpUserName
  [in] Long pointer to a null-terminated string that specifies a user name to be used in making the connection.

  If lpUserName is NULL, the function uses the default user name. For dial-up networking connections, the default user name is the one used to establish the connection. For LAN connections, the default user name is configured in the network control panel. On systems that support a windows user interface, the user is prompted to enter logon credentials if no default credentials exist or if the logon attempt fails using the existing credentials.

  The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

• dwFlags
  [in] Specifies connection options. It is the value shown in the following table.

  Value	Description
  CONNECT_UPDATE_PROFILE	The network resource connection should be remembered. If this bit flag is set, the registry will store the connection information and make it available when the system reboots. The operating system does not remember unsuccessful connections or unnamed connections. An unnamed connection occurs when lpLocalNameis NULL or points to an empty string.

Return Value

ERROR_SUCCESS indicates success. An error value indicates failure. Returning an error value provides compatibility with the behavior of the Windows for Workgroups function WNetAddConnection. You can also call the GetLastErrorfunction to obtain the same error value. Possible GetLastError values are described in the following table.

Remarks

Windows Embedded CE does not support the concept of drive-letters. An application can name a local resource "F:", but that naming convention has no special significance. The lpLocalName field of the NETRESOURCE structure can contain any string of up to 64 characters long. If the local name is NULL or empty, the resource is connected without a local name. If it is "*", the default name will be constructed as "<share> on <server>" extracted from the remote name of "\\server\share".

Except for nameless connections, the connected resource will appear as a subfolder under the Network directory. The subfolder is named after the lpLocalName string.

Windows Embedded CE supports only the "Microsoft Windows Network" provider. Persistent connections are stored in the registry and not automatically reconnected when the system is rebooted.

Requirements

See Also

Reference

NETRESOURCE