1 /* 2 * Copyright 2021 Google LLC 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 * https://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 package com.google.android.enterprise.connectedapps; 17 18 import android.content.Context; 19 import com.google.android.enterprise.connectedapps.exceptions.UnavailableProfileException; 20 21 /** A {@link ProfileConnector} is used to manage the connection between profiles. */ 22 public interface ProfileConnector { 23 /** 24 * Execute {@link #connect(Object)} with a new connection holder. 25 * 26 * <p>You must use {@link #removeConnectionHolder(Object)} with the returned {@link 27 * ProfileConnectionHolder} or call {@link ProfileConnectionHolder#close()} when you are finished 28 * with the connection. 29 */ connect()30 ProfileConnectionHolder connect() throws UnavailableProfileException; 31 32 /** 33 * Attempt to connect to the other profile and add a connection holder. 34 * 35 * <p>This will mean that the connection will not be dropped automatically to save resources. 36 * 37 * <p>This must not be called from the main thread. 38 * 39 * <p>You must remove the connection holder once you have finished with it. See {@link 40 * #removeConnectionHolder(Object)}. 41 * 42 * <p>Returns a {@link ProfileConnectionHolder} which can be used to automatically remove this 43 * connection holder using try-with-resources. Either the {@link ProfileConnectionHolder} or the 44 * passed in {@code connectionHolder} can be used with {@link #removeConnectionHolder(Object)}. 45 * 46 * @throws UnavailableProfileException If the connection cannot be made. 47 */ connect(Object connectionHolder)48 ProfileConnectionHolder connect(Object connectionHolder) throws UnavailableProfileException; 49 50 /** 51 * Return the {@link CrossProfileSender} being used for this connection. 52 * 53 * <p>This API should only be used by generated code. 54 */ crossProfileSender()55 CrossProfileSender crossProfileSender(); 56 57 /** 58 * Add a listener to be called when a profile is connected or disconnected. 59 * 60 * <p>{@link #isConnected()} can be called to check if a connection is established. 61 * 62 * @see #removeConnectionListener(ConnectionListener) 63 */ addConnectionListener(ConnectionListener listener)64 void addConnectionListener(ConnectionListener listener); 65 66 /** Remove a listener added using {@link #addConnectionListener(ConnectionListener)}. */ removeConnectionListener(ConnectionListener listener)67 void removeConnectionListener(ConnectionListener listener); 68 69 /** 70 * Add a listener to be called when a profile becomes available or unavailable. 71 * 72 * <p>{@link #isAvailable()} can be called to check if a profile is available. 73 * 74 * @see #removeAvailabilityListener(AvailabilityListener) 75 */ addAvailabilityListener(AvailabilityListener listener)76 void addAvailabilityListener(AvailabilityListener listener); 77 78 /** Remove a listener registered using {@link #addAvailabilityListener( AvailabilityListener)}. */ removeAvailabilityListener(AvailabilityListener listener)79 void removeAvailabilityListener(AvailabilityListener listener); 80 81 /** 82 * Return true if there is another profile which could be connected to. 83 * 84 * <p>If this returns true, then asynchronous calls should succeed. Synchronous calls will only 85 * succeed if {@link #isConnected()} also returns true. 86 */ isAvailable()87 boolean isAvailable(); 88 89 /** 90 * Return true if there is another profile connected. 91 * 92 * <p>If this returns true, then synchronous calls should succeed unless they are disconnected 93 * before the call completes. 94 */ isConnected()95 boolean isConnected(); 96 97 /** Return an instance of {@link ConnectedAppsUtils} for dealing with this connection. */ utils()98 ConnectedAppsUtils utils(); 99 permissions()100 Permissions permissions(); 101 102 /** Return the application context used by this connector. */ applicationContext()103 Context applicationContext(); 104 105 /** 106 * Register an object as holding the connection open. 107 * 108 * <p>While there is at least one connection holder, the connected apps SDK will attempt to stay 109 * connected. 110 * 111 * <p>You must remove the connection holder once you have finished with it. See {@link 112 * #removeConnectionHolder(Object)}. 113 * 114 * <p>Returns a {@link ProfileConnectionHolder} which can be used to automatically remove this 115 * connection holder using try-with-resources. Either the {@link ProfileConnectionHolder} or the 116 * passed in {@code connectionHolder} can be used with {@link #removeConnectionHolder(Object)}. 117 */ addConnectionHolder(Object connectionHolder)118 ProfileConnectionHolder addConnectionHolder(Object connectionHolder); 119 120 /** 121 * Registers a connection holder alias. 122 * 123 * <p>This means that if the key is removed, then the value will also be removed. If the value is 124 * removed, the key will not be removed. 125 */ addConnectionHolderAlias(Object key, Object value)126 void addConnectionHolderAlias(Object key, Object value); 127 128 /** 129 * Remove a connection holder. 130 * 131 * <p>Once there are no remaining connection holders, the connection will be able to be closed. 132 * 133 * <p>See {@link #addConnectionHolder(Object)}. 134 */ removeConnectionHolder(Object connectionHolder)135 void removeConnectionHolder(Object connectionHolder); 136 clearConnectionHolders()137 void clearConnectionHolders(); 138 } 139