Share via

WNetAddConnection3

  • Article

This function makes a connection to a network resource and can specify a local name for the resource.

DWORD WNetAddConnection3(
  HWND hwndOwner, 
  LPNETRESOURCE lpNetResource, 
  LPTSTR lpPassword, 
  LPTSTR lpUserName, 
  DWORD dwFlags 
);

Parameters

  • hwndOwner
    [in] Handle to a window that the provider of network resources can use as an owner window for dialog boxes.

    The hwndOwner parameter may be NULL.

  • lpNetResource
    [in] Long pointer to a NETRESOURCE data structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

    You must specify the following members of the NETRESOURCE structure.

    Value Description
    dwType Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
    LpLocalName Long pointer to a null-terminated string that specifies the name of a local device to be redirected, such as "MyDevice" or "LocalShare". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without assigning a local name.
    LpRemoteName Long 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. The string must follow the network provider's naming conventions.
    LpProvider Long pointer the network provider to connect to. Applications should set this to NULL because the Microsoft® Windows® Network is the only provider supported.

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

  • lpPassword
    [in] Long 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 lpUserName.

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

  • lpUserName
    [in] Long pointer to a null-terminated string that specifies a user name to be used in making the connection.

    If lpUserName is NULL, the function uses the default user name. For dial-up networking connections, the default user name is the one used to establish the connection. For LAN connections, the default user name is configured in the network control panel. On systems that support a windows user interface, the user is prompted to enter logon credentials if no default credentials exist or if the logon attempt fails using the existing credentials.

    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.

  • dwFlags
    [in] Specifies connection options. It is the value shown in the following table.

    Value Description
    CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

    If this bit flag is set, the registry will store the connection information and make it available when the system reboots.

    The operating system does not remember unsuccessful connections or unnamed connections. An unnamed connection occurs when lpLocalName is NULL or points to an empty string.

Return Values

ERROR_SUCCESS indicates success. An error value indicates failure. Returning an error value provides compatibility with the behavior of the Windows for Workgroups function WNetAddConnection. You can also call the GetLastError function to obtain the same error value. Possible GetLastError values are described in the following table.

Value Description
ERROR_ACCESS_DENIED Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED The local name specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEVICE The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME The value specified bylpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BUSY The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers or by a called resource.
ERROR_DEVICE_ALREADY_REMEMBERED An entry for the device specified in lpLocalName is already in the user profile.
ERROR_INVALID_PASSWORD The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH The network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK There is no network present.

Remarks

Windows CE does not support the concept of drive-letters. An application can name a local resource "F:", but that naming convention has no special significance. The lpLocalName field of the NETRESOURCE structure can contain any string of up to 64 characters long. If the local name is NULL or empty, the resource is connected without a local name. If it is "*", the default name will be constructed as "<share> on <server>" extracted from the remote name of "\\server\share".

Except for nameless connections, the connected resource will appear as a subfolder under the Network directory. The subfolder is named after the lpLocalName string.

Windows CE supports only the "Microsoft Windows Network" provider. Persistent connections are stored in the registry and not automatically reconnected when the system is rebooted.

Requirements

OS Versions: Windows CE 2.0 and later.
Header: Winnetwk.h.
Link Library: Coredll.lib.

See Also

NETRESOURCE

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.