WNetUseConnection

This function is used to establish a connection to a network object, especially for browsing . The function may optionally prompt the user for login or authentication. The connection is usually on a redirected local drive or a reference counted session (in which case this call increments the reference count to the session), although for some networks it may be on a non-reference counted session that does not have a local device redirection. See WNetCancelConnection2 for details on cancelling the connection

In addition, for file and disk resources, this API can return a name for the connection that can be pre-pended to file system requests on the network resource (e.g. "\\server\share" or "F:"). This enables directory service lookup. The API can also auto-pick a local device for redirecting local devices to networks that require local device redirection. 

DWORD WNetUseConnection(
    HWND hwndOwner,
    LPNETRESOURCE lpNetResource,
    LPTSTR lpPassword,
    LPTSTR lpUserID,
    DWORD dwFlags,
    LPTSTR lpAccessName,
    LPDWORD lpBufferSize,
    LPDWORD lpResult
    );
hwndOwner
A handle to a window which should be the owner for any messages or dialogs the network provider might display. This is used if CONNECT_INTERACTIVE is set.
lpNetResource
Specifies the network resource to connect to. This structure is defined the section describing Enumeration APIs. The following fields must be set when making a connection, the others are ignored.
lpRemoteName Specifies the network resource to connect to.
lpLocalName Pointer to a buffer that specifies the local device name that is to be redirected, such as "F:" or "LPT1".
  The string is treated in a case insensitive manner, and may be the empty string (or NULL) in which case either a connection to the network resource is made without making a redirection or, if CONNECT_REDIRECT is set or the network requires a redirected local device and none is specified a redirection is picked by the system which is returned in lpAccessName.
lpProvider Specifies the NP to connect to. If NULL or empty string, Windows will try each NP in turn. The caller should set lpProvider only if it knows for sure which network it wants. Otherwise, it is preferable to let Windows determine which NP the network name maps to. If this is non NULL, Windows will try the named NP and no other.
dwType Specifies the type of resource to connect to. It is most efficient to use a specific resource type (RESOURCETYPE_DISK or RESOURCETYPE_PRINT). It may be RESOURCETYPE_ANY if lpLocalName is the empty string and CONNECT_REDIRECT is not set.

lpPassword
Specifies the password to be used in making the connection, normally the password associated with lpUserID. A NULL value or string may be passed in to not specify the password. If the password is invalid or not specified, then the function tries to use the current default password. If this fails and CONNECT_INTERACTIVE is set, the function posts an appropriate dialog asking the user to type/retype the password.
lpUserID
This specifies the identity of the user needed to make the connection. If NULL, a default will be applied. This is used when the user wishes to connect to a resource, but has a different user name or account assigned to him for that resource. This identification represents a security context, and is NP specific.

This user specific information is stored to be subsequently used in re-establishing the connection (using a non-default username or telephone number, for example).

dwFlags
Any combination of the following bit values:
CONNECT_TEMPORARY The connection is being established for browsing purposes.
CONNECT_INTERACTIVE May have interaction with the user for authentication purposes.
CONNECT_PROMPT Do no use any defaults for usernames or passwords without offering user the chance to supply an alternative. This flag is only valid if CONNECT_INTERACTIVE is set.
CONNECT_UPDATE_PROFILE If the connection should be made persistent. If set, the connection is automatically restored every time the user starts up and logs on to the network. A connection is only made persistent if the connection was successful. This flag is only valid if lpLocalName specifies a local device to redirect, as otherwise it is ignored.
CONNECT_UPDATE_RECENT If the connection should be put in the recent connection list. If set, and the connection is successfully added, it will be put in the recent connection list only if it has a redirected local device associated with it.
CONNECT_REDIRECT If set, force the auto-picking of a local device for redirection when making the connection, otherwise only auto-pick a local device for redirection if the network requires it to make a connection.
  This flag is ignored if lpLocalName specifies a local device to redirect (since a redirection will always be attempted to the local device name specified in lpLocalName). Otherwise, setting this flag is invalid if either lpAccessName does not point to a return buffer (since the caller will not readily know how to access the resource) or dwType is RESOURCETYPE_ANY.
CONNECT_CURRENT_MEDIA If set, then do not start to use a new media to try to establish the connection (for example, do not initiate a new dial up connection).

lpAccessName
Points to a buffer to receive the name that can be used to make system requests on the connection. This conversion is useful for adding connections to aliased resources, such as through a directory service, and for autopicking of local devices for redirection.

If lpLocalName specifies a local device, then this buffer is optional, and if specified will have the local device name copied into it.Otherwise, if the network requires a local device redirection, or CONNECT_REDIRECT is set, then this buffer is required and the redirected local device is returned here. Otherwise, the name copied into the buffer is that of a remote resource, and if specified, this buffer must be at least as large as the string pointed to by lpRemoteName.

lpBufferSize
This is used to specify the size of the lpAccessName buffer passed in. If the call fails because the buffer is not big enough, this location will be used to return the required buffer size.
lpResult
Pointer to a DWORD in which is returned additional information about the connection. Currently has the following bit value:
CONNECT_REFCOUNT The connection was made without using a local device redirection and is to a network that understands reference counted sessions. If this bit is not set, then calling WNetCancelConnection2 will end the session and possibly interfere with other threads or processes that may be using the session. If this bit is set then calling WNetCancelConnection2 with CONNECT_REFCOUNT set in the dwFlags parameter will decrement the reference count to the connection and not interfere with other threads that are using the session.
CONNECT_LOCALDRIVE If set, the connection was made using a local drive redirection. If lpAccessName points to a buffer then the local drive is copied to the buffer.

WN_CANCEL the user cancelled the add connection attempt through some user interface.
WN_BAD_PROVIDER lpProvider does not match any NP.
WN_BAD_NETNAME lpRemoteName is not acceptable to any NP.
WN_BAD_LOCALNAME lpLocalName is invalid.
WN_BAD_PASSWORD bad password and CONNECT_INTERACTIVE is not set.
WN_BAD_VALUE one of the following: lpRemoteName is NULL; lpRemoteName is not NULL, and lpBufferSize is either NULL or points to zero; dwType is neither RESOURCETYPE_DISK nor RESOURCETYPE_PRINT, and either CONNECT_REDIRECT is set in dwFlags or lpLocalName is not NULL or the connection is to a network that requires a local device redirection to make a connection;
WN_BAD_POINTER lpAccessName does not point to a buffer and either CONNECT_REDIRECT is set in dwFlags or a connection is being attempted to a network that requires a local device redirection which is not specified in lpLocalName.
WN_MORE_DATA the lpAccessName buffer is too small. If a local device is redirected, the buffer needs to large enough to contain the local device name. Otherwise the buffer needs to be large enough to contain either the string pointed to by lpRemoteName or the name of the connectable resource whose alias is pointed to by lpRemoteName. If this status is returned, then no connection has been made.
WN_NO_MORE_ENTRIES a local redirection cannot be auto-picked because all of the valid local devices for the network are in use.
WN_NOT_AUTHENTICATED the call failed because the connection requires additional authentication information (e.g., a username or a password), not provided by the caller or the user through a dialog.
WN_NOT_LOGGED_ON a system logon needs to occur before a network connection can be added.
WN_ALREADY_CONNECTED lpLocalName is already connected to a network drive or is to a local drive that is already in use locally (e.g. is used for a hard drive or RAM drive).
WN_ACCESS_DENIED access denied.
WN_CANNOT_OPEN_PROFILE Unable to open the user profile to process persistent connections.
WN_BAD_PROFILE The user profile is in an incorrect format.
WN_FUNCTION_BUSY The MPR or NP is busy (possibly initializing). The caller should retry.
WN_NO_NETWORK network is not present.
WN_NO_NET_OR_BAD_PATH the operation could not be handled either because a network component is not started or the specified name could not be handled.
WN_EXTENDED_ERROR a network specific error occurred. WNetGetLastError should be called to obtain a description of the error.

See Also

WNetCancelConnection2