diff --git a/FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessaging.cs b/FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessaging.cs index 6271fd33..3db182df 100644 --- a/FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessaging.cs +++ b/FirebaseAdmin/FirebaseAdmin/Messaging/FirebaseMessaging.cs @@ -23,7 +23,7 @@ namespace FirebaseAdmin.Messaging /// This is the entry point to all server-side Firebase Cloud Messaging (FCM) operations. You /// can get an instance of this class via FirebaseMessaging.DefaultInstance. /// - public sealed class FirebaseMessaging : IFirebaseService + public sealed class FirebaseMessaging : IFirebaseService, IFirebaseMessageSender, IFirebaseMessageSubscriber { private readonly FirebaseMessagingClient messagingClient; private readonly InstanceIdClient instanceIdClient; @@ -72,98 +72,28 @@ public static FirebaseMessaging GetMessaging(FirebaseApp app) }); } - /// - /// Sends a message to the FCM service for delivery. The message gets validated both by - /// the Admin SDK, and the remote FCM service. A successful return value indicates - /// that the message has been successfully sent to FCM, where it has been accepted by the - /// FCM service. - /// - /// A task that completes with a message ID string, which represents - /// successful handoff to FCM. - /// If the message argument is null. - /// If the message contains any invalid - /// fields. - /// If an error occurs while sending the - /// message. - /// The message to be sent. Must not be null. + /// public async Task SendAsync(Message message) { return await this.SendAsync(message, false) .ConfigureAwait(false); } - /// - /// Sends a message to the FCM service for delivery. The message gets validated both by - /// the Admin SDK, and the remote FCM service. A successful return value indicates - /// that the message has been successfully sent to FCM, where it has been accepted by the - /// FCM service. - /// - /// A task that completes with a message ID string, which represents - /// successful handoff to FCM. - /// If the message argument is null. - /// If the message contains any invalid - /// fields. - /// If an error occurs while sending the - /// message. - /// The message to be sent. Must not be null. - /// A cancellation token to monitor the asynchronous - /// operation. + /// public async Task SendAsync(Message message, CancellationToken cancellationToken) { return await this.SendAsync(message, false, cancellationToken) .ConfigureAwait(false); } - /// - /// Sends a message to the FCM service for delivery. The message gets validated both by - /// the Admin SDK, and the remote FCM service. A successful return value indicates - /// that the message has been successfully sent to FCM, where it has been accepted by the - /// FCM service. - /// If the option is set to true, the message will not be - /// actually sent to the recipients. Instead, the FCM service performs all the necessary - /// validations, and emulates the send operation. This is a good way to check if a - /// certain message will be accepted by FCM for delivery. - /// - /// A task that completes with a message ID string, which represents - /// successful handoff to FCM. - /// If the message argument is null. - /// If the message contains any invalid - /// fields. - /// If an error occurs while sending the - /// message. - /// The message to be sent. Must not be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. + /// public async Task SendAsync(Message message, bool dryRun) { return await this.SendAsync(message, dryRun, default(CancellationToken)) .ConfigureAwait(false); } - /// - /// Sends a message to the FCM service for delivery. The message gets validated both by - /// the Admin SDK, and the remote FCM service. A successful return value indicates - /// that the message has been successfully sent to FCM, where it has been accepted by the - /// FCM service. - /// If the option is set to true, the message will not be - /// actually sent to the recipients. Instead, the FCM service performs all the necessary - /// validations, and emulates the send operation. This is a good way to check if a - /// certain message will be accepted by FCM for delivery. - /// - /// A task that completes with a message ID string, which represents - /// successful handoff to FCM. - /// If the message argument is null. - /// If the message contains any invalid - /// fields. - /// If an error occurs while sending the - /// message. - /// The message to be sent. Must not be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. - /// A cancellation token to monitor the asynchronous - /// operation. + /// public async Task SendAsync( Message message, bool dryRun, CancellationToken cancellationToken) { @@ -171,148 +101,56 @@ public async Task SendAsync( message, dryRun, cancellationToken).ConfigureAwait(false); } - /// - /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to - /// send the entire list as a single RPC call. Compared to the - /// method, this is a significantly more efficient way to send multiple messages. - /// - /// If an error occurs while sending the - /// messages. - /// Up to 100 messages to send in the batch. Cannot be null. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendAllAsync(IEnumerable messages) { return await this.SendAllAsync(messages, false) .ConfigureAwait(false); } - /// - /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to - /// send the entire list as a single RPC call. Compared to the - /// method, this is a significantly more efficient way to send multiple messages. - /// - /// If an error occurs while sending the - /// messages. - /// Up to 100 messages to send in the batch. Cannot be null. - /// A cancellation token to monitor the asynchronous - /// operation. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendAllAsync(IEnumerable messages, CancellationToken cancellationToken) { return await this.SendAllAsync(messages, false, cancellationToken) .ConfigureAwait(false); } - /// - /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to - /// send the entire list as a single RPC call. Compared to the - /// method, this is a significantly more efficient way to send multiple messages. - /// - /// If an error occurs while sending the - /// messages. - /// Up to 100 messages to send in the batch. Cannot be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendAllAsync(IEnumerable messages, bool dryRun) { return await this.SendAllAsync(messages, dryRun, default) .ConfigureAwait(false); } - /// - /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to - /// send the entire list as a single RPC call. Compared to the - /// method, this is a significantly more efficient way to send multiple messages. - /// - /// If an error occurs while sending the - /// messages. - /// Up to 100 messages to send in the batch. Cannot be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. - /// A cancellation token to monitor the asynchronous - /// operation. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendAllAsync(IEnumerable messages, bool dryRun, CancellationToken cancellationToken) { return await this.messagingClient.SendAllAsync(messages, dryRun, cancellationToken) .ConfigureAwait(false); } - /// - /// Sends the given multicast message to all the FCM registration tokens specified in it. - /// - /// If an error occurs while sending the - /// messages. - /// The message to be sent. Must not be null. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendMulticastAsync(MulticastMessage message) { return await this.SendMulticastAsync(message, false) .ConfigureAwait(false); } - /// - /// Sends the given multicast message to all the FCM registration tokens specified in it. - /// - /// If an error occurs while sending the - /// messages. - /// The message to be sent. Must not be null. - /// A cancellation token to monitor the asynchronous - /// operation. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendMulticastAsync(MulticastMessage message, CancellationToken cancellationToken) { return await this.SendMulticastAsync(message, false, cancellationToken) .ConfigureAwait(false); } - /// - /// Sends the given multicast message to all the FCM registration tokens specified in it. - /// If the option is set to true, the message will not be - /// actually sent to the recipients. Instead, the FCM service performs all the necessary - /// validations, and emulates the send operation. This is a good way to check if a - /// certain message will be accepted by FCM for delivery. - /// - /// If an error occurs while sending the - /// messages. - /// The message to be sent. Must not be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendMulticastAsync(MulticastMessage message, bool dryRun) { return await this.SendMulticastAsync(message, dryRun, default) .ConfigureAwait(false); } - /// - /// Sends the given multicast message to all the FCM registration tokens specified in it. - /// If the option is set to true, the message will not be - /// actually sent to the recipients. Instead, the FCM service performs all the necessary - /// validations, and emulates the send operation. This is a good way to check if a - /// certain message will be accepted by FCM for delivery. - /// - /// If an error occurs while sending the - /// messages. - /// The message to be sent. Must not be null. - /// A boolean indicating whether to perform a dry run (validation - /// only) of the send. If set to true, the message will be sent to the FCM backend service, - /// but it will not be delivered to any actual recipients. - /// A cancellation token to monitor the asynchronous - /// operation. - /// A containing details of the batch operation's - /// outcome. + /// public async Task SendMulticastAsync( MulticastMessage message, bool dryRun, CancellationToken cancellationToken) { @@ -321,12 +159,7 @@ public async Task SendMulticastAsync( .ConfigureAwait(false); } - /// - /// Subscribes a list of registration tokens to a topic. - /// - /// A list of registration tokens to subscribe. - /// The topic name to subscribe to. /topics/ will be prepended to the topic name provided if absent. - /// A task that completes with a , giving details about the topic subscription operations. + /// public async Task SubscribeToTopicAsync( IReadOnlyList registrationTokens, string topic) { @@ -334,12 +167,7 @@ public async Task SubscribeToTopicAsync( .ConfigureAwait(false); } - /// - /// Unsubscribes a list of registration tokens from a topic. - /// - /// A list of registration tokens to unsubscribe. - /// The topic name to unsubscribe from. /topics/ will be prepended to the topic name provided if absent. - /// A task that completes with a , giving details about the topic unsubscription operations. + /// public async Task UnsubscribeFromTopicAsync( IReadOnlyList registrationTokens, string topic) { diff --git a/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSender.cs b/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSender.cs new file mode 100644 index 00000000..28e25678 --- /dev/null +++ b/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSender.cs @@ -0,0 +1,227 @@ +// Copyright 2022, Google Inc. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; + +namespace FirebaseAdmin.Messaging +{ + /// + /// Service to send messages to the FCM service for delivery. + /// + public interface IFirebaseMessageSender + { + /// + /// Sends a message to the FCM service for delivery. The message gets validated both by + /// the Admin SDK, and the remote FCM service. A successful return value indicates + /// that the message has been successfully sent to FCM, where it has been accepted by the + /// FCM service. + /// + /// A task that completes with a message ID string, which represents + /// successful handoff to FCM. + /// If the message argument is null. + /// If the message contains any invalid + /// fields. + /// If an error occurs while sending the + /// message. + /// The message to be sent. Must not be null. + Task SendAsync(Message message); + + /// + /// Sends a message to the FCM service for delivery. The message gets validated both by + /// the Admin SDK, and the remote FCM service. A successful return value indicates + /// that the message has been successfully sent to FCM, where it has been accepted by the + /// FCM service. + /// + /// A task that completes with a message ID string, which represents + /// successful handoff to FCM. + /// If the message argument is null. + /// If the message contains any invalid + /// fields. + /// If an error occurs while sending the + /// message. + /// The message to be sent. Must not be null. + /// A cancellation token to monitor the asynchronous + /// operation. + Task SendAsync(Message message, CancellationToken cancellationToken); + + /// + /// Sends a message to the FCM service for delivery. The message gets validated both by + /// the Admin SDK, and the remote FCM service. A successful return value indicates + /// that the message has been successfully sent to FCM, where it has been accepted by the + /// FCM service. + /// If the option is set to true, the message will not be + /// actually sent to the recipients. Instead, the FCM service performs all the necessary + /// validations, and emulates the send operation. This is a good way to check if a + /// certain message will be accepted by FCM for delivery. + /// + /// A task that completes with a message ID string, which represents + /// successful handoff to FCM. + /// If the message argument is null. + /// If the message contains any invalid + /// fields. + /// If an error occurs while sending the + /// message. + /// The message to be sent. Must not be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + Task SendAsync(Message message, bool dryRun); + + /// + /// Sends a message to the FCM service for delivery. The message gets validated both by + /// the Admin SDK, and the remote FCM service. A successful return value indicates + /// that the message has been successfully sent to FCM, where it has been accepted by the + /// FCM service. + /// If the option is set to true, the message will not be + /// actually sent to the recipients. Instead, the FCM service performs all the necessary + /// validations, and emulates the send operation. This is a good way to check if a + /// certain message will be accepted by FCM for delivery. + /// + /// A task that completes with a message ID string, which represents + /// successful handoff to FCM. + /// If the message argument is null. + /// If the message contains any invalid + /// fields. + /// If an error occurs while sending the + /// message. + /// The message to be sent. Must not be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + /// A cancellation token to monitor the asynchronous + /// operation. + Task SendAsync( + Message message, bool dryRun, CancellationToken cancellationToken); + + /// + /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to + /// send the entire list as a single RPC call. Compared to the + /// method, this is a significantly more efficient way to send multiple messages. + /// + /// If an error occurs while sending the + /// messages. + /// Up to 100 messages to send in the batch. Cannot be null. + /// A containing details of the batch operation's + /// outcome. + Task SendAllAsync(IEnumerable messages); + + /// + /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to + /// send the entire list as a single RPC call. Compared to the + /// method, this is a significantly more efficient way to send multiple messages. + /// + /// If an error occurs while sending the + /// messages. + /// Up to 100 messages to send in the batch. Cannot be null. + /// A cancellation token to monitor the asynchronous + /// operation. + /// A containing details of the batch operation's + /// outcome. + Task SendAllAsync(IEnumerable messages, CancellationToken cancellationToken); + + /// + /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to + /// send the entire list as a single RPC call. Compared to the + /// method, this is a significantly more efficient way to send multiple messages. + /// + /// If an error occurs while sending the + /// messages. + /// Up to 100 messages to send in the batch. Cannot be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + /// A containing details of the batch operation's + /// outcome. + Task SendAllAsync(IEnumerable messages, bool dryRun); + + /// + /// Sends all the messages in the given list via Firebase Cloud Messaging. Employs batching to + /// send the entire list as a single RPC call. Compared to the + /// method, this is a significantly more efficient way to send multiple messages. + /// + /// If an error occurs while sending the + /// messages. + /// Up to 100 messages to send in the batch. Cannot be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + /// A cancellation token to monitor the asynchronous + /// operation. + /// A containing details of the batch operation's + /// outcome. + Task SendAllAsync(IEnumerable messages, bool dryRun, CancellationToken cancellationToken); + + /// + /// Sends the given multicast message to all the FCM registration tokens specified in it. + /// + /// If an error occurs while sending the + /// messages. + /// The message to be sent. Must not be null. + /// A containing details of the batch operation's + /// outcome. + Task SendMulticastAsync(MulticastMessage message); + + /// + /// Sends the given multicast message to all the FCM registration tokens specified in it. + /// + /// If an error occurs while sending the + /// messages. + /// The message to be sent. Must not be null. + /// A cancellation token to monitor the asynchronous + /// operation. + /// A containing details of the batch operation's + /// outcome. + Task SendMulticastAsync(MulticastMessage message, CancellationToken cancellationToken); + + /// + /// Sends the given multicast message to all the FCM registration tokens specified in it. + /// If the option is set to true, the message will not be + /// actually sent to the recipients. Instead, the FCM service performs all the necessary + /// validations, and emulates the send operation. This is a good way to check if a + /// certain message will be accepted by FCM for delivery. + /// + /// If an error occurs while sending the + /// messages. + /// The message to be sent. Must not be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + /// A containing details of the batch operation's + /// outcome. + Task SendMulticastAsync(MulticastMessage message, bool dryRun); + + /// + /// Sends the given multicast message to all the FCM registration tokens specified in it. + /// If the option is set to true, the message will not be + /// actually sent to the recipients. Instead, the FCM service performs all the necessary + /// validations, and emulates the send operation. This is a good way to check if a + /// certain message will be accepted by FCM for delivery. + /// + /// If an error occurs while sending the + /// messages. + /// The message to be sent. Must not be null. + /// A boolean indicating whether to perform a dry run (validation + /// only) of the send. If set to true, the message will be sent to the FCM backend service, + /// but it will not be delivered to any actual recipients. + /// A cancellation token to monitor the asynchronous + /// operation. + /// A containing details of the batch operation's + /// outcome. + Task SendMulticastAsync( + MulticastMessage message, bool dryRun, CancellationToken cancellationToken); + } +} diff --git a/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSubscriber.cs b/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSubscriber.cs new file mode 100644 index 00000000..2053d8ea --- /dev/null +++ b/FirebaseAdmin/FirebaseAdmin/Messaging/IFirebaseMessageSubscriber.cs @@ -0,0 +1,43 @@ +// Copyright 2022, Google Inc. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; +using System.Threading.Tasks; + +namespace FirebaseAdmin.Messaging +{ + /// + /// Service to subscribe or unsubscribe registration tokens to a topic. + /// + public interface IFirebaseMessageSubscriber + { + /// + /// Subscribes a list of registration tokens to a topic. + /// + /// A list of registration tokens to subscribe. + /// The topic name to subscribe to. /topics/ will be prepended to the topic name provided if absent. + /// A task that completes with a , giving details about the topic subscription operations. + Task SubscribeToTopicAsync( + IReadOnlyList registrationTokens, string topic); + + /// + /// Unsubscribes a list of registration tokens from a topic. + /// + /// A list of registration tokens to unsubscribe. + /// The topic name to unsubscribe from. /topics/ will be prepended to the topic name provided if absent. + /// A task that completes with a , giving details about the topic unsubscription operations. + Task UnsubscribeFromTopicAsync( + IReadOnlyList registrationTokens, string topic); + } +}