This function makes a connection to a network resource and can specify a local name for the resource.
At a Glance
| Header file: | Winnetwk.h |
| Windows CE versions: | 2.0 and later |
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 following value:
| 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 by lpRemoteName 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.