Leaked source code of windows server 2003
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

568 lines
18 KiB

  1. /*++ BUILD Version: 0001 Increment if a change has global effects
  2. Copyright (c) 1998-1999 Microsoft Corporation
  3. Module Name:
  4. frsapip.h
  5. Abstract:
  6. Header file for the application programmer's interfaces to the
  7. Microsoft File Replication Service (NtFrs).
  8. These APIs provide support for backup and restore.
  9. Environment:
  10. User Mode - Win32
  11. Notes:
  12. --*/
  13. #ifndef _FRSAPIP_H_
  14. #define _FRSAPIP_H_
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18. //
  19. // Replica set types.
  20. //
  21. #define NTFRSAPI_REPLICA_SET_TYPE_ENTERPRISE L"Enterprise"
  22. #define NTFRSAPI_REPLICA_SET_TYPE_DOMAIN L"Domain"
  23. #define NTFRSAPI_REPLICA_SET_TYPE_DFS L"DFS"
  24. #define NTFRSAPI_REPLICA_SET_TYPE_OTHER L"Other"
  25. //
  26. // BACKUP/RESTORE API
  27. //
  28. #define NTFRSAPI_BUR_FLAGS_NONE (0x00000000)
  29. #define NTFRSAPI_BUR_FLAGS_AUTHORITATIVE (0x00000001)
  30. #define NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE (0x00000002)
  31. #define NTFRSAPI_BUR_FLAGS_PRIMARY (0x00000004)
  32. #define NTFRSAPI_BUR_FLAGS_SYSTEM (0x00000008)
  33. #define NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY (0x00000010)
  34. #define NTFRSAPI_BUR_FLAGS_NORMAL (0x00000020)
  35. #define NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES (0x00000040)
  36. #define NTFRSAPI_BUR_FLAGS_RESTORE (0x00000080)
  37. #define NTFRSAPI_BUR_FLAGS_BACKUP (0x00000100)
  38. #define NTFRSAPI_BUR_FLAGS_RESTART (0x00000200)
  39. #define NTFRSAPI_BUR_FLAGS_TYPES_OF_RESTORE \
  40. (NTFRSAPI_BUR_FLAGS_AUTHORITATIVE | \
  41. NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE | \
  42. NTFRSAPI_BUR_FLAGS_PRIMARY)
  43. #define NTFRSAPI_BUR_FLAGS_MODES_OF_RESTORE \
  44. (NTFRSAPI_BUR_FLAGS_SYSTEM | \
  45. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY | \
  46. NTFRSAPI_BUR_FLAGS_NORMAL)
  47. #define NTFRSAPI_BUR_FLAGS_SUPPORTED_RESTORE \
  48. (NTFRSAPI_BUR_FLAGS_AUTHORITATIVE | \
  49. NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE | \
  50. NTFRSAPI_BUR_FLAGS_PRIMARY | \
  51. NTFRSAPI_BUR_FLAGS_SYSTEM | \
  52. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY | \
  53. NTFRSAPI_BUR_FLAGS_NORMAL | \
  54. NTFRSAPI_BUR_FLAGS_RESTORE | \
  55. NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES)
  56. #define NTFRSAPI_BUR_FLAGS_SUPPORTED_BACKUP \
  57. (NTFRSAPI_BUR_FLAGS_NORMAL | \
  58. NTFRSAPI_BUR_FLAGS_BACKUP)
  59. DWORD
  60. WINAPI
  61. NtFrsApiInitializeBackupRestore(
  62. IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG), OPTIONAL
  63. IN DWORD BurFlags,
  64. OUT PVOID *BurContext
  65. );
  66. /*++
  67. Routine Description:
  68. Called once in the lifetime of a backup/restore process. Must be
  69. matched with a subsequent call to NtFrsApiDestroyBackupRestore().
  70. Prepare the system for the backup or restore specified by BurFlags.
  71. Currently, the following combinations are supported:
  72. ASR - Automated System Recovery
  73. NTFRSAPI_BUR_FLAGS_RESTORE |
  74. NTFRSAPI_BUR_FLAGS_SYSTEM |
  75. NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
  76. NTFRSAPI_BUR_FLAGS_PRIMARY or NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE
  77. DSR - Distributed Services Restore (all sets)
  78. NTFRSAPI_BUR_FLAGS_RESTORE |
  79. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY |
  80. NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
  81. NTFRSAPI_BUR_FLAGS_PRIMARY or NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE
  82. DSR - Distributed Services Restore (just the sysvol)
  83. NTFRSAPI_BUR_FLAGS_RESTORE |
  84. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
  85. (may be followed by subsequent calls to NtFrsApiRestoringDirectory())
  86. Normal Restore - System is up and running; just restoring files
  87. NTFRSAPI_BUR_FLAGS_RESTORE |
  88. NTFRSAPI_BUR_FLAGS_NORMAL |
  89. NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
  90. NTFRSAPI_BUR_FLAGS_AUTHORITATIVE
  91. Normal Backup
  92. NTFRSAPI_BUR_FLAGS_BACKUP |
  93. NTFRSAPI_BUR_FLAGS_NORMAL
  94. Arguments:
  95. ErrorCallBack - Ignored if NULL.
  96. Address of function provided by the caller. If
  97. not NULL, this function calls back with a formatted
  98. error message and the error code that caused the
  99. error.
  100. BurFlags - See above for the supported combinations
  101. BurContext - Opaque context for this process
  102. Return Value:
  103. Win32 Status
  104. --*/
  105. DWORD
  106. WINAPI
  107. NtFrsApiDestroyBackupRestore(
  108. IN PVOID *BurContext,
  109. IN DWORD BurFlags,
  110. OUT HKEY *HKey,
  111. IN OUT DWORD *KeyPathSizeInBytes,
  112. OUT PWCHAR KeyPath
  113. );
  114. /*++
  115. Routine Description:
  116. Called once in the lifetime of a backup/restore process. Must be
  117. matched with a previous call to NtFrsApiInitializeBackupRestore().
  118. If NtFrsApiInitializeBackupRestore() was called with:
  119. NTFRSAPI_BUR_FLAGS_RESTORE |
  120. NTFRSAPI_BUR_FLAGS_SYSTEM or NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
  121. then BurFlags may be set to one of:
  122. NTFRSAPI_BUR_FLAGS_NONE - Do not restart the service. The key
  123. specified by (HKey, KeyPath) must be moved into the final
  124. registry.
  125. NTFRSAPI_BUR_FLAGS_RESTART - Restart the service. HKey,
  126. KeyPathSizeInBytes, and KeyPath must be NULL.
  127. If NtFrsApiInitializeBackupRestore() was not called the above flags,
  128. then BurFlags must be NTFRSAPI_BUR_FLAGS_NONE and HKey, KeyPathSizeInBytes,
  129. and KeyPath must be NULL.
  130. Arguments:
  131. BurContext - Returned by previous call to
  132. NtFrsApiInitializeBackupRestore().
  133. BurFlags - Backup/Restore Flags. See Routine Description.
  134. HKey - Address of a HKEY for that will be set to
  135. HKEY_LOCAL_MACHINE, ...
  136. NULL if BurContext is not for a System or
  137. Active Directory restore or Restart is set.
  138. KeyPathSizeInBytes - Address of of a DWORD specifying the size of
  139. KeyPath. Set to the actual number of bytes
  140. needed by KeyPath. ERROR_INSUFFICIENT_BUFFER
  141. is returned if the size of KeyPath is too small.
  142. NULL if BurContext is not for a System or
  143. Active Directory restore or Restart is set.
  144. KeyPath - Buffer to receive the path of the registry key.
  145. NULL if BurContext is not for a System or
  146. Active Directory restore or Restart is set.
  147. Return Value:
  148. Win32 Status
  149. --*/
  150. DWORD
  151. WINAPI
  152. NtFrsApiGetBackupRestoreSets(
  153. IN PVOID BurContext
  154. );
  155. /*++
  156. Routine Description:
  157. Cannot be called if BurContext is for a System restore.
  158. Retrieves information about the current replicated directories
  159. (AKA replica sets).
  160. Arguments:
  161. BurContext - From NtFrsApiInitializeBackupRestore()
  162. Return Value:
  163. Win32 Status
  164. --*/
  165. DWORD
  166. WINAPI
  167. NtFrsApiEnumBackupRestoreSets(
  168. IN PVOID BurContext,
  169. IN DWORD BurSetIndex,
  170. OUT PVOID *BurSet
  171. );
  172. /*++
  173. Routine Description:
  174. Returns ERROR_NO_MORE_ITEMS if BurSetIndex exceeds the number of
  175. sets returned by NtFrsApiGetBackupRestoreSets().
  176. Arguments:
  177. BurContext - From NtFrsApiInitializeBackupRestore()
  178. BurSetIndex - Index of set. Starts at 0.
  179. BurSet - Opaque struct representing a replicating directory.
  180. Return Value:
  181. Win32 Status
  182. --*/
  183. DWORD
  184. WINAPI
  185. NtFrsApiIsBackupRestoreSetASysvol(
  186. IN PVOID BurContext,
  187. IN PVOID BurSet,
  188. OUT BOOL *IsSysvol
  189. );
  190. /*++
  191. Routine Description:
  192. Does the specified BurSet represent a replicating SYSVOL share?
  193. Arguments:
  194. BurContext - From NtFrsApiInitializeBackupRestore()
  195. BurSet - Opaque struct representing a replicating directory.
  196. Returned by NtFrsApiEnumBackupRestoreSets(). Not
  197. valid across calls to NtFrsApiGetBackupRestoreSets().
  198. IsSysvol - TRUE : set is a system volume (AKA SYSVOL).
  199. FALSE: set is a not a system volume (AKA SYSVOL).
  200. Return Value:
  201. Win32 Status
  202. --*/
  203. DWORD
  204. WINAPI
  205. NtFrsApiGetBackupRestoreSetDirectory(
  206. IN PVOID BurContext,
  207. IN PVOID BurSet,
  208. IN OUT DWORD *DirectoryPathSizeInBytes,
  209. OUT PWCHAR DirectoryPath
  210. );
  211. /*++
  212. Routine Description:
  213. Return the path of the replicating directory represented by BurSet.
  214. Arguments:
  215. BurContext - From NtFrsApiInitializeBackupRestore()
  216. BurSet - Opaque struct representing a replicating directory.
  217. Returned by NtFrsApiEnumBackupRestoreSets(). Not
  218. valid across calls to NtFrsApiGetBackupRestoreSets().
  219. DirectoryPathSizeInBytes - Address of DWORD giving size of
  220. DirectoryPath. Cannot be NULL.
  221. Set to the number of bytes needed
  222. to return DirectoryPath.
  223. ERROR_INSUFFICIENT_BUFFER is returned if
  224. DirectoryPath is too small.
  225. DirectoryPath - Buffer that is *DirectoryPathSizeInBytes
  226. bytes in length. Contains path of replicating
  227. directory.
  228. Return Value:
  229. Win32 Status
  230. --*/
  231. DWORD
  232. WINAPI
  233. NtFrsApiGetBackupRestoreSetPaths(
  234. IN PVOID BurContext,
  235. IN PVOID BurSet,
  236. IN OUT DWORD *PathsSizeInBytes,
  237. OUT PWCHAR Paths,
  238. IN OUT DWORD *FiltersSizeInBytes,
  239. OUT PWCHAR Filters
  240. );
  241. /*++
  242. Routine Description:
  243. Return a multistring that contains the paths to other files
  244. and directories needed for proper operation of the replicated
  245. directory represented by BurSet. Return another multistring
  246. that details the backup filters to be applied to the paths
  247. returned by this function and the path returned by
  248. NtFrsApiGetBackupRestoreSetDirectory().
  249. The paths may overlap the replicated directory.
  250. The paths may contain nested entries.
  251. Filters is a multistring in the same format as the values for
  252. the registry key FilesNotToBackup.
  253. The replicated directory can be found with
  254. NtFrsApiGetBackupRestoreSetDirectory(). The replicated directory
  255. may overlap one or more entries in Paths.
  256. ERROR_PATH_NOT_FOUND is returned if the paths could not be
  257. determined.
  258. Arguments:
  259. BurContext - From NtFrsApiInitializeBackupRestore()
  260. BurSet - Opaque struct representing a replicating directory.
  261. Returned by NtFrsApiEnumBackupRestoreSets(). Not
  262. valid across calls to NtFrsApiGetBackupRestoreSets().
  263. PathsSizeInBytes - Address of DWORD giving size of Paths.
  264. Cannot be NULL. Set to the number of bytes
  265. needed to return Paths.
  266. ERROR_INSUFFICIENT_BUFFER is returned if
  267. Paths is too small.
  268. Paths - Buffer that is *PathsSizeInBytes
  269. bytes in length. Contains the paths of the
  270. other files and directories needed for proper
  271. operation of the replicated directory.
  272. FiltersSizeInBytes - Address of DWORD giving size of Filters.
  273. Cannot be NULL. Set to the number of bytes
  274. needed to return Filters.
  275. ERROR_INSUFFICIENT_BUFFER is returned if
  276. Filters is too small.
  277. Filters - Buffer that is *FiltersSizeInBytes bytes in
  278. length. Contains the backup filters to be
  279. applied to Paths, the contents of directories
  280. in Paths, and the replicated directory.
  281. Return Value:
  282. Win32 Status
  283. --*/
  284. DWORD
  285. WINAPI
  286. NtFrsApiRestoringDirectory(
  287. IN PVOID BurContext,
  288. IN PVOID BurSet,
  289. IN DWORD BurFlags
  290. );
  291. /*++
  292. Routine Description:
  293. The backup/restore application is about to restore the directory
  294. specified by BurSet (See NtFrsApiEnumBackupRestoreSets()). Matched
  295. with a later call to NtFrsApiFinishedRestoringDirectory().
  296. This call is supported only if NtFrsApiInitializeBackupRestore()
  297. were called with the flags:
  298. NTFRSAPI_BUR_FLAGS_RESTORE |
  299. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
  300. BurFlags can be NTFRSAPI_BUR_FLAGS_PRIMARY or
  301. NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE and overrides any value
  302. specified in the call to NtFrsApiInitializeBackupRestore().
  303. Arguments:
  304. BurContext - Opaque context from NtFrsApiInitializeBackupRestore()
  305. BurSet - Opaque set from NtFrsApiEnumBackupRestoreSets();
  306. BurFlags - See above for the supported combinations
  307. Return Value:
  308. Win32 Status
  309. --*/
  310. DWORD
  311. WINAPI
  312. NtFrsApiFinishedRestoringDirectory(
  313. IN PVOID BurContext,
  314. IN PVOID BurSet,
  315. IN DWORD BurFlags
  316. );
  317. /*++
  318. Routine Description:
  319. Finished restoring directory for BurSet. Matched by a previous call
  320. to NtFrsApiRestoringDirectory().
  321. This call is supported only if NtFrsApiInitializeBackupRestore()
  322. were called with the flags:
  323. NTFRSAPI_BUR_FLAGS_RESTORE |
  324. NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
  325. BurFlags must be NTFRSAPI_BUR_FLAGS_NONE.
  326. Arguments:
  327. BurContext - Opaque context from NtFrsApiInitializeBackupRestore()
  328. BurSet - Opaque set from NtFrsApiEnumBackupRestoreSets();
  329. BurFlags - See above for the supported combinations
  330. Return Value:
  331. Win32 Status
  332. --*/
  333. #define NTFRSAPI_MAX_INTERVAL ((((ULONG)0x7FFFFFFF) / 1000) / 60)
  334. #define NTFRSAPI_MIN_INTERVAL (1)
  335. #define NTFRSAPI_DEFAULT_LONG_INTERVAL (1 * 60) // 1 hour
  336. #define NTFRSAPI_DEFAULT_SHORT_INTERVAL (5) // 5 minutes
  337. DWORD
  338. WINAPI
  339. NtFrsApi_Set_DsPollingIntervalW(
  340. IN PWCHAR ComputerName, OPTIONAL
  341. IN ULONG UseShortInterval,
  342. IN ULONG LongInterval,
  343. IN ULONG ShortInterval
  344. );
  345. /*++
  346. Routine Description:
  347. The NtFrs service polls the DS occasionally for configuration changes.
  348. This API alters the polling interval and, if the service is not
  349. in the middle of a polling cycle, forces the service to begin a
  350. polling cycle.
  351. The service uses the long interval by default. The short interval
  352. is used after the ds configuration has been successfully
  353. retrieved and the service is now verifying that the configuration
  354. is not in flux. This API can be used to force the service to use
  355. the short interval until a stable configuration has been retrieved.
  356. After which, the service reverts back to the long interval.
  357. The default values for ShortInterval and LongInterval can be
  358. changed by setting the parameters to a non-zero value. If zero,
  359. the current values remain unchanged and a polling cycle is initiated.
  360. Arguments:
  361. ComputerName - Poke the service on this computer. The computer
  362. name can be any RPC-bindable name. Usually, the
  363. NetBIOS or DNS name works just fine. The NetBIOS
  364. name can be found with GetComputerName() or
  365. hostname. The DNS name can be found with
  366. gethostbyname() or ipconfig /all. If NULL, the
  367. service on this computer is contacted. The service
  368. is contacted using Secure RPC.
  369. UseShortInterval - If non-zero, the service switches to the short
  370. interval until a stable configuration is retrieved
  371. from the DS or another call to this API is made.
  372. Otherwise, the service uses the long interval.
  373. LongInterval - Minutes between polls of the DS. The value must fall
  374. between NTFRSAPI_MIN_INTERVAL and NTFRSAPI_MAX_INTERVAL,
  375. inclusive. If 0, the interval is unchanged.
  376. ShortInterval - Minutes between polls of the DS. The value must fall
  377. between NTFRSAPI_MIN_INTERVAL and NTFRSAPI_MAX_INTERVAL,
  378. inclusive. If 0, the interval is unchanged.
  379. Return Value:
  380. Win32 Status
  381. --*/
  382. DWORD
  383. WINAPI
  384. NtFrsApi_Get_DsPollingIntervalW(
  385. IN PWCHAR ComputerName, OPTIONAL
  386. OUT ULONG *Interval,
  387. OUT ULONG *LongInterval,
  388. OUT ULONG *ShortInterval
  389. );
  390. /*++
  391. Routine Description:
  392. The NtFrs service polls the DS occasionally for configuration changes.
  393. This API returns the values the service uses for polling intervals.
  394. The service uses the long interval by default. The short interval
  395. is used after the ds configuration has been successfully
  396. retrieved and the service is now verifying that the configuration
  397. is not in flux. The short interval is also used if the
  398. NtFrsApi_Set_DsPollingIntervalW() is used to force usage of the short
  399. interval until a stable configuration has been retrieved. After which,
  400. the service reverts back to the long interval.
  401. The value returned in Interval is the polling interval currently in
  402. use.
  403. Arguments:
  404. ComputerName - Poke the service on this computer. The computer
  405. name can be any RPC-bindable name. Usually, the
  406. NetBIOS or DNS name works just fine. The NetBIOS
  407. name can be found with GetComputerName() or
  408. hostname. The DNS name can be found with
  409. gethostbyname() or ipconfig /all. If NULL, the
  410. service on this computer is contacted. The service
  411. is contacted using Secure RPC.
  412. Interval - The current polling interval in minutes.
  413. LongInterval - The long interval in minutes.
  414. ShortInterval - The short interval in minutes.
  415. Return Value:
  416. Win32 Status
  417. --*/
  418. #ifdef __cplusplus
  419. }
  420. #endif
  421. #endif _FRSAPIP_H_