WNetAddConnectionA function

The WNetAddConnection function enables the calling application to connect a local device to a network resource. A successful connection is persistent, meaning that the system automatically restores the connection during subsequent logon operations.

Note  This function is provided only for compatibility with 16-bit versions of Windows. Other Windows-based applications should call the WNetAddConnection2 or the WNetAddConnection3 function.
 

Syntax

DWORD WNetAddConnectionA(
  LPCSTR lpRemoteName,
  LPCSTR lpPassword,
  LPCSTR lpLocalName
);

Parameters

lpRemoteName

A pointer to a constant null-terminated string that specifies the network resource to connect to.

lpPassword

A pointer to a constant null-terminated string that specifies the password to be used to make a connection. This parameter is usually the password associated with the current user.

If this parameter is NULL, the default password is used. If the string is empty, no password is used.

Windows Me/98/95:  This parameter must be NULL or an empty string.

lpLocalName

A pointer to a constant null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is NULL, a connection to the network resource is made without redirecting the local device.

Return value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is a system error code, such as one of the following values.

Return code Description
ERROR_ACCESS_DENIED
The caller does not have access to the network resource.
ERROR_ALREADY_ASSIGNED
The device specified in the lpLocalName parameter is already connected.
ERROR_BAD_DEV_TYPE
The device type and the resource type do not match.
ERROR_BAD_DEVICE
The value specified in the lpLocalName parameter is invalid.
ERROR_BAD_NET_NAME
The value specified in the lpRemoteName parameter is not valid or cannot be located.
ERROR_BAD_PROFILE
The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE
The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED
An entry for the device specified in the lpLocalName parameter is already in the user profile.
ERROR_EXTENDED_ERROR
A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_INVALID_PASSWORD
The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH
The operation cannot be performed because a network component is not started or because a specified name cannot be used.
ERROR_NO_NETWORK
The network is unavailable.

Remarks

On Windows Server 2003 and Windows XP, the WNet functions create and delete network drive letters in the MS-DOS device namespace associated with a logon session because MS-DOS devices are identified by AuthenticationID (a
locally unique identifier, or LUID, associated with a logon session.) This can affect applications that call one of the WNet functions to create a network drive letter under one user logon, but query for existing network drive letters under a different user logon. An example of this situation could be when a user's second logon is created within a logon session, for example, by calling the CreateProcessAsUser function, and the second logon runs an application that calls the GetLogicalDrives function. The call to the GetLogicalDrives function does not return network drive letters created by WNet function calls under the first logon. Note that in the preceding example the first logon session still exists, and the example could apply to any logon session, including a Terminal Services session. For more information, see Defining an MS-DOS Device Name.

On Windows Server 2003 and Windows XP, if a service that runs as LocalSystem calls the WNetAddConnection function, then the mapped drive is visible to all user logon sessions.

Requirements

   
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header winnetwk.h
Library Mpr.lib
DLL Mpr.dll

See also

WNetAddConnection2

WNetAddConnection3

WNetCancelConnection

WNetCancelConnection2

WNetGetConnection

Windows Networking (WNet) Overview

Windows Networking Functions