dfs function calls

Luke Kenneth Casson Leighton lkcl at switchboard.net
Thu Mar 19 14:14:34 GMT 1998 

info copyright microsoft.  this info will be useful in creating the
dce/rpc calls which i believe to be on \PIPE\srvsvc, if you install DFS on
your Build 1381 SP3 NT 4.0 server.

luke

Appendix I:
Dfs Programming Interfaces
Public Interfaces
The file \public\sdk\inc\lmdfs.h is the final definition of these interfaces. There are flag and structure definitions in this file as well. However, they are reprinted here to provide a better idea of what they are. This interface applies to both the Win
dows NT 4.0 and Directory Service versions of Dfs.
NetDfsAdd 
The NetDfsAdd function either creates a new junction point, that is, a link to a server share, or adds shares to an existing junction point in a distributed file system (Dfs) tree structure.

NET_API_STATUS NET_API_FUNCTION NetDfsAdd(
   LPWSTR DfsEntryPath, 	// Dfs entry path for this added volume or storage 	
   LPWSTR ServerName, 	// Name of server exporting the storage 	
   LPWSTR 0, 	// Existing share name for the storage 	
   LPWSTR Comment, 	// Optional comment for this volume or storage 	
   DWORD Flags, 	// Zero for no flags 	
  );		

Parameters 
DfsEntryPath
[in] Points to a null-terminated Unicode character string that specifies the Universal Naming Convention (UNC) path name of a junction point in a Dfs tree structure. The string must be of the form:
Dfsname\sharename\path-to-junction-point 
where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the UNC network path name to a physical shared volume. 
ServerName 
[in] Points to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. 
ShareName 
[in] Points to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. 
Comment 
[in] Points to a null-terminated Unicode character string that contains an optional comment associated with the junction point. 
Flags 
[in] Specifies a flag value. If you set this parameter to the value DFS_ADD_VOLUME the NetDfsAdd function will fail if the junction point already exists. If you set this parameter to zero, the function either creates a new junction point if one does not e
xist, or it adds a new share to an existing junction point. 

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. See Error Codes in the Appendix for a list of error codes. 
See Also: NetDfsEnum, NetDfsRemove 
NetDfsRemove 
The NetDfsRemove function removes a server share from a junction point in a distributed file system (Dfs) tree structure. If the specified share is the last share associated with the junction point, then the NetDfsRemove function also removes the junction
 point.

NET_API_STATUS NET_API_FUNCTION NetDfsRemove(
   LPWSTR DfsEntryPath, 	// Dfs entry path for this volume or storage 	
   LPWSTR ServerName, 	// Name of server exporting the storage 	
   LPWSTR ShareName, 	// Name of share exporting the storage 	
  );		

Parameters 

DfsEntryPath 
[in] Points to a null-terminated Unicode character string that specifies the Universal Naming Convention (UNC) path name of a junction point in a Dfs tree structure. The string must be of the form: 
Dfsname\sharename\path-to-junction-point 
where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the UNC network path name to a physical shared volume. 
ServerName 
[in] Points to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. 
ShareName 
[in] Points to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. 
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. See Error Codes in the Appendix for a list of error codes.
See Also: NetDfsAdd, NetDfsEnum
NetDfsEnum 
The NetDfsEnum function enumerates all the junction points in the named distributed file system (Dfs) tree structure. The function returns information about the junction points based on the level of information specified by the Level parameter. 

NET_API_STATUS NET_API_FUNCTION NetDfsEnum(
   LPWSTR DfsName, 	// Name of the Dfs for enumeration 	
   DWORD Level, 	// Level of information requested 	
   DWORD PrefMaxLen, 	// Advisory, but -1 means "get it all" 	
   LPBYTE* Buffer, 	// API allocates and returns buffer with requested info 	
   LPDWORD EntriesRead, 	// Number of entries returned 	
   LPDWORD ResumeHandle, 	// Must be 0 on first call, reused on subsequent calls 	
  );		
	
Parameters 
DfsName 
[in] Points to a null-terminated Unicode character string that specifies the name of a Windows NT server that hosts the Dfs root volume. 
Level 
[in] Specifies the information level of the request. This parameter can be one of the following values:

 Value 	Meaning 	
  1	Return Dfs volume names. The Buffer parameter will contain an array of DFS_INFO_1 structures. 	
  2	Return Dfs volume names and volume information. The Buffer parameter will contain an array of DFS_INFO_2 structures. 	
  3	Return Dfs names, volume information, and network path information. The Buffer parameter will contain an array of DFS_INFO_3 structures. 	

PrefMaxLen 
[in] Specifies the preferred maximum number of bytes, in units of 8-bit bytes, that should be returned by this enumeration function call. 
Buffer 
[out] Points to the address of a buffer that contains the requested information structures. 
EntriesRead 
[out] Points to a DWORD that contains the actual enumerated junction point count. 
ResumeHandle 
[in/out] Points to a DWORD that contains a handle that is used to continue the enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. 
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. See Error Codes in the Appendix for a list of error codes. 
Remarks 
Call the NetDfsEnum function with the ResumeHandle parameter set to zero to begin the enumeration. To retrieve information about additional junction points, call the function with the ResumeHandle returned by the previous call to NetDfsEnum. 
The NetDfsEnum function allocates the memory required for the information structure buffer. The size of the memory can be greater than the amount specified by the PrefMaxLen parameter. 
See Also: DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_STORAGE_INFO, NetDfsAdd, NetDfsRemove 
NetDfsGetInfo 
The NetDfsGetInfo function retrieves information about a junction point in the named distributed file system (Dfs) tree structure. The function can return information specific to a server and share, or information specific to an entire junction point.

NET_API_STATUS NET_API_FUNCTION NetDfsGetInfo(
   LPWSTR DfsEntryPath, 	// Dfs entry path for the volume 	
   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, 	// API allocates and returns buffer with requested info 	
  );		

Parameters 

DfsEntryPath 
[in] Points to a null-terminated Unicode character string that specifies the Universal Naming Convention (UNC) path name of a junction point in a Dfs tree structure. The string must be of the form: 
Dfsname\sharename\path-to-junction-point 
where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the UNC network path name to a physical shared volume. 
ServerName 
[in] Points to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. This parameter is optional. See the Remarks section for additional information. 
ShareName 
[in] Points to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. This parameter is optional. See the Remarks section for additional information. 
Level 
[in] Specifies the information level of the request. This parameter can be one of the following values:

 Value 	Meaning 	
  1	Return Dfs volume names. The Buffer parameter will contain an array of DFS_INFO_1 structures. 	
  2	Return Dfs volume names and volume information. The Buffer parameter will contain an array of DFS_INFO_2 structures. 	
  3	Return Dfs names, volume information, and network path information. The Buffer parameter will contain an array of DFS_INFO_3 structures.	
 100	Return a comment about this Dfs volume or server. The Buffer parameter will contain a DFS_INFO_100 structure. 	

Buffer
[out] Points to the address of a buffer that contains the requested information structures. 
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. See Error Codes in the Appendix for a list of 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 junction po
int.
See Also: DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_INFO_100, DFS_STORAGE_INFO, NetDfsEnum 
NetDfsSetInfo 
The NetDfsSetInfo function associates information with a junction point in the named distributed file system (Dfs) tree structure. The function can set information relevant to a specific server and share, or information specific to an entire junction poin
t.

NET_API_STATUS NET_API_FUNCTION NetDfsSetInfo(
   LPWSTR DfsEntryPath, 	// Dfs entry path for the volume 	
   LPWSTR ServerName OPTIONAL, 	// Name of server exporting the storage 	
   LPWSTR ShareName OPTIONAL, 	// Name of share exporting the storage 	
   DWORD Level, 	// Level of information to be set 	
   LPBYTE Buffer, 	// Buffer holding information 	
  );		
	
Parameters 

DfsEntryPath 
[in] Points to a null-terminated Unicode character string that specifies the Universal Naming Convention (UNC) path name of a junction point in a Dfs tree structure. The string must be of the form: 
Dfsname\sharename\path-to-junction-point 
where Dfsname is the name of a Windows NT server that hosts the Dfs root volume; sharename is the name of a share that is published on the Dfs host server; and path-to-junction-point specifies the UNC network path name to a physical shared volume. 
ServerName 
[in] Points to a null-terminated Unicode character string that specifies the name of the storage server that the junction point references. This parameter is optional. See the Remarks section for additional information. 
ShareName 
[in] Points to a null-terminated Unicode character string that specifies the name of the share on the storage server that the junction point references. This parameter is optional. See the Remarks section for additional information. 
Level 
[in] Specifies the information level of the set request. This parameter can only be the following value:

 Value 	Meaning 	
  100	Return a comment about this Dfs volume or server. The Buffer parameter contains a DFS_INFO_100 structure.	

Buffer 
[in] Points to a buffer that contains the information structure. 
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. See Error Codes in the Appendix for a list of error codes. 
Remarks 
If you specify both the ServerName and ShareName parameters, the NetDfsSetInfo 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 junction po
int.
See Also: DFS_INFO_100, NetDfsEnum


Dfs API Error Codes

Value 	Meaning 	
NERR_DfsInternalCorruption (NERR_BASE+560) 	The internal database that the Dfs Service maintains is corrupt. 	
NERR_DfsVolumeDataCorrupt (NERR_BASE+561) 	One of the records in the internal database that the Dfs Service maintains is corrupt. 	
NERR_DfsNoSuchVolume (NERR_BASE+562) 	There is no volume that matches the DfsEntryPath parameter. 	
NERR_DfsVolumeAlreadyExists (NERR_BASE+563) 	A Dfs volume with the specified name already exists. 	
NERR_DfsAlreadyShared NERR_BASE+564) 	The server share specified is already shared. 	
NERR_DfsNoSuchShare (NERR_BASE+565) 	The indicated server share does not support the indicated volume. 	
NERR_DfsNotALeafVolume (NERR_BASE+566) 	The operation is not valid on a non-leaf Dfs volume. 	
NERR_DfsLeafVolume (NERR_BASE+567) 	The operation is not valid on a Dfs leaf volume. 	
NERR_DfsVolumeHasMultipleServers(NERR_BASE+568) 	The Dfs Service is unable to complete this operation because the volume has multiple servers. 	
NERR_DfsCantCreateJunctionPoint (NERR_BASE+569) 	The Dfs Service is unable to create this junction point. 	
NERR_DfsServerNotDfsAware (NERR_BASE+570) 	The server is not Dfs-aware either because Dfs server software has not been installed or because the Distributed File Service has been terminated manually. 	
NERR_DfsBadRenamePath (NERR_BASE+571) 	The specified rename target path is invalid. 	
NERR_DfsVolumeIsOffline (NERR_BASE+572) 	The specified Dfs volume is offline. 	
NERR_DfsNoSuchServer (NERR_BASE+573) 	The specified server is not a server for this Dfs volume. 	
NERR_DfsCyclicalName (NERR_BASE+574) 	A cycle in the Dfs name was detected. 	
NERR_DfsNotSupportedInServerDfs (NERR_BASE+575) 	This operation is not supported on a server-based Dfs; it is only supported on a domain-based Dfs. 	
NERR_DfsInternalError (NERR_BASE+590) 	A Dfs internal error has occurred. 	


<a href="mailto:lkcl at samba.anu.edu.au" > Luke Kenneth Casson Leighton  </a>
<a href="http://mailhost.cb1.com/~lkcl"> Samba and Network Development </a>
<a href="http://www.samba.co.uk"       > Samba and Network Consultancy </a>

More information about the samba-technical mailing list