Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 hwndOwnerparameter may be NULL.

lpNetResource

[in] Long pointer to a NETRESOURCEdata 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 NETRESOURCEstructure.

Value Description

dwType

Specifies the type of network resource to connect to. If lpLocalNamepoints to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalNameis NULL or points to an empty string, dwTypecan 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 lpLocalNameis 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 WNetAddConnection3function ignores the other members of the NETRESOURCEstructure.

lpPassword

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

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

If lpPasswordpoints 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 lpUserNameis 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 lpUserNameparameter 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 GetLastErrorvalues are described in the following table.

Value Description

ERROR_ACCESS_DENIED

Access to the network resource was denied.

ERROR_ALREADY_ASSIGNED

The local name specified by lpLocalNameis already connected to a network resource.

ERROR_BAD_DEVICE

The value specified by lpLocalNameis invalid.

ERROR_BAD_NET_NAME

The value specified by lpRemoteNameis not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.

ERROR_BUSY

The router or provider is busy, possibly initializing. The caller should retry.

ERROR_CANCELLED

The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers or by a called resource.

ERROR_DEVICE_ALREADY_REMEMBERED

An entry for the device specified in lpLocalNameis already in the user profile.

ERROR_INVALID_PASSWORD

The specified password is invalid.

ERROR_NO_NET_OR_BAD_PATH

The network component has not started, or the specified name could not be handled.

ERROR_NO_NETWORK

There is no network present.

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 lpLocalNamefield of the NETRESOURCEstructure 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 lpLocalNamestring.

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

Header winnetwk.h
Library coredll.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

NETRESOURCE