--- /dev/null
+/*
+ * 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"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@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:(nullable 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:(nullable 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;
+
+/**
+ * Removes the "/topics/" prefix from the topic.
+ *
+ * @param topic The topic to remove the prefix from.
+ *
+ * @return The new topic name with the "/topics/" prefix removed.
+ */
+
++ (NSString *)removePrefixFromTopic:(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
+
+NS_ASSUME_NONNULL_END
fnp / wl-app.git / blobdiff