Platform SDK: Windows Networking

WNetGetConnection

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

DWORD WNetGetConnection(
  LPCTSTR lpLocalName,  // local name
  LPTSTR lpRemoteName,  // buffer for remote name
  LPDWORD lpnLength     // buffer size
);

Parameters

lpLocalName: [in] Pointer to a constant null-terminated string that specifies the name of the local device to get the network name for.
lpRemoteName: [out] Pointer to a buffer that receives the null-terminated remote name used to make the connection.
lpnLength: [in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpRemoteName parameter. If the function fails because the buffer is not large enough, this parameter returns the required buffer size.

Return Values

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.

Value	Meaning
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

Windows NT/Windows 2000: 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.)

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.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winnetwk.h.
  Library: Use Mpr.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

WNetGetConnection

Parameters

Return Values

Remarks

Requirements

See Also