Expand Minimize

NetUseAdd function

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 NetUseAdd(
  _In_   LMSTR UncServerName,
  _In_   DWORD Level,
  _In_   LPBYTE Buf,
  _Out_  LPDWORD ParmError
);

Parameters

UncServerName [in]

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.

Level [in]

A value that specifies the information level of the data. This parameter can be one of the following values.

ValueMeaning
1

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.

2

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.

 

Buf [in]

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.

ParmError [out]

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_.)

ConstantValueMember
USE_LOCAL_PARMNUM1ui*_local
USE_REMOTE_PARMNUM2ui*_remote
USE_PASSWORD_PARMNUM3ui*_password
USE_ASGTYPE_PARMNUM4ui*_asg_type
USE_USERNAME_PARMNUM5ui*_username
USE_DOMAINNAME_PARMNUM6ui*_domainname

 

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Lmuse.h (include Lm.h)

Library

Netapi32.lib

DLL

Netapi32.dll

See also

NetUseDel
Network Management Overview
Network Management Functions
Use Functions
USE_INFO_1
USE_INFO_2
WNetAddConnection2
WNetAddConnection3

 

 

Community Additions

ADD
Show:
© 2014 Microsoft