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 Windows 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 exist, 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 point.

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 point.

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 point.

See Also: DFS_INFO_100, NetDfsEnum

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.