Platform SDK: Network Management

NetDfsAdd

The NetDfsAdd function creates a new Distributed File System (Dfs) link or adds shares to an existing link in a Dfs root.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsAdd function.

NET_API_STATUS NetDfsAdd(
  LPWSTR DfsEntryPath,   // Dfs entry path for added Dfs link
  LPWSTR ServerName,     // name of server exporting the storage
  LPWSTR ShareName,      // existing share name for the storage
  LPWSTR Comment,        // optional comment for the Dfs link
  DWORD Flags            // zero for no flags
);

Parameters

DfsEntryPath

[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string must be in one of two forms. The first form is as follows:

\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share that is published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName

[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the Dfs link references. The string must begin with \\.

ShareName

[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references.

Comment

[in] Pointer to a null-terminated Unicode character string that specifies an optional comment associated with the Dfs link.

Flags

[in] Specifies a DWORD value that contains a set of bit flags defining various options. This parameter can be one or more of the following values, or you can specify zero for no flags.

Value	Meaning
DFS_ADD_VOLUME	Fail the call to the NetDfsAdd function if the Dfs link already exists.
DFS_RESTORE_VOLUME	Do not check for the existence of specified host servers or shares when creating Dfs links. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The DFS_RESTORE_VOLUME value is intended primarily for use during restoration of a Dfs root. If you set the Flags parameter to DFS_RESTORE_VOLUME, when the Dfs service is creating Dfs links it does not verify whether the ServerName and ShareName parameters contain valid references. This is useful in the case when a server or computer that is the target of a Dfs link is offline or unavailable at the time of Dfs root restoration.

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 storage to an existing Dfs link, you can specify zero in the Flags parameter.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

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], argv[4], DFS_ADD_VOLUME);
      //
      // If the call succeeds,
      //
      if(res==0)
         printf("Added Dfs link\n");
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements