Added Android code
[wl-app.git] / 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—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