WNetAddConnectionA function (winnetwk.h)
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.
Syntax
DWORD WNetAddConnectionA(
[in] LPCSTR lpRemoteName,
[in] LPCSTR lpPassword,
[in] LPCSTR lpLocalName
);
Parameters
[in] lpRemoteName
A pointer to a constant null-terminated string that specifies the network resource to connect to.
[in] 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.
[in] 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 |
|---|---|
|
The caller does not have access to the network resource. |
|
The device specified in the lpLocalName parameter is already connected. |
|
The device type and the resource type do not match. |
|
The value specified in the lpLocalName parameter is invalid. |
|
The value specified in the lpRemoteName parameter is not valid or cannot be located. |
|
The user profile is in an incorrect format. |
|
The system is unable to open the user profile to process persistent connections. |
|
An entry for the device specified in the lpLocalName parameter is already in the user profile. |
|
A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function. |
|
The specified password is invalid. |
|
The operation cannot be performed because a network component is not started or because a specified name cannot be used. |
|
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.
Note
The winnetwk.h header defines WNetAddConnection as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| 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 |