The functions in the Replication category control the Directory Replicator service
|
Function |
Description |
|
Registers an existing directory in the export path to be replicated. |
|
|
Deregisters a replicated directory. |
|
|
Lists the replicated directories in the export path. |
|
|
Retrieves a replicated directory’s control information. |
|
|
Locks a replicated directory so that replication from it can be suspended. |
|
|
Modifies the control information of a replicated directory. |
|
|
Unlocks a directory so that replication from it can resume. |
|
|
Retrieves the Directory Replicator service configuration information. |
|
|
Registers an existing directory in the import path to receive replication from a master. |
|
|
Deregisters a directory so that it no longer receives updates from the master. |
|
|
Lists the replicated directories in the import path. |
|
|
Retrieves the status information on a client replicated directory. |
|
|
Locks a replicated directory so that replication to it can be suspended. |
|
|
Unlocks a directory so that replication to it can resume. |
|
|
Modifies the Directory Replicator service configuration information. |
The Replicator Export Directory APIs control top-level directories under the export path on the master. A user can create a new directory under the export path and the Directory Replicator service will automatically replicate that directory. Or, a directory under the export path can be registered using NetReplExportDirAdd.
When adding a directory to be replicated via these APIs, the replication controls (integrity and extent) are specified via NetReplExportDirAdd. If the directory is created in the file system and no replication APIs are called, then the directory is treated as having file integrity and tree extent.
Integrity determines when a master updates a client. When integrity is REPL_INTEGRITY_FILE, the client gets a replica of a file within the directory when it is not in use (being changed or replicated). When integrity is set to REPL_INTEGRITY_TREE, every file and directory within the replicated directory must be stable for the amount of time specified by the guardtime parameter before the client is updated.
Extent determines whether the entire tree within the directory is replicated (REPL_EXTENT_TREE) or only the files in the first-level directory is replicated (REPL_EXTENT_FILE). The replication controls of replicated directories can be examined with NetReplExportDirGetInfo and dynamically modified using NetReplExportDirSetInfo. These control fields used to be specified in the repl.ini file within each replicated directory in LAN Manager 2.x, and were not dynamically settable.
NetReplExportDirEnum returns a list of directories that currently are replicated.
NetReplExportDirDel deregisters a directory so that it no longer is replicated.The lock status information is returned in two fields: lockcount and locktime. The lockcount field indicates the number of outstanding locks on a directory. The locktime field is the time (in seconds since 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.
NetReplExportDirLock locks a directory so that it is not replicated, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplExportDirUnlock. The replication does not resume unless all outstanding locks on that directory are released, and the lock reference count is returned to 0. (The locktime field is automatically set to 0 when lockcount is 0.)
The Replicator Export Directory APIs can be called whether or not the Directory Replicator service is running. If the Directory Replicator service is running as a master, any modification to the directory controls takes effect immediately and are persistent after the Directory Replicator service has been stopped. If the Directory Replicator service is not started, the controls for the directory are stored as persistent information and take effect when the Directory Replicator service starts.
The Replicator Import Directory APIs designate the top-level directories under the import path to receive updates on. They also return status information about a replicated directory on the client.
NetReplImportDirAdd registers an import directory in advance of it being exported. This API does not create the directory itself. This is useful if you wish to modify some of the properties of the import directory (for example, to lock it) prior to it first beginning to import this directory.
NetReplImportDirDel deregisters a directory. This is used to clean up a directory that is no longer being exported. It will not stop replication if there is an active exporter, since it will be re-registered the next time the exporter tells the importer what directories it is exporting. To prevent import of an actively exported directory, use NetReplImportDirLock.
NetReplImportDirEnum lists all the directories that are replicated to a client; NetReplImportDirGetInfo returns the status of a directory.
The status information of a directory consists of its replication state, the UNC computer name of the master (mastername), and the time (in seconds since 1970, GMT) when the directory last was updated (last_update_time).
If the state is REPL_STATE_OK, the directory currently has a master, and is receiving regular update notices from it. If the state is REPL_STATE_NO_MASTER, the directory is not supported by any master, and it is normally empty.
If the state is REPL_STATE_NO_SYNC, the directory has a master, but the master has not sent any update notices within the interval time period. This may be due to a communication failure, the master crashing, the directory being locked, files in the client directory being opened at update time or an unstable REPL_INTEGRITY_TREE integrity directory on the master.
If the client Directory Replicator service is not started the state is REPL_STATE_NEVER_REPLICATED, mastername is a NULL string, and last_update_time is 0.
NetReplImportDirLock locks a directory so that it does not receive updates, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplImportDirUnlock. The directory is not updated unless all outstanding locks on that directory are released, and the lock reference count is returned to 0.
The lock status information is returned in two fields: lockcount and locktime. The lockcount field indicates the number of outstanding locks on a directory. The locktime is the time (in seconds since 1970, GMT) when the directory was first locked. (locktime is set to 0 whenever lockcount goes to 0.) The Replicator Import Directory APIs can be called whether or not the Directory Replicator service is running.
If the Directory Replicator service is running as a client, directory adds or deletes take effect immediately and is persistent after the Directory Replicator service has been stopped.
If the Directory Replicator service is not started, any added directory will receive updates when the Directory Replicator service starts up (if there exists a master which exports the directory).
The configuration parameters of the Directory Replicator service can be examined using NetReplGetInfo. They can be modified using NetReplSetInfo.
The configuration parameters (except the importpath and 0) values are all dynamically settable.
These APIs can be called whether or not the Directory Replicator service is running. If the Directory Replicator service is already running, any modification (except to the importpath and exportpath) to the replication configuration takes effect immediately, and is persistent after the Replicator service has been stopped.
If the Directory Replicator service is not started, the parameters are stored as persistent information and will take effect when the Directory Replicator service starts. The service must be stopped to set the importpath and exportpath values.
The level parameter controls the level of information provided to or returned from NetReplExportDirAdd, NetReplExportDirEnum, NetReplExportDirGetInfo and NetReplExportDir. These functions use a level 1 data structure.
Additionally, NetReplExportDirEnum and NetReplExportDirGetInfo can use level 0 or 2 data structures, and NetReplExportDirSetInfo can use level 1000 or level 1001 data structure.
The REPL_EDIR_INFO_0 data structure has the following format:
typedef struct _REPL_EDIR_INFO_0 {
LPTSTR rped0_dirname;
} REPL_EDIR_INFO_0, *PREPL_EDIR_INFO_0, *LPREPL_EDIR_INFO_0;
Within this structure, rped0_dirname points to ASCIIZ string specifying an export directory name.
The REPL_EDIR_INFO_1 data structure has the following format:
typedef struct _REPL_EDIR_INFO_1 {
LPTSTR rped1_dirname;
DWORD rped1_integrity;
DWORD rped1_extent;
} REPL_EDIR_INFO_1, *PREPL_EDIR_INFO_1, *LPREPL_EDIR_INFO_1;
Within this structure, rped1_dirname points to ASCIIZ string specifying an export directory name.
rped1_integrity specifies when a master updates a client.
The value of rped1_integrity is defined in the unixapi.h file as follows:
|
Manifest |
Value |
Meaning |
|
REPL_INTEGRITY_FILE |
1 |
The client gets a replica of a file within the directory when it is not in use (being changed or replicated). |
|
REPL_INTEGRITY_TREE |
2 |
Every file and directory within the replicated directory must be stable for the amount of time specified by the guardtime parameter before the client is updated. |
rped1_extent specifies the extent of the replication.
The value of rped1_extent is defined in the unixapi.h file as follows:
|
Manifest |
Value |
Meaning |
|
REPL_EXTENT_FILE |
1 |
Only the files in the first-level directory are replicated. |
|
REPL_EXTENTY_TREE |
2 |
The entire tree within the directory is replicated. |
The REPL_EDIR_INFO_2 data structure has the following format:
typedef struct _REPL_EDIR_INFO_2 {
LPTSTR rped2_dirname;
DWORD rped2_integrity;
DWORD rped2_extent;
DWORD rped2_lockcount;
DWORD rped2_locktime;
} REPL_EDIR_INFO_2, *PREPL_EDIR_INFO_2, *LPREPL_EDIR_INFO_2;
Within this structure, rped2_dirname points to ASCIIZ string specifying an export directory name.
rped2_integrity specifies when a master updates a client (for more information see rped1_integrity).
rped2_extent specifies the extent of the replication (for more information see rped1_extent).
rped2_lockcount indicates the number of outstanding locks on a directory.
rped2_locktime is the time (in seconds since 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.
The REPL_EDIR_INFO_1000 data structure has the following format:
typedef struct _REPL_EDIR_INFO_1000 {
DWORD rped1000_integrity;
} REPL_EDIR_INFO_1000, *PREPL_EDIR_INFO_1000, *LPREPL_EDIR_INFO_1000;
Within this structure, rped1000_integrity specifies when a master updates a client (for more information see rped1_integrity).
The REPL_EDIR_INFO_1001 data structure has the following format:
typedef struct _REPL_EDIR_INFO_1001 {
DWORD rped1001_extent;
} REPL_EDIR_INFO_1001, *PREPL_EDIR_INFO_1001, *LPREPL_EDIR_INFO_1001;
Within this structure, rped1001_extent specifies the extent of the replication (for more information see rped1_extent).
The Replicatior Import Directory heading data structures use the level parameter to control the level of information provided to or returned from NetReplImportDirAdd, NetReplImportDirEnum, and NetReplImportDirGetInfo. These functions use level 1 data structure. And, NetReplImportDirEnum and NetReplImportDirGetInfo also can use level 0 data structure.
The REPL_IDIR_INFO_0 data structure has the following format:
typedef struct _REPL_IDIR_INFO_0 {
LPTSTR rpid0_dirname;
} REPL_IDIR_INFO_0, *PREPL_IDIR_INFO_0, *LPREPL_IDIR_INFO_0;
Within this structure, rpid0_dirname points to ASCIIZ string specifying an import directory name.
The REPL_IDIR_INFO_1 data structure has the following format:
typedef struct _REPL_IDIR_INFO_1 {
LPTSTR pid1_dirname;
DWORD rpid1_state;
LPTSTR pid1_mastername;
DWORD rpid1_last_update_time;
DWORD rpid1_lockcount;
DWORD rpid1_locktime;
} REPL_IDIR_INFO_1, *PREPL_IDIR_INFO_1, *LPREPL_IDIR_INFO_1;
Within this structure, rpid1_dirname points to ASCIIZ string specifying an import directory name.
rpid1_state describes the replication state.
The values for rpid1_state are defined in the unixapi.h file as follows:
|
Manifest |
Value |
Meaning |
|
REPL_STATE_OK |
0 |
The directory currently has a master, and is receiving regular update notices. |
|
REPL_STATE_NO_MASTER |
1 |
The directory is not supported by any master, and it is normally empty. |
|
REPL_STATE_NO_SYNC |
2 |
The directory has a master, but the master has not sent any update notices within the interval time period. |
|
REPL_STATE_NEVER_ REPLICATED |
3 |
The Directory Replicator service is not started. |
rpid1_mastername points to ASCIIZ string containing the UNC computer name of the master.
rpid1_last_update_time is the time (in seconds since 1970, GMT) when the directory was last updated.
rpid2_lockcount indicates the number of outstanding locks on a directory.
rpid2_locktime is the time (in seconds since 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.
The level parameter controls the level of information provided to or returned from NetReplGetInfo and NetReplSetInfo. Both functions use level 0 data structure. Additionally, NetReplSetInfo can use levels 1000, 1001, 1002 and 1003 data structures.
The REPL_INFO_0 data structure has the following format:
typedef struct _REPL_INFO_0 {
DWORD rp0_role;
LPTSTR rp0_exportpath;
LPTSTR rp0_exportlist;
LPTSTR rp0_importpath;
LPTSTR rp0_importlist;
LPTSTR rp0_logonusername;
DWORD rp0_interval;
DWORD rp0_pulse;
DWORD rp0_guardtime;
DWORD rp0_random;
} REPL_INFO_0, *PREPL_INFO_0, *LPREPL_INFO_0;
Within this structure, rp0_role describes the role of the Replicator service.
The values of rp0_role are defined in the unixapi.h file as follows:
|
Manifest |
Value |
Meaning |
|
REPL_ROLE_EXPORT |
1 |
The Directory Replicator service is configured as an export (master). |
|
REPL_ROLE_IMPORT |
2 |
The Directory Replicator service is configured as an import (client). This is the only value allowed on Windows NT Workstation computers. |
|
REPL_ROLE_BOTH |
3 |
The Directory Replicator service is configured for both export and import. |
rp0_exportpath points to ASCIIZ string specifying a fully-qualified path name to the master tree in which directories are created and replicated from. This path must include the drive letter.
rp0_exportlist points to a list of machine and domain names to send update announcements to. If this list is not provided, then update announcements will be sent to the server's domain. The list entries are separated by semicolons; machine names in the list must not have leading backslashes.
rp0_importpath points to ASCIIZ string specifying a fully-qualified path name to the client tree in which directories are created to receive the replicas of the master. This path must include the drive letter.
rp0_importlist points to a list of machines and domain names to receive updates from. If this list is not provided, then update announcements are received from the server's domain. The list entries are separated by semicolons; machine names in the list must not have leading backslashes.
rp0_logonusername points to ASCIIZ string containing a user account name belonging to the replicator group which the client logs on with to read files from its master(s).
rp0_interval specifies time in minutes within which the master checks for changes in all the replicated directories.
rp0_pulse specifies time in number of intervals within which the master notifies its clients of the current replica version when no updates are necessary.
rp0_guardtime specifies time in minutes which a REPL_INTEGRITY_TREE level integrity directory must be stable before a client is allowed to update from it. (See rped1_integrity for more information).
rp0_random specifies a value in seconds sent by a master to its clients so that the clients can use the 0 random range to generate a random time to wait on before updating from the master.
The REPL_INFO_1000 data structure has the following format:
typedef struct _REPL_INFO_1000 {
DWORD rp1000_interval;
} REPL_INFO_1000, *PREPL_INFO_1000, *LPREPL_INFO_1000;
For the description of rp1000_interval, see rp0_interval.
The REPL_INFO_1001 data structure has the following format:
typedef struct _REPL_INFO_1001 {
DWORD rp1001_pulse;
} REPL_INFO_1001, *PREPL_INFO_1001, *LPREPL_INFO_1001;
For the description of rp1001_pulse, see rp0_pulse.
The REPL_INFO_1002 data structure has the following format:
typedef struct _REPL_INFO_1002 {
DWORD rp1002_guardtime;
} REPL_INFO_1002, *PREPL_INFO_1002, *LPREPL_INFO_1002;
For the description of rp1002_guardtime. see rp0_guardtime.
The REPL_INFO_1003 data structure has the following format:
typedef struct _REPL_INFO_1003 {
DWORD rp1003_random;
} REPL_INFO_1003, *PREPL_INFO_1003, *LPREPL_INFO_1003;
For the description of rp1003_random, see rp0_random.