Tell us about your PDF experience.

Windows Networking (WNet)

Article • 01/24/20235 minutes to read

Overview of the Windows Networking (WNet) technology.

The Windows Networking (WNet) technology is not associated with any headers.

For programming guidance for this technology, see:

Windows Networking (WNet)

Functions
 

MultinetGetConnectionPerformanceA

Returns information about the expected performance of a connection used to access a network
resource. (ANSI)

MultinetGetConnectionPerformanceW

Returns information about the expected performance of a connection used to access a network
resource. (Unicode)

WNetAddConnection2A

The WNetAddConnection2 function makes a connection to a network resource and can redirect a
local device to the network resource. (ANSI)

WNetAddConnection2W

The WNetAddConnection2 function makes a connection to a network resource and can redirect a
local device to the network resource. (Unicode)

WNetAddConnection3A

The WNetAddConnection3 function makes a connection to a network resource. The function can
redirect a local device to the network resource. (ANSI)

WNetAddConnection3W

The WNetAddConnection3 function makes a connection to a network resource. The function can
redirect a local device to the network resource. (Unicode)
 

WNetAddConnectionA

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. (ANSI)

WNetAddConnectionW

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. (Unicode)

WNetCancelConnection2A

The WNetCancelConnection2 function cancels an existing network connection. You can also call
the function to remove remembered network connections that are not currently connected.
(ANSI)

WNetCancelConnection2W

The WNetCancelConnection2 function cancels an existing network connection. You can also call
the function to remove remembered network connections that are not currently connected.
(Unicode)

WNetCancelConnectionA

The WNetCancelConnection function cancels an existing network connection. (ANSI)

WNetCancelConnectionW

The WNetCancelConnection function cancels an existing network connection. (Unicode)

WNetCloseEnum

The WNetCloseEnum function ends a network resource enumeration started by a call to the
WNetOpenEnum function.

WNetConnectionDialog

The WNetConnectionDialog function starts a general browsing dialog box for connecting to
network resources. The function requires a handle to the owner window for the dialog box.

WNetConnectionDialog1A

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to

network resources. The function requires a CONNECTDLGSTRUCT to establish the dialog box
parameters. (ANSI)
 

WNetConnectionDialog1W

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to

network resources. The function requires a CONNECTDLGSTRUCT to establish the dialog box
parameters. (Unicode)

WNetDisconnectDialog

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from
network resources. The function requires a handle to the owner window for the dialog box.

WNetDisconnectDialog1A

The WNetDisconnectDialog1 function attempts to disconnect a network resource. (ANSI)

WNetDisconnectDialog1W

The WNetDisconnectDialog1 function attempts to disconnect a network resource. (Unicode)

WNetEnumResourceA

The WNetEnumResource function continues an enumeration of network resources that was

started by a call to the WNetOpenEnum function. (ANSI)

WNetEnumResourceW

The WNetEnumResource function continues an enumeration of network resources that was

started by a call to the WNetOpenEnum function. (Unicode)

WNetGetConnectionA

The WNetGetConnection function retrieves the name of the network resource associated with a
local device. (ANSI)

WNetGetConnectionW

The WNetGetConnection function retrieves the name of the network resource associated with a
local device. (Unicode)

WNetGetLastErrorA

The WNetGetLastError function retrieves the most recent extended error code set by a WNet
function. The network provider reported this error code; it will not generally be one of the errors
included in the SDK header file WinError.h. (ANSI)
 

WNetGetLastErrorW

The WNetGetLastError function retrieves the most recent extended error code set by a WNet
function. The network provider reported this error code; it will not generally be one of the errors
included in the SDK header file WinError.h. (Unicode)

WNetGetNetworkInformationA

The WNetGetNetworkInformation function returns extended information about a specific network

provider whose name was returned by a previous network enumeration. (ANSI)

WNetGetNetworkInformationW

The WNetGetNetworkInformation function returns extended information about a specific network

provider whose name was returned by a previous network enumeration. (Unicode)

WNetGetProviderNameA

The WNetGetProviderName function obtains the provider name for a specific type of network.
(ANSI)

WNetGetProviderNameW

The WNetGetProviderName function obtains the provider name for a specific type of network.
(Unicode)

WNetGetResourceInformationA

When provided with a remote path to a network resource, the WNetGetResourceInformation

function identifies the network provider that owns the resource and obtains information about the
type of the resource. (ANSI)

WNetGetResourceInformationW

When provided with a remote path to a network resource, the WNetGetResourceInformation

function identifies the network provider that owns the resource and obtains information about the
type of the resource. (Unicode)

WNetGetResourceParentA

The WNetGetResourceParent function returns the parent of a network resource in the network
browse hierarchy. Browsing begins at the location of the specified network resource. (ANSI)

WNetGetResourceParentW

The WNetGetResourceParent function returns the parent of a network resource in the network
browse hierarchy. Browsing begins at the location of the specified network resource. (Unicode)
 

WNetGetUniversalNameA

The WNetGetUniversalName function takes a drive-based path for a network resource and returns
an information structure that contains a more universal form of the name. (ANSI)

WNetGetUniversalNameW

The WNetGetUniversalName function takes a drive-based path for a network resource and returns
an information structure that contains a more universal form of the name. (Unicode)

WNetGetUserA

The WNetGetUser function retrieves the current default user name, or the user name used to
establish a network connection. (ANSI)

WNetGetUserW

The WNetGetUser function retrieves the current default user name, or the user name used to
establish a network connection. (Unicode)

WNetOpenEnumA

The WNetOpenEnum function starts an enumeration of network resources or existing

connections. You can continue the enumeration by calling the WNetEnumResource function.
(ANSI)

WNetOpenEnumW

The WNetOpenEnum function starts an enumeration of network resources or existing

connections. You can continue the enumeration by calling the WNetEnumResource function.
(Unicode)

WNetRestoreConnectionW

The WNetRestoreConnectionW function restores the connection to a network resource. The

function prompts the user, if necessary, for a name and password.

WNetUseConnectionA

The WNetUseConnection function makes a connection to a network resource. The function can
redirect a local device to a network resource. (ANSI)

WNetUseConnectionW

The WNetUseConnection function makes a connection to a network resource. The function can
redirect a local device to a network resource. (Unicode)
Structures
 

CONNECTDLGSTRUCTA

Used by the WNetConnectionDialog1 function to establish browsing dialog box parameters.

(ANSI)

CONNECTDLGSTRUCTW

Used by the WNetConnectionDialog1 function to establish browsing dialog box parameters.

(Unicode)

DISCDLGSTRUCTA

Used in the WNetDisconnectDialog1 function. The structure contains required information for the
disconnect attempt. (ANSI)

DISCDLGSTRUCTW

Used in the WNetDisconnectDialog1 function. The structure contains required information for the
disconnect attempt. (Unicode)

NETINFOSTRUCT

Contains information describing the network provider returned by the

WNetGetNetworkInformation function.
winnetwk.h header
Article • 01/24/20236 minutes to read

This header is used by multiple technologies. For more information, see:

Security and Identity

Windows Networking (WNet)

winnetwk.h contains the following programming interfaces:

Functions
 

MultinetGetConnectionPerformanceA

Returns information about the expected performance of a connection used to access a network
resource. (ANSI)

MultinetGetConnectionPerformanceW

Returns information about the expected performance of a connection used to access a network
resource. (Unicode)

WNetAddConnection2A

The WNetAddConnection2 function makes a connection to a network resource and can redirect a
local device to the network resource. (ANSI)

WNetAddConnection2W

The WNetAddConnection2 function makes a connection to a network resource and can redirect a
local device to the network resource. (Unicode)

WNetAddConnection3A

The WNetAddConnection3 function makes a connection to a network resource. The function can
redirect a local device to the network resource. (ANSI)

WNetAddConnection3W

The WNetAddConnection3 function makes a connection to a network resource. The function can
redirect a local device to the network resource. (Unicode)
 

WNetAddConnectionA

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. (ANSI)

WNetAddConnectionW

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. (Unicode)

WNetCancelConnection2A

The WNetCancelConnection2 function cancels an existing network connection. You can also call
the function to remove remembered network connections that are not currently connected.
(ANSI)

WNetCancelConnection2W

The WNetCancelConnection2 function cancels an existing network connection. You can also call
the function to remove remembered network connections that are not currently connected.
(Unicode)

WNetCancelConnectionA

The WNetCancelConnection function cancels an existing network connection. (ANSI)

WNetCancelConnectionW

The WNetCancelConnection function cancels an existing network connection. (Unicode)

WNetCloseEnum

The WNetCloseEnum function ends a network resource enumeration started by a call to the
WNetOpenEnum function.

WNetConnectionDialog

The WNetConnectionDialog function starts a general browsing dialog box for connecting to
network resources. The function requires a handle to the owner window for the dialog box.

WNetConnectionDialog1A

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to

network resources. The function requires a CONNECTDLGSTRUCT to establish the dialog box
parameters. (ANSI)
 

WNetConnectionDialog1W

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to

network resources. The function requires a CONNECTDLGSTRUCT to establish the dialog box
parameters. (Unicode)

WNetDisconnectDialog

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from
network resources. The function requires a handle to the owner window for the dialog box.

WNetDisconnectDialog1A

The WNetDisconnectDialog1 function attempts to disconnect a network resource. (ANSI)

WNetDisconnectDialog1W

The WNetDisconnectDialog1 function attempts to disconnect a network resource. (Unicode)

WNetEnumResourceA

The WNetEnumResource function continues an enumeration of network resources that was

started by a call to the WNetOpenEnum function. (ANSI)

WNetEnumResourceW

The WNetEnumResource function continues an enumeration of network resources that was

started by a call to the WNetOpenEnum function. (Unicode)

WNetGetConnectionA

The WNetGetConnection function retrieves the name of the network resource associated with a
local device. (ANSI)

WNetGetConnectionW

The WNetGetConnection function retrieves the name of the network resource associated with a
local device. (Unicode)

WNetGetLastErrorA

The WNetGetLastError function retrieves the most recent extended error code set by a WNet
function. The network provider reported this error code; it will not generally be one of the errors
included in the SDK header file WinError.h. (ANSI)
 

WNetGetLastErrorW

The WNetGetLastError function retrieves the most recent extended error code set by a WNet
function. The network provider reported this error code; it will not generally be one of the errors
included in the SDK header file WinError.h. (Unicode)

WNetGetNetworkInformationA

The WNetGetNetworkInformation function returns extended information about a specific network

provider whose name was returned by a previous network enumeration. (ANSI)

WNetGetNetworkInformationW

The WNetGetNetworkInformation function returns extended information about a specific network

provider whose name was returned by a previous network enumeration. (Unicode)

WNetGetProviderNameA

The WNetGetProviderName function obtains the provider name for a specific type of network.
(ANSI)

WNetGetProviderNameW

The WNetGetProviderName function obtains the provider name for a specific type of network.
(Unicode)

WNetGetResourceInformationA

When provided with a remote path to a network resource, the WNetGetResourceInformation

function identifies the network provider that owns the resource and obtains information about the
type of the resource. (ANSI)

WNetGetResourceInformationW

When provided with a remote path to a network resource, the WNetGetResourceInformation

function identifies the network provider that owns the resource and obtains information about the
type of the resource. (Unicode)

WNetGetResourceParentA

The WNetGetResourceParent function returns the parent of a network resource in the network
browse hierarchy. Browsing begins at the location of the specified network resource. (ANSI)

WNetGetResourceParentW

The WNetGetResourceParent function returns the parent of a network resource in the network
browse hierarchy. Browsing begins at the location of the specified network resource. (Unicode)
 

WNetGetUniversalNameA

The WNetGetUniversalName function takes a drive-based path for a network resource and returns
an information structure that contains a more universal form of the name. (ANSI)

WNetGetUniversalNameW

The WNetGetUniversalName function takes a drive-based path for a network resource and returns
an information structure that contains a more universal form of the name. (Unicode)

WNetGetUserA

The WNetGetUser function retrieves the current default user name, or the user name used to
establish a network connection. (ANSI)

WNetGetUserW

The WNetGetUser function retrieves the current default user name, or the user name used to
establish a network connection. (Unicode)

WNetOpenEnumA

The WNetOpenEnum function starts an enumeration of network resources or existing

connections. You can continue the enumeration by calling the WNetEnumResource function.
(ANSI)

WNetOpenEnumW

The WNetOpenEnum function starts an enumeration of network resources or existing

connections. You can continue the enumeration by calling the WNetEnumResource function.
(Unicode)

WNetRestoreConnectionW

The WNetRestoreConnectionW function restores the connection to a network resource. The

function prompts the user, if necessary, for a name and password.

WNetUseConnectionA

The WNetUseConnection function makes a connection to a network resource. The function can
redirect a local device to a network resource. (ANSI)

WNetUseConnectionW

The WNetUseConnection function makes a connection to a network resource. The function can
redirect a local device to a network resource. (Unicode)
Structures
 

CONNECTDLGSTRUCTA

Used by the WNetConnectionDialog1 function to establish browsing dialog box parameters.

(ANSI)

CONNECTDLGSTRUCTW

Used by the WNetConnectionDialog1 function to establish browsing dialog box parameters.

(Unicode)

DISCDLGSTRUCTA

Used in the WNetDisconnectDialog1 function. The structure contains required information for the
disconnect attempt. (ANSI)

DISCDLGSTRUCTW

Used in the WNetDisconnectDialog1 function. The structure contains required information for the
disconnect attempt. (Unicode)

NETCONNECTINFOSTRUCT

The NETCONNECTINFOSTRUCT structure contains information about the performance of a

network. It is used by the NPGetConnectionPerformance function.

NETINFOSTRUCT

Contains information describing the network provider returned by the

WNetGetNetworkInformation function.

NETRESOURCEA

The following structure contains information about a network resource. It is used by several of the
network provider functions, including NPOpenEnum and NPAddConnection. (ANSI)

NETRESOURCEW

The following structure contains information about a network resource. It is used by several of the
network provider functions, including NPOpenEnum and NPAddConnection. (Unicode)

REMOTE_NAME_INFOA

The REMOTE_NAME_INFO structure contains information about the remote form of a universal
name. It is used by the NPGetUniversalName function. (ANSI)
 

REMOTE_NAME_INFOW

The REMOTE_NAME_INFO structure contains information about the remote form of a universal
name. It is used by the NPGetUniversalName function. (Unicode)

UNIVERSAL_NAME_INFOA

The UNIVERSAL_NAME_INFO structure contains information about the UNC form of a universal
name. It is used by the NPGetUniversalName function. (ANSI)

UNIVERSAL_NAME_INFOW

The UNIVERSAL_NAME_INFO structure contains information about the UNC form of a universal
name. It is used by the NPGetUniversalName function. (Unicode)
CONNECTDLGSTRUCTA structure
(winnetwk.h)
Article • 07/27/20222 minutes to read

The
CONNECTDLGSTRUCT structure is used by the
WNetConnectionDialog1 function to
establish browsing dialog box parameters.

Syntax

typedef struct _CONNECTDLGSTRUCTA {

DWORD cbStructure;

HWND hwndOwner;

LPNETRESOURCEA lpConnRes;

DWORD dwFlags;

DWORD dwDevNum;

} CONNECTDLGSTRUCTA, *LPCONNECTDLGSTRUCTA;

Members
cbStructure

Type: DWORD

The size, in bytes, of the

CONNECTDLGSTRUCT structure. The caller must supply this
value.

hwndOwner

Type: HWND

The handle to the owner window for the dialog box.

lpConnRes

Type: LPNETRESOURCE

A pointer to a
NETRESOURCE structure.

If the lpRemoteName member of

NETRESOURCE is specified, it will be entered into the
path field of the dialog box. With the exception of the dwType member, all other
members of the
NETRESOURCE structure must be set to NULL. The dwType member
must be equal to RESOURCETYPE_DISK.

The system does not support the RESOURCETYPE_PRINT flag for browsing and
connecting to print resources.

dwFlags

Type: DWORD

A set of bit flags that describe options for the dialog box display. This member can be a
combination of the following values.

Value Meaning

SidTypeUser The account is a user account.

CONNDLG_RO_PATH Display a read-only path instead of allowing the user to

type in a path.
This flag should be set only if the lpRemoteName
member of the
NETRESOURCE structure pointed to by
lpConnRes member is not NULL (or an empty string), and
the CONNDLG_USE_MRU flag is not set.

CONNDLG_CONN_POINT Internal flag. Do not use.

CONNDLG_USE_MRU Enter the most recently used paths into the combination
box. Set this value to simulate the
WNetConnectionDialog function.

CONNDLG_HIDE_BOX Show the check box allowing the user to restore the
connection at logon.

CONNDLG_PERSIST Restore the connection at logon.

CONNDLG_NOT_PERSIST Do not restore the connection at logon.

For more information, see the following Remarks section.

dwDevNum

Type: DWORD

If the call to the

WNetConnectionDialog1 function is successful, this member returns the
number of the connected device. The value is 1 for A:, 2 for B:, 3 for C:, and so on. If the
user made a deviceless connection, the value is –1.
Remarks
If neither the CONNDLG_RO_PATH nor the CONNDLG_USE_MRU flag is set, and the
lpRemoteName member of the
NETRESOURCE structure does not specify a remote
path, the request defaults to the CONNDLG_RO_PATH dialog display type.

The CONNDLG_PERSIST and CONNDLG_NOT_PERSIST values cannot both be set. If

neither is set, the dialog box defaults to the last option that was selected in this dialog
box for the particular type of device connection.

７ Note

The winnetwk.h header defines CONNECTDLGSTRUCT as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

Requirements
   

Minimum supported client Windows 2000 Professional [desktop apps only]

Minimum supported server Windows 2000 Server [desktop apps only]

Header winnetwk.h

See also
NETRESOURCE

WNetConnectionDialog1

Windows Networking (WNet) Overview

Windows Networking Structures

CONNECTDLGSTRUCTW structure
(winnetwk.h)
Article • 07/27/20222 minutes to read

The
CONNECTDLGSTRUCT structure is used by the
WNetConnectionDialog1 function to
establish browsing dialog box parameters.

Syntax
C++

typedef struct _CONNECTDLGSTRUCTW {

DWORD cbStructure;

HWND hwndOwner;

LPNETRESOURCEW lpConnRes;

DWORD dwFlags;

DWORD dwDevNum;

} CONNECTDLGSTRUCTW, *LPCONNECTDLGSTRUCTW;

Members
cbStructure

Type: DWORD

The size, in bytes, of the

CONNECTDLGSTRUCT structure. The caller must supply this
value.

hwndOwner

Type: HWND

The handle to the owner window for the dialog box.

lpConnRes

Type: LPNETRESOURCE

A pointer to a
NETRESOURCE structure.

If the lpRemoteName member of

NETRESOURCE is specified, it will be entered into the
path field of the dialog box. With the exception of the dwType member, all other
members of the
NETRESOURCE structure must be set to NULL. The dwType member
must be equal to RESOURCETYPE_DISK.

The system does not support the RESOURCETYPE_PRINT flag for browsing and
connecting to print resources.

dwFlags

Type: DWORD

A set of bit flags that describe options for the dialog box display. This member can be a
combination of the following values.

Value Meaning

SidTypeUser The account is a user account.

CONNDLG_RO_PATH Display a read-only path instead of allowing the user to

type in a path.
This flag should be set only if the lpRemoteName
member of the
NETRESOURCE structure pointed to by
lpConnRes member is not NULL (or an empty string), and
the CONNDLG_USE_MRU flag is not set.

CONNDLG_CONN_POINT Internal flag. Do not use.

CONNDLG_USE_MRU Enter the most recently used paths into the combination
box. Set this value to simulate the
WNetConnectionDialog function.

CONNDLG_HIDE_BOX Show the check box allowing the user to restore the
connection at logon.

CONNDLG_PERSIST Restore the connection at logon.

CONNDLG_NOT_PERSIST Do not restore the connection at logon.

For more information, see the following Remarks section.

dwDevNum

Type: DWORD

If the call to the

WNetConnectionDialog1 function is successful, this member returns the
number of the connected device. The value is 1 for A:, 2 for B:, 3 for C:, and so on. If the
user made a deviceless connection, the value is –1.
Remarks
If neither the CONNDLG_RO_PATH nor the CONNDLG_USE_MRU flag is set, and the
lpRemoteName member of the
NETRESOURCE structure does not specify a remote
path, the request defaults to the CONNDLG_RO_PATH dialog display type.

The CONNDLG_PERSIST and CONNDLG_NOT_PERSIST values cannot both be set. If

neither is set, the dialog box defaults to the last option that was selected in this dialog
box for the particular type of device connection.

７ Note

The winnetwk.h header defines CONNECTDLGSTRUCT as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

Requirements
   

Minimum supported client Windows 2000 Professional [desktop apps only]

Minimum supported server Windows 2000 Server [desktop apps only]

Header winnetwk.h

See also
NETRESOURCE

WNetConnectionDialog1

Windows Networking (WNet) Overview

Windows Networking Structures

DISCDLGSTRUCTA structure
(winnetwk.h)
Article • 07/27/20222 minutes to read

The
DISCDLGSTRUCT structure is used in the
WNetDisconnectDialog1 function. The
structure contains required information for the disconnect attempt.

Syntax
C++

typedef struct _DISCDLGSTRUCTA {

DWORD cbStructure;

HWND hwndOwner;

LPSTR lpLocalName;

LPSTR lpRemoteName;

DWORD dwFlags;

} DISCDLGSTRUCTA, *LPDISCDLGSTRUCTA;

Members
cbStructure

Type: DWORD

The size, in bytes, of the

DISCDLGSTRUCT structure. The caller must supply this value.

hwndOwner

Type: HWND

A handle to the owner window of the dialog box.

lpLocalName

Type: LPTSTR

A pointer to a NULL-terminated string that specifies the local device name that is
redirected to the network resource, such as "F:" or "LPT1".

lpRemoteName

Type: LPTSTR
A pointer to a NULL-terminated string that specifies the name of the network resource
to disconnect. This member can be NULL if the lpLocalName member is specified. When
lpLocalName is specified, the connection to the network resource redirected from
lpLocalName is disconnected.

dwFlags

Type: DWORD

A set of bit flags describing the connection. This member can be a combination of the
following values.

Value Meaning

DISC_UPDATE_PROFILE If this value is set, the specified connection is no longer a

persistent one (automatically restored every time the user
logs on). This flag is valid only if the lpLocalName
member specifies a local device.

DISC_NO_FORCE If this value is not set, the system applies force when
attempting to disconnect from the network resource.
This situation typically occurs when the user has files
open over the connection. This value means that the user
will be informed if there are open files on the connection,
and asked if he or she still wants to disconnect. If the user
wants to proceed, the disconnect procedure re-attempts
with additional force.

Remarks

７ Note

The winnetwk.h header defines DISCDLGSTRUCT as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements
   

Minimum supported client Windows 2000 Professional [desktop apps only]

    

Minimum supported server Windows 2000 Server [desktop apps only]

Header winnetwk.h

See also
WNetDisconnectDialog1

Windows Networking (WNet) Overview

Windows Networking Structures

DISCDLGSTRUCTW structure
(winnetwk.h)
Article • 07/27/20222 minutes to read

The
DISCDLGSTRUCT structure is used in the
WNetDisconnectDialog1 function. The
structure contains required information for the disconnect attempt.

Syntax
C++

typedef struct _DISCDLGSTRUCTW {

DWORD cbStructure;

HWND hwndOwner;

LPWSTR lpLocalName;

LPWSTR lpRemoteName;

DWORD dwFlags;

} DISCDLGSTRUCTW, *LPDISCDLGSTRUCTW;

Members
cbStructure

Type: DWORD

The size, in bytes, of the

DISCDLGSTRUCT structure. The caller must supply this value.

hwndOwner

Type: HWND

A handle to the owner window of the dialog box.

lpLocalName

Type: LPTSTR

A pointer to a NULL-terminated string that specifies the local device name that is
redirected to the network resource, such as "F:" or "LPT1".

lpRemoteName

Type: LPTSTR
A pointer to a NULL-terminated string that specifies the name of the network resource
to disconnect. This member can be NULL if the lpLocalName member is specified. When
lpLocalName is specified, the connection to the network resource redirected from
lpLocalName is disconnected.

dwFlags

Type: DWORD

A set of bit flags describing the connection. This member can be a combination of the
following values.

Value Meaning

DISC_UPDATE_PROFILE If this value is set, the specified connection is no longer a

persistent one (automatically restored every time the user
logs on). This flag is valid only if the lpLocalName
member specifies a local device.

DISC_NO_FORCE If this value is not set, the system applies force when
attempting to disconnect from the network resource.
This situation typically occurs when the user has files
open over the connection. This value means that the user
will be informed if there are open files on the connection,
and asked if he or she still wants to disconnect. If the user
wants to proceed, the disconnect procedure re-attempts
with additional force.

Remarks

７ Note

The winnetwk.h header defines DISCDLGSTRUCT as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements
   

Minimum supported client Windows 2000 Professional [desktop apps only]

    

Minimum supported server Windows 2000 Server [desktop apps only]

Header winnetwk.h

See also
WNetDisconnectDialog1

Windows Networking (WNet) Overview

Windows Networking Structures

MultinetGetConnectionPerformanceA
function (winnetwk.h)
Article • 02/09/20233 minutes to read

The
MultinetGetConnectionPerformance function returns information about the
expected performance of a connection used to access a network resource.

Syntax
C++

DWORD MultinetGetConnectionPerformanceA(

[in] LPNETRESOURCEA lpNetResource,

[out] LPNETCONNECTINFOSTRUCT lpNetConnectInfoStruct

);

Parameters
[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies the network resource. The
following members have specific meanings in this context.

Member Meaning

lpLocalName A pointer to a buffer that specifies a local device, such as

"F:" or "LPT1", that is redirected to a network resource to
be queried.
If this member is NULL or an empty string, the network
resource is specified in the lpRemoteName member. If
this flag specifies a local device, lpRemoteName is
ignored.

lpRemoteName A pointer to a network resource to query. The resource

must currently have an established connection. For
example, if the resource is a file on a file server, then
having the file open will ensure the connection.

lpProvider Usually set to NULL, but can be a pointer to the owner

(provider) of the resource if the network on which the
resource resides is known.
 If the lpProvider member is not NULL, the system
attempts to return information only about the named
network.

[out] lpNetConnectInfoStruct

A pointer to the
NETCONNECTINFOSTRUCT structure that receives the data.

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_NOT_SUPPORTED The network resource does not supply this information.

ERROR_NOT_CONNECTED The lpLocalName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter does
not specify a redirected device, or the lpRemoteName
member does not specify the name of a resource that is
currently connected.

ERROR_NO_NET_OR_BAD_PATH The operation could not be completed, either because a

network component is not started, or because the
specified resource name is not recognized.

ERROR_BAD_DEVICE The local device specified by the lpLocalName member is

invalid.

ERROR_BAD_NET_NAME The network name cannot be found. This error is returned

if the lpLocalName member of the NETRESOURCE
structure pointed to by the lpNetResource parameter was
NULL and the lpRemoteName member of the
NETRESOURCE structure pointed to by the lpNetResource
was also or NULL or could not recognized by any
network.

ERROR_INVALID_ADDRESS An attempt to access an invalid address. This error is

returned if the lpNetResource or lpNetConnectInfoStruct
parameters were NULL.

ERROR_INVALID_PARAMETER A bad parameter was passed. This error is returned if the

lpNetConnectInfoStruct parameter does not point to a
NETCONNECTINFOSTRUCT structure in which the
cbStructure member is filled with the proper structure
size.
 ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call WNetGetLastError.

Remarks
The MultinetGetConnectionPerformance function returns the information in a
NETCONNECTINFOSTRUCT structure.

The information returned by the

MultinetGetConnectionPerformance function is an
estimate only. Network traffic and routing can affect the accuracy of the results
returned.

Note that the

MultinetGetConnectionPerformance function can be used only to
request information for a local device that is redirected to a network resource, or for a
network resource to which there is currently a connection.

If a UNC path is specified in the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter, the lpRemoteName member must
be a directory name, not a filename.

A typical way to use this function would be to open a file on a network server (which
would ensure that there is a connection to the file), call this function, and use the results
to make decisions about how to manage file I/O. For example, you can decide whether
to read the entire file into a temporary file on the client or directly access the file on the
server.

７ Note

The winnetwk.h header defines MultinetGetConnectionPerformance as an alias

which 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 not encoding-neutral can lead to mismatches
that result in compilation or runtime errors. For more information, see Conventions
for Function Prototypes.

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
NETCONNECTINFOSTRUCT

NETRESOURCE

Windows
Networking (WNet) Overview

Windows
Networking Functions
MultinetGetConnectionPerformanceW
function (winnetwk.h)
Article • 02/09/20233 minutes to read

The
MultinetGetConnectionPerformance function returns information about the
expected performance of a connection used to access a network resource.

Syntax
C++

DWORD MultinetGetConnectionPerformanceW(

[in] LPNETRESOURCEW lpNetResource,

[out] LPNETCONNECTINFOSTRUCT lpNetConnectInfoStruct

);

Parameters
[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies the network resource. The
following members have specific meanings in this context.

Member Meaning

lpLocalName A pointer to a buffer that specifies a local device, such as

"F:" or "LPT1", that is redirected to a network resource to
be queried.
If this member is NULL or an empty string, the network
resource is specified in the lpRemoteName member. If
this flag specifies a local device, lpRemoteName is
ignored.

lpRemoteName A pointer to a network resource to query. The resource

must currently have an established connection. For
example, if the resource is a file on a file server, then
having the file open will ensure the connection.

lpProvider Usually set to NULL, but can be a pointer to the owner

(provider) of the resource if the network on which the
resource resides is known.
 If the lpProvider member is not NULL, the system
attempts to return information only about the named
network.

[out] lpNetConnectInfoStruct

A pointer to the
NETCONNECTINFOSTRUCT structure that receives the data.

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_NOT_SUPPORTED The network resource does not supply this information.

ERROR_NOT_CONNECTED The lpLocalName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter does
not specify a redirected device, or the lpRemoteName
member does not specify the name of a resource that is
currently connected.

ERROR_NO_NET_OR_BAD_PATH The operation could not be completed, either because a

network component is not started, or because the
specified resource name is not recognized.

ERROR_BAD_DEVICE The local device specified by the lpLocalName member is

invalid.

ERROR_BAD_NET_NAME The network name cannot be found. This error is returned

if the lpLocalName member of the NETRESOURCE
structure pointed to by the lpNetResource parameter was
NULL and the lpRemoteName member of the
NETRESOURCE structure pointed to by the lpNetResource
was also or NULL or could not recognized by any
network.

ERROR_INVALID_ADDRESS An attempt to access an invalid address. This error is

returned if the lpNetResource or lpNetConnectInfoStruct
parameters were NULL.

ERROR_INVALID_PARAMETER A bad parameter was passed. This error is returned if the

lpNetConnectInfoStruct parameter does not point to a
NETCONNECTINFOSTRUCT structure in which the
cbStructure member is filled with the proper structure
size.
 ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call WNetGetLastError.

Remarks
The MultinetGetConnectionPerformance function returns the information in a
NETCONNECTINFOSTRUCT structure.

The information returned by the

MultinetGetConnectionPerformance function is an
estimate only. Network traffic and routing can affect the accuracy of the results
returned.

Note that the

MultinetGetConnectionPerformance function can be used only to
request information for a local device that is redirected to a network resource, or for a
network resource to which there is currently a connection.

If a UNC path is specified in the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter, the lpRemoteName member must
be a directory name, not a filename.

A typical way to use this function would be to open a file on a network server (which
would ensure that there is a connection to the file), call this function, and use the results
to make decisions about how to manage file I/O. For example, you can decide whether
to read the entire file into a temporary file on the client or directly access the file on the
server.

７ Note

The winnetwk.h header defines MultinetGetConnectionPerformance as an alias

which 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 not encoding-neutral can lead to mismatches
that result in compilation or runtime errors. For more information, see Conventions
for Function Prototypes.

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
NETCONNECTINFOSTRUCT

NETRESOURCE

Windows
Networking (WNet) Overview

Windows
Networking Functions
NETINFOSTRUCT structure (winnetwk.h)
Article • 04/02/20212 minutes to read

The
NETINFOSTRUCT structure contains information describing the network provider
returned by the
WNetGetNetworkInformation function.

Syntax
C++

typedef struct _NETINFOSTRUCT {

DWORD cbStructure;

DWORD dwProviderVersion;

DWORD dwStatus;

DWORD dwCharacteristics;

ULONG_PTR dwHandle;

WORD wNetType;

DWORD dwPrinters;

DWORD dwDrives;

} NETINFOSTRUCT, *LPNETINFOSTRUCT;

Members
cbStructure

Type: DWORD

The size, in bytes, of the

NETINFOSTRUCT structure. The caller must supply this value to
indicate the size of the structure passed in. Upon return, it has the size of the structure
filled in.

dwProviderVersion

Type: DWORD

The version number of the network provider software.

dwStatus

Type: DWORD

The current status of the network provider software. This member can be one of the
following values.
 Value Meaning

NO_ERROR The network is running.

ERROR_NO_NETWORK The network is unavailable.

ERROR_BUSY The network is not currently able to service requests, but

it should become available shortly. (This value typically
indicates that the network is starting up.)

dwCharacteristics

Type: DWORD

Characteristics of the network provider software.

This value is zero.

Windows Me/98/95:  This member can be one or more of the following values.

Value Meaning

NETINFO_DLL16 The network provider is running as a 16-bit Windows

network driver.

NETINFO_DISKRED The network provider requires a redirected local disk

drive device to access server file systems.

NETINFO_PRINTERRED The network provider requires a redirected local printer

port to access server file systems.

dwHandle

Type: ULONG_PTR

An instance handle for the network provider or for the 16-bit Windows network driver.

wNetType

Type: WORD

The network type unique to the running network. This value associates resources with a
specific network when the resources are persistent or stored in links. You can find a
complete list of network types in the header file Winnetwk.h.

dwPrinters

Type: DWORD
A set of bit flags indicating the valid print numbers for redirecting local printer devices,
with the low-order bit corresponding to LPT1.

Windows Me/98/95:  This value is always set to –1.

dwDrives

Type: DWORD

A set of bit flags indicating the valid local disk devices for redirecting disk drives, with
the low-order bit corresponding to A:.

Windows Me/98/95:  This value is always set to –1.

Remarks
The NETINFOSTRUCT structure contains information describing the network, such as
the version of the network provider software and the network's current status.

Requirements
   

Minimum supported client Windows 2000 Professional [desktop apps only]

Minimum supported server Windows 2000 Server [desktop apps only]

Header winnetwk.h

See also
WNetGetNetworkInformation

Windows Networking (WNet) Overview

Windows Networking Structures

WNetAddConnection2A function
(winnetwk.h)
Article • 02/09/202312 minutes to read

The
WNetAddConnection2 function makes a connection to a network resource and can
redirect a local device to the network resource.

The
WNetAddConnection2 function supersedes the
WNetAddConnection function. If
you can pass a handle to a window that the provider of network resources can use as an
owner window for dialog boxes, call the
WNetAddConnection3 function instead.

Syntax
C++

DWORD WNetAddConnection2A(

[in] LPNETRESOURCEA lpNetResource,

[in] LPCSTR lpPassword,

[in] LPCSTR lpUserName,
[in] DWORD dwFlags

);

Parameters
[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies details of the proposed
connection, such as information about the network resource, the local device, and the
network resource provider.

You must specify the following members of the

NETRESOURCE structure.

Member Meaning

dwType The type of network resource to connect to.

If the lpLocalName member points to a nonempty string,
this member can be equal to RESOURCETYPE_DISK or
RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string,

dwType can be equal to RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
 Although this member is required, its information may be
ignored by the network service provider.

lpLocalName A pointer to a null-terminated string that specifies the

name of a local device to redirect, such as "F:" or "LPT1".
The string is treated in a case-insensitive manner.

If the string is empty, or if lpLocalName is NULL, the

function makes a connection to the network resource
without redirecting a local device.

lpRemoteName A 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, and must follow the
network provider's naming conventions.

lpProvider A pointer to a null-terminated string that specifies the

network provider to connect to.

If lpProvider is NULL, or if it points to an empty string,

the operating system attempts to determine the correct
provider by parsing the string pointed to by the
lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know the network
provider you want to use. Otherwise, let the operating
system determine which provider the network name
maps to.

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

[in] lpPassword

A pointer to a constant 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 the lpUserName parameter.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

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

[in] lpUserName

A pointer to a constant null-terminated string that specifies a user name for making the
connection.

If lpUserName is NULL, the function uses the default user name. (The user context for
the process provides the default user name.)

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.

The user-name string represents a

security context. It may be specific to a network
provider.

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

[in] dwFlags

A set of connection options. The possible values for the connection options are defined
in the Winnetwk.h header file.
The following values can currently be used.

Value Meaning

CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

0x00000001 If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on.

The operating system remembers only successful

connections that redirect local devices. It does not
remember connections that are unsuccessful or
deviceless connections. (A deviceless connection occurs
when the lpLocalName member is NULL or points to an
empty string.)

If this bit flag is clear, the operating system does not try
to restore the connection when the user logs on.

CONNECT_UPDATE_RECENT The network resource connection should not be put in

0x00000002 the recent connection list.
If this flag is set and the connection is successfully added,
the network resource connection will be put in the recent
connection list only if it has a redirected local device
associated with it.
CONNECT_TEMPORARY The network resource connection should not be
0x00000004 remembered.
If this flag is set, the operating system will not attempt to
restore the connection when the user logs on again.

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
0x00000008 the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
0x00000010 settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.

CONNECT_REDIRECT This flag forces the redirection of a local device when

0x00000080 making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows Server 2003 and Windows XP:  When the

system automatically assigns network drive letters, letters
are assigned beginning with Z:, then Y:, and ending with
C:. This reduces collision between per-logon drive letters
(such as network drive letters) and global drive letters
(such as disk drives). Note that earlier versions of
Windows assigned drive letters beginning with C: and
ending with Z:.

CONNECT_CURRENT_MEDIA If this flag is set, then the operating system does not start
0x00000200 to use a new media to try to establish the connection
(initiate a new dial up connection, for example).

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
0x00000800 for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows XP:  This value is supported on Windows XP
and later.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
0x00001000 credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
 does not support saving credentials, this flag is ignored.
This flag is ignored unless CONNECT_INTERACTIVE is also
set. This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
Windows XP:  This value is supported on Windows XP
and later.

CONNECT_CRED_RESET If this flag is set, and the operating system prompts for a
0x00002000 credential, the credential is reset by the credential
manager. If the credential manager is disabled for the
caller's logon session, or if the network provider does not
support saving credentials, this flag is ignored. This flag is
also ignored unless you set the
CONNECT_COMMANDLINE flag.
Windows Vista:  This value is supported on
Windows Vista and later.

Return value
If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes or one of
the
system error codes.

Return code Description

ERROR_ACCESS_DENIED The caller does not have access to the network

resource.

ERROR_ALREADY_ASSIGNED The local device specified by the lpLocalName

member is already connected to a network resource.

ERROR_BAD_DEV_TYPE The type of local device and the type of network

resource do not match.

ERROR_BAD_DEVICE The specified device name is not valid. This error is

returned if the lpLocalName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a device that is not
redirectable.

ERROR_BAD_NET_NAME The network name cannot be found. This value is

returned if the lpRemoteName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a resource that is
not acceptable to any network resource provider,
either because the resource name is empty, not valid,
or because the named resource cannot be located.
ERROR_BAD_PROFILE The user profile is in an incorrect format.

ERROR_BAD_PROVIDER The specified network provider name is not valid. This

error is returned if the lpProvider member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a value that does
not match any network provider.

ERROR_BAD_USERNAME The specified user name is not valid.

ERROR_BUSY The router or provider is busy, possibly initializing.

The caller should retry.

ERROR_CANCELLED The attempt to make the connection was canceled by

the user through a dialog box from one of the
network resource providers, or by a called resource.

ERROR_CANNOT_OPEN_PROFILE The system is unable to open the user profile to

process persistent connections.

ERROR_DEVICE_ALREADY_REMEMBERED The local device name has a remembered connection

to another network resource. This error is returned if
an entry for the device specified by lpLocalName
member of the NETRESOURCE structure pointed to
by the lpNetResource parameter specifies a value that
is already in the user profile for a different
connection than that specified in the
lpNetResource
parameter.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of
the error.

ERROR_INVALID_ADDRESS An attempt was made to access an invalid address.

This error is returned if the dwFlags parameter
specifies a value of CONNECT_REDIRECT, but the
lpLocalName member of the NETRESOURCE
structure pointed to by the lpNetResource parameter
was unspecified.

ERROR_INVALID_PARAMETER A parameter is incorrect. This error is returned if the

dwType member of the NETRESOURCE structure
pointed to by the lpNetResource parameter specifies
a value other than RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY. This
error is also returned if the dwFlags parameter
specifies an incorrect or unknown value.

ERROR_INVALID_PASSWORD The specified password is invalid and the

CONNECT_INTERACTIVE flag is not set.

ERROR_LOGON_FAILURE A logon failure because of an unknown user name or

 a bad password.

ERROR_NO_NET_OR_BAD_PATH No network provider accepted the given network

path. This error is returned if no network provider
recognized the lpRemoteName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter.

ERROR_NO_NETWORK The network is unavailable.

Other Use FormatMessage to obtain the message string for

the returned error.

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
WNetAddConnection2 function, then the mapped drive is visible to all user logon
sessions.

For Microsoft network providers, the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter can contain an IPv4 address in
dotted-decimal notation. An example for a share might be the following:

\192.168.1.1\share

For Microsoft network providers on Windows Vista and later, the lpRemoteName

member of the NETRESOURCE structure pointed to by the lpNetResource parameter can
contain an IPv6 address. However, the IPv6 literal format must be used so that the IPv6
address is parsed correctly. An IPv6 literal address is of the form:
ipv6-address with the ':' characters replaced by '-' characters followed by the ".ipv6-
literal.net" string.

For example, for the following IPv6 address:

2001:4898:9:3:c069:aa97:fe76:2449

an example for a share might be the following:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Other network providers may support the lpRemoteName member of the

NETRESOURCE structure pointed to by the lpNetResource parameter that contains an
IPv4 or IPv6 address, but this is up to specific network provider.

Windows 7 and Windows Server 2008 R2:  If the WNetAddConnection2 function is

called with explicit user credentials specified in the pUsername and lpPassword to
establish a connection with a network resource on a specific server and then called
again with either of these parameters as NULL (to use the default user name or default
password) to the same server, the call with fail. The error returned will be
ERROR_BAD_USERNAME or ERROR_INVALID_PASSWORD.

Examples
The following code sample illustrates how to use the
WNetAddConnection2 function to
make connection to a network resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

// Need to link with Netapi32.lib and Mpr.lib

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

NETRESOURCE nr;

DWORD dwFlags;

 if (argc != 5) {

wprintf(L"Usage: %s <localname> <remotename> <username>

<password>\n",

argv[0]);

wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",

argv[0]);

exit(1);

wprintf(L"Calling WNetAddConnection2 with\n");

wprintf(L" lpLocalName = %s\n", argv[1]);

wprintf(L" lpRemoteName = %s\n", argv[2]);

wprintf(L" lpUsername = %s\n", argv[3]);

wprintf(L" lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct

memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];

nr.lpRemoteName = argv[2];

nr.lpProvider = NULL;

// Assign a value to the connection options

dwFlags = CONNECT_UPDATE_PROFILE;

//

// Call the WNetAddConnection2 function to assign

// a drive letter to the share.

//

dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);

//

// If the call succeeds, inform the user; otherwise,

// print the error.

//

if (dwRetVal == NO_ERROR)

wprintf(L"Connection added to %s\n", nr.lpRemoteName);

else

wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

exit(1);

For other code samples that illustrates how to make a connection to a network resource
using the
WNetAddConnection2 function, see
Adding a Network Connection and
Assigning a Drive to a Share.

７ Note
 The winnetwk.h header defines WNetAddConnection2 as an alias which
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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetAddConnection2W function
(winnetwk.h)
Article • 02/09/202312 minutes to read

The
WNetAddConnection2 function makes a connection to a network resource and can
redirect a local device to the network resource.

The
WNetAddConnection2 function supersedes the
WNetAddConnection function. If
you can pass a handle to a window that the provider of network resources can use as an
owner window for dialog boxes, call the
WNetAddConnection3 function instead.

Syntax
C++

DWORD WNetAddConnection2W(

[in] LPNETRESOURCEW lpNetResource,

[in] LPCWSTR lpPassword,

[in] LPCWSTR lpUserName,
[in] DWORD dwFlags

);

Parameters
[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies details of the proposed
connection, such as information about the network resource, the local device, and the
network resource provider.

You must specify the following members of the

NETRESOURCE structure.

Member Meaning

dwType The type of network resource to connect to.

If the lpLocalName member points to a nonempty string,
this member can be equal to RESOURCETYPE_DISK or
RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string,

dwType can be equal to RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
 Although this member is required, its information may be
ignored by the network service provider.

lpLocalName A pointer to a null-terminated string that specifies the

name of a local device to redirect, such as "F:" or "LPT1".
The string is treated in a case-insensitive manner.

If the string is empty, or if lpLocalName is NULL, the

function makes a connection to the network resource
without redirecting a local device.

lpRemoteName A 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, and must follow the
network provider's naming conventions.

lpProvider A pointer to a null-terminated string that specifies the

network provider to connect to.

If lpProvider is NULL, or if it points to an empty string,

the operating system attempts to determine the correct
provider by parsing the string pointed to by the
lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know the network
provider you want to use. Otherwise, let the operating
system determine which provider the network name
maps to.

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

[in] lpPassword

A pointer to a constant 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 the lpUserName parameter.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

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

[in] lpUserName

A pointer to a constant null-terminated string that specifies a user name for making the
connection.

If lpUserName is NULL, the function uses the default user name. (The user context for
the process provides the default user name.)

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.

The user-name string represents a

security context. It may be specific to a network
provider.

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

[in] dwFlags

A set of connection options. The possible values for the connection options are defined
in the Winnetwk.h header file.
The following values can currently be used.

Value Meaning

CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

0x00000001 If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on.

The operating system remembers only successful

connections that redirect local devices. It does not
remember connections that are unsuccessful or
deviceless connections. (A deviceless connection occurs
when the lpLocalName member is NULL or points to an
empty string.)

If this bit flag is clear, the operating system does not try
to restore the connection when the user logs on.

CONNECT_UPDATE_RECENT The network resource connection should not be put in

0x00000002 the recent connection list.
If this flag is set and the connection is successfully added,
the network resource connection will be put in the recent
connection list only if it has a redirected local device
associated with it.
CONNECT_TEMPORARY The network resource connection should not be
0x00000004 remembered.
If this flag is set, the operating system will not attempt to
restore the connection when the user logs on again.

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
0x00000008 the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
0x00000010 settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.

CONNECT_REDIRECT This flag forces the redirection of a local device when

0x00000080 making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows Server 2003 and Windows XP:  When the

system automatically assigns network drive letters, letters
are assigned beginning with Z:, then Y:, and ending with
C:. This reduces collision between per-logon drive letters
(such as network drive letters) and global drive letters
(such as disk drives). Note that earlier versions of
Windows assigned drive letters beginning with C: and
ending with Z:.

CONNECT_CURRENT_MEDIA If this flag is set, then the operating system does not start
0x00000200 to use a new media to try to establish the connection
(initiate a new dial up connection, for example).

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
0x00000800 for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows XP:  This value is supported on Windows XP
and later.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
0x00001000 credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
 does not support saving credentials, this flag is ignored.
This flag is ignored unless CONNECT_INTERACTIVE is also
set. This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
Windows XP:  This value is supported on Windows XP
and later.

CONNECT_CRED_RESET If this flag is set, and the operating system prompts for a
0x00002000 credential, the credential is reset by the credential
manager. If the credential manager is disabled for the
caller's logon session, or if the network provider does not
support saving credentials, this flag is ignored. This flag is
also ignored unless you set the
CONNECT_COMMANDLINE flag.
Windows Vista:  This value is supported on
Windows Vista and later.

Return value
If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes or one of
the
system error codes.

Return code Description

ERROR_ACCESS_DENIED The caller does not have access to the network

resource.

ERROR_ALREADY_ASSIGNED The local device specified by the lpLocalName

member is already connected to a network resource.

ERROR_BAD_DEV_TYPE The type of local device and the type of network

resource do not match.

ERROR_BAD_DEVICE The specified device name is not valid. This error is

returned if the lpLocalName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a device that is not
redirectable.

ERROR_BAD_NET_NAME The network name cannot be found. This value is

returned if the lpRemoteName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a resource that is
not acceptable to any network resource provider,
either because the resource name is empty, not valid,
or because the named resource cannot be located.
ERROR_BAD_PROFILE The user profile is in an incorrect format.

ERROR_BAD_PROVIDER The specified network provider name is not valid. This

error is returned if the lpProvider member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter specifies a value that does
not match any network provider.

ERROR_BAD_USERNAME The specified user name is not valid.

ERROR_BUSY The router or provider is busy, possibly initializing.

The caller should retry.

ERROR_CANCELLED The attempt to make the connection was canceled by

the user through a dialog box from one of the
network resource providers, or by a called resource.

ERROR_CANNOT_OPEN_PROFILE The system is unable to open the user profile to

process persistent connections.

ERROR_DEVICE_ALREADY_REMEMBERED The local device name has a remembered connection

to another network resource. This error is returned if
an entry for the device specified by lpLocalName
member of the NETRESOURCE structure pointed to
by the lpNetResource parameter specifies a value that
is already in the user profile for a different
connection than that specified in the
lpNetResource
parameter.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of
the error.

ERROR_INVALID_ADDRESS An attempt was made to access an invalid address.

This error is returned if the dwFlags parameter
specifies a value of CONNECT_REDIRECT, but the
lpLocalName member of the NETRESOURCE
structure pointed to by the lpNetResource parameter
was unspecified.

ERROR_INVALID_PARAMETER A parameter is incorrect. This error is returned if the

dwType member of the NETRESOURCE structure
pointed to by the lpNetResource parameter specifies
a value other than RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY. This
error is also returned if the dwFlags parameter
specifies an incorrect or unknown value.

ERROR_INVALID_PASSWORD The specified password is invalid and the

CONNECT_INTERACTIVE flag is not set.

ERROR_LOGON_FAILURE A logon failure because of an unknown user name or

 a bad password.

ERROR_NO_NET_OR_BAD_PATH No network provider accepted the given network

path. This error is returned if no network provider
recognized the lpRemoteName member of the
NETRESOURCE structure pointed to by the
lpNetResource parameter.

ERROR_NO_NETWORK The network is unavailable.

Other Use FormatMessage to obtain the message string for

the returned error.

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
WNetAddConnection2 function, then the mapped drive is visible to all user logon
sessions.

For Microsoft network providers, the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter can contain an IPv4 address in
dotted-decimal notation. An example for a share might be the following:

\192.168.1.1\share

For Microsoft network providers on Windows Vista and later, the lpRemoteName

member of the NETRESOURCE structure pointed to by the lpNetResource parameter can
contain an IPv6 address. However, the IPv6 literal format must be used so that the IPv6
address is parsed correctly. An IPv6 literal address is of the form:
ipv6-address with the ':' characters replaced by '-' characters followed by the ".ipv6-
literal.net" string.

For example, for the following IPv6 address:

2001:4898:9:3:c069:aa97:fe76:2449

an example for a share might be the following:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Other network providers may support the lpRemoteName member of the

NETRESOURCE structure pointed to by the lpNetResource parameter that contains an
IPv4 or IPv6 address, but this is up to specific network provider.

Windows 7 and Windows Server 2008 R2:  If the WNetAddConnection2 function is

called with explicit user credentials specified in the pUsername and lpPassword to
establish a connection with a network resource on a specific server and then called
again with either of these parameters as NULL (to use the default user name or default
password) to the same server, the call with fail. The error returned will be
ERROR_BAD_USERNAME or ERROR_INVALID_PASSWORD.

Examples
The following code sample illustrates how to use the
WNetAddConnection2 function to
make connection to a network resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

// Need to link with Netapi32.lib and Mpr.lib

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

NETRESOURCE nr;

DWORD dwFlags;

 if (argc != 5) {

wprintf(L"Usage: %s <localname> <remotename> <username>

<password>\n",

argv[0]);

wprintf(L" %s X: \\\\contoso\\public testuser testpasswd\n",

argv[0]);

exit(1);

wprintf(L"Calling WNetAddConnection2 with\n");

wprintf(L" lpLocalName = %s\n", argv[1]);

wprintf(L" lpRemoteName = %s\n", argv[2]);

wprintf(L" lpUsername = %s\n", argv[3]);

wprintf(L" lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct

memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = argv[1];

nr.lpRemoteName = argv[2];

nr.lpProvider = NULL;

// Assign a value to the connection options

dwFlags = CONNECT_UPDATE_PROFILE;

//

// Call the WNetAddConnection2 function to assign

// a drive letter to the share.

//

dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);

//

// If the call succeeds, inform the user; otherwise,

// print the error.

//

if (dwRetVal == NO_ERROR)

wprintf(L"Connection added to %s\n", nr.lpRemoteName);

else

wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

exit(1);

For other code samples that illustrates how to make a connection to a network resource
using the
WNetAddConnection2 function, see
Adding a Network Connection and
Assigning a Drive to a Share.

７ Note
 The winnetwk.h header defines WNetAddConnection2 as an alias which
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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetAddConnection3A function
(winnetwk.h)
Article • 02/09/20239 minutes to read

The
WNetAddConnection3 function makes a connection to a network resource. The
function can redirect a local device to the network resource.

The
WNetAddConnection3 function is similar to the
WNetAddConnection2 function.
The main difference is that
WNetAddConnection3 has an additional parameter, a
handle to a window that the provider of network resources can use as an owner window
for dialog boxes. The
WNetAddConnection2 function and the
WNetAddConnection3
function supersede the
WNetAddConnection function.

Syntax
C++

DWORD WNetAddConnection3A(

[in] HWND hwndOwner,

[in] LPNETRESOURCEA lpNetResource,

[in] LPCSTR lpPassword,

[in] LPCSTR lpUserName,
[in] DWORD dwFlags

);

Parameters
[in] hwndOwner

A handle to a window that the provider of network resources can use as an owner
window for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE
value in the dwFlags parameter.

The hwndOwner parameter can be NULL. If it is, a call to

WNetAddConnection3 is
equivalent to calling the
WNetAddConnection2 function.

[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies details of the proposed
connection, such as information about the network resource, the local device, and the
network resource provider.
You must specify the following members of the
NETRESOURCE structure.

Member Meaning

dwType The type of network resource to connect to.

If the lpLocalName member points to a nonempty string,
this member can be equal to RESOURCETYPE_DISK or
RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string,

dwType can be equal to RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.

Although this member is required, its information may be

ignored by the network service provider.

lpLocalName A pointer to a null-terminated string that specifies the

name of a local device to redirect, such as "F:" or "LPT1".
The string is treated in a case-insensitive manner.

If the string is empty or if lpLocalName is NULL, the

function makes a connection to the network resource
without redirecting a local device.

lpRemoteName A 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, and must follow the
network provider's naming conventions.

lpProvider A pointer to a null-terminated string that specifies the

network provider to connect to.

If lpProvider is NULL, or if it points to an empty string,

the operating system attempts to determine the correct
provider by parsing the string pointed to by the
lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know which

network provider you want to use. Otherwise, let the
operating system determine which network provider the
network name maps to.

The
WNetAddConnection3 function ignores the other members of the
NETRESOURCE
structure.
[in] lpPassword

A 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 the lpUserName parameter.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

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

[in] lpUserName

A pointer to a null-terminated string that specifies a user name for making the
connection.

If lpUserName is NULL, the function uses the default user name. (The user context for
the process provides the default user name.)

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.

The user-name string represents a

security context. It may be specific to a network
provider.

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

[in] dwFlags

A set of connection options. The following values are currently defined.

Value Meaning

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.

CONNECT_REDIRECT This flag forces the redirection of a local device when

 making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows Server 2003 and Windows XP:  When the

system automatically assigns network drive letters, letters
are assigned beginning with Z:, then Y:, and ending with
C:. This reduces collision between per-logon drive letters
(such as network drive letters) and global drive letters
(such as disk drives). Note that earlier versions of
Windows assigned drive letters beginning with C: and
ending with Z:.

CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on.

The operating system remembers only successful

connections that redirect local devices. It does not
remember connections that are unsuccessful or
deviceless connections. (A deviceless connection occurs
when the lpLocalName member is NULL or when it
points to an empty string.)

If this bit flag is clear, the operating system does not

automatically restore the connection at logon.

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
does not support saving credentials, this flag is ignored.
This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
 Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

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 local device specified by the lpLocalName

member is already connected to a network resource.

ERROR_BAD_DEV_TYPE The type of local device and the type of network

resource do not match.

ERROR_BAD_DEVICE The value specified by lpLocalName is invalid.

ERROR_BAD_NET_NAME The value specified by the lpRemoteName member

is not acceptable to any network resource provider,
either because the resource name is invalid, or
because the named resource cannot be located.

ERROR_BAD_PROFILE The user profile is in an incorrect format.

ERROR_BAD_PROVIDER The value specified by the lpProvider member does

not match any provider.

ERROR_BUSY The router or provider is busy, possibly initializing.

The caller should retry.

ERROR_CANCELLED The attempt to make the connection was canceled by

the user through a dialog box from one of the
network resource providers, or by a called resource.

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 by the lpLocalName

member is already in the user profile.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of
the error.
 ERROR_INVALID_PASSWORD The specified password is invalid and the
CONNECT_INTERACTIVE flag is not set.

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
The
WNetUseConnection function is similar to the
WNetAddConnection3 function. The
main difference is that
WNetUseConnection can automatically select an unused local
device to redirect to the network resource.

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
WNetAddConnection3 function, then the mapped drive is visible to all user logon
sessions.

For Microsoft network providers, the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter can contain an IPv4 address in
dotted-decimal notation. An example for a share might be the following:

\192.168.1.1\share

For Microsoft network providers on Windows Vista and later, the lpRemoteName

member of the NETRESOURCE structure pointed to by the lpNetResource parameter can
contain an IPv6 address. However, the IPv6 literal format must be used so that the IPv6
address is parsed correctly. An IPv6 literal address is of the form:
ipv6-address with the ':' characters replaced by '-' characters followed by the ".ipv6-
literal.net" string.

For example, for the following IPv6 address:

2001:4898:9:3:c069:aa97:fe76:2449

an example for a share might be the following:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Other network providers may support the lpRemoteName member of the

NETRESOURCE structure pointed to by the lpNetResource parameter that contains an
IPv4 or IPv6 address, but this is up to specific network provider.

Windows 7 and Windows Server 2008 R2:  If the WNetAddConnection3 function is

called with explicit user credentials specified in the pUsername and lpPassword to
establish a connection with a network resource on a specific server and then called
again with either of these parameters as NULL (to use the default user name or default
password) to the same server, the call with fail. The error returned will be
ERROR_BAD_USERNAME or ERROR_INVALID_PASSWORD.

７ Note

The winnetwk.h header defines WNetAddConnection3 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetAddConnection3W function
(winnetwk.h)
Article • 02/09/20239 minutes to read

The
WNetAddConnection3 function makes a connection to a network resource. The
function can redirect a local device to the network resource.

The
WNetAddConnection3 function is similar to the
WNetAddConnection2 function.
The main difference is that
WNetAddConnection3 has an additional parameter, a
handle to a window that the provider of network resources can use as an owner window
for dialog boxes. The
WNetAddConnection2 function and the
WNetAddConnection3
function supersede the
WNetAddConnection function.

Syntax
C++

DWORD WNetAddConnection3W(

[in] HWND hwndOwner,

[in] LPNETRESOURCEW lpNetResource,

[in] LPCWSTR lpPassword,

[in] LPCWSTR lpUserName,
[in] DWORD dwFlags

);

Parameters
[in] hwndOwner

A handle to a window that the provider of network resources can use as an owner
window for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE
value in the dwFlags parameter.

The hwndOwner parameter can be NULL. If it is, a call to

WNetAddConnection3 is
equivalent to calling the
WNetAddConnection2 function.

[in] lpNetResource

A pointer to a
NETRESOURCE structure that specifies details of the proposed
connection, such as information about the network resource, the local device, and the
network resource provider.
You must specify the following members of the
NETRESOURCE structure.

Member Meaning

dwType The type of network resource to connect to.

If the lpLocalName member points to a nonempty string,
this member can be equal to RESOURCETYPE_DISK or
RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string,

dwType can be equal to RESOURCETYPE_DISK,
RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.

Although this member is required, its information may be

ignored by the network service provider.

lpLocalName A pointer to a null-terminated string that specifies the

name of a local device to redirect, such as "F:" or "LPT1".
The string is treated in a case-insensitive manner.

If the string is empty or if lpLocalName is NULL, the

function makes a connection to the network resource
without redirecting a local device.

lpRemoteName A 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, and must follow the
network provider's naming conventions.

lpProvider A pointer to a null-terminated string that specifies the

network provider to connect to.

If lpProvider is NULL, or if it points to an empty string,

the operating system attempts to determine the correct
provider by parsing the string pointed to by the
lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know which

network provider you want to use. Otherwise, let the
operating system determine which network provider the
network name maps to.

The
WNetAddConnection3 function ignores the other members of the
NETRESOURCE
structure.
[in] lpPassword

A 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 the lpUserName parameter.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

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

[in] lpUserName

A pointer to a null-terminated string that specifies a user name for making the
connection.

If lpUserName is NULL, the function uses the default user name. (The user context for
the process provides the default user name.)

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.

The user-name string represents a

security context. It may be specific to a network
provider.

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

[in] dwFlags

A set of connection options. The following values are currently defined.

Value Meaning

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.

CONNECT_REDIRECT This flag forces the redirection of a local device when

 making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows Server 2003 and Windows XP:  When the

system automatically assigns network drive letters, letters
are assigned beginning with Z:, then Y:, and ending with
C:. This reduces collision between per-logon drive letters
(such as network drive letters) and global drive letters
(such as disk drives). Note that earlier versions of
Windows assigned drive letters beginning with C: and
ending with Z:.

CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on.

The operating system remembers only successful

connections that redirect local devices. It does not
remember connections that are unsuccessful or
deviceless connections. (A deviceless connection occurs
when the lpLocalName member is NULL or when it
points to an empty string.)

If this bit flag is clear, the operating system does not

automatically restore the connection at logon.

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
does not support saving credentials, this flag is ignored.
This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
 Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

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 local device specified by the lpLocalName

member is already connected to a network resource.

ERROR_BAD_DEV_TYPE The type of local device and the type of network

resource do not match.

ERROR_BAD_DEVICE The value specified by lpLocalName is invalid.

ERROR_BAD_NET_NAME The value specified by the lpRemoteName member

is not acceptable to any network resource provider,
either because the resource name is invalid, or
because the named resource cannot be located.

ERROR_BAD_PROFILE The user profile is in an incorrect format.

ERROR_BAD_PROVIDER The value specified by the lpProvider member does

not match any provider.

ERROR_BUSY The router or provider is busy, possibly initializing.

The caller should retry.

ERROR_CANCELLED The attempt to make the connection was canceled by

the user through a dialog box from one of the
network resource providers, or by a called resource.

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 by the lpLocalName

member is already in the user profile.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of
the error.
 ERROR_INVALID_PASSWORD The specified password is invalid and the
CONNECT_INTERACTIVE flag is not set.

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
The
WNetUseConnection function is similar to the
WNetAddConnection3 function. The
main difference is that
WNetUseConnection can automatically select an unused local
device to redirect to the network resource.

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
WNetAddConnection3 function, then the mapped drive is visible to all user logon
sessions.

For Microsoft network providers, the lpRemoteName member of the NETRESOURCE

structure pointed to by the lpNetResource parameter can contain an IPv4 address in
dotted-decimal notation. An example for a share might be the following:

\192.168.1.1\share

For Microsoft network providers on Windows Vista and later, the lpRemoteName

member of the NETRESOURCE structure pointed to by the lpNetResource parameter can
contain an IPv6 address. However, the IPv6 literal format must be used so that the IPv6
address is parsed correctly. An IPv6 literal address is of the form:
ipv6-address with the ':' characters replaced by '-' characters followed by the ".ipv6-
literal.net" string.

For example, for the following IPv6 address:

2001:4898:9:3:c069:aa97:fe76:2449

an example for a share might be the following:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Other network providers may support the lpRemoteName member of the

NETRESOURCE structure pointed to by the lpNetResource parameter that contains an
IPv4 or IPv6 address, but this is up to specific network provider.

Windows 7 and Windows Server 2008 R2:  If the WNetAddConnection3 function is

called with explicit user credentials specified in the pUsername and lpPassword to
establish a connection with a network resource on a specific server and then called
again with either of these parameters as NULL (to use the default user name or default
password) to the same server, the call with fail. The error returned will be
ERROR_BAD_USERNAME or ERROR_INVALID_PASSWORD.

７ Note

The winnetwk.h header defines WNetAddConnection3 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetAddConnectionA function
(winnetwk.h)
Article • 02/09/20233 minutes to read

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
C++

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

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.

７ Note

The winnetwk.h header defines WNetAddConnection as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetAddConnectionW function
(winnetwk.h)
Article • 02/09/20233 minutes to read

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
C++

DWORD WNetAddConnectionW(

[in] LPCWSTR lpRemoteName,

[in] LPCWSTR lpPassword,

[in] LPCWSTR 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

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.

７ Note

The winnetwk.h header defines WNetAddConnection as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetCancelConnection2A function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetCancelConnection2 function cancels an existing network connection. You can
also call the function to remove remembered network connections that are not currently
connected.

The
WNetCancelConnection2 function supersedes the
WNetCancelConnection function.

Syntax
C++

DWORD WNetCancelConnection2A(

[in] LPCSTR lpName,

[in] DWORD dwFlags,

[in] BOOL fForce

);

Parameters
[in] lpName

Pointer to a constant null-terminated string that specifies the name of either the
redirected local device or the remote network resource to disconnect from.

If this parameter specifies a redirected local device, the function cancels only the
specified device redirection. If the parameter specifies a remote network resource, all
connections without devices are canceled.

[in] dwFlags

Connection type. The following values are defined.

Value Meaning

0 The system does not update information about the

connection.
If the connection was marked as persistent in the registry,
the system continues to restore the connection at the
next logon. If the connection was not marked as
 persistent, the function ignores the setting of the
CONNECT_UPDATE_PROFILE flag.

CONNECT_UPDATE_PROFILE The system updates the user profile with the information
that the connection is no longer a persistent one.
The system will not restore this connection during
subsequent logon operations. (Disconnecting resources
using remote names has no effect on persistent
connections.)

[in] fForce

Specifies whether the disconnection should occur if there are open files or jobs on the
connection. If this parameter is FALSE, the function fails if there are open files or jobs.

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_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_IN_USE The device is in use by an active process and cannot be

disconnected.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NOT_CONNECTED The name specified by the lpName parameter is not a

redirected device, or the system is not currently
connected to the device specified by the parameter.

ERROR_OPEN_FILES There are open files, and the fForce parameter is FALSE.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

Examples
For a code sample that illustrates how to cancel a connection to a network resource with
a call to the
WNetCancelConnection2 function, see
Canceling a Network Connection.

７ Note

The winnetwk.h header defines WNetCancelConnection2 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetCancelConnection2W function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetCancelConnection2 function cancels an existing network connection. You can
also call the function to remove remembered network connections that are not currently
connected.

The
WNetCancelConnection2 function supersedes the
WNetCancelConnection function.

Syntax
C++

DWORD WNetCancelConnection2W(

[in] LPCWSTR lpName,

[in] DWORD dwFlags,

[in] BOOL fForce

);

Parameters
[in] lpName

Pointer to a constant null-terminated string that specifies the name of either the
redirected local device or the remote network resource to disconnect from.

If this parameter specifies a redirected local device, the function cancels only the
specified device redirection. If the parameter specifies a remote network resource, all
connections without devices are canceled.

[in] dwFlags

Connection type. The following values are defined.

Value Meaning

0 The system does not update information about the

connection.
If the connection was marked as persistent in the registry,
the system continues to restore the connection at the
next logon. If the connection was not marked as
 persistent, the function ignores the setting of the
CONNECT_UPDATE_PROFILE flag.

CONNECT_UPDATE_PROFILE The system updates the user profile with the information
that the connection is no longer a persistent one.
The system will not restore this connection during
subsequent logon operations. (Disconnecting resources
using remote names has no effect on persistent
connections.)

[in] fForce

Specifies whether the disconnection should occur if there are open files or jobs on the
connection. If this parameter is FALSE, the function fails if there are open files or jobs.

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_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_IN_USE The device is in use by an active process and cannot be

disconnected.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NOT_CONNECTED The name specified by the lpName parameter is not a

redirected device, or the system is not currently
connected to the device specified by the parameter.

ERROR_OPEN_FILES There are open files, and the fForce parameter is FALSE.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

Examples
For a code sample that illustrates how to cancel a connection to a network resource with
a call to the
WNetCancelConnection2 function, see
Canceling a Network Connection.

７ Note

The winnetwk.h header defines WNetCancelConnection2 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetCancelConnectionA function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetCancelConnection function cancels an existing network connection.

The
WNetCancelConnection function is provided for compatibility with 16-bit versions
of Windows. Other Windows-based applications should call the
WNetCancelConnection2 function.

Syntax
C++

DWORD WNetCancelConnectionA(

[in] LPCSTR lpName,

[in] BOOL fForce

);

Parameters
[in] lpName

Pointer to a constant null-terminated string that specifies the name of either the
redirected local device or the remote network resource to disconnect from.

When this parameter specifies a redirected local device, the function cancels only the
specified device redirection. If the parameter specifies a remote network resource, only
the connections to remote networks without devices are canceled.

[in] fForce

Specifies whether or not the disconnection should occur if there are open files or jobs
on the connection. If this parameter is FALSE, the function fails if there are open files or
jobs.

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_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_IN_USE The device is in use by an active process and cannot be

disconnected.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NOT_CONNECTED The name specified by the lpName parameter is not a

redirected device, or the system is not currently
connected to the device specified by the parameter.

ERROR_OPEN_FILES There are open files, and the fForce parameter is FALSE.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

７ Note

The winnetwk.h header defines WNetCancelConnection as an alias which

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 not encoding-neutral can lead to mismatches that
 result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetAddConnection

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetCancelConnectionW function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetCancelConnection function cancels an existing network connection.

The
WNetCancelConnection function is provided for compatibility with 16-bit versions
of Windows. Other Windows-based applications should call the
WNetCancelConnection2 function.

Syntax
C++

DWORD WNetCancelConnectionW(

[in] LPCWSTR lpName,

[in] BOOL fForce

);

Parameters
[in] lpName

Pointer to a constant null-terminated string that specifies the name of either the
redirected local device or the remote network resource to disconnect from.

When this parameter specifies a redirected local device, the function cancels only the
specified device redirection. If the parameter specifies a remote network resource, only
the connections to remote networks without devices are canceled.

[in] fForce

Specifies whether or not the disconnection should occur if there are open files or jobs
on the connection. If this parameter is FALSE, the function fails if there are open files or
jobs.

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_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_IN_USE The device is in use by an active process and cannot be

disconnected.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NOT_CONNECTED The name specified by the lpName parameter is not a

redirected device, or the system is not currently
connected to the device specified by the parameter.

ERROR_OPEN_FILES There are open files, and the fForce parameter is FALSE.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

７ Note

The winnetwk.h header defines WNetCancelConnection as an alias which

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 not encoding-neutral can lead to mismatches that
 result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetAddConnection

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetCloseEnum function (winnetwk.h)
Article • 10/13/20212 minutes to read

The
WNetCloseEnum function ends a network resource enumeration started by a call to
the
WNetOpenEnum function.

Syntax
C++

DWORD WNetCloseEnum(

[in] HANDLE hEnum

);

Parameters
[in] hEnum

Handle that identifies an enumeration instance. This handle must be returned by the
WNetOpenEnum function.

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_NO_NETWORK The network is unavailable. (This condition is tested

before the handle specified in the hEnum parameter is
tested for validity.)

ERROR_INVALID_HANDLE The hEnum parameter does not specify a valid handle.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

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
WNetEnumResource

WNetOpenEnum

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetConnectionDialog function
(winnetwk.h)
Article • 10/13/20212 minutes to read

The
WNetConnectionDialog function starts a general browsing dialog box for
connecting to network resources. The function requires a handle to the owner window
for the dialog box.

Syntax
C++

DWORD WNetConnectionDialog(

[in] HWND hwnd,

[in] DWORD dwType

);

Parameters
[in] hwnd

Handle to the owner window for the dialog box.

[in] dwType

Resource type to allow connections to. This parameter can be the following value.

Value Meaning

RESOURCETYPE_DISK Connections to disk resources.

Return value
If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog
box, the function returns –1.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

 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_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to start the dialog box.

Remarks
If the user clicks OK in the dialog box, the requested network connection will have been
made when the
WNetConnectionDialog function returns.

If the function attempts to make a connection and the network provider returns the
message ERROR_INVALID_PASSWORD, the system prompts the user to enter a
password. The system uses the new password in another attempt to make the
connection.

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
WNetAddConnection3

WNetCancelConnection2

WNetDisconnectDialog

Windows
Networking (WNet) Overview
Windows
Networking Functions
WNetConnectionDialog1A function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetConnectionDialog1 function brings up a general browsing dialog for
connecting to network resources. The function requires a
CONNECTDLGSTRUCT to
establish the dialog box parameters.

Syntax
C++

DWORD WNetConnectionDialog1A(

[in, out] LPCONNECTDLGSTRUCTA lpConnDlgStruct

);

Parameters
[in, out] lpConnDlgStruct

Pointer to a
CONNECTDLGSTRUCT structure. The structure establishes the browsing
dialog parameters.

Return value
If the user cancels the dialog box, the function returns –1. If the function is successful, it
returns NO_ERROR. Also, if the call is successful, the dwDevNum member of the
CONNECTDLGSTRUCT structure contains the number of the connected device.

Typically this dialog returns an error only if the user cannot enter a dialog session. This is
because errors that occur after a dialog session are reported to the user directly. If the
function fails, the return value is a
system error code, such as one of the following
values.

Return code Description

ERROR_INVALID_PARAMETER Both the CONNDLG_RO_PATH and the

CONNDLG_USE_MRU dialog box options are set. (Dialog
box options are specified by the dwFlags member of the
CONNECTDLGSTRUCT structure.)
 -or-

Both the CONNDLG_PERSIST and the

CONNDLG_NOT_PERSIST dialog box options are set.

-or-

The CONNDLG_RO_PATH dialog box option is set and the

lpRemoteName member of the
NETRESOURCE structure
does not point to a remote network. (The
CONNECTDLGSTRUCT structure points to a
NETRESOURCE structure.)

ERROR_BAD_DEV_TYPE The dwType member of the NETRESOURCE structure is

not set to RESOURCETYPE_DISK.

ERROR_BUSY The network provider is busy (possibly initializing). The

caller should retry.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to display the dialog box.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call WNetGetLastError

to obtain a description of the error.

Remarks

７ Note

The winnetwk.h header defines WNetConnectionDialog1 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
CONNECTDLGSTRUCT

NETRESOURCE

WNetConnectionDialog

WNetDisconnectDialog

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetConnectionDialog1W function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetConnectionDialog1 function brings up a general browsing dialog for
connecting to network resources. The function requires a
CONNECTDLGSTRUCT to
establish the dialog box parameters.

Syntax
C++

DWORD WNetConnectionDialog1W(

[in, out] LPCONNECTDLGSTRUCTW lpConnDlgStruct

);

Parameters
[in, out] lpConnDlgStruct

Pointer to a
CONNECTDLGSTRUCT structure. The structure establishes the browsing
dialog parameters.

Return value
If the user cancels the dialog box, the function returns –1. If the function is successful, it
returns NO_ERROR. Also, if the call is successful, the dwDevNum member of the
CONNECTDLGSTRUCT structure contains the number of the connected device.

Typically this dialog returns an error only if the user cannot enter a dialog session. This is
because errors that occur after a dialog session are reported to the user directly. If the
function fails, the return value is a
system error code, such as one of the following
values.

Return code Description

ERROR_INVALID_PARAMETER Both the CONNDLG_RO_PATH and the

CONNDLG_USE_MRU dialog box options are set. (Dialog
box options are specified by the dwFlags member of the
CONNECTDLGSTRUCT structure.)
 -or-

Both the CONNDLG_PERSIST and the

CONNDLG_NOT_PERSIST dialog box options are set.

-or-

The CONNDLG_RO_PATH dialog box option is set and the

lpRemoteName member of the
NETRESOURCE structure
does not point to a remote network. (The
CONNECTDLGSTRUCT structure points to a
NETRESOURCE structure.)

ERROR_BAD_DEV_TYPE The dwType member of the NETRESOURCE structure is

not set to RESOURCETYPE_DISK.

ERROR_BUSY The network provider is busy (possibly initializing). The

caller should retry.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to display the dialog box.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call WNetGetLastError

to obtain a description of the error.

Remarks

７ Note

The winnetwk.h header defines WNetConnectionDialog1 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
CONNECTDLGSTRUCT

NETRESOURCE

WNetConnectionDialog

WNetDisconnectDialog

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetDisconnectDialog function
(winnetwk.h)
Article • 10/13/20212 minutes to read

The
WNetDisconnectDialog function starts a general browsing dialog box for
disconnecting from network resources. The function requires a handle to the owner
window for the dialog box.

Syntax
C++

DWORD WNetDisconnectDialog(

[in] HWND hwnd,

[in] DWORD dwType

);

Parameters
[in] hwnd

Handle to the owner window for the dialog box.

[in] dwType

Resource type to disconnect from. This parameter can have the following value.

Value Meaning

RESOURCETYPE_DISK Disconnects from disk resources.

Return value
If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog
box, the return value is –1.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

 ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description
of the error, call the WNetGetLastError function.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to start the dialog box.

Remarks
The
WNetDisconnectDialog function returns immediately and creates a dialog box for
disconnecting networked drives. This dialog box runs asynchronously on a worker
thread.

If the worker thread is terminated, the owner window and its associated dialog box are
also terminated. If this occurs, the user might not be able to interact with the dialog box,
because it will not appear on the user's screen or will appear briefly.

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

WNetCancelConnection2

WNetConnectionDialog

WNetConnectionDialog1

Windows
Networking (WNet) Overview
Windows
Networking Functions
WNetDisconnectDialog1A function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetDisconnectDialog1 function attempts to disconnect a network resource. If the
underlying network returns ERROR_OPEN_FILES, the function prompts the user for
confirmation. If there is any error, the function informs the user. The function requires a
DISCDLGSTRUCT to specify the parameters for the disconnect attempt.

Syntax
C++

DWORD WNetDisconnectDialog1A(

[in] LPDISCDLGSTRUCTA lpConnDlgStruct

);

Parameters
[in] lpConnDlgStruct

Pointer to a
DISCDLGSTRUCT structure. The structure specifies the behavior for the
disconnect attempt.

Return value
If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog
box, the return value is –1.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

ERROR_CANCELLED When the system prompted the user for a decision about
disconnecting, the user elected not to disconnect.

ERROR_OPEN_FILES Unable to disconnect because the user is actively using

the connection.

ERROR_BUSY The network provider is busy (possibly initializing). The

 caller should retry.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to start the dialog box.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of the
error.

Remarks

７ Note

The winnetwk.h header defines WNetDisconnectDialog1 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
DISCDLGSTRUCT

WNetConnectionDialog

WNetConnectionDialog1
WNetDisconnectDialog

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetDisconnectDialog1W function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetDisconnectDialog1 function attempts to disconnect a network resource. If the
underlying network returns ERROR_OPEN_FILES, the function prompts the user for
confirmation. If there is any error, the function informs the user. The function requires a
DISCDLGSTRUCT to specify the parameters for the disconnect attempt.

Syntax
C++

DWORD WNetDisconnectDialog1W(

[in] LPDISCDLGSTRUCTW lpConnDlgStruct

);

Parameters
[in] lpConnDlgStruct

Pointer to a
DISCDLGSTRUCT structure. The structure specifies the behavior for the
disconnect attempt.

Return value
If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog
box, the return value is –1.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

ERROR_CANCELLED When the system prompted the user for a decision about
disconnecting, the user elected not to disconnect.

ERROR_OPEN_FILES Unable to disconnect because the user is actively using

the connection.

ERROR_BUSY The network provider is busy (possibly initializing). The

 caller should retry.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_ENOUGH_MEMORY There is insufficient memory to start the dialog box.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of the
error.

Remarks

７ Note

The winnetwk.h header defines WNetDisconnectDialog1 as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
DISCDLGSTRUCT

WNetConnectionDialog

WNetConnectionDialog1
WNetDisconnectDialog

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetEnumResourceA function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetEnumResource function continues an enumeration of network resources that
was started by a call to the
WNetOpenEnum function.

Syntax
C++

DWORD WNetEnumResourceA(

[in] HANDLE hEnum,

[in, out] LPDWORD lpcCount,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] hEnum

Handle that identifies an enumeration instance. This handle must be returned by the
WNetOpenEnum function.

[in, out] lpcCount

Pointer to a variable specifying the number of entries requested. If the number

requested is –1, the function returns as many entries as possible.

If the function succeeds, on return the variable pointed to by this parameter contains
the number of entries actually read.

[out] lpBuffer

Pointer to the buffer that receives the enumeration results. The results are returned as
an array of
NETRESOURCE structures. Note that the buffer you allocate must be large
enough to hold the structures, plus the strings to which their members point. For more
information, see the following Remarks section.

The buffer is valid until the next call using the handle specified by the hEnum parameter.
The order of
NETRESOURCE structures in the array is not predictable.
[in, out] lpBufferSize

Pointer to a variable that specifies the size of the lpBuffer parameter, in bytes. If the
buffer is too small to receive even one entry, this parameter receives the required size of
the buffer.

Return value
If the function succeeds, the return value is one of the following values.

Return code Description

NO_ERROR The enumeration succeeded, and the buffer contains the

requested data. The calling application can continue to
call WNetEnumResource to complete the enumeration.

ERROR_NO_MORE_ITEMS There are no more entries. The buffer contents are

undefined.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

ERROR_MORE_DATA More entries are available with subsequent calls. For

more information, see the following Remarks section.

ERROR_INVALID_HANDLE The handle specified by the hEnum parameter is not valid.

ERROR_NO_NETWORK The network is unavailable. (This condition is tested

before hEnum is tested for validity.)

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

Remarks
The
WNetEnumResource function does not enumerate users connected to a share; you
can call the
NetConnectionEnum function to accomplish this task. To enumerate hidden
shares, call the
NetShareEnum function.

An application cannot set the lpBuffer parameter to NULL and retrieve the required
buffer size from the lpBufferSize parameter. Instead, the application should allocate a
buffer of a reasonable size—16 kilobytes is typical—and use the value of lpBufferSize for
error detection.

Examples

For a code sample that illustrates an application-defined function that enumerates all
the resources on a network, see
Enumerating Network Resources.

７ Note

The winnetwk.h header defines WNetEnumResource as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
NETRESOURCE

WNetCloseEnum

WNetOpenEnum

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetEnumResourceW function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetEnumResource function continues an enumeration of network resources that
was started by a call to the
WNetOpenEnum function.

Syntax
C++

DWORD WNetEnumResourceW(

[in] HANDLE hEnum,

[in, out] LPDWORD lpcCount,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] hEnum

Handle that identifies an enumeration instance. This handle must be returned by the
WNetOpenEnum function.

[in, out] lpcCount

Pointer to a variable specifying the number of entries requested. If the number

requested is –1, the function returns as many entries as possible.

If the function succeeds, on return the variable pointed to by this parameter contains
the number of entries actually read.

[out] lpBuffer

Pointer to the buffer that receives the enumeration results. The results are returned as
an array of
NETRESOURCE structures. Note that the buffer you allocate must be large
enough to hold the structures, plus the strings to which their members point. For more
information, see the following Remarks section.

The buffer is valid until the next call using the handle specified by the hEnum parameter.
The order of
NETRESOURCE structures in the array is not predictable.
[in, out] lpBufferSize

Pointer to a variable that specifies the size of the lpBuffer parameter, in bytes. If the
buffer is too small to receive even one entry, this parameter receives the required size of
the buffer.

Return value
If the function succeeds, the return value is one of the following values.

Return code Description

NO_ERROR The enumeration succeeded, and the buffer contains the

requested data. The calling application can continue to
call WNetEnumResource to complete the enumeration.

ERROR_NO_MORE_ITEMS There are no more entries. The buffer contents are

undefined.

If the function fails, the return value is a

system error code, such as one of the following
values.

Return code Description

ERROR_MORE_DATA More entries are available with subsequent calls. For

more information, see the following Remarks section.

ERROR_INVALID_HANDLE The handle specified by the hEnum parameter is not valid.

ERROR_NO_NETWORK The network is unavailable. (This condition is tested

before hEnum is tested for validity.)

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

Remarks
The
WNetEnumResource function does not enumerate users connected to a share; you
can call the
NetConnectionEnum function to accomplish this task. To enumerate hidden
shares, call the
NetShareEnum function.

An application cannot set the lpBuffer parameter to NULL and retrieve the required
buffer size from the lpBufferSize parameter. Instead, the application should allocate a
buffer of a reasonable size—16 kilobytes is typical—and use the value of lpBufferSize for
error detection.

Examples

For a code sample that illustrates an application-defined function that enumerates all
the resources on a network, see
Enumerating Network Resources.

７ Note

The winnetwk.h header defines WNetEnumResource as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
NETRESOURCE

WNetCloseEnum

WNetOpenEnum

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetConnectionA function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetGetConnection function retrieves the name of the network resource
associated with a local device.

Syntax
C++

DWORD WNetGetConnectionA(

[in] LPCSTR lpLocalName,

[out] LPSTR lpRemoteName,

[in, out] LPDWORD lpnLength

);

Parameters
[in] lpLocalName

Pointer to a constant null-terminated string that specifies the name of the local device
to get the network name for.

[out] lpRemoteName

Pointer to a null-terminated string that receives the remote name used to make the
connection.

[in, out] lpnLength

Pointer to a variable that specifies the size of the buffer pointed to by the
lpRemoteName parameter, in characters. If the function fails because the buffer is not
large enough, this parameter returns the required buffer size.

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_BAD_DEVICE The string pointed to by the lpLocalName parameter is

invalid.

ERROR_NOT_CONNECTED The device specified by lpLocalName is not a redirected

device. For more information, see the following Remarks
section.

ERROR_MORE_DATA The buffer is too small. The lpnLength parameter points

to a variable that contains the required buffer size. More
entries are available with subsequent calls.

ERROR_CONNECTION_UNAVAIL The device is not currently connected, but it is a

persistent connection. For more information, see the
following Remarks section.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NO_NET_OR_BAD_PATH None of the providers recognize the local name as having

a connection. However, the network is not available for at
least one provider to whom the connection may belong.

Remarks
If the network connection was made using the Microsoft LAN Manager network, and the
calling application is running in a different logon session than the application that made
the connection, a call to the
WNetGetConnection function for the associated local
device will fail. The function fails with ERROR_NOT_CONNECTED or
ERROR_CONNECTION_UNAVAIL. This is because a connection made using Microsoft
LAN Manager is visible only to applications running in the same logon session as the
application that made the connection. (To prevent the call to
WNetGetConnection from
failing it is not sufficient for the application to be running in the user account that
created the connection.)

Windows Server 2003 and Windows XP:  This function queries the MS-DOS device

namespaces associated with a logon session because MS-DOS devices are identified by
AuthenticationID. (An AuthenticationID is the
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. GetLogicalDrives does not return network drive letters
created by a WNet function 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.

Examples
For a code sample that illustrates how to use the
WNetGetConnection function to
retrieve the name of the network resource associated with a local device, see
Retrieving
the Connection Name.

７ Note

The winnetwk.h header defines WNetGetConnection as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
WNetGetUser

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetConnectionW function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetGetConnection function retrieves the name of the network resource
associated with a local device.

Syntax
C++

DWORD WNetGetConnectionW(

[in] LPCWSTR lpLocalName,

[out] LPWSTR lpRemoteName,

[in, out] LPDWORD lpnLength

);

Parameters
[in] lpLocalName

Pointer to a constant null-terminated string that specifies the name of the local device
to get the network name for.

[out] lpRemoteName

Pointer to a null-terminated string that receives the remote name used to make the
connection.

[in, out] lpnLength

Pointer to a variable that specifies the size of the buffer pointed to by the
lpRemoteName parameter, in characters. If the function fails because the buffer is not
large enough, this parameter returns the required buffer size.

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_BAD_DEVICE The string pointed to by the lpLocalName parameter is

invalid.

ERROR_NOT_CONNECTED The device specified by lpLocalName is not a redirected

device. For more information, see the following Remarks
section.

ERROR_MORE_DATA The buffer is too small. The lpnLength parameter points

to a variable that contains the required buffer size. More
entries are available with subsequent calls.

ERROR_CONNECTION_UNAVAIL The device is not currently connected, but it is a

persistent connection. For more information, see the
following Remarks section.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NO_NET_OR_BAD_PATH None of the providers recognize the local name as having

a connection. However, the network is not available for at
least one provider to whom the connection may belong.

Remarks
If the network connection was made using the Microsoft LAN Manager network, and the
calling application is running in a different logon session than the application that made
the connection, a call to the
WNetGetConnection function for the associated local
device will fail. The function fails with ERROR_NOT_CONNECTED or
ERROR_CONNECTION_UNAVAIL. This is because a connection made using Microsoft
LAN Manager is visible only to applications running in the same logon session as the
application that made the connection. (To prevent the call to
WNetGetConnection from
failing it is not sufficient for the application to be running in the user account that
created the connection.)

Windows Server 2003 and Windows XP:  This function queries the MS-DOS device

namespaces associated with a logon session because MS-DOS devices are identified by
AuthenticationID. (An AuthenticationID is the
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. GetLogicalDrives does not return network drive letters
created by a WNet function 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.

Examples
For a code sample that illustrates how to use the
WNetGetConnection function to
retrieve the name of the network resource associated with a local device, see
Retrieving
the Connection Name.

７ Note

The winnetwk.h header defines WNetGetConnection as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
WNetGetUser

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetLastErrorA function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetLastError function retrieves the most recent extended error code set by a
WNet function. The network provider reported this error code; it will not generally be
one of the errors included in the SDK header file WinError.h.

Syntax
C++

DWORD WNetGetLastErrorA(

[out] LPDWORD lpError,

[out] LPSTR lpErrorBuf,

[in] DWORD nErrorBufSize,

[out] LPSTR lpNameBuf,

[in] DWORD nNameBufSize

);

Parameters
[out] lpError

Pointer to a variable that receives the error code reported by the network provider. The
error code is specific to the network provider.

[out] lpErrorBuf

Pointer to the buffer that receives the null-terminated string describing the error.

[in] nErrorBufSize

Size of the buffer pointed to by the lpErrorBuf parameter, in characters. If the buffer is
too small for the error string, the string is truncated but still null-terminated. A buffer of
at least 256 characters is recommended.

[out] lpNameBuf

Pointer to the buffer that receives the null-terminated string identifying the network
provider that raised the error.
[in] nNameBufSize

Size of the buffer pointed to by the lpNameBuf parameter, in characters. If the buffer is
too small for the error string, the string is truncated but still null-terminated.

Return value
If the function succeeds, and it obtains the last error that the network provider reported,
the return value is NO_ERROR.

If the caller supplies an invalid buffer, the return value is ERROR_INVALID_ADDRESS.

Remarks
The
WNetGetLastError function retrieves errors that are specific to a network provider.
You can call
WNetGetLastError when a WNet function returns
ERROR_EXTENDED_ERROR.

Like the
GetLastError function,
WNetGetLastError returns extended error information,
which is maintained on a per-thread basis. Unlike GetLastError, the
WNetGetLastError
function can return a string for reporting errors that are not described by any existing
error code in WinError.h.

For more information about using an application-defined error handler that calls the
WNetGetLastError function, see
Retrieving Network Errors.

７ Note

The winnetwk.h header defines WNetGetLastError as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetLastErrorW function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetLastError function retrieves the most recent extended error code set by a
WNet function. The network provider reported this error code; it will not generally be
one of the errors included in the SDK header file WinError.h.

Syntax
C++

DWORD WNetGetLastErrorW(

[out] LPDWORD lpError,

[out] LPWSTR lpErrorBuf,

[in] DWORD nErrorBufSize,

[out] LPWSTR lpNameBuf,

[in] DWORD nNameBufSize

);

Parameters
[out] lpError

Pointer to a variable that receives the error code reported by the network provider. The
error code is specific to the network provider.

[out] lpErrorBuf

Pointer to the buffer that receives the null-terminated string describing the error.

[in] nErrorBufSize

Size of the buffer pointed to by the lpErrorBuf parameter, in characters. If the buffer is
too small for the error string, the string is truncated but still null-terminated. A buffer of
at least 256 characters is recommended.

[out] lpNameBuf

Pointer to the buffer that receives the null-terminated string identifying the network
provider that raised the error.
[in] nNameBufSize

Size of the buffer pointed to by the lpNameBuf parameter, in characters. If the buffer is
too small for the error string, the string is truncated but still null-terminated.

Return value
If the function succeeds, and it obtains the last error that the network provider reported,
the return value is NO_ERROR.

If the caller supplies an invalid buffer, the return value is ERROR_INVALID_ADDRESS.

Remarks
The
WNetGetLastError function retrieves errors that are specific to a network provider.
You can call
WNetGetLastError when a WNet function returns
ERROR_EXTENDED_ERROR.

Like the
GetLastError function,
WNetGetLastError returns extended error information,
which is maintained on a per-thread basis. Unlike GetLastError, the
WNetGetLastError
function can return a string for reporting errors that are not described by any existing
error code in WinError.h.

For more information about using an application-defined error handler that calls the
WNetGetLastError function, see
Retrieving Network Errors.

７ Note

The winnetwk.h header defines WNetGetLastError as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetNetworkInformationA function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetNetworkInformation function returns extended information about a
specific network provider whose name was returned by a previous network
enumeration.

Syntax
C++

DWORD WNetGetNetworkInformationA(

[in] LPCSTR lpProvider,

[out] LPNETINFOSTRUCT lpNetInfoStruct

);

Parameters
[in] lpProvider

Pointer to a constant null-terminated string that contains the name of the network
provider for which information is required.

[out] lpNetInfoStruct

Pointer to a
NETINFOSTRUCT structure. The structure describes characteristics of the
network.

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_BAD_PROVIDER The lpProvider parameter does not match any running

network provider.
 ERROR_BAD_VALUE The cbStructure member of the NETINFOSTRUCT
structure does not contain a valid structure size.

Remarks

７ Note

The winnetwk.h header defines WNetGetNetworkInformation as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETINFOSTRUCT

NETRESOURCE

WNetEnumResource

WNetGetProviderName

WNetOpenEnum

Windows
Networking (WNet) Overview
Windows
Networking Functions
WNetGetNetworkInformationW
function (winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetNetworkInformation function returns extended information about a
specific network provider whose name was returned by a previous network
enumeration.

Syntax
C++

DWORD WNetGetNetworkInformationW(

[in] LPCWSTR lpProvider,

[out] LPNETINFOSTRUCT lpNetInfoStruct

);

Parameters
[in] lpProvider

Pointer to a constant null-terminated string that contains the name of the network
provider for which information is required.

[out] lpNetInfoStruct

Pointer to a
NETINFOSTRUCT structure. The structure describes characteristics of the
network.

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_BAD_PROVIDER The lpProvider parameter does not match any running

network provider.
 ERROR_BAD_VALUE The cbStructure member of the NETINFOSTRUCT
structure does not contain a valid structure size.

Remarks

７ Note

The winnetwk.h header defines WNetGetNetworkInformation as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
NETINFOSTRUCT

NETRESOURCE

WNetEnumResource

WNetGetProviderName

WNetOpenEnum

Windows
Networking (WNet) Overview
Windows
Networking Functions
WNetGetProviderNameA function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetProviderName function obtains the provider name for a specific type of
network.

Syntax
C++

DWORD WNetGetProviderNameA(

[in] DWORD dwNetType,

[out] LPSTR lpProviderName,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] dwNetType

Network type that is unique to the network. If two networks claim the same type, the
function returns the name of the provider loaded first. Only the high word of the
network type is used. If a network reports a subtype in the low word, it is ignored.

You can find a complete list of network types in the header file Winnetwk.h.

[out] lpProviderName

Pointer to a buffer that receives the network provider name.

[in, out] lpBufferSize

Size of the buffer passed to the function, in characters. If the return value is
ERROR_MORE_DATA, lpBufferSize returns the buffer size required (in characters) to hold
the provider name.

Windows Me/98/95:  The size of the buffer is in bytes, not characters. Also, the buffer
must be at least 1 byte long.

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_MORE_DATA The buffer is too small to hold the network provider

name.

ERROR_NO_NETWORK The network is unavailable.

ERROR_INVALID_ADDRESS The lpProviderName parameter or the lpBufferSize

parameter is invalid.

Remarks

７ Note

The winnetwk.h header defines WNetGetProviderName as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetGetNetworkInformation

WNetGetResourceInformation

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetProviderNameW function
(winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetProviderName function obtains the provider name for a specific type of
network.

Syntax
C++

DWORD WNetGetProviderNameW(

[in] DWORD dwNetType,

[out] LPWSTR lpProviderName,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] dwNetType

Network type that is unique to the network. If two networks claim the same type, the
function returns the name of the provider loaded first. Only the high word of the
network type is used. If a network reports a subtype in the low word, it is ignored.

You can find a complete list of network types in the header file Winnetwk.h.

[out] lpProviderName

Pointer to a buffer that receives the network provider name.

[in, out] lpBufferSize

Size of the buffer passed to the function, in characters. If the return value is
ERROR_MORE_DATA, lpBufferSize returns the buffer size required (in characters) to hold
the provider name.

Windows Me/98/95:  The size of the buffer is in bytes, not characters. Also, the buffer
must be at least 1 byte long.

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_MORE_DATA The buffer is too small to hold the network provider

name.

ERROR_NO_NETWORK The network is unavailable.

ERROR_INVALID_ADDRESS The lpProviderName parameter or the lpBufferSize

parameter is invalid.

Remarks

７ Note

The winnetwk.h header defines WNetGetProviderName as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetGetNetworkInformation

WNetGetResourceInformation

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetResourceInformationA
function (winnetwk.h)
Article • 02/09/20233 minutes to read

When provided with a remote path to a network resource, the

WNetGetResourceInformation function identifies the network provider that owns the
resource and obtains information about the type of the resource. The function is
typically used in conjunction with the
WNetGetResourceParent function to parse and
interpret a network path typed in by a user.

Syntax
C++

DWORD WNetGetResourceInformationA(

[in] LPNETRESOURCEA lpNetResource,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpcbBuffer,

[out] LPSTR *lplpSystem

);

Parameters
[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the network resource for which
information is required.

The lpRemoteName member of the structure should specify the remote path name of
the resource, typically one typed in by a user. The lpProvider and dwType members
should also be filled in if known, because this operation can be memory intensive,
especially if you do not specify the dwType member. If you do not know the values for
these members, you should set them to NULL. All other members of the
NETRESOURCE
structure are ignored.

[out] lpBuffer

Pointer to the buffer to receive the result. On successful return, the first portion of the
buffer is a
NETRESOURCE structure representing that portion of the input resource path
that is accessed through the WNet functions, rather than through system functions
specific to the input resource type. (The remainder of the buffer contains the variable-
length strings to which the members of the
NETRESOURCE structure point.)

For example, if the input remote resource path is \server\share\dir1\dir2, then the
output
NETRESOURCE structure contains information about the resource \server\share.
The \dir1\dir2 portion of the path is accessed through the
file management functions.
The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage members of
NETRESOURCE are returned, with all other members set to NULL.

The lpRemoteName member is returned in the same syntax as the one returned from
an enumeration by the
WNetEnumResource function. This allows the caller to perform a
string comparison to determine whether the resource passed to
WNetGetResourceInformation is the same as the resource returned by a separate call
to
WNetEnumResource.

[in, out] lpcbBuffer

Pointer to a location that, on entry, specifies the size of the lpBuffer buffer, in bytes. The
buffer you allocate must be large enough to hold the
NETRESOURCE structure, plus the
strings to which its members point. If the buffer is too small for the result, this location
receives the required buffer size, and the function returns ERROR_MORE_DATA.

[out] lplpSystem

If the function returns successfully, this parameter points to a string in the output buffer
that specifies the part of the resource that is accessed through system functions. (This
applies only to functions specific to the resource type rather than the WNet functions.)

For example, if the input remote resource name is \server\share\dir1\dir2, the

lpRemoteName member of the output
NETRESOURCE structure points to \server\share.
Also, the lplpSystem parameter points to \dir1\dir2. Both strings are stored in the buffer
pointed to by the lpBuffer parameter.

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_BAD_NET_NAME The input lpRemoteName member is not an existing

network resource for any network.
 ERROR_BAD_DEV_TYPE The input dwType member does not match the type of
resource specified by the lpRemoteName member.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call WNetGetLastError

to obtain a description of the error.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small.

ERROR_NO_NETWORK The network is unavailable.

Remarks

７ Note

The winnetwk.h header defines WNetGetResourceInformation as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetGetNetworkInformation

WNetGetProviderName
WNetGetResourceParent

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetResourceInformationW
function (winnetwk.h)
Article • 02/09/20233 minutes to read

When provided with a remote path to a network resource, the

WNetGetResourceInformation function identifies the network provider that owns the
resource and obtains information about the type of the resource. The function is
typically used in conjunction with the
WNetGetResourceParent function to parse and
interpret a network path typed in by a user.

Syntax
C++

DWORD WNetGetResourceInformationW(

[in] LPNETRESOURCEW lpNetResource,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpcbBuffer,

[out] LPWSTR *lplpSystem

);

Parameters
[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the network resource for which
information is required.

The lpRemoteName member of the structure should specify the remote path name of
the resource, typically one typed in by a user. The lpProvider and dwType members
should also be filled in if known, because this operation can be memory intensive,
especially if you do not specify the dwType member. If you do not know the values for
these members, you should set them to NULL. All other members of the
NETRESOURCE
structure are ignored.

[out] lpBuffer

Pointer to the buffer to receive the result. On successful return, the first portion of the
buffer is a
NETRESOURCE structure representing that portion of the input resource path
that is accessed through the WNet functions, rather than through system functions
specific to the input resource type. (The remainder of the buffer contains the variable-
length strings to which the members of the
NETRESOURCE structure point.)

For example, if the input remote resource path is \server\share\dir1\dir2, then the
output
NETRESOURCE structure contains information about the resource \server\share.
The \dir1\dir2 portion of the path is accessed through the
file management functions.
The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage members of
NETRESOURCE are returned, with all other members set to NULL.

The lpRemoteName member is returned in the same syntax as the one returned from
an enumeration by the
WNetEnumResource function. This allows the caller to perform a
string comparison to determine whether the resource passed to
WNetGetResourceInformation is the same as the resource returned by a separate call
to
WNetEnumResource.

[in, out] lpcbBuffer

Pointer to a location that, on entry, specifies the size of the lpBuffer buffer, in bytes. The
buffer you allocate must be large enough to hold the
NETRESOURCE structure, plus the
strings to which its members point. If the buffer is too small for the result, this location
receives the required buffer size, and the function returns ERROR_MORE_DATA.

[out] lplpSystem

If the function returns successfully, this parameter points to a string in the output buffer
that specifies the part of the resource that is accessed through system functions. (This
applies only to functions specific to the resource type rather than the WNet functions.)

For example, if the input remote resource name is \server\share\dir1\dir2, the

lpRemoteName member of the output
NETRESOURCE structure points to \server\share.
Also, the lplpSystem parameter points to \dir1\dir2. Both strings are stored in the buffer
pointed to by the lpBuffer parameter.

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_BAD_NET_NAME The input lpRemoteName member is not an existing

network resource for any network.
 ERROR_BAD_DEV_TYPE The input dwType member does not match the type of
resource specified by the lpRemoteName member.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call WNetGetLastError

to obtain a description of the error.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small.

ERROR_NO_NETWORK The network is unavailable.

Remarks

７ Note

The winnetwk.h header defines WNetGetResourceInformation as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
WNetGetNetworkInformation

WNetGetProviderName
WNetGetResourceParent

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetResourceParentA function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetGetResourceParent function returns the parent of a network resource in the
network browse hierarchy. Browsing begins at the location of the specified network
resource.

Call the
WNetGetResourceInformation and
WNetGetResourceParent functions to move
up the network hierarchy. Call the
WNetOpenEnum function to move down the
hierarchy.

Syntax
C++

DWORD WNetGetResourceParentA(

[in] LPNETRESOURCEA lpNetResource,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpcbBuffer

);

Parameters
[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the network resource for which the
parent name is required.

Specify the members of the input

NETRESOURCE structure as follows. The caller
typically knows the values to provide for the lpProvider and dwType members after
previous calls to
WNetGetResourceInformation or
WNetGetResourceParent.

Member Meaning

dwType This member should be filled in if known; otherwise, it

should be set to NULL.

lpRemoteName This member should specify the remote name of the

network resource whose parent is required.

lpProvider This member should specify the network provider that

 owns the resource. This member is required; otherwise,
the function could produce incorrect results.

All other members of the

NETRESOURCE structure are ignored.

[out] lpBuffer

Pointer to a buffer to receive a single

NETRESOURCE structure that represents the
parent resource. The function returns the lpRemoteName, lpProvider, dwType,
dwDisplayType, and dwUsage members of the structure; all other members are set to
NULL.

The lpRemoteName member points to the remote name for the parent resource. This
name uses the same syntax as the one returned from an enumeration by the
WNetEnumResource function. The caller can perform a string comparison to determine
whether the
WNetGetResourceParent resource is the same as that returned by
WNetEnumResource. If the input resource has no parent on any of the networks, the
lpRemoteName member is returned as NULL.

The presence of the RESOURCEUSAGE_CONNECTABLE bit in the dwUsage member

indicates that you can connect to the parent resource, but only when it is available on
the network.

[in, out] lpcbBuffer

Pointer to a location that, on entry, specifies the size of the lpBuffer buffer, in bytes. If
the buffer is too small to hold the result, this location receives the required buffer size,
and the function returns ERROR_MORE_DATA.

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_BAD_NET_NAME The input lpRemoteName member is not an existing

network resource for any network.

ERROR_BAD_PROVIDER The input lpProvider member does not match any

 installed network provider.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small.

ERROR_NOT_AUTHENTICATED The caller does not have the necessary permissions to

obtain the name of the parent.

Remarks
The
WNetGetResourceParent function is typically used in conjunction with the
WNetGetResourceInformation function to parse and interpret a network path typed in
by a user.

Unlike the
WNetGetResourceInformation function, if the resource includes a parent in
its syntax, the
WNetGetResourceParent function returns the parent, whether or not the
resource actually exists.
WNetGetResourceParent should typically be used only by
applications that display network resources to the user in a hierarchical fashion. The
Windows Explorer and the File Open dialog box are two well-known examples of this
type of application. Note that no assumptions should be made about the type of
resource that will be returned.

You can call the

WNetEnumResource,
WNetGetResourceInformation, or
WNetGetResourceParent function to return information from the
NETRESOURCE
structure. You can also construct network resource information using the members of
the
NETRESOURCE structure.

An example of an inappropriate use of

WNetGetResourceParent is to determine the
name of the domain to which a specified server belongs. The function may happen to
return the correct domain name for some networks in which domains appear directly
above servers in the browse hierarchy. The function will return incorrect results for other
networks.

７ Note

The winnetwk.h header defines WNetGetResourceParent as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.
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
WNetGetNetworkInformation

WNetGetProviderName

WNetGetResourceInformation

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetResourceParentW function
(winnetwk.h)
Article • 02/09/20233 minutes to read

The
WNetGetResourceParent function returns the parent of a network resource in the
network browse hierarchy. Browsing begins at the location of the specified network
resource.

Call the
WNetGetResourceInformation and
WNetGetResourceParent functions to move
up the network hierarchy. Call the
WNetOpenEnum function to move down the
hierarchy.

Syntax
C++

DWORD WNetGetResourceParentW(

[in] LPNETRESOURCEW lpNetResource,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpcbBuffer

);

Parameters
[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the network resource for which the
parent name is required.

Specify the members of the input

NETRESOURCE structure as follows. The caller
typically knows the values to provide for the lpProvider and dwType members after
previous calls to
WNetGetResourceInformation or
WNetGetResourceParent.

Member Meaning

dwType This member should be filled in if known; otherwise, it

should be set to NULL.

lpRemoteName This member should specify the remote name of the

network resource whose parent is required.

lpProvider This member should specify the network provider that

 owns the resource. This member is required; otherwise,
the function could produce incorrect results.

All other members of the

NETRESOURCE structure are ignored.

[out] lpBuffer

Pointer to a buffer to receive a single

NETRESOURCE structure that represents the
parent resource. The function returns the lpRemoteName, lpProvider, dwType,
dwDisplayType, and dwUsage members of the structure; all other members are set to
NULL.

The lpRemoteName member points to the remote name for the parent resource. This
name uses the same syntax as the one returned from an enumeration by the
WNetEnumResource function. The caller can perform a string comparison to determine
whether the
WNetGetResourceParent resource is the same as that returned by
WNetEnumResource. If the input resource has no parent on any of the networks, the
lpRemoteName member is returned as NULL.

The presence of the RESOURCEUSAGE_CONNECTABLE bit in the dwUsage member

indicates that you can connect to the parent resource, but only when it is available on
the network.

[in, out] lpcbBuffer

Pointer to a location that, on entry, specifies the size of the lpBuffer buffer, in bytes. If
the buffer is too small to hold the result, this location receives the required buffer size,
and the function returns ERROR_MORE_DATA.

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_BAD_NET_NAME The input lpRemoteName member is not an existing

network resource for any network.

ERROR_BAD_PROVIDER The input lpProvider member does not match any

 installed network provider.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small.

ERROR_NOT_AUTHENTICATED The caller does not have the necessary permissions to

obtain the name of the parent.

Remarks
The
WNetGetResourceParent function is typically used in conjunction with the
WNetGetResourceInformation function to parse and interpret a network path typed in
by a user.

Unlike the
WNetGetResourceInformation function, if the resource includes a parent in
its syntax, the
WNetGetResourceParent function returns the parent, whether or not the
resource actually exists.
WNetGetResourceParent should typically be used only by
applications that display network resources to the user in a hierarchical fashion. The
Windows Explorer and the File Open dialog box are two well-known examples of this
type of application. Note that no assumptions should be made about the type of
resource that will be returned.

You can call the

WNetEnumResource,
WNetGetResourceInformation, or
WNetGetResourceParent function to return information from the
NETRESOURCE
structure. You can also construct network resource information using the members of
the
NETRESOURCE structure.

An example of an inappropriate use of

WNetGetResourceParent is to determine the
name of the domain to which a specified server belongs. The function may happen to
return the correct domain name for some networks in which domains appear directly
above servers in the browse hierarchy. The function will return incorrect results for other
networks.

７ Note

The winnetwk.h header defines WNetGetResourceParent as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.
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
WNetGetNetworkInformation

WNetGetProviderName

WNetGetResourceInformation

WNetGetUniversalName

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetUniversalNameA function
(winnetwk.h)
Article • 02/09/20236 minutes to read

The
WNetGetUniversalName function takes a drive-based path for a network resource
and returns an information structure that contains a more universal form of the name.

Syntax
C++

DWORD WNetGetUniversalNameA(

[in] LPCSTR lpLocalPath,

[in] DWORD dwInfoLevel,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] lpLocalPath

A pointer to a constant null-terminated string that is a drive-based path for a network

resource.

For example, if drive H has been mapped to a network drive share, and the network
resource of interest is a file named Sample.doc in the directory \Win32\Examples on that
share, the drive-based path is H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

The type of structure that the function stores in the buffer pointed to by the lpBuffer
parameter. This parameter can be one of the following values defined in the Winnetwk.h
header file.

Value Meaning

UNIVERSAL_NAME_INFO_LEVEL The function stores a UNIVERSAL_NAME_INFO structure

in the buffer.

REMOTE_NAME_INFO_LEVEL The function stores a REMOTE_NAME_INFO structure in

the buffer.
 

The
UNIVERSAL_NAME_INFO structure points to a Universal Naming Convention (UNC)
name string.

The
REMOTE_NAME_INFO structure points to a UNC name string and two additional
connection information strings. For more information, see the following Remarks
section.

[out] lpBuffer

A pointer to a buffer that receives the structure specified by the dwInfoLevel parameter.

[in, out] lpBufferSize

A pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the
lpBuffer parameter.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the number of
bytes stored in the buffer. If the function fails because the buffer is too small, this
location receives the required buffer size, and the function returns ERROR_MORE_DATA.

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_BAD_DEVICE The string pointed to by the lpLocalPath parameter is

invalid.

ERROR_CONNECTION_UNAVAIL There is no current connection to the remote device, but

there is a remembered (persistent) connection to it.

ERROR_EXTENDED_ERROR A network-specific error occurred. Use the

WNetGetLastError function to obtain a description of the
error.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small. The function sets the variable pointed to by the
lpBufferSize parameter to the required buffer size. More
entries are available with subsequent calls.

ERROR_NOT_SUPPORTED The dwInfoLevel parameter is set to

 UNIVERSAL_NAME_INFO_LEVEL, but the network provider
does not support UNC names. (None of the network
providers support this function.)

ERROR_NO_NET_OR_BAD_PATH None of the network providers recognize the local name

as having a connection. However, the network is not
available for at least one provider to whom the
connection may belong.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_CONNECTED The device specified by the lpLocalPath parameter is not

redirected.

Remarks
A universal form of a local drive-based path identifies a network resource in an
unambiguous, computer-independent manner. The name can then be passed to
processes on other computers, allowing those processes to obtain access to the
resource.

The
WNetGetUniversalName function currently supports one universal name form:
universal naming convention (UNC) names, which look like the following:

syntax

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the
shared network drive is on a server named COOLSERVER, and the share name is
HOTSHARE, the UNC name for the network resource whose drive-based name is
H:\Win32\Examples\Sample.doc would be the following:

syntax

\\coolserver\hotshare\win32\examples\sample.doc

The
UNIVERSAL_NAME_INFO structure contains a pointer to a UNC name string. The
REMOTE_NAME_INFO structure also contains a pointer to a UNC name string as well as
pointers to two other useful strings. For example, a process can pass the
REMOTE_NAME_INFO structure's lpszConnectionInfo member to the
WNetAddConnection2 function to connect a local device to the network resource. Then
the process can append the string pointed to by the lpszRemainingPath member to the
local device string. The resulting string can be passed to functions that require a drive-
based path.

The lpLocalPath parameter does not have to specify a path or resource that is already
present on a remote resource. For example, the lpLocalPath parameter could specify and
folder, a hierarchy of folders, or a file that does not currently exist. The
WNetGetUniversalName function returns a more universal form of the name in these
cases.

The size of the buffer pointed to by the lpBuffer parameter and specified in the
lpBufferSize parameter must be much larger than the size of the REMOTE_NAME_INFO
or UNIVERSAL_NAME_INFO structures. The buffer pointed to by the lpBuffer parameter
must be large enough to store the UNC strings pointed to by the members in the
REMOTE_NAME_INFO
or UNIVERSAL_NAME_INFO structures. If the buffer size is too
small, then the function fails with ERROR_MORE_DATA and the variable pointed to by
the lpBufferSize parameter indicates the required buffer size.

Windows Server 2003 and Windows XP:  This function queries the MS-DOS device

namespaces associated with a logon session because MS-DOS devices are identified by
AuthenticationID. (An AuthenticationID is the
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. GetLogicalDrives does not return network drive letters
created by a WNet function 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.

Examples
The following code sample illustrates how to use the
WNetGetUniversalName function
to retrieve the universal UNC name strings associated with drive-based path for a
network resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

WCHAR Buffer[1024];

DWORD dwBufferLength = 1024;

UNIVERSAL_NAME_INFO * unameinfo;

REMOTE_NAME_INFO *remotenameinfo;

wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n",

argv[1]);

unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;

dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL,

(LPVOID) unameinfo, &dwBufferLength );

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUniversalName returned success for

InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");

wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);

else {

wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL

with error: %u\n", dwRetVal);

remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;

dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,

(LPVOID) remotenameinfo, &dwBufferLength );

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUniversalName returned success for

InfoLevel=REMOTE_NAME_INFO_LEVEL\n");

wprintf(L"\tUniversal name = %s\n", remotenameinfo-

>lpUniversalName);

wprintf(L"\tConnection name = %s\n", remotenameinfo-

>lpConnectionName);

wprintf(L"\tRemaining path = %s\n", remotenameinfo-

>lpRemainingPath);

else {

wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL

with error: %u\n", dwRetVal);

７ Note

The winnetwk.h header defines WNetGetUniversalName as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
Determining the Location of a Share

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2
Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetUniversalNameW function
(winnetwk.h)
Article • 02/09/20236 minutes to read

The
WNetGetUniversalName function takes a drive-based path for a network resource
and returns an information structure that contains a more universal form of the name.

Syntax
C++

DWORD WNetGetUniversalNameW(

[in] LPCWSTR lpLocalPath,

[in] DWORD dwInfoLevel,

[out] LPVOID lpBuffer,

[in, out] LPDWORD lpBufferSize

);

Parameters
[in] lpLocalPath

A pointer to a constant null-terminated string that is a drive-based path for a network

resource.

For example, if drive H has been mapped to a network drive share, and the network
resource of interest is a file named Sample.doc in the directory \Win32\Examples on that
share, the drive-based path is H:\Win32\Examples\Sample.doc.

[in] dwInfoLevel

The type of structure that the function stores in the buffer pointed to by the lpBuffer
parameter. This parameter can be one of the following values defined in the Winnetwk.h
header file.

Value Meaning

UNIVERSAL_NAME_INFO_LEVEL The function stores a UNIVERSAL_NAME_INFO structure

in the buffer.

REMOTE_NAME_INFO_LEVEL The function stores a REMOTE_NAME_INFO structure in

the buffer.
 

The
UNIVERSAL_NAME_INFO structure points to a Universal Naming Convention (UNC)
name string.

The
REMOTE_NAME_INFO structure points to a UNC name string and two additional
connection information strings. For more information, see the following Remarks
section.

[out] lpBuffer

A pointer to a buffer that receives the structure specified by the dwInfoLevel parameter.

[in, out] lpBufferSize

A pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the
lpBuffer parameter.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the number of
bytes stored in the buffer. If the function fails because the buffer is too small, this
location receives the required buffer size, and the function returns ERROR_MORE_DATA.

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_BAD_DEVICE The string pointed to by the lpLocalPath parameter is

invalid.

ERROR_CONNECTION_UNAVAIL There is no current connection to the remote device, but

there is a remembered (persistent) connection to it.

ERROR_EXTENDED_ERROR A network-specific error occurred. Use the

WNetGetLastError function to obtain a description of the
error.

ERROR_MORE_DATA The buffer pointed to by the lpBuffer parameter is too

small. The function sets the variable pointed to by the
lpBufferSize parameter to the required buffer size. More
entries are available with subsequent calls.

ERROR_NOT_SUPPORTED The dwInfoLevel parameter is set to

 UNIVERSAL_NAME_INFO_LEVEL, but the network provider
does not support UNC names. (None of the network
providers support this function.)

ERROR_NO_NET_OR_BAD_PATH None of the network providers recognize the local name

as having a connection. However, the network is not
available for at least one provider to whom the
connection may belong.

ERROR_NO_NETWORK The network is unavailable.

ERROR_NOT_CONNECTED The device specified by the lpLocalPath parameter is not

redirected.

Remarks
A universal form of a local drive-based path identifies a network resource in an
unambiguous, computer-independent manner. The name can then be passed to
processes on other computers, allowing those processes to obtain access to the
resource.

The
WNetGetUniversalName function currently supports one universal name form:
universal naming convention (UNC) names, which look like the following:

syntax

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the
shared network drive is on a server named COOLSERVER, and the share name is
HOTSHARE, the UNC name for the network resource whose drive-based name is
H:\Win32\Examples\Sample.doc would be the following:

syntax

\\coolserver\hotshare\win32\examples\sample.doc

The
UNIVERSAL_NAME_INFO structure contains a pointer to a UNC name string. The
REMOTE_NAME_INFO structure also contains a pointer to a UNC name string as well as
pointers to two other useful strings. For example, a process can pass the
REMOTE_NAME_INFO structure's lpszConnectionInfo member to the
WNetAddConnection2 function to connect a local device to the network resource. Then
the process can append the string pointed to by the lpszRemainingPath member to the
local device string. The resulting string can be passed to functions that require a drive-
based path.

The lpLocalPath parameter does not have to specify a path or resource that is already
present on a remote resource. For example, the lpLocalPath parameter could specify and
folder, a hierarchy of folders, or a file that does not currently exist. The
WNetGetUniversalName function returns a more universal form of the name in these
cases.

The size of the buffer pointed to by the lpBuffer parameter and specified in the
lpBufferSize parameter must be much larger than the size of the REMOTE_NAME_INFO
or UNIVERSAL_NAME_INFO structures. The buffer pointed to by the lpBuffer parameter
must be large enough to store the UNC strings pointed to by the members in the
REMOTE_NAME_INFO
or UNIVERSAL_NAME_INFO structures. If the buffer size is too
small, then the function fails with ERROR_MORE_DATA and the variable pointed to by
the lpBufferSize parameter indicates the required buffer size.

Windows Server 2003 and Windows XP:  This function queries the MS-DOS device

namespaces associated with a logon session because MS-DOS devices are identified by
AuthenticationID. (An AuthenticationID is the
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. GetLogicalDrives does not return network drive letters
created by a WNet function 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.

Examples
The following code sample illustrates how to use the
WNetGetUniversalName function
to retrieve the universal UNC name strings associated with drive-based path for a
network resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

WCHAR Buffer[1024];

DWORD dwBufferLength = 1024;

UNIVERSAL_NAME_INFO * unameinfo;

REMOTE_NAME_INFO *remotenameinfo;

wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n",

argv[1]);

unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;

dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL,

(LPVOID) unameinfo, &dwBufferLength );

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUniversalName returned success for

InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");

wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);

else {

wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL

with error: %u\n", dwRetVal);

remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;

dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL,

(LPVOID) remotenameinfo, &dwBufferLength );

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUniversalName returned success for

InfoLevel=REMOTE_NAME_INFO_LEVEL\n");

wprintf(L"\tUniversal name = %s\n", remotenameinfo-

>lpUniversalName);

wprintf(L"\tConnection name = %s\n", remotenameinfo-

>lpConnectionName);

wprintf(L"\tRemaining path = %s\n", remotenameinfo-

>lpRemainingPath);

else {

wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL

with error: %u\n", dwRetVal);

７ Note

The winnetwk.h header defines WNetGetUniversalName as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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
Determining the Location of a Share

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2
Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetUserA function (winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetUser function retrieves the current default user name, or the user name
used to establish a network connection.

Syntax
C++

DWORD WNetGetUserA(

[in] LPCSTR lpName,

[out] LPSTR lpUserName,

[in, out] LPDWORD lpnLength

);

Parameters
[in] lpName

A pointer to a constant null-terminated string that specifies either the name of a local
device that has been redirected to a network resource, or the remote name of a network
resource to which a connection has been made without redirecting a local device.

If this parameter is NULL or the empty string, the system returns the name of the
current user for the process.

[out] lpUserName

A pointer to a buffer that receives the null-terminated user name.

[in, out] lpnLength

A pointer to a variable that specifies the size of the lpUserName buffer, in characters. If
the call fails because the buffer is not large enough, this variable contains the required
buffer size.

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_NOT_CONNECTED The device specified by the lpName parameter is not a

redirected device or a connected network name.

ERROR_MORE_DATA More entries are available with subsequent calls.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NO_NET_OR_BAD_PATH None of the providers recognize the local name as having

a connection. However, the network is not available for at
least one provider to whom the connection may belong.

Remarks
The WNetGetUser function is not aware of shares on the Distributed File System (DFS).
If the name specified by the lpName parameter is a local device redirected to a DFS
share or a remote resource that represents a DFS share, the WNetGetUser function fails
with ERROR_NOT_CONNECTED.

Examples

The following code sample illustrates how to use the

WNetGetUser function to retrieve
the name of the user associated with a redirected local device or a remote network
resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

 WCHAR UserName[MAX_PATH];

DWORD dwNameLength = MAX_PATH;

if (argc != 2) {

wprintf

(L"Usage: %s [Redirected-LocalDevice or Network-Resource-Remote-

name\n",

argv[0]);

exit(1);

wprintf(L"Calling WNetGetUser with Network-Resource = %s\n", argv[1]);

dwRetVal = WNetGetUser(argv[1], UserName, &dwNameLength);

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUser returned success\n");

wprintf(L"\tUsername=%s NameLength=%d\n", &UserName,

dwNameLength);

exit(0);

else {

wprintf(L"WNetGetUser failed with error: %u\n", dwRetVal);

exit(1);

７ Note

The winnetwk.h header defines WNetGetUser as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
Retrieving the User Name

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetGetUserW function (winnetwk.h)
Article • 02/09/20232 minutes to read

The
WNetGetUser function retrieves the current default user name, or the user name
used to establish a network connection.

Syntax
C++

DWORD WNetGetUserW(

[in] LPCWSTR lpName,

[out] LPWSTR lpUserName,

[in, out] LPDWORD lpnLength

);

Parameters
[in] lpName

A pointer to a constant null-terminated string that specifies either the name of a local
device that has been redirected to a network resource, or the remote name of a network
resource to which a connection has been made without redirecting a local device.

If this parameter is NULL or the empty string, the system returns the name of the
current user for the process.

[out] lpUserName

A pointer to a buffer that receives the null-terminated user name.

[in, out] lpnLength

A pointer to a variable that specifies the size of the lpUserName buffer, in characters. If
the call fails because the buffer is not large enough, this variable contains the required
buffer size.

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_NOT_CONNECTED The device specified by the lpName parameter is not a

redirected device or a connected network name.

ERROR_MORE_DATA More entries are available with subsequent calls.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_NO_NET_OR_BAD_PATH None of the providers recognize the local name as having

a connection. However, the network is not available for at
least one provider to whom the connection may belong.

Remarks
The WNetGetUser function is not aware of shares on the Distributed File System (DFS).
If the name specified by the lpName parameter is a local device redirected to a DFS
share or a remote resource that represents a DFS share, the WNetGetUser function fails
with ERROR_NOT_CONNECTED.

Examples

The following code sample illustrates how to use the

WNetGetUser function to retrieve
the name of the user associated with a redirected local device or a remote network
resource.

C++

#ifndef UNICODE

#define UNICODE

#endif

#pragma comment(lib, "mpr.lib")

#include <windows.h>

#include <tchar.h>

#include <stdio.h>

#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])

DWORD dwRetVal;

 WCHAR UserName[MAX_PATH];

DWORD dwNameLength = MAX_PATH;

if (argc != 2) {

wprintf

(L"Usage: %s [Redirected-LocalDevice or Network-Resource-Remote-

name\n",

argv[0]);

exit(1);

wprintf(L"Calling WNetGetUser with Network-Resource = %s\n", argv[1]);

dwRetVal = WNetGetUser(argv[1], UserName, &dwNameLength);

//

// If the call succeeds, print the user information.

//

if (dwRetVal == NO_ERROR) {

wprintf(L"WNetGetUser returned success\n");

wprintf(L"\tUsername=%s NameLength=%d\n", &UserName,

dwNameLength);

exit(0);

else {

wprintf(L"WNetGetUser failed with error: %u\n", dwRetVal);

exit(1);

７ Note

The winnetwk.h header defines WNetGetUser as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
Retrieving the User Name

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetOpenEnumA function
(winnetwk.h)
Article • 02/09/20234 minutes to read

The
WNetOpenEnum function starts an enumeration of network resources or existing
connections. You can continue the enumeration by calling the
WNetEnumResource
function.

Syntax
C++

DWORD WNetOpenEnumA(

[in] DWORD dwScope,

[in] DWORD dwType,

[in] DWORD dwUsage,

[in] LPNETRESOURCEA lpNetResource,

[out] LPHANDLE lphEnum

);

Parameters
[in] dwScope

Scope of the enumeration. This parameter can be one of the following values.

Value Meaning

RESOURCE_CONNECTED Enumerate all currently connected resources. The

function ignores the dwUsage parameter. For more
information, see the following Remarks section.

RESOURCE_CONTEXT Enumerate only resources in the network context of the

caller. Specify this value for a Network Neighborhood
view. The function ignores the dwUsage parameter.

RESOURCE_GLOBALNET Enumerate all resources on the network.

RESOURCE_REMEMBERED Enumerate all remembered (persistent) connections. The

function ignores the dwUsage parameter.

[in] dwType
Resource types to be enumerated. This parameter can be a combination of the following
values.

Value Meaning

RESOURCETYPE_ANY All resources. This value cannot be combined with

RESOURCETYPE_DISK or RESOURCETYPE_PRINT.

RESOURCETYPE_DISK All disk resources.

RESOURCETYPE_PRINT All print resources.

If a network provider cannot distinguish between print and disk resources, it can
enumerate all resources.

[in] dwUsage

Resource usage type to be enumerated. This parameter can be a combination of the

following values.

Value Meaning

0 All resources.

RESOURCEUSAGE_CONNECTABLE All connectable resources.

RESOURCEUSAGE_CONTAINER All container resources.

RESOURCEUSAGE_ATTACHED Setting this value forces WNetOpenEnum to fail if the

user is not authenticated. The function fails even if the
network allows enumeration without authentication.

RESOURCEUSAGE_ALL Setting this value is equivalent to setting

RESOURCEUSAGE_CONNECTABLE,
RESOURCEUSAGE_CONTAINER, and
RESOURCEUSAGE_ATTACHED.

This parameter is ignored unless the dwScope parameter is equal to

RESOURCE_GLOBALNET. For more information, see the following Remarks section.

[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the container to enumerate. If the
dwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.
If this parameter is NULL, the root of the network is assumed. (The system organizes a
network as a hierarchy; the root is the topmost container in the network.)

If this parameter is not NULL, it must point to a

NETRESOURCE structure. This structure
can be filled in by the application or it can be returned by a call to the
WNetEnumResource function. The
NETRESOURCE structure must specify a container
resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the
dwUsage parameter.

To enumerate all network resources, an application can begin the enumeration by

calling
WNetOpenEnum with the lpNetResource parameter set to NULL, and then use
the returned handle to call
WNetEnumResource to enumerate resources. If one of the
resources in the
NETRESOURCE array returned by the
WNetEnumResource function is a
container resource, you can call
WNetOpenEnum to open the resource for further
enumeration.

[out] lphEnum

Pointer to an enumeration handle that can be used in a subsequent call to

WNetEnumResource.

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_NOT_CONTAINER The lpNetResource parameter does not point to a

container.

ERROR_INVALID_PARAMETER Either the dwScope or the dwType parameter is invalid, or

there is an invalid combination of parameters.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_INVALID_ADDRESS A remote network resource name supplied in the

NETRESOURCE structure resolved to an invalid network
address.
Remarks
If the dwScope parameter is equal to RESOURCE_CONNECTED, a network connection
made using the Microsoft LAN Manager network is omitted from the enumeration if the
connection was made by an application running in a different logon session than the
application calling the
WNetOpenEnum function. This is because connections made
using Microsoft LAN Manager are visible only to applications running in the same logon
session as the application that made the connection. (To include the connection in the
enumeration, it is not sufficient for the application to be running in the user account
that created the connection.)

The exact interpretation of RESOURCE_CONTEXT in the dwScope parameter depends on

the networks installed on the machine.

The
WNetOpenEnum function is used to begin enumeration of the resources in a single
container. The following examples show the hierarchical structure of a Microsoft LAN
Manager network and a Novell NetWare network and identify the containers.

syntax

LanMan (container, in this case the provider)

ACCOUNTING (container, in this case the domain)

\\ACCTSPAY (container, in this case the server)

PAYFILES (disk)

LASERJET (print)

NetWare (container, in this case the provider)

MARKETING (container, in this case the server)

SYS (disk, first one on any NetWare server)

ANOTHERVOLUME (disk)

LASERJET (print)

Examples
For a code sample that illustrates an application-defined function that enumerates all
the resources on a network, see
Enumerating Network Resources.

７ Note

The winnetwk.h header defines WNetOpenEnum as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
NETRESOURCE

WNetCloseEnum

WNetEnumResource

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetOpenEnumW function
(winnetwk.h)
Article • 02/09/20234 minutes to read

The
WNetOpenEnum function starts an enumeration of network resources or existing
connections. You can continue the enumeration by calling the
WNetEnumResource
function.

Syntax
C++

DWORD WNetOpenEnumW(

[in] DWORD dwScope,

[in] DWORD dwType,

[in] DWORD dwUsage,

[in] LPNETRESOURCEW lpNetResource,

[out] LPHANDLE lphEnum

);

Parameters
[in] dwScope

Scope of the enumeration. This parameter can be one of the following values.

Value Meaning

RESOURCE_CONNECTED Enumerate all currently connected resources. The

function ignores the dwUsage parameter. For more
information, see the following Remarks section.

RESOURCE_CONTEXT Enumerate only resources in the network context of the

caller. Specify this value for a Network Neighborhood
view. The function ignores the dwUsage parameter.

RESOURCE_GLOBALNET Enumerate all resources on the network.

RESOURCE_REMEMBERED Enumerate all remembered (persistent) connections. The

function ignores the dwUsage parameter.

[in] dwType
Resource types to be enumerated. This parameter can be a combination of the following
values.

Value Meaning

RESOURCETYPE_ANY All resources. This value cannot be combined with

RESOURCETYPE_DISK or RESOURCETYPE_PRINT.

RESOURCETYPE_DISK All disk resources.

RESOURCETYPE_PRINT All print resources.

If a network provider cannot distinguish between print and disk resources, it can
enumerate all resources.

[in] dwUsage

Resource usage type to be enumerated. This parameter can be a combination of the

following values.

Value Meaning

0 All resources.

RESOURCEUSAGE_CONNECTABLE All connectable resources.

RESOURCEUSAGE_CONTAINER All container resources.

RESOURCEUSAGE_ATTACHED Setting this value forces WNetOpenEnum to fail if the

user is not authenticated. The function fails even if the
network allows enumeration without authentication.

RESOURCEUSAGE_ALL Setting this value is equivalent to setting

RESOURCEUSAGE_CONNECTABLE,
RESOURCEUSAGE_CONTAINER, and
RESOURCEUSAGE_ATTACHED.

This parameter is ignored unless the dwScope parameter is equal to

RESOURCE_GLOBALNET. For more information, see the following Remarks section.

[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies the container to enumerate. If the
dwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.
If this parameter is NULL, the root of the network is assumed. (The system organizes a
network as a hierarchy; the root is the topmost container in the network.)

If this parameter is not NULL, it must point to a

NETRESOURCE structure. This structure
can be filled in by the application or it can be returned by a call to the
WNetEnumResource function. The
NETRESOURCE structure must specify a container
resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the
dwUsage parameter.

To enumerate all network resources, an application can begin the enumeration by

calling
WNetOpenEnum with the lpNetResource parameter set to NULL, and then use
the returned handle to call
WNetEnumResource to enumerate resources. If one of the
resources in the
NETRESOURCE array returned by the
WNetEnumResource function is a
container resource, you can call
WNetOpenEnum to open the resource for further
enumeration.

[out] lphEnum

Pointer to an enumeration handle that can be used in a subsequent call to

WNetEnumResource.

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_NOT_CONTAINER The lpNetResource parameter does not point to a

container.

ERROR_INVALID_PARAMETER Either the dwScope or the dwType parameter is invalid, or

there is an invalid combination of parameters.

ERROR_NO_NETWORK The network is unavailable.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_INVALID_ADDRESS A remote network resource name supplied in the

NETRESOURCE structure resolved to an invalid network
address.
Remarks
If the dwScope parameter is equal to RESOURCE_CONNECTED, a network connection
made using the Microsoft LAN Manager network is omitted from the enumeration if the
connection was made by an application running in a different logon session than the
application calling the
WNetOpenEnum function. This is because connections made
using Microsoft LAN Manager are visible only to applications running in the same logon
session as the application that made the connection. (To include the connection in the
enumeration, it is not sufficient for the application to be running in the user account
that created the connection.)

The exact interpretation of RESOURCE_CONTEXT in the dwScope parameter depends on

the networks installed on the machine.

The
WNetOpenEnum function is used to begin enumeration of the resources in a single
container. The following examples show the hierarchical structure of a Microsoft LAN
Manager network and a Novell NetWare network and identify the containers.

syntax

LanMan (container, in this case the provider)

ACCOUNTING (container, in this case the domain)

\\ACCTSPAY (container, in this case the server)

PAYFILES (disk)

LASERJET (print)

NetWare (container, in this case the provider)

MARKETING (container, in this case the server)

SYS (disk, first one on any NetWare server)

ANOTHERVOLUME (disk)

LASERJET (print)

Examples
For a code sample that illustrates an application-defined function that enumerates all
the resources on a network, see
Enumerating Network Resources.

７ Note

The winnetwk.h header defines WNetOpenEnum as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation
or runtime errors. For more information, see Conventions for Function Prototypes.

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
NETRESOURCE

WNetCloseEnum

WNetEnumResource

Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetRestoreConnectionW function
(winnetwk.h)
Article • 10/13/20212 minutes to read

[WNetRestoreConnectionW is not available for use as of Windows Vista.]

The WNetRestoreConnectionW function restores the connection to a network resource.

The function prompts the user, if necessary, for a name and password.

Syntax
C++

DWORD WNetRestoreConnectionW(

[in] HWND hWnd,

[in] LPCWSTR lpDevice

);

Parameters
[in] hWnd

Handle to the parent window that the function uses to display the user interface (UI)
that prompts the user for a name and password when making the network connection.
If this parameter is NULL, there is no owner window.

[in] lpDevice

Pointer to a null-terminated Unicode string that specifies the local name of the drive to
connect to, such as "Z:". If this parameter is NULL, the function reconnects all persistent
drives stored in the registry for the current user.

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 local device specified by lpDevice is already

connected to a network resource.

ERROR_BAD_DEV_TYPE The type of local device and the type of network

resource do not match.

ERROR_BAD_DEVICE The value specified by lpDevice is invalid.

ERROR_BAD_PROFILE The user profile is in an incorrect format.

ERROR_BUSY The router or provider is busy, possibly initializing.

The caller should retry.

ERROR_CANCELLED The attempt to make the connection was canceled by

the user through a dialog box from one of the
network resource providers, or by a called resource.

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 is already in the user profile.

ERROR_EXTENDED_ERROR A network-specific error occurred. Call the

WNetGetLastError function to obtain a description of
the error.

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
The WNetRestoreConnectionW function is not supported on Windows Vista and later.

To call this function, first call the LoadLibrary function to load Mpr.dll. Then call the
GetProcAddress function to retrieve the address of the WNetRestoreConnectionW
function.

WNetRestoreConnectionW is used by Winlogon to restore all persistent drive mappings

during the interactive logon process. The function is also called by the Microsoft
Windows Shell to reconnect individual drives at the user's request. This can occur, for
example, when a drive fails to reconnect at logon and the user double-clicks the drive
under the My Computer virtual folder.

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
Windows
Networking (WNet) Overview

Windows
Networking Functions
WNetUseConnectionA function
(winnetwk.h)
Article • 02/09/20239 minutes to read

The
WNetUseConnection function makes a connection to a network resource. The
function can redirect a local device to a network resource.

The
WNetUseConnection function is similar to the
WNetAddConnection3 function. The
main difference is that
WNetUseConnection can automatically select an unused local
device to redirect to the network resource.

Syntax
C++

DWORD WNetUseConnectionA(

[in] HWND hwndOwner,

[in] LPNETRESOURCEA lpNetResource,

[in] LPCSTR lpPassword,

[in] LPCSTR lpUserId,

[in] DWORD dwFlags,

[out] LPSTR lpAccessName,

[in, out] LPDWORD lpBufferSize,

[out] LPDWORD lpResult

);

Parameters
[in] hwndOwner

Handle to a window that the provider of network resources can use as an owner window
for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE value in the
dwFlags parameter.

[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies details of the proposed connection.
The structure contains information about the network resource, the local device, and the
network resource provider.

You must specify the following members of the

NETRESOURCE structure.
 Member Meaning

dwType Specifies the type of resource to connect to.

It is most efficient to specify a resource type in this
member, such as RESOURCETYPE_DISK or
RESOURCETYPE_PRINT. However, if the lpLocalName
member is NULL, or if it points to an empty string and
CONNECT_REDIRECT is not set, dwType can be
RESOURCETYPE_ANY.

This method works only if the function does not

automatically choose a device to redirect to the network
resource.

Although this member is required, its information may be

ignored by the network service provider.

lpLocalName Pointer to a 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 empty, or if lpLocalName is NULL, a

connection to the network occurs without redirection.

If the CONNECT_REDIRECT value is set in the dwFlags

parameter, or if the network requires a redirected local
device, the function chooses a local device to redirect and
returns the name of the device in the lpAccessName
parameter.

lpRemoteName 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, and it must follow the
network provider's naming conventions.

lpProvider Pointer to a null-terminated string that specifies the

network provider to connect to. If lpProvider is NULL, or
if it points to an empty string, the operating system
attempts to determine the correct provider by parsing
the string pointed to by the lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know the network
provider you want to use. Otherwise, let the operating
system determine which provider the network name
maps to.

 
The
WNetUseConnection function ignores the other members of the
NETRESOURCE
structure. For more information, see the descriptions following for the dwFlags
parameter.

[in] lpPassword

Pointer to a constant 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 lpUserID.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

[in] lpUserId

Pointer to a constant null-terminated string that specifies a user name for making the
connection.

If lpUserID is NULL, the function uses the default user name. (The user context for the
process provides the default user name.)

The lpUserID 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.

The user-name string represents a

security context. It may be specific to a network
provider.

[in] dwFlags

Set of bit flags describing the connection. This parameter can be any combination of the
following values.

Value Meaning

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_REDIRECT This flag forces the redirection of a local device when
making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows XP:  When the system automatically assigns

network drive letters, letters are assigned beginning with
Z:, then Y:, and ending with C:. This reduces collision
between per-logon drive letters (such as network drive
letters) and global drive letters (such as disk drives). Note
that previous releases assigned drive letters beginning
with C: and ending with Z:.

CONNECT_UPDATE_PROFILE This flag instructs the operating system to store the

network resource connection.
If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on. The system remembers only successful connections
that redirect local devices. It does not remember
connections that are unsuccessful or deviceless
connections. (A deviceless connection occurs when
lpLocalName is NULL or when it points to an empty
string.)

If this bit flag is clear, the operating system does not

automatically restore the connection at logon.

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
does not support saving credentials, this flag is ignored.
This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
 Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

[out] lpAccessName

Pointer to a buffer that receives system requests on the connection. This parameter can
be NULL.

If this parameter is specified, and the lpLocalName member of the

NETRESOURCE
structure specifies a local device, this buffer receives the local device name. If
lpLocalName does not specify a device and the network requires a local device
redirection, or if the CONNECT_REDIRECT value is set, this buffer receives the name of
the redirected local device.

Otherwise, the name copied into the buffer is that of a remote resource. If specified, this
buffer must be at least as large as the string pointed to by the lpRemoteName member.

[in, out] lpBufferSize

Pointer to a variable that specifies the size of the lpAccessName buffer, in characters. If
the call fails because the buffer is not large enough, the function returns the required
buffer size in this location. For more information, see the descriptions of the
lpAccessName parameter and the ERROR_MORE_DATA error code in the Return Values
section.

[out] lpResult

Pointer to a variable that receives additional information about the connection. This
parameter can be the following value.

Value Meaning

CONNECT_LOCALDRIVE If this flag is set, the connection was made using a local
device redirection. If the lpAccessName parameter points
to a buffer, the local device name is copied to the buffer.

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 local device specified by the lpLocalName member is

already connected to a network resource.

ERROR_BAD_DEVICE The value specified by lpLocalName is invalid.

ERROR_BAD_NET_NAME The value specified by the lpRemoteName member is not

acceptable to any network resource provider because the
resource name is invalid, or because the named resource
cannot be located.

ERROR_BAD_PROVIDER The value specified by the lpProvider member does not

match any provider.

ERROR_CANCELLED The attempt to make the connection was canceled by the

user through a dialog box from one of the network
resource providers, or by a called resource.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_INVALID_ADDRESS The caller passed in a pointer to a buffer that could not

be accessed.

ERROR_INVALID_PARAMETER This error is a result of one of the following conditions:

1. The lpRemoteName member is NULL. In addition,

lpAccessName is not NULL, but lpBufferSize is either
NULL or points to zero.
2. The dwType member is neither
RESOURCETYPE_DISK nor RESOURCETYPE_PRINT.
In addition, either CONNECT_REDIRECT is set in
dwFlags and lpLocalName is NULL, or the
connection is to a network that requires the
redirecting of a local device.

ERROR_INVALID_PASSWORD The specified password is invalid and the

CONNECT_INTERACTIVE flag is not set.

ERROR_MORE_DATA The lpAccessName buffer is too small.

If a local device is redirected, the buffer needs to be large

enough to contain the local device name. Otherwise, the
buffer needs to be large enough to contain either the
string pointed to by lpRemoteName, or the name of the
connectable resource whose alias is pointed to by
lpRemoteName. If this error is returned, then no
connection has been made.

ERROR_NO_MORE_ITEMS The operating system cannot automatically choose a local

 redirection because all the valid local devices are in use.

ERROR_NO_NET_OR_BAD_PATH The operation could not be completed, either because a

network component is not started, or because the
specified resource name is not recognized.

ERROR_NO_NETWORK The network is unavailable.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

７ Note

The winnetwk.h header defines WNetUseConnection as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions

WnetCancelConnection
WNetUseConnectionW function
(winnetwk.h)
Article • 02/09/20239 minutes to read

The
WNetUseConnection function makes a connection to a network resource. The
function can redirect a local device to a network resource.

The
WNetUseConnection function is similar to the
WNetAddConnection3 function. The
main difference is that
WNetUseConnection can automatically select an unused local
device to redirect to the network resource.

Syntax
C++

DWORD WNetUseConnectionW(

[in] HWND hwndOwner,

[in] LPNETRESOURCEW lpNetResource,

[in] LPCWSTR lpPassword,

[in] LPCWSTR lpUserId,

[in] DWORD dwFlags,

[out] LPWSTR lpAccessName,

[in, out] LPDWORD lpBufferSize,

[out] LPDWORD lpResult

);

Parameters
[in] hwndOwner

Handle to a window that the provider of network resources can use as an owner window
for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE value in the
dwFlags parameter.

[in] lpNetResource

Pointer to a
NETRESOURCE structure that specifies details of the proposed connection.
The structure contains information about the network resource, the local device, and the
network resource provider.

You must specify the following members of the

NETRESOURCE structure.
 Member Meaning

dwType Specifies the type of resource to connect to.

It is most efficient to specify a resource type in this
member, such as RESOURCETYPE_DISK or
RESOURCETYPE_PRINT. However, if the lpLocalName
member is NULL, or if it points to an empty string and
CONNECT_REDIRECT is not set, dwType can be
RESOURCETYPE_ANY.

This method works only if the function does not

automatically choose a device to redirect to the network
resource.

Although this member is required, its information may be

ignored by the network service provider.

lpLocalName Pointer to a 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 empty, or if lpLocalName is NULL, a

connection to the network occurs without redirection.

If the CONNECT_REDIRECT value is set in the dwFlags

parameter, or if the network requires a redirected local
device, the function chooses a local device to redirect and
returns the name of the device in the lpAccessName
parameter.

lpRemoteName 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, and it must follow the
network provider's naming conventions.

lpProvider Pointer to a null-terminated string that specifies the

network provider to connect to. If lpProvider is NULL, or
if it points to an empty string, the operating system
attempts to determine the correct provider by parsing
the string pointed to by the lpRemoteName member.

If this member is not NULL, the operating system

attempts to make a connection only to the named
network provider.

You should set this member only if you know the network
provider you want to use. Otherwise, let the operating
system determine which provider the network name
maps to.

 
The
WNetUseConnection function ignores the other members of the
NETRESOURCE
structure. For more information, see the descriptions following for the dwFlags
parameter.

[in] lpPassword

Pointer to a constant 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 lpUserID.

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

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE

value is set in the dwFlags parameter, the function displays a dialog box asking the user
to type the password.

[in] lpUserId

Pointer to a constant null-terminated string that specifies a user name for making the
connection.

If lpUserID is NULL, the function uses the default user name. (The user context for the
process provides the default user name.)

The lpUserID 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.

The user-name string represents a

security context. It may be specific to a network
provider.

[in] dwFlags

Set of bit flags describing the connection. This parameter can be any combination of the
following values.

Value Meaning

CONNECT_INTERACTIVE If this flag is set, the operating system may interact with
the user for authentication purposes.

CONNECT_PROMPT This flag instructs the system not to use any default
settings for user names or passwords without offering the
user the opportunity to supply an alternative. This flag is
ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_REDIRECT This flag forces the redirection of a local device when
making the connection.
If the lpLocalName member of
NETRESOURCE specifies a
local device to redirect, this flag has no effect, because
the operating system still attempts to redirect the
specified device. When the operating system
automatically chooses a local device, the dwType
member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically

chosen for redirection only if the network requires a local
device to be redirected.

Windows XP:  When the system automatically assigns

network drive letters, letters are assigned beginning with
Z:, then Y:, and ending with C:. This reduces collision
between per-logon drive letters (such as network drive
letters) and global drive letters (such as disk drives). Note
that previous releases assigned drive letters beginning
with C: and ending with Z:.

CONNECT_UPDATE_PROFILE This flag instructs the operating system to store the

network resource connection.
If this bit flag is set, the operating system automatically
attempts to restore the connection when the user logs
on. The system remembers only successful connections
that redirect local devices. It does not remember
connections that are unsuccessful or deviceless
connections. (A deviceless connection occurs when
lpLocalName is NULL or when it points to an empty
string.)

If this bit flag is clear, the operating system does not

automatically restore the connection at logon.

CONNECT_COMMANDLINE If this flag is set, the operating system prompts the user
for authentication using the command line instead of a
graphical user interface (GUI). This flag is ignored unless
CONNECT_INTERACTIVE is also set.
Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

CONNECT_CMD_SAVECRED If this flag is set, and the operating system prompts for a
credential, the credential should be saved by the
credential manager. If the credential manager is disabled
for the caller's logon session, or if the network provider
does not support saving credentials, this flag is ignored.
This flag is also ignored unless you set the
CONNECT_COMMANDLINE flag.
 Windows 2000/NT and Windows Me/98/95:  This value
is not supported.

[out] lpAccessName

Pointer to a buffer that receives system requests on the connection. This parameter can
be NULL.

If this parameter is specified, and the lpLocalName member of the

NETRESOURCE
structure specifies a local device, this buffer receives the local device name. If
lpLocalName does not specify a device and the network requires a local device
redirection, or if the CONNECT_REDIRECT value is set, this buffer receives the name of
the redirected local device.

Otherwise, the name copied into the buffer is that of a remote resource. If specified, this
buffer must be at least as large as the string pointed to by the lpRemoteName member.

[in, out] lpBufferSize

Pointer to a variable that specifies the size of the lpAccessName buffer, in characters. If
the call fails because the buffer is not large enough, the function returns the required
buffer size in this location. For more information, see the descriptions of the
lpAccessName parameter and the ERROR_MORE_DATA error code in the Return Values
section.

[out] lpResult

Pointer to a variable that receives additional information about the connection. This
parameter can be the following value.

Value Meaning

CONNECT_LOCALDRIVE If this flag is set, the connection was made using a local
device redirection. If the lpAccessName parameter points
to a buffer, the local device name is copied to the buffer.

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 local device specified by the lpLocalName member is

already connected to a network resource.

ERROR_BAD_DEVICE The value specified by lpLocalName is invalid.

ERROR_BAD_NET_NAME The value specified by the lpRemoteName member is not

acceptable to any network resource provider because the
resource name is invalid, or because the named resource
cannot be located.

ERROR_BAD_PROVIDER The value specified by the lpProvider member does not

match any provider.

ERROR_CANCELLED The attempt to make the connection was canceled by the

user through a dialog box from one of the network
resource providers, or by a called resource.

ERROR_EXTENDED_ERROR A network-specific error occurred. To obtain a description

of the error, call the WNetGetLastError function.

ERROR_INVALID_ADDRESS The caller passed in a pointer to a buffer that could not

be accessed.

ERROR_INVALID_PARAMETER This error is a result of one of the following conditions:

1. The lpRemoteName member is NULL. In addition,

lpAccessName is not NULL, but lpBufferSize is either
NULL or points to zero.
2. The dwType member is neither
RESOURCETYPE_DISK nor RESOURCETYPE_PRINT.
In addition, either CONNECT_REDIRECT is set in
dwFlags and lpLocalName is NULL, or the
connection is to a network that requires the
redirecting of a local device.

ERROR_INVALID_PASSWORD The specified password is invalid and the

CONNECT_INTERACTIVE flag is not set.

ERROR_MORE_DATA The lpAccessName buffer is too small.

If a local device is redirected, the buffer needs to be large

enough to contain the local device name. Otherwise, the
buffer needs to be large enough to contain either the
string pointed to by lpRemoteName, or the name of the
connectable resource whose alias is pointed to by
lpRemoteName. If this error is returned, then no
connection has been made.

ERROR_NO_MORE_ITEMS The operating system cannot automatically choose a local

 redirection because all the valid local devices are in use.

ERROR_NO_NET_OR_BAD_PATH The operation could not be completed, either because a

network component is not started, or because the
specified resource name is not recognized.

ERROR_NO_NETWORK The network is unavailable.

Remarks
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. (An AuthenticationID is the
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. GetLogicalDrives
does not return network drive letters created by a WNet function 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.

７ Note

The winnetwk.h header defines WNetUseConnection as an alias which

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 not encoding-neutral can lead to mismatches that
result in compilation or runtime errors. For more information, see Conventions for
Function Prototypes.

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

WNetGetConnection

Windows
Networking (WNet) Overview

Windows
Networking Functions

WnetCancelConnection