The Win32 Network Management APIs 6

 

 

 

 

 

About Export and Import Servers

 

To replicate a set of files and directories on several computers, you must store the primary set of files and directories on a server that you designate as an export server. An export server maintains the primary files in an export directory tree with a maximum of 32 levels. Each directory can contain as many as 1000 files. Import servers are servers and workstations that receive replicated files. Import servers and workstations have import directories that correspond to the export directories. When a file changes in the export directory, the file replicator service copies the changes to the corresponding import directories on all designated import servers and workstations. The service replicates all directory and file additions and deletions to the import servers. A network can have any number of export and import servers. A server can be designated as both an export and an import server. You can configure workstations only as import servers.

 

About the File Replicator Service

 

Before using the replicator functions, check the Control Panel Services application to make sure the file replicator service is configured to log on using a specific user account. The user account must be a member of the Replicator local group, the account must not be disabled, and the account must have permission to access the import and export trees on the respective servers. For more information about the Replicator local group, see Well-Known SIDs. Changing from file system replication control in LAN Manager 2.x to replicator function control has the following implications:

 

  1. To terminate replication from a client's export server, applications can no longer delete a directory in the client's import path.
  2. To control the method of replication, applications can no longer use the REPL.INI file located in each replicated directory on the export server with the primary set of files.
  3. To control replication of a directory on the primary export server, applications can no longer create or delete USERLOCK.* files.
  4. To prevent replication on a client from a directory on the primary export server, applications can no longer create or delete USERLOCK.* files.
  5. You will need to modify applications that depend on the LAN Manager 2.x behavior of ignoring locks for file integrity trees. (The current policy differs from LAN Manager 2.x policy; the locks are always respected.)

 

Each of the options listed preceding can be specified to the file replicator service by calling the appropriate network management replicator function. Only a user or application logged on as a member of either the Administrators group or the Server Operators group can modify the parameters that control the file replicator service. This requirement applies to both local and remote export servers. You can use the file replicator service to copy relatively small directory trees. If you are attempting to replicate multi-megabyte directory trees or trees containing thousands of directories and files, you should consider some other means of doing so.

 

Replicator Configuration Functions

 

You can use the replicator configuration functions to examine and modify the configuration parameters for the file replicator service. The replicator configuration functions are listed following.

 

Function

Description

NetReplGetInfo()

Returns configuration information for the file replicator service.

NetReplSetInfo()

Modifies configuration information for the file replicator service.

 

Configuration information for the file replicator service is available at the following levels:

 

  1. REPL_INFO_0
  2. REPL_INFO_1000
  3. REPL_INFO_1001
  4. REPL_INFO_1002
  5. REPL_INFO_1003

 

Replicator Export Directory Functions

 

The replicator export directory functions control top-level directories under the export path on the primary export export server. The replicator export directory functions are listed following.

 

Function

Description

NetReplExportDirAdd()

Registers an existing directory in the export path for replication.

NetReplExportDirDel()

Removes the registration of a replicated directory.

NetReplExportDirEnum()

Lists the replicated directories in the export path.

NetReplExportDirGetInfo()

Returns the control information for a replicated directory.

NetReplExportDirLock()

Locks a directory so that replication of it can be suspended.

NetReplExportDirSetInfo()

Modifies the control information for a replicated directory.

NetReplExportDirUnlock()

Unlocks a directory so that replication of it can resume.

 

A primary directory can be registered for replication in one of the following ways:

 

  1. The file replicator service automatically registers a new directory for replication when a user creates it under the primary export server's directory export path. In this case, the file replicator service gives the directory the REPL_INTEGRITY_FILE and REPL_EXTENT_TREE settings for the integrity and extent replication controls.
  2. An application can call the NetReplExportDirAdd() function to register a pre-existing directory in the export path for replication. When adding a directory in this manner, you must specify the settings for the integrity and extent replication controls using the rpedX_integrity and rpedX_extent members of the appropriate REPL_EDIR_INFO structure.

 

The integrity control determines when a primary export server updates a client. The control can be one of the following values.

 

Value

Meaning

REPL_INTEGRITY_FILE

The client receives a replica of a file within the directory when the directory isn't being modified or replicated.

REPL_INTEGRITY_TREE

Before the file replicator service updates the client, each file and directory within the replicated directory must be stable for a specific period of time. This time is specified by the rp0_guardtime member of the REPL_INFO_0 structure. (Call the NetReplGetInfo() function to retrieve this type of configuration information for the file replicator service.)

 

The extent control specifies the selection of files for replication within the main export directory. The control can be one of the following values.

 

Value

Meaning

REPL_EXTENT_TREE

The file replicator service replicates the entire tree within the directory.

REPL_EXTENT_FILE

The file replicator service replicates only the files in the first-level directory.

 

To examine the replication controls of a directory, call the NetReplExportDirGetInfo() function; to modify them, call NetReplExportDirSetInfo(). You can call the replicator export directory functions whether or not the file replicator service is running. If the service is running on a primary export server, modifications to the directory controls take effect immediately, and the changes persist after the file replicator service stops. If the service has not started, the changes to the directory controls are stored as persistent information and take effect when the file replicator service starts. The replicator export directory functions are available at the following information levels:

 

  1. REPL_EDIR_INFO_0
  2. REPL_EDIR_INFO_1
  3. REPL_EDIR_INFO_2
  4. REPL_EDIR_INFO_1000
  5. REPL_EDIR_INFO_1001

 

The rped2_lockcount and rped2_locktime members of the REPL_EDIR_INFO_2 structure contain lock status information.

 

Replicator Import Directory Functions

 

The replicator import directory functions designate the top-level directories in the client's import path that should receive updates from the primary export server. The functions also return status information about a replicated directory on the client. (On LAN Manager 2.x, after a user creates a directory under the import path, the file replicator service automatically replicates to it.) The replicator import directory functions are listed following.

 

Function

Description

NetReplImportDirAdd()

Registers an existing directory in the import path to receive replication from a primary export server.

NetReplImportDirDel()

Removes the registration of a directory in the import path so that it no longer receives updates from the primary export server; the function does not delete the directory from the file system.

NetReplImportDirEnum()

Lists the client directories that are registered for replication.

NetReplImportDirGetInfo()

Returns status information for a replicated directory on an import server.

NetReplImportDirLock()

Locks a directory so that replication to it can be suspended.

NetReplImportDirUnlock()

Unlocks a directory so that replication to it can resume.

 

You can register a client directory for replication in one of the following ways:

 

  1. The file replicator service automatically adds a directory to the client's import path if the directory is exported by a primary export server from which the import server is already importing.
  2. An application can call the NetReplImportDirAdd() function to register a preexisting directory in the import path for replication. This can be useful if you want to modify the import directory's properties prior to importing the directory; for example, you may want to lock the directory and suspend replication. (The function does not create the directory.)

 

You can call the replicator import directory functions whether or not the file replicator service is running. If the service is running on a client, directory additions and deletions take effect immediately, and the changes persist after the file replicator service stops. If the service has not started, and if there is a primary export server that exports the directory, directory additions receive updates when the file replicator service starts. The replicator import directory functions are available at the following information levels:

 

  1. REPL_IDIR_INFO_0
  2. REPL_IDIR_INFO_1

 

 

 

 

< Win32 Network Management APIs 5 | Win32 Network Management APIs | Win32 Programming | Win32 Network Management APIs 7 >