Class RustPlusFcmSocket

Namespace

RustPlusApi.Fcm

Assembly

RustPlusApi.Fcm.dll

Represents a RustPlus FCM listener client for handling FCM connections and notifications.

public abstract class RustPlusFcmSocket : IRustPlusFcmSocket, IDisposable, IAsyncDisposable

Inheritance

object

RustPlusFcmSocket

Implements

IRustPlusFcmSocket

IDisposable

IAsyncDisposable

Derived

RustPlusFcm

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

RustPlusFcmSocket(Credentials, ICollection<string>?, RustPlusFcmSocketOptions?, ILoggerFactory?)

Represents a RustPlus FCM listener client for handling FCM connections and notifications.

protected RustPlusFcmSocket(Credentials credentials, ICollection<string>? persistentIds = null, RustPlusFcmSocketOptions? options = null, ILoggerFactory? loggerFactory = null)

Parameters

credentials Credentials

The Credentials used for authentication.

persistentIds ICollection<string>

Already-processed message ids, used for de-duplication, and the collection the socket harvests new ids into — pass a mutable, caller-owned set (prefer a HashSet<T>; a List<T> makes the duplicate check an O(n) scan). When null, de-duplication is disabled. The set is NOT cleared on login, so seeded ids survive reconnect. Read the current ids back via PersistentIds (snapshot) or subscribe to PersistentIdReceived (incremental) to persist them; ids have a server-side lifespan, so pruning your stored copy is your responsibility.

options RustPlusFcmSocketOptions

Tuning options (heartbeat interval, inactivity timeout); defaults are used when null.

loggerFactory ILoggerFactory

Routes the client's diagnostics into your logging stack; logging is disabled (a no-op NullLogger) when null.

Properties

PersistentIds

A snapshot of the FCM persistentIds currently tracked for de-duplication — the ids supplied at construction plus every id harvested since. Persist these and pass them back into a new instance to suppress redelivery of already-processed messages across reconnects. The collection is never null (empty when no ids are tracked). Ids have a server-side lifespan; pruning your persisted copy is the caller's responsibility.

public IReadOnlyCollection<string> PersistentIds { get; }

Property Value

IReadOnlyCollection<string>

Remarks

Thread safety: the snapshot enumerates the caller-owned collection with no lock. The receive loop adds ids on its own task, so reading PersistentIds from an unrelated thread while live traffic is flowing can throw InvalidOperationException (collection modified during enumeration). Safe read points: inside a PersistentIdReceived handler or any other notification event (same thread as the harvest), or after Disconnect().

Methods

ConnectAsync(CancellationToken)

Connects to the FCM MCS server over TLS, performs the MCS login handshake, and starts the background message-receive loop. On failure, ErrorOccurred is raised, the partial transport is released (so the instance can retry), and the exception is rethrown to the caller. Instances are single-connection: after Disconnect() or disposal, create a new instance to reconnect.

[ExcludeFromCodeCoverage]
public Task ConnectAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A token to cancel the connection attempt (TLS connect on net10.0+).

Returns

Task

Remarks

Excluded from coverage: live TLS connection to mtalk.google.com:5228; the MCS pipeline it drives is exercised offline via the RunReceiveLoopOverStreamAsync seam.

Exceptions

InvalidOperationException

Thrown when the socket is already connected, or was closed by Disconnect()/disposal.

Disconnect()

Disconnects the client from the FCM server and releases associated resources.

public void Disconnect()

Remarks

Invokes the Disconnecting and Disconnected events.

Dispose()

Releases resources used by the RustPlusFcmSocket.

public void Dispose()

Dispose(bool)

Releases the resources used by the RustPlusFcmSocket.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

DisposeAsync()

Asynchronously disposes the socket: cancels background work, unblocks the in-progress read by tearing down the transport, then awaits the tracked receive loop (bounded by RustPlusApi.Fcm.RustPlusFcmSocket.TeardownTimeout) before releasing remaining resources. Prefer this over Dispose() so teardown deterministically drains the receive loop instead of abandoning it.

public ValueTask DisposeAsync()

Returns

ValueTask

DisposeCoreAsync()

Cancels the instance token, tears down the transport to unblock the synchronous read, awaits the tracked receive loop (bounded), then disposes remaining resources. Override to extend async teardown.

protected virtual ValueTask DisposeCoreAsync()

Returns

ValueTask

ParseNotification(FcmMessage)

Parses an incoming FcmMessage notification. Override this method in a derived class to handle specific notification logic.

protected virtual void ParseNotification(FcmMessage message)

Parameters

message FcmMessage

The FcmMessage to parse.

Events

Connected

Occurs when the client has successfully connected to the FCM server.

public event EventHandler? Connected

Event Type

EventHandler

Connecting

Occurs when the client is starting to connect to the FCM server.

public event EventHandler? Connecting

Event Type

EventHandler

Disconnected

Occurs when the client has disconnected from the FCM server.

public event EventHandler? Disconnected

Event Type

EventHandler

Disconnecting

Occurs when the client is disconnecting from the FCM server.

public event EventHandler? Disconnecting

Event Type

EventHandler

ErrorOccurred

Occurs when an error is encountered.

public event EventHandler<Exception>? ErrorOccurred

Event Type

EventHandler<Exception>

Remarks

The event data is the Exception that was thrown.

NotificationReceived

Occurs when a notification is received.

public event EventHandler<string>? NotificationReceived

Event Type

EventHandler<string>

Remarks

The event data is the notification as a string.

PersistentIdReceived

Occurs once for each newly-harvested FCM persistentId, immediately after it is added to the tracked set. Subscribe to persist ids incrementally so a crash or quick restart cannot reopen the redelivery window (the server only stops redelivering a message once its id is replayed in a later login's ReceivedPersistentIds).

public event EventHandler<string>? PersistentIdReceived

Event Type

EventHandler<string>

Remarks

The event data is the harvested persistentId as a string.

SocketClosed

Occurs when the socket is closed.

public event EventHandler? SocketClosed

Event Type

EventHandler