BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Network and Internet
.NET 1.1+

Mapping a Drive Letter Programmatically

Some legacy applications do not permit the use of UNC paths when accessing network folders, instead requiring that a drive letter be mapped. When interacting with such software it may be necessary to map a drive letter and later remove mappings using C#.

Connection Flags

When the connection functions are called, a series of flags can be passed to the command to affect its behaviour. There are six flags, each defined in the table below:

Flag NameValueDescription
CONNECT_UPDATE_PROFILE0x1If this flag is set, the operating system is instructed to remember the mapping of the drive letter in the user's profile. This means that if the user logs off, when they log on again at a later date, an attempt to restore the connection will be made.
CONNECT_INTERACTIVE0x8When this flag is set, the operating system is permitted to ask the user for authentication information before attempting to map the drive letter.
CONNECT_PROMPT0x10When set, this flag indicates that any default user name and password credentials will not be used without first giving the user the opportunity to override them. This flag is ignored if CONNECT_INTERACTIVE is not also specified.
CONNECT_REDIRECT0x80This flag forces the redirection of a local device when making the connection. For the functionality described in this article the flag has no effect. It is included here for completeness.
CONNECT_COMMANDLINE0x800This flag indicates that if the operating system needs to ask for a user name and password, it should do so using the command line rather than by using dialog boxes. This flag is ignored if CONNECT_INTERACTIVE is not also specified. It is not available to Windows 2000 or earlier versions of the operating system.
CONNECT_CMD_SAVECRED0x1000If set, this flag specifies that any credentials entered by the user will be saved. If it is not possible to save the credentials or the CONNECT_INTERACTIVE is not also specified then the flag is ignored.

We can create these values in the program by defining the following constants:

const uint CONNECT_UPDATE_PROFILE = 0x1;
const uint CONNECT_INTERACTIVE = 0x8;
const uint CONNECT_PROMPT = 0x10;
const uint CONNECT_REDIRECT = 0x80;
const uint CONNECT_COMMANDLINE = 0x800;
const uint CONNECT_CMD_SAVECRED = 0x1000;

Calling WNetAddConnection2

We have now prepared all of the constants and structures that are used by the WNetAddConnection functions. Let's now look at calling the simpler of the two methods, WNetAddConnection2. To do so, we use the following syntax:

result = WNetAddConnection2(ref lpNetResource, lpPassword, lpUserName, dwFlags);

The result value returns an unsigned 32-bit integer. A returned zero indicates that the process completed successfully. All other values represent a standard system error code that explains why the call failed. This value should be checked as the function does not throw exceptions to indicate failure.

lpNetResource holds a NETRESOURCE value. This item contains the details of the shared folder and the local drive letter to be mapped. Note that this parameter must be passed by reference.

lpPassword and lpUserName should contain the login credentials of the user that you wish to use to make the connection to the shared resource. These values may be different to that of the currently logged in interactive user, or of the user that the process is executing under. If you pass null to both of these values, the operating system will automatically use the details from the current user context.

dwFlags is an unsigned integer containing the flags that will be used to control the call's exact behaviour. The flags are described in the earlier. They should be combined using logical bitwise operations.

Example 1 - Simple Mapping

The simplest way to call the WNetAddConnection2 function is to pass the details of the network resource but not specify any user credentials or flags. Using this method, the system will simply try to map a drive letter using the current credentials without prompting the user for login details. The example below tries to map Z: to the path "\\BlackWasp\ImageGallery". To try it, change the drive letter to one that is not already mapped on your system and the UNC path to a shared resource that you have access to.

NETRESOURCE networkResource = new NETRESOURCE();
networkResource.dwType = RESOURCETYPE_DISK;
networkResource.lpLocalName = "Z:";
networkResource.lpRemoteName = @"\\BlackWasp\ImageGallery";
networkResource.lpProvider = null;

uint result = WNetAddConnection2(ref networkResource, null, null, 0);
MessageBox.Show(result.ToString());

Example 2 - Specifying User Credentials

In the second example, we will specify the user name and password to use when connecting the new drive letter to the shared folder. This method is useful when you have requested these details from the user at an earlier time, particularly if you are mapping several drive letters using the same login details. You should not use this method with hard-coded credentials, as in the sample code, as this could pose a security risk.

To try this sample, disconnect the previously mapped drive and modify the call to WNetAddConnection2 as follows. You should include a login name and password that is valid for the UNC path.

uint result = WNetAddConnection2(ref networkResource, "password", "username", 0);

Example 3 - Requesting Credentials

In the third example we will allow the operating system to request the logon credentials to use when accessing the shared resource. We will also instruct the O/S to remember these login details and add the drive mapping to the user's profile. This is achieved by modifying the call as follows:

uint flags =
    CONNECT_INTERACTIVE | CONNECT_PROMPT | CONNECT_CMD_SAVECRED | CONNECT_UPDATE_PROFILE;
    
uint result = WNetAddConnection2(ref networkResource, null, null, flags);
21 September 2008