Platform SDK: Network Management

NetDfsGetInfo

The NetDfsGetInfo function retrieves information about a Distributed File System (Dfs) link in the named Dfs root. The function can return information specific to a server and share, or information specific to an entire Dfs link.

Security Requirements

No special group membership is required to successfully execute the NetDfsGetInfo function.

NET_API_STATUS NetDfsGetInfo(
  LPWSTR DfsEntryPath,        // Dfs entry path for the Dfs link
  LPWSTR ServerName OPTIONAL, // name of server exporting the storage
  LPWSTR ShareName OPTIONAL,  // name of share exporting the storage
  DWORD Level,                // level of information requested
  LPBYTE *Buffer              // function allocates and returns 
                              //  buffer with requested info
);

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 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 host server that the Dfs link references. The string must begin with \\. This parameter is optional. For additional information, see the following Remarks section.

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. This parameter is optional. For additional information, see the following Remarks section.

Level

[in] Specifies the information level of the request. This parameter can be one of the following values.

Value	Meaning
1	Return the Dfs link name. The Buffer parameter points to a DFS_INFO_1 structure.
2	Return the Dfs link name and additional information. The Buffer parameter points to a DFS_INFO_2 structure.
3	Return Dfs link information and share information. The Buffer parameter points to a DFS_INFO_3 structure.
4	Return Dfs link information, share information, and storage-specific information. The Buffer parameter points to a DFS_INFO_4 structure.
100	Return a comment about the Dfs link. The Buffer parameter points to a DFS_INFO_100 structure.

Buffer

[out] Pointer to the address of a buffer that receives the requested information structures. The format of this data depends on the value of the Level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

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

If you specify both the ServerName and ShareName parameters, the NetDfsGetInfo function returns information specific to that server and share. If the parameters are not specified, the function returns information that is specific to the entire Dfs link.

The following code sample demonstrates how to retrieve information about a Dfs link using a call to the NetDfsGetInfo function. The sample calls NetDfsGetInfo, specifying information level 3 (DFS_INFO_3). If the call succeeds, the sample prints information about the Dfs link, including the name and status of each share referenced by the link. Finally, the code sample frees the memory allocated for the information buffer.

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

void wmain(int argc, wchar_t *argv[ ])
{
   PDFS_INFO_3 pData;
   PDFS_STORAGE_INFO ps;
   DWORD er=0, tr=0, res, j;

   LPTSTR lpszServer, lpszShare;
   //
   // Check command line arguments.
   //
   lpszShare = argc < 4 ? NULL : argv[3];
   lpszServer = argc < 3 ? NULL : argv[2];
   if (argc<2)
      wprintf(L"Syntax: %s DfsEntryPath [ServerName ShareName]\n", argv[0]);
   else
   {
      //
      // Call the NetDfsGetInfo function, specifying level 3.
      //
      res = NetDfsGetInfo(argv[1], lpszServer, lpszShare, 3, (LPBYTE *) &pData);
      //
      // If the call succeeds, print the data.
      //
      if(res==0)
      {
         printf("%-30S Storages: %u\nComment: %S\n",pData->EntryPath, pData->NumberOfStorages, pData->Comment);
         ps = pData->Storage;
         //
         // Loop through each storage.
         //
         for(j=1;j<=pData->NumberOfStorages;j++)
         {
            //
            // Print the status (Offline/Online) and the name 
            //  of each storage referenced by the Dfs link.
            //
            printf("    %S  ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"): TEXT("Online "));
            printf("\\\\%S\\%S\n",ps->ServerName,ps->ShareName);
            ps++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pData);
      }
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements