NetUseAdd or Net32UseAdd

The NetUseAdd API establishes a connection between a local or null device name and a shared resource by redirecting the local or null (UNC) device name to the shared resource.

Restrictions

This API can be called from DLS and OS/2 workstations, but DOS does not support COMx serial devices when invoking this API locally. Administrator authority is required to call this API remotely. However, no access authority is required for local execution.

 
#include <netcons.h>
#include <use.h>
 
NetUseAdd(pszServername, sLevel,
          buf, usBuflen);    /* 16 bit */
 
Net32UseAdd(pszServername, ulLevel,
          buf, ulBuflen);    /* 32 bit */

See Common Parameter Definitions for descriptions of parameters not defined here.

sLevel or ulLevel

(16-bit short or 32-bit unsigned long) must be 1, which specifies the data structure described in Use Level 1.

The following table lists the return codes most significant to this API. (See API Return Codes for a complete list of return codes.) кФФФФФФФФФФФФФФФФФФФФФФФФФФФФФТФФФФФФФТФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФПГSYMBOLICCONSTANT ГVALUEГMEANING Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_Success Г 0 Г No errors were encountered. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_ACCESS_DENIED Г 5 Г Administrator privilege is required. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_BAD_NETPATH Г 53 Г The network path cannot be found. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_NETWORK_ACCESS_DENIED Г 65 Г Network access is denied. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_BAD_DEV_TYPE Г 66 Г This network device type is incorrect. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_BAD_NET_NAME Г 67 Г This network name cannot be found. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_ALREADY_ASSIGNED Г 85 Г Duplicate redirection. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_INVALID_PASSWORD Г 86 Г The specified password is not valid. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_INVALID_PARAMETER Г 87 Г At least one parameter value is not Г
Г Г Г valid. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г ERROR_INVALID_LEVEL Г 124 Г The sLevel parameter is not valid. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_NetNotStarted Г 2102 Г The redirector NETWKSTA.200 has not Г
Г Г Г been started. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_BufTooSmall Г 2123 Г The buffer is too small for fixed- Г
Г Г Г length data. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_RemoteErr Г 2127 Г A remote API error has occurred. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_WkstaNotStarted Г 2138 Г The Requester service has not been Г
Г Г Г started. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_InternalError Г 2140 Г An internal error has occurred. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_BadTransactConfig Г 2141 Г The server is not configured for Г
Г Г Г transactions. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_UseNotFound Г 2250 Г The connection cannot be found. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_BadAsgType Г 2251 Г This asg_type is not valid. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_DeviceIsShared Г 2252 Г This device is already being shared. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_InvalidComputer Г 2351 Г The specified computer name is not Г
Г Г Г valid. Г
УФФФФФФФФФФФФФФФФФФФФФФФФФФФФФХФФФФФФФХФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФД
Г NERR_LocalDrive Г 2405 Г The drive letter is in use locally. Г
РФФФФФФФФФФФФФФФФФФФФФФФФФФФФФСФФФФФФФСФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФФй

Other codes could be returned from the following functions:

DosFsRamSemRequest
DosFsAttach
DosFsCtl
DosGetShrSeg
DosSemRequest

A local device name can be redirected to only one shared resource at a time. To establish a new direction for a redirected device, an application first must delete the existing connection by calling the NetUseDel function.

A COM or LPT device can be redirected even if it already is open. Redirecting the device has no effect on the handle of the device if it already is open. Subsequent openings, however, return a handle to the remote device to which the local device was redirected.

When a server is running user-level or share-level security, the ui1_password needed to access a shared resource can be provided in the following ways:

A string that is not NULL specifies the password.
A null pointer forces the OS/2 LAN Server software to use the same password given to the logon function.
A null string indicates that no password is provided.

NetUseAdd ignores the ui1_status, ui1_refcount, and ui1_usecount components in the use_info_1 data structure.

If a call to NetUseAdd duplicates an existing connection, the usecount component of the use_info_1 data structure is incremented and the function succeeds, returning NERR_Success.

DOS users at a local requester cannot redirect COMx serial devices with the NetUseAdd API.

For information about:

Disconnecting a device from a shared resource, see Use - NetUseDel.
Listing all devices redirected to a shared resource, see Use - NetUseEnum.

[Back]

[Next]