# The C# ReplicaConnection Class

### For an overview see page C# Classes

## Class Definition

        public class ReplicaConnection : Connection
        {
            // ===== HA MODE FLAGS (constants) =====
            public const int MCO_HAMODE_FORCE_MASTER = 0x4000;
            public const int MCO_HAMODE_FORCE_SYNC = 0x10000;
            public const int MCO_HAMODE_SEND_RESTLIST = 0x20000;
            public const int MCO_HAMODE_EXPLICIT_WRITE_ACCESS = 0x40000;

            // ===== NESTED ENUM: NotificationCode =====
            public enum NotificationCode {
                Connected, ConnectFailed, DbEqual, DbLoadBegin, DbLoadFailed,
                DbLoadOK, CommitFailed, ReplicaStopped, DbCreationFailed,
                HotSync, HotSyncEnd, StatefulSync, StatefulSyncEnd,
                MasterDbExtended, MasterDbCleaned
            }

            // ===== NESTED DELEGATE =====
            public delegate void ReplicaNotifyDelegate(NotificationCode code, long param);

            // ===== NESTED CLASS: Parameters =====
            public class Parameters
            {
                public const int MSEC = 1000;

                // Configuration Fields
                public int CommitTimeout;
                public int InitialTimeout;
                public int WaitDataTimeout;
                public int RepeatCounter;
                public int McastPort;
                public String McastAddr;
                public Database.CommitPolicy InitialCommitPolicy;
                public int InitialObjsInTrans;
                public int BatchCommitLength;
                public int BatchCommitBSize;
                public int BatchCommitPeriod;
                public int ModeFlags;
                public ReplicaNotifyDelegate NotifyDelegate;
                public String CancelpointAddr;
                public TransIterator.Iterator Iterator;
                public Database.SSLParameters SSLParameters;
                public int CompressionLevel;

                // Constructors
                public Parameters();
                public Parameters(int mode);
            }

            // ===== CONSTRUCTOR =====
            public ReplicaConnection(Database db);

            // ===== REPLICATION CONTROL METHODS =====
            public bool AttachMaster(String connectionString, Parameters parameters, int timeout);
            public void StopReplication();
            public void EnableFilter(bool enabled);
            public void Cancel(String cancelAddr, int timeout);
        }

## Member Descriptions

MCO_HAMODE_FORCE_MASTER
Flag: Switch to master role after initial synchronization completes. Use when the replica should automatically promote itself if the master becomes unavailable.
MCO_HAMODE_FORCE_SYNC
Flag: Enforce synchronous replication mode. Transactions on the master wait for acknowledgment from this replica before committing, ensuring stronger consistency at the cost of latency.
MCO_HAMODE_SEND_RESTLIST
Flag: Send the list of registered REST interfaces from the replica to the master during connection setup. Enables dynamic REST endpoint synchronization in HA clusters.
MCO_HAMODE_EXPLICIT_WRITE_ACCESS
Flag: Prevent automatic restoration of WRITE access on the replica when the master disconnects. Requires explicit application logic to enable writes during failover scenarios.
NotificationCode enum
Replication lifecycle events reported via `ReplicaNotifyDelegate`: connection status (`Connected`, `ConnectFailed`), synchronization progress (`DbLoadBegin`, `DbLoadOK`, `HotSync`), errors (`CommitFailed`, `DbLoadFailed`), and state changes (`ReplicaStopped`, `MasterDbExtended`).
ReplicaNotifyDelegate
Callback delegate for receiving asynchronous replication notifications. Signature: `void(NotificationCode code, long param)`. The `param` value provides additional context (e.g., transaction count, error code).
Parameters class
Configuration container for HA replica connection tuning. Controls timeouts, batching, multicast, compression, and failover behavior via structured fields.
Parameters.CommitTimeout / WaitDataTimeout / RepeatCounter
Commit acknowledgment timeout (`CommitTimeout`), data-wait timeout per commit attempt (`WaitDataTimeout`), and retry count for unacknowledged commits (`RepeatCounter`). Tune for network reliability vs. responsiveness.
Parameters.InitialTimeout / InitialCommitPolicy / InitialObjsInTrans
Initial synchronization settings: maximum wait time (`InitialTimeout`), disk flush policy during bulk load (`InitialCommitPolicy`), and objects-per-transaction batch size (`InitialObjsInTrans`) for controlled replay.
Parameters.BatchCommitLength / BatchCommitBSize / BatchCommitPeriod
Replica-side commit merging: maximum transaction count (`BatchCommitLength`), total byte size (`BatchCommitBSize`), and time window (`BatchCommitPeriod` in ms) for batching incoming changes to improve throughput.
Parameters.McastPort / McastAddr
Multicast replication settings: UDP port (`McastPort`, 0 = disabled) and multicast group address (`McastAddr`, default "224.0.0.1") for one-to-many replication topologies.
Parameters.ModeFlags
Bitmask combining `MCO_HAMODE_*` constants to control replica behavior (failover, sync mode, REST sync, write access policy).
Parameters.NotifyDelegate / CancelpointAddr / Iterator
Advanced hooks: notification callback (`NotifyDelegate`), address for cancellation signaling (`CancelpointAddr`), and custom transaction iterator (`Iterator`) for fine-grained replication control.
Parameters.SSLParameters / CompressionLevel
Security and performance: SSL/TLS configuration (`SSLParameters`) and network compression level (`CompressionLevel`, 0–9, where 0 = disabled) for encrypted and/or compressed replication traffic.
Parameters() / Parameters(int mode)
Constructors initializing parameters with default values. The overload accepts initial `ModeFlags` bitmask. Defaults: 10s commit timeout, 60s initial sync timeout, delayed commits, 100 objects/transaction, no multicast.
ReplicaConnection(Database)
Creates a replica connection instance for the specified database. The database must be opened in replica-compatible mode. Call `AttachMaster()` to begin replication.
AttachMaster(String, Parameters, int)
Connects the replica to the master node. `connectionString` format: `"host:port"` (e.g., `"192.168.0.1:10000"`). Returns `true` on successful connection within `timeout` milliseconds; `false` on timeout or failure.
StopReplication()
Terminates the replica's wait for updates from the master. The replica stops receiving new transactions but retains its current database state. Use for graceful shutdown or manual failover.
EnableFilter(bool)
Enables or disables replication filtering for classes marked as "local". When enabled, changes to local classes are not replicated, allowing replica-specific data alongside shared schema.
Cancel(String, int)
Instantly interrupts replication processing by signaling the master at `cancelAddr`. Waits up to `timeout` milliseconds for acknowledgment. Use for emergency failover or administrative intervention.
Replication Workflow
Typical usage: create `ReplicaConnection` → configure `Parameters` → call `AttachMaster()` → handle notifications via `NotifyDelegate` → process replicated data → call `StopReplication()` on shutdown.
Thread Safety
`ReplicaConnection` instances are not thread-safe. Use one instance per thread. The underlying `Connection` base class enforces thread-affinity for database operations.
Failover Considerations
Use `MCO_HAMODE_FORCE_MASTER` with caution: automatic promotion requires application logic to handle role transitions. `MCO_HAMODE_EXPLICIT_WRITE_ACCESS` provides safer manual control over write enablement during master loss.