iOS/Pods/FirebaseMessaging/Firebase/Messaging/FIRMessagingClient.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 @class GULReachabilityChecker;
  20 @class GPBMessage;
  21
  22 @class FIRMessagingConnection;
  23 @class FIRMessagingDataMessageManager;
  24 @class FIRMessagingRmqManager;
  25
  26 /**
  27  *  Callback to handle MCS connection requests.
  28  *
  29  *  @param error The error object if any while trying to connect with MCS else nil.
  30  */
  31 typedef void(^FIRMessagingConnectCompletionHandler)(NSError *error);
  32
  33 @protocol FIRMessagingClientDelegate <NSObject>
  34
  35 @end
  36
  37 /**
  38  * The client handles the subscribe/unsubscribe for an unregistered senderID
  39  * and device. It also manages the FIRMessaging data connection, the exponential backoff
  40  * algorithm in case of registration failures, sign in failures and unregister
  41  * failures. It also handles the reconnect logic if the FIRMessaging connection is
  42  * broken off by some error during an active session.
  43  */
  44 @interface FIRMessagingClient : NSObject
  45
  46 @property(nonatomic, readonly, strong) FIRMessagingConnection *connection;
  47 @property(nonatomic, readwrite, weak) FIRMessagingDataMessageManager *dataMessageManager;
  48
  49 // Designated initializer
  50 - (instancetype)initWithDelegate:(id<FIRMessagingClientDelegate>)delegate
  51                     reachability:(GULReachabilityChecker *)reachability
  52                      rmq2Manager:(FIRMessagingRmqManager *)rmq2Manager;
  53
  54 - (void)teardown;
  55
  56 - (void)cancelAllRequests;
  57
  58 #pragma mark - FIRMessaging subscribe
  59
  60 /**
  61  *  Update the subscription associated with the given token and topic.
  62  *
  63  *  For a to-be-created subscription we check if the client is already
  64  *  subscribed to the topic or not. If subscribed we should have the
  65  *  subscriptionID in the cache and we return from there itself, else we call
  66  *  the FIRMessaging backend to create a new subscription for the topic for this client.
  67  *
  68  *  For delete subscription requests we delete the stored subscription in the
  69  *  client and then invoke the FIRMessaging backend to delete the existing subscription
  70  *  completely.
  71  *
  72  *  @param token        The token associated with the device.
  73  *  @param topic        The topic for which the subscription should be updated.
  74  *  @param options      The options to be passed in to the subscription request.
  75  *  @param shouldDelete If YES this would delete the subscription from the cache
  76  *                      and also let the FIRMessaging backend know that we need to delete
  77  *                      the subscriptionID associated with this topic.
  78  *                      If NO we try to create a new subscription for the given
  79  *                      token and topic.
  80  *  @param handler      The handler to invoke once the subscription request
  81  *                      finishes.
  82  */
  83 - (void)updateSubscriptionWithToken:(NSString *)token
  84                               topic:(NSString *)topic
  85                             options:(NSDictionary *)options
  86                        shouldDelete:(BOOL)shouldDelete
  87                             handler:(FIRMessagingTopicOperationCompletion)handler;
  88
  89 #pragma mark - MCS Connection
  90
  91 /**
  92  *  Create a MCS connection.
  93  *
  94  *  @param handler  The handler to be invokend once the connection is setup. If
  95  *                  setting up the connection fails we invoke the handler with
  96  *                  an appropriate error object.
  97  */
  98 - (void)connectWithHandler:(FIRMessagingConnectCompletionHandler)handler;
  99
 100 /**
 101  *  Disconnect the current MCS connection. If there is no valid connection this
 102  *  should be a NO-OP.
 103  */
 104 - (void)disconnect;
 105
 106 #pragma mark - MCS Connection State
 107
 108 /**
 109  *  If we are connected to MCS or not. This doesn't take into account the fact if
 110  *  the client has been signed in(verified) by MCS.
 111  *
 112  *  @return YES if we are signed in or connecting and trying to sign-in else NO.
 113  */
 114 @property(nonatomic, readonly) BOOL isConnected;
 115
 116 /**
 117  *  If we have an active MCS connection
 118  *
 119  *  @return YES if we have an active MCS connection else NO.
 120  */
 121 @property(nonatomic, readonly) BOOL isConnectionActive;
 122
 123 /**
 124  *  If we should be connected to MCS
 125  *
 126  *  @return YES if we have attempted a connection and not requested to disconect.
 127  */
 128 @property(nonatomic, readonly) BOOL shouldStayConnected;
 129
 130 /**
 131  *  Schedule a retry to connect to MCS. If `immediately` is `YES` try to
 132  *  schedule a retry now else retry with some delay.
 133  *
 134  *  @param immediately Should retry right now.
 135  */
 136 - (void)retryConnectionImmediately:(BOOL)immediately;
 137
 138 #pragma mark - Messages
 139
 140 /**
 141  *  Send a message over the MCS connection.
 142  *
 143  *  @param message Message to be sent.
 144  */
 145 - (void)sendMessage:(GPBMessage *)message;
 146
 147 /**
 148  *  Send message if we have an active MCS connection. If not cache the  message
 149  *  for this session and in case we are able to re-establish the connection try
 150  *  again else drop it. This should only be used for TTL=0 messages for now.
 151  *
 152  *  @param message Message to be sent.
 153  */
 154 - (void)sendOnConnectOrDrop:(GPBMessage *)message;
 155
 156 @end