iOS/Pods/FirebaseMessaging/Firebase/Messaging/FIRMessagingPubSub.h

   1 /*
   2  * Copyright 2017 Google
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #import "FIRMessaging.h"
  18
  19 NS_ASSUME_NONNULL_BEGIN
  20
  21 @class FIRMessagingClient;
  22 @class FIRMessagingPubSubCache;
  23
  24 /**
  25  *  FIRMessagingPubSub provides a publish-subscribe model for sending FIRMessaging topic messages.
  26  *
  27  *  An app can subscribe to different topics defined by the
  28  *  developer. The app server can then send messages to the subscribed devices
  29  *  without having to maintain topic-subscribers mapping. Topics do not
  30  *  need to be explicitly created before subscribing or publishing&mdash;they
  31  *  are automatically created when publishing or subscribing.
  32  *
  33  *  Messages published to the topic will be received as regular FIRMessaging messages
  34  *  with `"from"` set to `"/topics/myTopic"`.
  35  *
  36  *  Only topic names that match the pattern `"/topics/[a-zA-Z0-9-_.~%]{1,900}"`
  37  *  are allowed for subscribing and publishing.
  38  */
  39 @interface FIRMessagingPubSub : NSObject
  40
  41 @property(nonatomic, readonly, strong) FIRMessagingPubSubCache *cache;
  42 @property(nonatomic, readonly, strong) FIRMessagingClient *client;
  43
  44 /**
  45  *  Initializes an instance of FIRMessagingPubSub.
  46  *
  47  *  @return An instance of FIRMessagingPubSub.
  48  */
  49 - (instancetype)initWithClient:(FIRMessagingClient *)client NS_DESIGNATED_INITIALIZER;
  50
  51 /**
  52  *  Subscribes an app instance to a topic, enabling it to receive messages
  53  *  sent to that topic.
  54  *
  55  *  This is an asynchronous call. If subscription fails, FIRMessaging
  56  *  invokes the completion callback with the appropriate error.
  57  *
  58  *  @see FIRMessagingPubSub unsubscribeWithToken:topic:handler:
  59  *
  60  *  @param token    The registration token as received from the InstanceID
  61  *                   library for a given `authorizedEntity` and "gcm" scope.
  62  *  @param topic    The topic to subscribe to. Should be of the form
  63  *                  `"/topics/<topic-name>"`.
  64  *  @param options  Unused parameter, please pass nil or empty dictionary.
  65  *  @param handler  The callback handler invoked when the subscribe call
  66  *                  ends. In case of success, a nil error is returned. Otherwise,
  67  *                  an appropriate error object is returned.
  68  *  @discussion     This method is thread-safe. However, it is not guaranteed to
  69  *                  return on the main thread.
  70  */
  71 - (void)subscribeWithToken:(NSString *)token
  72                      topic:(NSString *)topic
  73                    options:(nullable NSDictionary *)options
  74                    handler:(FIRMessagingTopicOperationCompletion)handler;
  75
  76 /**
  77  *  Unsubscribes an app instance from a topic, stopping it from receiving
  78  *  any further messages sent to that topic.
  79  *
  80  *  This is an asynchronous call. If the attempt to unsubscribe fails,
  81  *  we invoke the `completion` callback passed in with an appropriate error.
  82  *
  83  *  @param token   The token used to subscribe to this topic.
  84  *  @param topic   The topic to unsubscribe from. Should be of the form
  85  *                 `"/topics/<topic-name>"`.
  86  *  @param options Unused parameter, please pass nil or empty dictionary.
  87  *  @param handler The handler that is invoked once the unsubscribe call ends.
  88  *                 In case of success, nil error is returned. Otherwise, an
  89  *                  appropriate error object is returned.
  90  *  @discussion     This method is thread-safe. However, it is not guaranteed to
  91  *                  return on the main thread.
  92  */
  93 - (void)unsubscribeWithToken:(NSString *)token
  94                        topic:(NSString *)topic
  95                      options:(nullable NSDictionary *)options
  96                      handler:(FIRMessagingTopicOperationCompletion)handler;
  97
  98 /**
  99  *  Asynchronously subscribe to the topic. Adds to the pending list of topic operations.
 100  *  Retry in case of failures. This makes a repeated attempt to subscribe to the topic
 101  *  as compared to the `subscribe` method above which tries once.
 102  *
 103  *  @param topic The topic name to subscribe to. Should be of the form `"/topics/<topic-name>"`.
 104  *  @param handler The handler that is invoked once the unsubscribe call ends.
 105  *                 In case of success, nil error is returned. Otherwise, an
 106  *                  appropriate error object is returned.
 107  */
 108 - (void)subscribeToTopic:(NSString *)topic
 109                  handler:(nullable FIRMessagingTopicOperationCompletion)handler;
 110
 111 /**
 112  *  Asynchronously unsubscribe from the topic. Adds to the pending list of topic operations.
 113  *  Retry in case of failures. This makes a repeated attempt to unsubscribe from the topic
 114  *  as compared to the `unsubscribe` method above which tries once.
 115  *
 116  *  @param topic The topic name to unsubscribe from. Should be of the form `"/topics/<topic-name>"`.
 117  *  @param handler The handler that is invoked once the unsubscribe call ends.
 118  *                 In case of success, nil error is returned. Otherwise, an
 119  *                  appropriate error object is returned.
 120  */
 121 - (void)unsubscribeFromTopic:(NSString *)topic
 122                      handler:(nullable FIRMessagingTopicOperationCompletion)handler;
 123
 124 /**
 125  *  Schedule subscriptions sync.
 126  *
 127  *  @param immediately YES if the sync should be scheduled immediately else NO if we can delay
 128  *                     the sync.
 129  */
 130 - (void)scheduleSync:(BOOL)immediately;
 131
 132 /**
 133  *  Adds the "/topics/" prefix to the topic.
 134  *
 135  *  @param topic The topic to add the prefix to.
 136  *
 137  *  @return The new topic name with the "/topics/" prefix added.
 138  */
 139 + (NSString *)addPrefixToTopic:(NSString *)topic;
 140
 141 /**
 142  *  Removes the "/topics/" prefix from the topic.
 143  *
 144  *  @param topic The topic to remove the prefix from.
 145  *
 146  *  @return The new topic name with the "/topics/" prefix removed.
 147  */
 148
 149 + (NSString *)removePrefixFromTopic:(NSString *)topic;
 150 /**
 151  *  Check if the topic name has "/topics/" prefix.
 152  *
 153  *  @param topic The topic name to verify.
 154  *
 155  *  @return YES if the topic name has "/topics/" prefix else NO.
 156  */
 157 + (BOOL)hasTopicsPrefix:(NSString *)topic;
 158
 159 /**
 160  *  Check if it's a valid topic name. This includes "/topics/" prefix in the topic name.
 161  *
 162  *  @param topic The topic name to verify.
 163  *
 164  *  @return YES if the topic name satisfies the regex "/topics/[a-zA-Z0-9-_.~%]{1,900}".
 165  */
 166 + (BOOL)isValidTopicWithPrefix:(NSString *)topic;
 167
 168 @end
 169
 170 NS_ASSUME_NONNULL_END