Share via

WNetAddConnection3 (Windows Embedded CE 6.0)

  • Article

1/6/2010

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

Syntax

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 lpLocalNameis NULL or points to an empty string.

Return Value

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 GetLastErrorfunction 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 bylpLocalName 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 Embedded 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 Embedded 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

Header winnetwk.h
Library coredll.lib
Windows Embedded CE Windows CE 2.0 and later

See Also

Reference

Windows Networking API/Redirector Functions
NETRESOURCE