From e611b132f9b8abe35b362e5870b74bce94a1e58e Mon Sep 17 00:00:00 2001 From: Adam Date: Sat, 16 May 2020 20:51:50 -0700 Subject: initial commit --- public/sdk/inc/dfsapi.h | 870 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 870 insertions(+) create mode 100644 public/sdk/inc/dfsapi.h (limited to 'public/sdk/inc/dfsapi.h') diff --git a/public/sdk/inc/dfsapi.h b/public/sdk/inc/dfsapi.h new file mode 100644 index 000000000..8e3859660 --- /dev/null +++ b/public/sdk/inc/dfsapi.h @@ -0,0 +1,870 @@ +//+---------------------------------------------------------------------------- +// +// Copyright (C) 1992, Microsoft Corporation +// +// File: dfsapi.h +// +// Contents: C Callable DFS API. +// +// Classes: +// +// Functions: +// +// History: 29 Sep 92 Milans created. +// 04-Aug-93 randyd Converted/moved to common\types +// 05-Aug-93 alanw Added administration APIs +// +//----------------------------------------------------------------------------- + +#ifndef _DFS_API_ +#define _DFS_API_ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#if !defined(_DFSSYSTEM_) +#define DFSAPI DECLSPEC_IMPORT +#else +#define DFSAPI +#endif + +// +// These are the names of Win32 events that get toggled when the Dfs PKT +// changes. They are a handy way to figure out when to call the +// DfsGetActiveVolumes API. +// + +#define DFS_PKT_CHANGE_EVENT_A L"DfsPktChangeA" +#define DFS_PKT_CHANGE_EVENT_B L"DfsPktChangeB" + + +//+---------------------------------------------------------------------------- +// +// Function: DfsSetDomainInfo +// +// Synopsis: Seeds the Dfs driver with information about the domain +// name and DC addressing info to bootstrap the name resolution +// process. +// +// Arguments: [pglDomain] -- pointer to gluon describing domain/DCs +// [iConnectedDC] -- index into gluon for the DC that should +// be preferred for referrals etc. +// +// Returns: S_OK +// DFS_E_NO_MEMORY +// DFS_E_INVALID_PARAM +// DFS_E_NO_DRIVER -- if NOCAIRO or STANDALONE machine +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI DfsSetDomainInfo( + IN PDS_GLUON pglDomain, + IN USHORT iConnectedDC); + + +//+---------------------------------------------------------------------------- +// +// Function: DfsRegisterSCM +// +// Synopsis: To be called by the SCM to register BindingStrings with Dfs. +// +// Arguments: None +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI DfsRegisterSCM(void); + + +//+------------------------------------------------------------------------- +// +// Function: DfsRegisterFileService +// +// Synopsis: This function is called by a file service which is +// supporting DFS via a DFS$ share targeted at the WinDfs device. +// It registers the principal name for the file service and +// its transport addresses. +// +// Arguments: [usFsp] -- file level protocol supported by the server +// (see FSP_xxx definitions in gluon.h) +// [pwszPrincipalName] -- security principal name under which +// the server operates. +// [cTransports] -- number of transports on which the server +// is listening +// [prgTrans] -- pointer to an array of TA_ADDRESS pointers, +// giving the TDI addresses for the server. +// +// Notes: A service which supports multiple file protocols should +// issue this call once for each protocol. +// +//-------------------------------------------------------------------------- + +DFSAPI STDAPI DfsRegisterFileService ( + IN USHORT usFsp, + IN LPCWSTR pwszPrincipalName, + IN ULONG cTransports, + IN TA_ADDRESS **prgTrans ); + +//+------------------------------------------------------------------------- +// +// Function: DfsGetLocalAddress +// +// Synopsis: Returns the addressing descriptor (DS_MACHINE) for the +// local machine. This is a composite resulting from calls +// to DfsRegisterSCM and DfsRegisterFileService. +// +// Arguments: [ppdsm] -- output pointer +// +// Notes: The DS_MACHINE returned is callee-allocated. The caller must +// free it by walking the structure, freeing each sub-piece +// using CoTaskMemFree. +// +// BUGBUG: it isn't really intended that this function should +// be public. It is only for use internal to DSYS. +// +//-------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetLocalAddress ( OUT DS_MACHINE **ppdsm ); + +//+------------------------------------------------------------------------- +// +// Function: DfsGetMachineVolumeId +// +// Synopsis: Returns the volume id for the local DS volume for the +// machine on which the call is issued. This id is also +// the globally unique "DFS machine id" which appears in +// the guidMachine field of the DS_MACHINE for the machine. +// +// Arguments: [pguidMachine] -- output pointer for returned GUID +// +// Notes: +// +//-------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetMachineVolumeId ( GUID * pguidMachine ); + +//+------------------------------------------------------------------------- +// +// Function: DfsUpdateMachineVolume +// +// Synopsis: Allows DFS to transmit updated addressing information +// for the local volume to the DC. +// +// Notes: BUGBUG: this is function is intended only for the use of +// SpMgr and is not supposed to be public. +// +//-------------------------------------------------------------------------- + +DFSAPI STDAPI DfsUpdateMachineVolume ( void ); + +//+---------------------------------------------------------------------------- +// +// Function: DfsUpdateDomainKnowledge +// +// Synopsis: Takes a gluon for a new domain's DS volume. This should be +// called only on a DC else call will fail. +// +// Arguments: [pglDomain] -- gluon for the new domain's DS volume. +// [dwFlags] -- if DFS_UDK_DELETE bit is set, the domain's +// knowledge will be deleted from Dfs data structures +// +// Returns: S_OK +// +//----------------------------------------------------------------------------- + +#define DFS_UDK_DELETE 0x1 + +DFSAPI STDAPI DfsUpdateDomainKnowledge( + IN PDS_GLUON pglDomain, + IN const USHORT iConnectedDC, + IN const DWORD dwFlags); + + +//+---------------------------------------------------------------------------- +// +// Function: DfsUpdateSiteCosts +// +// Synopsis: Updates the site costs. This should be called only on a DC +// else the call will fail. Note that only sites whose +// communication costs have changed need be included in the +// list - sites whose costs have not changed since the last +// call to this API need not be included, and their costs will +// not be disturbed. Cost vectors are *not* persistent across +// boots. +// +// Arguments: [cSiteCosts] -- The number of site costs listed below. +// [rgpSiteCosts] -- The actual array of DFS_SITE_COST structs. +// +// Returns: S_OK +// +//----------------------------------------------------------------------------- + +HRESULT +DfsUpdateSiteCosts( + IN ULONG cSiteCost, + IN DFS_SITE_COST *prgSiteCost); + + +//------------------------------------------------------------------------ +// +// Function: DfsGetReplicaSpecificPath, public +// +// Synopsis: This function returns a replica specific name, given a Win32 +// path. The user has to mention the full DN of the specific +// replica which he/she wants to access. +// +// Arguments: [pwszPath] -- The Win32 path to be converted to repl specific +// eg. x:\volumes\domainrt +// \\thebese\dfs$\cairo\ds\dsdomain\volumes\domainrt +// [pwszReplName] -- The full DN of the server +// eg. \msft\redmond\bsd\test\thebes +// [ppwszReplSpecificPath] -- The Replica specific name is +// returned here. +// eg. \\thebese\org$\cairo\ds\dsdomain\volumes\domainrt +// +// Notes: The ppwszReplSpecificName is freed using CoTaskMemFree. +// One can convert a ReplSpecificPath back to a Win32 path by +// using the dual of this api, DfsPathFromReplSpecificPath, +// provided that the repl specific path does not refer to a +// downlevel replica. +// +// History: Sudk Created 3/25/94 +// Milans Updated comments 5/15/95 +// +//------------------------------------------------------------------------ + +DFSAPI STDAPI DfsGetReplicaSpecificPath( + PWSTR pwszDfsPath, + PWSTR pwszReplName, + PWSTR *ppwszReplSpecificPath +); + + +//------------------------------------------------------------------------ +// +// Function: DfsPathFromReplSpecificPath, public +// +// Synopsis: This function retrieves a Win32 Path given a replica +// specific path. The Replica specific path should refer to a +// DFS aware machine (not to a downlevel machine). Usually, +// the repl specific path is generated by the dual of this API, +// DfsGetReplicaSpecificPath. +// +// Arguments: [pwszReplSpecificPath] -- The Repl Specific path here. +// eg. \\thebes\org$\msft\volumes\domainrt +// [ppwszPath] -- The Win32 Path is returned here. +// eg. x:\volumes\domainrt +// +// Notes: Free ppwszDfsPath using CoTaskMemFree. +// +// History: Sudk Created 3/25/94 +// Milans Updated comments 5/15/95 +// +//------------------------------------------------------------------------ + +DFSAPI STDAPI DfsPathFromReplSpecificPath( + PWSTR pwszReplSpecificPath, + PWSTR *ppwszPath +); + + +//+---------------------------------------------------------------------------- +// +// Function: DfsGetActiveVolumeList, public +// +// Synopsis: The DFS design is centered around a cache which stores a map +// for the most recently accessed DFS volumes. This API will +// return the Entry Paths (as DFS_PATHs) of the volumes. +// +// Arguments: [pcVolumes] -- On successful return, number of volume entry +// paths returned. +// [pawszVolumes] -- On successful return, pointer to array of +// Volume Entry Paths. +// +// Returns: SUCCESS_SUCCESS, DFS_E_NO_MEMORY +// +// Notes: pawszVolumes must be freed by the caller via MemFree. +// The volume names will also be deleted at the same time. +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetActiveVolumeList( + OUT UINT *pcVolumes, + OUT PWSTR *pawszVolumes[] +); + + +// +// BUGBUG: This Function to be removed once transition to new model is complete. +// + + +//+---------------------------------------------------------------------------- +// +// Function: DfsEnumVolumeChildren, public +// +// Synopsis: The single logical volume rooted at DFS_ROOT_ORG presented by +// DFS is actually composed of many Dfs volumes arranged in a +// hierarchy. Given the Entry Path of a volume, this API will +// return the volume entry paths of its child volumes. +// +// The names of the volume children are given as relative +// path names from the input parent volume entry path. +// +// Arguments: [wszParent] -- Entry path of parent volume. +// [pcChildren] -- On successful return, number of children. +// [pawszChildren] -- On successful return, pointer to array of +// volume entry paths of child volumes. +// +// Returns: SUCCESS_SUCCESS, DFS_E_NO_MEMORY +// +// Notes: pawszChildren must be freed by the caller via MemFree. The +// names of the child volumes will be freed at the same time. +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI DfsEnumVolumeChildren( + IN PWSTR wszParent, + OUT UINT *pcChildren, + OUT PWSTR *pawszChildren[] +); + + +//+----------------------------------------------------------------------- +// +// Function: DfsAddLocalMachShare +// +// Synopsis: This function adds a new LocalMachShare and inits it in PKT. +// +// Arguments: [pwszPrefix] -- Prefix relative to Mach:\ for new Share. +// [pwszStorageId] -- Storage for new MachShare. +// +//------------------------------------------------------------------------ + +DFSAPI STDAPI DfsAddLocalMachShare( + PWSTR pwszPrefix, + PWSTR pwszStorageId +); + +//+----------------------------------------------------------------------- +// +// Function: DfsDeleteLocalMachShare +// +// Synopsis: This function deletes a LocalMachShare. +// +// Arguments: [pwszPrefix] -- Prefix relative to Mach:\ for Share to delete. +// +//------------------------------------------------------------------------ + +DFSAPI STDAPI DfsDeleteLocalMachShare( + PWSTR pwszPrefix +); + +//+------------------------------------------------------------------- +// +// DFS Administration API - For use with the IDfsVolume interface +// +//-------------------------------------------------------------------- + +//+-------------------------------------------------------------------------- +// +// Function: DfsGetEnumDfsVolumes, public +// +// Synopsis: This method takes an entryPath and then returns an IEnumDfsVol +// interface using which the caller can enumerate all the DFS +// volumes underneath that entryPath. +// +// Arguments: [pwszPrefix] -- Prefix to enumerate volumes underneath. +// [ppEnum] -- The Enumeration interface is returned here. +// +// Returns: +// +//--------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetEnumDfsVolumes( + LPWSTR pwszPrefix, + IEnumDfsVolumes **ppEnum +); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsCreateVolume, public +// +// Synopsis: This API creates a DFS volume in the namespace based on the +// parameters passed in. +// +// Arguments: [pwszPrefix] -- The Prefix for the new volume. +// [ulVolType] -- The Volume Type for volume to be created. +// [pReplicaInfo]--The ReplicaInfo for the first replica of volume. +// [fCreateOptions] -- The Create Options (CreateStgId etc.) +// [pwszComment] --Any comment that needs to be set on volume. +// +// Returns: +// +//--------------------------------------------------------------------------- + +DFSAPI STDAPI DfsCreateVolume( + LPWSTR pwszPrefix, + ULONG ulVolumeType, + PDFS_REPLICA_INFO pReplicaInfo, + ULONG fCreateOptions, + PWCHAR pwszComment +); + +//+-------------------------------------------------------------------------- +// +// Function: DfsGetVolumeFromPrefix, public +// +// Synopsis: This API returns an IDfsVolume interface given an EntryPath +// that identifies a volume. The IDfsVolume can then be used to +// do further operations on the volume. +// +// Arguments: [pwszPrefix] -- The Entry path that identifies volume. +// This has to be an org-based prefix +// [ppIDfsVol] -- The IDfsVOlume interface is returned here. +// +// Returns: +// +//--------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetVolumeFromPrefix( + LPWSTR pwszPrefix, + IDfsVolume **ppIDfsVol); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsRenamePath, public +// +// Synopsis: This is the function to be used to rename a directory which +// falls along on exit point on some volume. The old and new paths +// can differ only in component of their entryPaths and that is the +// last component. They should be identical otherwise. +// +// Arguments: [oldPath] -- The old path that has to be renamed. +// [newPath] -- The new name and only the last component is +// different here. +// +// Returns: +// +//--------------------------------------------------------------------------- + +DFSAPI STDAPI DfsRenamePath( + LPWSTR oldPath, + LPWSTR newPath); + + +DFSAPI STDAPI_(VOID) DfsFreeVolInfo( + PDFS_VOLUME_INFO pInfo); + +// +// FOLLOWING ARE THE COMMON PUBLIC DFS APIS +// + +//+-------------------------------------------------------------------------- +// +// Function: DfsGetPathForPrefix, public +// +// Synopsis: This API returns a Win32 path for an object in the Dfs namespace +// given the ORG relative prefix of that object in the Dfs +// namespace. +// +// Arguments: [lpPrefix] -- The Prefix for which a Win32 path is desired. +// [lpPath] -- The Win32 Path is returned here. +// [lpBufferSize] -- On entry, contains the size of lpPath in +// bytes. If DFS_E_BUFFER_TOO_SMALL is returned, this +// will be set to indicate the required buffer size, in +// bytes. +// +// Returns: [S_OK] -- If all went well. +// [DFS_E_BUFFER_TOO_SMALL] -- If the buffer passed in small. +// Required size will be in lpBufSize. +// +//--------------------------------------------------------------------------- +DFSAPI STDAPI +DfsGetPathForPrefix( + LPCWSTR lpPrefix, + LPWSTR lpPath, + LPDWORD lpBufferSize); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsGetPrefixForPath, public +// +// Synopsis: This API returns the org relative prefix given a Win32 path +// which points into the Dfs namespace. Note that the Win32 path +// can either be a drive based path or a UNC path (\\..\dfs$\..) +// +// Arguments: [lpPath] -- The Win32 Path. +// [lpPrefix] -- The org relative Prefix is returned here. +// [lpBufferSize] -- On entry, contains the size of lpPrefix in +// bytes. If DFS_E_BUFFER_TOO_SMALL is returned, this +// will be set to indicate the required buffer size, in +// bytes. +// +// Returns: [S_OK] -- If all went well. +// [DFS_E_BUFFER_TOO_SMALL] -- If the buffer passed in small. +// Required size will be in lpBufSize. +// +//--------------------------------------------------------------------------- +DFSAPI STDAPI +DfsGetPrefixForPath( + LPCWSTR lpPath, + LPWSTR lpPrefix, + LPDWORD lpBufferSize); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsGetDriveBasedPath, public +// +// Synopsis: This function takes a universal name (UNC form) and returns +// a drive based path for it - If that path is in Dfs namespace. +// +// Arguments: [lpUniversalPath] -- The universal name. +// [lpDriveBasedPath] -- The drive based path is returned here. +// [lpBufferSize] -- On entry, contains the size of +// lpDriveBasedPath in bytes. If DFS_E_BUFFER_TOO_SMALL +// is returned, this will be set to indicate the +// required buffer size, in bytes. +// +// Returns: [S_OK] -- If all went well. +// [DFS_E_BUFFER_TOO_SMALL] -- If the buffer passed in small. +// Required size will be in lpBufSize. +// [DFS_E_NOT_DFS_NAMESPACE] --If the universal path does not +// refer to Dfs namespace at all. +// [DFS_E_NO_DRIVE_MAPPING] -- In the event that there is no drive +// mapping available for this path. +// +//--------------------------------------------------------------------------- +DFSAPI STDAPI +DfsGetDriveBasedPath( + LPCWSTR lpUniversalPath, + LPWSTR lpDriveBasedPath, + LPDWORD lpBufferSize); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsPathsEqual, public +// +// Synopsis: This function compares two Win32 paths which point into the +// Dfs namespace. It returns TRUE if the two paths refer to the +// same ORG based prefix in the Dfs namespace and false if not. +// +// Arguments: [lpPath1] -- First Path +// [lpPath2] -- Second Path +// +// Returns: TRUE If paths are equal else FALSE. +// +// Note: If the two paths differ in even a L'\' character at the end +// a FALSE will be returned. +// +//--------------------------------------------------------------------------- +DFSAPI BOOLEAN +DfsPathsEqual( + LPCWSTR lpPath1, + LPCWSTR lpPath2); + + +//+-------------------------------------------------------------------------- +// +// Function: DfsFindVolumePrefix, public +// +// Synopsis: Given a Win32 path this function will return the entrypath of +// the volume on which this path lies. +// +// Arguments: [lpPath] -- The path is passed in here. +// [lpPrefix] -- The org based prefix form of the above path. +// [lpBufferSize] -- On entry, contains the size of lpPrefix in +// bytes. If DFS_E_BUFFER_TOO_SMALL is returned, this +// will be set to indicate the required buffer size, in +// bytes. +// [lpVolPrefixLen] -- The portion of the lpPrefix which forms the +// prefix of volume where the object lies. This +// is in WCHARs. +// +// Returns: [S_OK] -- If all went well. +// [DFS_E_NOT_DFS_NAMESPACE] --If the universal path does not +// refer to Dfs namespace at all. +// [DFS_E_BUFFER_TOO_SMALL] -- If the buffer passed in small. +// Required size will be in lpBufSize. +// +// Notes: Memory is allocated for returned args here. Use MemFree. +// +//--------------------------------------------------------------------------- +DFSAPI STDAPI +DfsFindVolumePrefix( + LPCWSTR lpPath, + LPWSTR lpPrefix, + LPDWORD lpBufferSize, + LPDWORD lpVolPrefixLen); + +//+-------------------------------------------------------------------------- +// +// Function: DfsFindLocalPath, public +// +// Synopsis: This function returns the local path to an object (if such +// a path exists) given the name of that object in the Dfs +// namespace. +// +// Arguments: [lpPath] -- The path is passed in here. +// [lpLocalPath] -- The local path to the same object. +// [lpBufferSize] -- On entry, contains the size of lpLocalPath +// in bytes. If DFS_E_BUFFER_TOO_SMALL is returned, this +// will be set to indicate the required buffer size, in +// bytes. +// +// Returns: [S_OK] -- If all went well. +// [DFS_E_NOT_DFS_NAMESPACE] --If the universal path does not +// refer to Dfs namespace at all. +// [DFS_E_BUFFER_TOO_SMALL] -- If the buffer passed in small. +// Required size will be in lpBufSize. +// +//--------------------------------------------------------------------------- +DFSAPI STDAPI +DfsFindLocalPath( + LPCWSTR lpPath, + LPWSTR lpLocalPath, + LPDWORD lpBufferSize); + + +//+---------------------------------------------------------------------------- +// +// Function: DfsGetHandleServerInfo, public +// +// Synopsis: Given a NT or Win32 handle to an Open file, this function +// will return the name of the server that opened the file. +// +// Arguments: [hFile] -- Handle to open file. +// [lpServerName] -- Pointer to buffer that will contain the +// server name. If the file was opened on the local +// machine, lpServerName[0] will be UNICODE_NULL (ie, +// lpServerName == L"". +// [lpcbServerName] -- On entry, size in bytes of lpServerName. +// On return, if DFS_E_BUFFER_TOO_SMALL is returned, +// this contains the size required. +// [lpReplSpecificPath] -- Pointer to buffer that will contain +// the replica specific path to the file that was +// opened. +// [lpcbReplSpecificPath] -- On entry, size in bytes of +// lpdwReplSpecificPath. On return, if +// DFS_E_BUFFER_TOO_SMALL is returned, this contains the +// size required. +// +// Returns: [S_OK] -- lpServerName has the server's name, and +// lpReplSpecifcPath has the replica specific path. +// +// [DFS_E_BUFFER_TOO_SMALL] -- Either lpServerName or +// lpReplSpecificPath is too small. +// +// [DFS_E_NOT_DFS_NAMESPACE] -- Handle is not a Dfs handle. +// +// [E_HANDLE] -- Handle is invalid, the server that opened the +// handle can no longer be reached, or some other network +// error happened. +// +// [E_OUTOFMEMORY] -- Unable to allocate enough memory for +// internal functioning. +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI +DfsGetHandleServerInfo( + IN HANDLE hFile, + IN OUT LPWSTR lpServerName, + IN OUT LPDWORD lpcbServerName, + IN OUT LPWSTR lpReplSpecificPath, + IN OUT LPDWORD lpcbReplSpecificPath); + +//+---------------------------------------------------------------------------- +// +// Function: DfsGetHandleIDs, public +// +// Synopsis: Given a Win32 or NT Handle (to a file/dir/obj), this function +// will return the domain, volume, and object ids of the +// object opened via the handle. +// +// +// Arguments: [hFile] -- [NT or Win32] Handle to the file/directory/object. +// [pDomainId] -- On successful return, these three fields +// [pVolumeId] -- contain the domain, volume and object id. +// [pObjectId] +// +// Returns: [S_OK] -- IDs returned successfully +// +// [E_HANDLE] -- Handle is invalid, is not a Dfs handle, +// the server that opened the handle can no longer be +// reached, or the underlying file system does not +// support object ids. +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI +DfsGetHandleIDs( + IN HANDLE hFile, + OUT GUID *pDomainId, + OUT GUID *pVolumeId, + OUT OBJECTID *pObjectId); + +//+---------------------------------------------------------------------------- +// +// Function: DfsGetVolumeFromID, public +// +// Synopsis: Given a domain and volume id (probably returned by +// DfsGetHandleIDs), this routine will return a Win32 name +// corresponding to the given ids. +// +// Arguments: [pDomainId] -- The domain and volume ids to "resolve". +// [pVolumeId] +// [pwszPath] -- The path is returned here. This must point to a +// valid buffer. +// [lpdwSize] -- The size, in bytes, of pwszPath. If the buffer +// is too small, then on return, this variable will +// contain the required number of bytes. +// +// +// Returns: [S_OK] -- Everything went ok, and the path is in pszPath. +// +// [DFS_E_BUFFER_TOO_SMALL] -- The provided buffer was too small; +// the required buffer size, in bytes, is returned in +// lpdwSize. +// +// [E_INVALIDARG] -- pwszPath does not point to a valid buffer. +// +// [DFS_E_NO_MAPPING] -- Either the domain id could not be +// resolved to a domain name, or the volume id did not +// correspond to an existing volume. +// +//----------------------------------------------------------------------------- + +DFSAPI STDAPI +DfsGetVolumeFromID( + IN GUID *pDomainId, + IN GUID *pVolumeId, + OUT LPWSTR pwszPath, + IN OUT LPDWORD lpdwSize); + + +// +// FOLLOWING ARE APIS FOR ACQUIRING BINDING STRINGS VIA DFS +// + +// +// Following are the values for the grfFlags argument in DfsGetBindingsFirst +// +#define DFS_ALLOW_DATAGRAM 0x01 + +// +// Following are the values for the ulReason argument in DfsGetBindingsNext +// +#define REASON_UNAVAILABLE 0x01 +#define REASON_TOOBUSY 0x02 +#define REASON_OTHER 0x04 + +//+--------------------------------------------------------------------------- +// +// Function: DfsGetBindingsFirst +// +// Synopsis: Given the name of an object, this function figures out the +// machine on which the object lies and returns an RPC binding +// handle to that machine. This will be a partial binding handle. +// If the path resolves to a replicated volume, a binding to the +// preferred replica is returned, along with a cookie which +// can be passed back into DfsGetBindingsNext (see below) to +// iterate through the other replicas. +// +// Arguments: [grfFlags] -- Flags. Currently only one value: +// +// DFS_ALLOW_DATAGRAM - indicates that the binding +// returned may be for a datagram +// transport. Otherwise, only +// connection-oriented transports +// will be considered. +// +// [pwszObjectName] -- Win32 path to the object for which +// a binding is requested. +// +// [pbh] -- The Binding Handle is returned here. See notes below. +// +// [pdwContinuation] -- Returns the continuation cookie for +// accessing alternative replicas. +// +// Returns: S_OK -- If there are other replicas and caller can call +// Close/Next APIs to get more binding handles using the +// continuation cookie. +// +// S_FALSE -- If there are no other replicas. +// +// +// Notes: If the path specified resolves to the local machine, the function +// will return S_FALSE and *pbh will be set to NULL. If the path +// resolves into DFS, the binding handle returned will be for the +// optimal compatible transport. If the path resolves to a non-DFS +// network path, a named pipe binding will be returned (along with +// S_FALSE). +// +//---------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetBindingsFirst( + DWORD grfFlags, + LPWSTR pwszObjectName, + RPC_BINDING_HANDLE *pbh, + LPDWORD pdwContinuation); + + +//+--------------------------------------------------------------------------- +// +// Function: DfsGetBindingsNext +// +// Synopsis: This function should be called only after DfsGetBindingsFirst +// has been called. If the first binding handle returned +// does not work then this function is called to see if there +// are other replicas for which a binding handle can be obtained +// +// Arguments: [dwContinuation] -- The continuation handle returned in +// DfsGetBindingsFirst API. +// [ulReason] -- The reason additional bindings are being +// requested. This is only informational to Dfs. +// [pbh] -- The binding handle for the next replica. +// +// Returns: [S_OK] -- If there are other replicas still available. +// [S_FALSE] -- If the vector returned is for last replica. +// +//---------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetBindingsNext( + DWORD dwContinuation, + ULONG ulReason, + RPC_BINDING_HANDLE *pbh); + + +//+--------------------------------------------------------------------------- +// +// Function: DfsGetBindingsClose +// +// Synopsis: This function releases the continuation pseudo-handle. This +// call should not be issued if DfsGetBindingsFirst/Next returns +// S_FALSE or an error. +// +// Arguments: [dwContinuation] -- Continuation handle returned from +// DfsGetBindingsFirst +// +// Returns: +// +//---------------------------------------------------------------------------- + +DFSAPI STDAPI DfsGetBindingsClose( + DWORD dwContinuation); + +#ifdef __cplusplus +} +#endif + +#endif -- cgit v1.2.3