NetDfsAdd function (lmdfs.h)

Article
10/13/2021

Creates a new Distributed File System (DFS) link or adds targets to an existing link in a DFS namespace.

Syntax

NET_API_STATUS NET_API_FUNCTION NetDfsAdd(
  [in]           LPWSTR DfsEntryPath,
  [in]           LPWSTR ServerName,
  [in]           LPWSTR ShareName,
  [in, optional] LPWSTR Comment,
  [in]           DWORD  Flags
);

Parameters

[in] DfsEntryPath

Pointer to a string that specifies the Universal Naming Convention (UNC) path of a DFS link in a DFS namespace.

The string can be in one of two forms. The first form is as follows:

\\ServerName\DfsName\link_path

where ServerName is the name of the root target server that hosts a stand-alone DFS namespace; DfsName is the name of the DFS namespace; and link_path is a DFS link.

The second form is as follows:

\\DomainName\DomDfsname\link_path

where DomainName is the name of the domain that hosts a domain-based DFS namespace; DomDfsname is the name of the domain-based DFS namespace; and link_path is a DFS link.

This parameter is required.

[in] ServerName

Pointer to a string that specifies the link target server name. This parameter is required.

[in] ShareName

Pointer to a string that specifies the link target share name. This can also be a share name with a path relative to the share. For example, share1\mydir1\mydir2. This parameter is required.

[in, optional] Comment

Pointer to a string that specifies an optional comment associated with the DFS link. This parameter is ignored when the function adds a target to an existing link.

[in] Flags

This parameter can specify the following value, or you can specify zero for no flags.

DFS_ADD_VOLUME (0x00000001)

Create a DFS link. If the DFS link already exists, the NetDfsAdd function fails. For more information, see the Remarks section.

DFS_RESTORE_VOLUME (0x00000002)

This flag is not supported.

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

The DFS namespace must already exist. This function does not create a new DFS namespace.

The caller must have Administrator privilege on the DFS server. For more information about calling functions that require administrator privileges, see Running with Special Privileges.

Use of the DFS_ADD_VOLUME flag is optional. If you specify DFS_ADD_VOLUME and the link already exists, NetDfsAdd fails. If you do not specify DFS_ADD_VOLUME, NetDfsAdd creates the link, if required, and adds the target to the link. You should specify this value when you need to determine when new links are created.

Examples

The following code sample demonstrates how to create a new DFS link using a call to the NetDfsAdd function. Because the sample specifies the value DFS_ADD_VOLUME in the Flags parameter, the call to NetDfsAdd fails if the DFS link already exists. To add additional targets to an existing DFS link, you can specify zero in the Flags parameter.

#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>
#pragma comment(lib, "NetApi32.lib")

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res;
   LPTSTR lpszComment;
   lpszComment = argc < 5 ? NULL : argv[4];
   //
   // Check for required parameters.
   //
   if (argc < 4)
      wprintf(L"Syntax: %s DfsEntryPath ServerName ShareName [\"Comment\"]\n", argv[0]);
   else
   {
      //
      // Call the NetDfsAdd function; fail the call 
      // if the DFS link already exists (DFS_ADD_VOLUME).
         //
      // To add a second storage to a DFS link, change
      // the last parameter to 0.
      //
      res = NetDfsAdd(argv[1], argv[2], argv[3], lpszComment, DFS_ADD_VOLUME);
      //
      // If the call succeeds,
      //
      if(res == 0)
         printf("Added DFS link\n");
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	lmdfs.h (include LmDfs.h, Lm.h)
Library	NetApi32.lib
DLL	NetApi32.dll