firebase-ios-sdk/Firebase/Messaging/FIRMessagingPubSub.h

/*
 * Copyright 2017 Google
 *
 * 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.
 */

#import "FIRMessaging.h"

@class FIRMessagingClient;
@class FIRMessagingPubSubCache;

/**
 *  FIRMessagingPubSub provides a publish-subscribe model for sending FIRMessaging topic messages.
 *
 *  An app can subscribe to different topics defined by the
 *  developer. The app server can then send messages to the subscribed devices
 *  without having to maintain topic-subscribers mapping. Topics do not
 *  need to be explicitly created before subscribing or publishing—they
 *  are automatically created when publishing or subscribing.
 *
 *  Messages published to the topic will be received as regular FIRMessaging messages
 *  with `"from"` set to `"/topics/myTopic"`.
 *
 *  Only topic names that match the pattern `"/topics/[a-zA-Z0-9-_.~%]{1,900}"`
 *  are allowed for subscribing and publishing.
 */
@interface FIRMessagingPubSub : NSObject

@property(nonatomic, readonly, strong) FIRMessagingPubSubCache *cache;
@property(nonatomic, readonly, strong) FIRMessagingClient *client;

/**
 *  Initializes an instance of FIRMessagingPubSub.
 *
 *  @return An instance of FIRMessagingPubSub.
 */
- (instancetype)initWithClient:(FIRMessagingClient *)client NS_DESIGNATED_INITIALIZER;

/**
 *  Subscribes an app instance to a topic, enabling it to receive messages
 *  sent to that topic.
 *
 *  This is an asynchronous call. If subscription fails, FIRMessaging
 *  invokes the completion callback with the appropriate error.
 *
 *  @see FIRMessagingPubSub unsubscribeWithToken:topic:handler:
 *
 *  @param token    The registration token as received from the InstanceID
 *                   library for a given `authorizedEntity` and "gcm" scope.
 *  @param topic    The topic to subscribe to. Should be of the form
 *                  `"/topics/<topic-name>"`.
 *  @param options  Unused parameter, please pass nil or empty dictionary.
 *  @param handler  The callback handler invoked when the subscribe call
 *                  ends. In case of success, a nil error is returned. Otherwise,
 *                  an appropriate error object is returned.
 *  @discussion     This method is thread-safe. However, it is not guaranteed to
 *                  return on the main thread.
 */
- (void)subscribeWithToken:(NSString *)token
                     topic:(NSString *)topic
                   options:(NSDictionary *)options
                   handler:(FIRMessagingTopicOperationCompletion)handler;

/**
 *  Unsubscribes an app instance from a topic, stopping it from receiving
 *  any further messages sent to that topic.
 *
 *  This is an asynchronous call. If the attempt to unsubscribe fails,
 *  we invoke the `completion` callback passed in with an appropriate error.
 *
 *  @param token   The token used to subscribe to this topic.
 *  @param topic   The topic to unsubscribe from. Should be of the form
 *                 `"/topics/<topic-name>"`.
 *  @param options Unused parameter, please pass nil or empty dictionary.
 *  @param handler The handler that is invoked once the unsubscribe call ends.
 *                 In case of success, nil error is returned. Otherwise, an
 *                  appropriate error object is returned.
 *  @discussion     This method is thread-safe. However, it is not guaranteed to
 *                  return on the main thread.
 */
- (void)unsubscribeWithToken:(NSString *)token
                       topic:(NSString *)topic
                     options:(NSDictionary *)options
                     handler:(FIRMessagingTopicOperationCompletion)handler;

/**
 *  Asynchronously subscribe to the topic. Adds to the pending list of topic operations.
 *  Retry in case of failures. This makes a repeated attempt to subscribe to the topic
 *  as compared to the `subscribe` method above which tries once.
 *
 *  @param topic The topic name to subscribe to. Should be of the form `"/topics/<topic-name>"`.
 *  @param handler The handler that is invoked once the unsubscribe call ends.
 *                 In case of success, nil error is returned. Otherwise, an
 *                  appropriate error object is returned.
 */
- (void)subscribeToTopic:(NSString *)topic
                 handler:(nullable FIRMessagingTopicOperationCompletion)handler;

/**
 *  Asynchronously unsubscribe from the topic. Adds to the pending list of topic operations.
 *  Retry in case of failures. This makes a repeated attempt to unsubscribe from the topic
 *  as compared to the `unsubscribe` method above which tries once.
 *
 *  @param topic The topic name to unsubscribe from. Should be of the form `"/topics/<topic-name>"`.
 *  @param handler The handler that is invoked once the unsubscribe call ends.
 *                 In case of success, nil error is returned. Otherwise, an
 *                  appropriate error object is returned.
 */
- (void)unsubscribeFromTopic:(NSString *)topic
                     handler:(nullable FIRMessagingTopicOperationCompletion)handler;

/**
 *  Schedule subscriptions sync.
 *
 *  @param immediately YES if the sync should be scheduled immediately else NO if we can delay
 *                     the sync.
 */
- (void)scheduleSync:(BOOL)immediately;

/**
 *  Adds the "/topics/" prefix to the topic.
 *
 *  @param topic The topic to add the prefix to.
 *
 *  @return The new topic name with the "/topics/" prefix added.
 */
+ (NSString *)addPrefixToTopic:(NSString *)topic;

/**
 *  Check if the topic name has "/topics/" prefix.
 *
 *  @param topic The topic name to verify.
 *
 *  @return YES if the topic name has "/topics/" prefix else NO.
 */
+ (BOOL)hasTopicsPrefix:(NSString *)topic;

/**
 *  Check if it's a valid topic name. This includes "/topics/" prefix in the topic name.
 *
 *  @param topic The topic name to verify.
 *
 *  @return YES if the topic name satisfies the regex "/topics/[a-zA-Z0-9-_.~%]{1,900}".
 */
+ (BOOL)isValidTopicWithPrefix:(NSString *)topic;

@end