This category includes the following APIs:

Use - NetUseAdd
Use - NetUseDel
Use - NetUseEnum
Use - NetUseGetInfo

Use APIs to examine or control connections (uses) between requesters and servers. Administrative privilege is required to call them remotely. They are used with the USE.H and NETCONS.H header files.

The NetUseAdd function establishes a connection between a local computer and a resource shared on a server by redirecting a null or local device name to a shared resource on that remote server. The following types of connections can be made:

• Device name connections, which only can be explicit 
  Universal naming convention (UNC) connections, which can be either explicit or implicit

  To establish an explicit device name connection, NetUseAdd redirects a local device name to the netname of a remote server resource (\\servername\netname). Once a device name connection is made, users or applications can use the remote resource by specifying the local device name.

  UNC connections can be explicit, created by the NetUseAdd function, or implicit, made by way of an OS/2 function (responsible for the connection).

  To establish an explicit UNC connection, NetUseAdd redirects a null device name to the netname of a remote server resource.

  To establish an implicit UNC connection, an application passes the netname of the resource to any one of the OS/2 functions that accept netnames (such as the DosOpen function). The UNC name is understood by the OS/2 function and a connection is made to the specified netname. All further requests on this connection require the full netname.

  Note: Connections are to be distinguished from sessions. A session is a path between a requester and a server, established the first time a requester makes a connection with one of the shared resources of the server. All further connections between the requester and the server are part of this same session until the session is ended by calling the NetSessionDel function.

  The following examples show how the three types of connections work:

  • Explicit device name connection. Assume an application redirected the local device name d: to the netname \\DEVELOP\SRCDRV by calling the NetUseAdd function as shown:

    strncpy (buf.ui1_local, "d:", 3);retcode = NetUseAdd(NULL, 1, BUF, BUFLEN);
    

    To access files on this resource, an application need only specify the redirected device name and the name of the file, as shown:

    retcode = system("type d:\\read.me");
    

  • Explicit UNC connection. Assume an application redirected a null device name to the remote resource \\DEVELOP\SRCDRV by calling the NetUseAdd function, as shown:

    strncpy (buf.ui1_local, "", 3);
    retcode = NetUseAdd(NULL, 1, BUF, BUFLEN);
    

    To display the contents of the READ.ME file on the resource \\DEVELOP\SRCDRV, an application also can specify only the name of the resource with the following command:

    retcode=system("type \\\\develop\\srcdrv\\read.me");
    

    Note that this does not create a new connection to the resource, as an implicit UNC connection would if no NetUseAdd function was called.

  • Implicit UNC connection. An implicit connection is made by calling to an OS/2 function and by passing the remote netname as part of a parameter. For example, the following call to DosOpen establishes an implicit UNC connection to the remote resource \\DEVELOP\SRCDRV and opens FILE.1:

    retcode = DosOpen ("\\\\develop\\srcdrv\\file.1", ...);
    

    If the ui1_password field is set to NULL, the logon password is used to establish the first connection between a requester and a server. To establish a connection to a server on a domain where the user's password is different from that on the logon domain, the first NetUseAdd command must specify the password by which the user is defined on the server's domain. Subsequent connections to the same server will use the same password as that specified in the first NetUseAdd.

  ---

  [Back] [Next]