WNetGetConnectionA function (winnetwk.h)

Article
02/09/2023

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

Syntax

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 that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

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

Share via