NetUseAdd function (lmuse.h)
The NetUseAdd function establishes a connection between the local computer and a remote server. You can specify a local drive letter or a printer device to connect. If you do not specify a local drive letter or printer device, the function authenticates the client with the server for future connections.
Syntax
NET_API_STATUS NET_API_FUNCTION NetUseAdd(
[in] LPTSTR servername,
[in] DWORD LevelFlags,
[in] LPBYTE buf,
[out] LPDWORD parm_err
);
Parameters
[in] servername
The UNC name of the computer on which to execute this function. If this parameter is NULL, then the local computer is used. If the UncServerName parameter specified is a remote computer, then the remote computer must support remote RPC calls using the legacy Remote Access Protocol mechanism.
This string is Unicode if _WIN32_WINNT or FORCE_UNICODE are defined.
[in] LevelFlags
A value that specifies the information level of the data. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
|
Specifies information about the connection between a local device and a shared resource. Information includes the connection status and type. The Buf parameter is a pointer to a USE_INFO_1 structure. |
|
Specifies information about the connection between a local device and a shared resource. Information includes the connection status and type, and a user name and domain name. The Buf parameter is a pointer to a USE_INFO_2 structure. |
[in] buf
A pointer to the buffer that specifies the data. The format of this data depends on the value of the Level parameter. For more information, see Network Management Function Buffers.
[out] parm_err
A pointer to a value that receives the index of the first member of the information structure in error when the ERROR_INVALID_PARAMETER error is returned. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.
Return value
If the function succeeds, the return value is NERR_Success.
If the function fails, the return value is a system error code. For a list of error codes, see System Error Codes.
Remarks
You can also use the WNetAddConnection2 and WNetAddConnection3 functions to redirect a local device to a network resource.
No special group membership is required to call the NetUseAdd function. This function cannot be executed on a remote server except in cases of downlevel compatibility.
This function applies only to the Server Message Block (LAN Manager Workstation) client. The NetUseAdd function does not support Distributed File System (DFS) shares. To add a share using a different network provider (WebDAV or a DFS share, for example), use the WNetAddConnection2 or WNetAddConnection3 function.
If the NetUseAdd function returns ERROR_INVALID_PARAMETER, you can use the ParmError parameter to indicate the first member of the information structure that is invalid. (The information structure begins with USE_INFO_ and its format is specified by the Level parameter.) The following table lists the values that can be returned in the ParmError parameter and the corresponding structure member that is in error. (The prefix ui*_ indicates that the member can begin with multiple prefixes, for example, ui1_ or ui2_.)
| Constant | Value | Member |
|---|---|---|
| USE_LOCAL_PARMNUM | 1 | ui*_local |
| USE_REMOTE_PARMNUM | 2 | ui*_remote |
| USE_PASSWORD_PARMNUM | 3 | ui*_password |
| USE_ASGTYPE_PARMNUM | 4 | ui*_asg_type |
| USE_USERNAME_PARMNUM | 5 | ui*_username |
| USE_DOMAINNAME_PARMNUM | 6 | ui*_domainname |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | lmuse.h (include Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |