GoogleApiClient

Kotlin |Java

public abstract class GoogleApiClient

---

This class is deprecated.

Use GoogleApi based APIs instead. SeeMoving Past GoogleApiClient.

The main entry point for Google Play services integration.

GoogleApiClient is used with a variety of static methods. Some of these methods require that GoogleApiClient be connected, some will queue up calls before GoogleApiClient is connected; check the specific API documentation to determine whether you need to be connected.

Before any operation is executed, the GoogleApiClient must be connected. The simplest way to manage the connection is to use enableAutoManage. See Accessing Google APIs.

GoogleApiClient instances are not thread-safe. To access Google APIs from multiple threads simultaneously, create a GoogleApiClient on each thread. GoogleApiClient service connections are cached internally, so creating multiple instances is fast.

Summary

Nested types
public final class GoogleApiClient.Builder This class is deprecated. Use GoogleApi based APIs instead.
public interface GoogleApiClient.ConnectionCallbacks This interface is deprecated. use GoogleApi based APIs instead. seemoving past googleapiclient.
public interface GoogleApiClient.OnConnectionFailedListener This interface is deprecated. use GoogleApi based apis instead. seemoving past googleapiclient. api implementors should use the stand-alone instead.

Constants
static final int	SIGN_IN_MODE_OPTIONAL = 2 If authenticated APIs are present they will attempt to connect, but failure of an authenticated API will not cause the GoogleApiClient connection to fail.
static final int	SIGN_IN_MODE_REQUIRED = 1 If a required authenticated API fails to connect, the entire GoogleApiClient will fail to connect and a failed ConnectionResult will be delivered to OnConnectionFailedListener#onConnectionFailed.

Public constructors
GoogleApiClient()

Public methods
abstract ConnectionResult	blockingConnect() Connects the client to Google Play services.
abstract ConnectionResult	blockingConnect(long timeout, @NonNull TimeUnit unit) Connects the client to Google Play services.
abstract PendingResult<Status>	clearDefaultAccountAndReconnect() Clears the account selected by the user and reconnects the client asking the user to pick an account again if useDefaultAccount was set.
abstract void	connect() Connects the client to Google Play services.
void	connect(int signInMode) Connects the client to Google Play services using the given sign in mode.
abstract void	disconnect() Closes the connection to Google Play services.
abstract void	dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args) Prints the GoogleApiClient's state into the given stream.
static void	dumpAll(     String prefix,     FileDescriptor fd,     PrintWriter writer,     String[] args ) Prints the state of all GoogleApiClients in the current process into the given stream.
abstract @NonNull ConnectionResult	getConnectionResult(@NonNull Api<Object> api) Returns the ConnectionResult for the GoogleApiClient's connection to the specified API.
abstract boolean	hasConnectedApi(@NonNull Api<Object> api) Returns whether or not this GoogleApiClient has the specified API in a connected state.
abstract boolean	isConnected() Checks if the client is currently connected to the service, so that requests to other methods will succeed.
abstract boolean	isConnecting() Checks if the client is attempting to connect to the service.
abstract boolean	isConnectionCallbacksRegistered(     @NonNull GoogleApiClient.ConnectionCallbacks listener ) Returns true if the specified listener is currently registered to receive connection events.
abstract boolean	isConnectionFailedListenerRegistered(     @NonNull GoogleApiClient.OnConnectionFailedListener listener ) Returns true if the specified listener is currently registered to receive connection failed events.
abstract void	reconnect() Closes the current connection to Google Play services and creates a new connection.
abstract void	registerConnectionCallbacks(     @NonNull GoogleApiClient.ConnectionCallbacks listener ) Registers a listener to receive connection events from this GoogleApiClient.
abstract void	registerConnectionFailedListener(     @NonNull GoogleApiClient.OnConnectionFailedListener listener ) Registers a listener to receive connection failed events from this GoogleApiClient.
abstract void	stopAutoManage(@NonNull FragmentActivity lifecycleActivity) Disconnects the client and stops automatic lifecycle management.
abstract void	unregisterConnectionCallbacks(     @NonNull GoogleApiClient.ConnectionCallbacks listener ) Removes a connection listener from this GoogleApiClient.
abstract void	unregisterConnectionFailedListener(     @NonNull GoogleApiClient.OnConnectionFailedListener listener ) Removes a connection failed listener from the GoogleApiClient.

Constants

SIGN_IN_MODE_OPTIONAL

public static final int SIGN_IN_MODE_OPTIONAL = 2

If authenticated APIs are present they will attempt to connect, but failure of an authenticated API will not cause the GoogleApiClient connection to fail. After ConnectionCallbacks#onConnected is received, the status of an authenticated API can be checked with hasConnectedApi.

A GoogleApiClient using this mode may be transitioned between authenticated and unauthenticated states by adding GOOGLE_SIGN_IN_API and using . To get an Intent that will allow the user to sign-in, call getSignInIntent. To sign the user out, call signOut.

It is an error to call connect with no arguments on a client in this mode.

See also
GoogleSignInApi

SIGN_IN_MODE_REQUIRED

public static final int SIGN_IN_MODE_REQUIRED = 1

If a required authenticated API fails to connect, the entire GoogleApiClient will fail to connect and a failed ConnectionResult will be delivered to OnConnectionFailedListener#onConnectionFailed. Once a connection has successfully completed the only way to disconnect the authenticated APIs is to call disconnect on this GoogleApiClient.

Using this mode is equivalent to calling connect on a GoogleApiClient that contains authenticated APIs.

It is an error to use this mode if no authenticated APIs have been added to this GoogleApiClient.

Public constructors

GoogleApiClient

public GoogleApiClient()

Public methods

blockingConnect

public abstract ConnectionResult blockingConnect()

Connects the client to Google Play services. Blocks until the connection either succeeds or fails.

Keep in mind this method will cause ANRs if called from the main thread.

If the client is already connected, this methods returns immediately. If the client is already connecting (for example due to a prior call to connect), this method blocks until the existing connection attempt completes. If a prior connection attempt has already failed, then a new connection attempt is started.

Returns
ConnectionResult	the result of the connection

blockingConnect

public abstract ConnectionResult blockingConnect(long timeout, @NonNull TimeUnit unit)

Connects the client to Google Play services. Blocks until the connection either succeeds or fails, or the timeout is reached.

Keep in mind this method will cause ANRs if called from the main thread.

If the client is already connected, this methods returns immediately. If the client is already connecting (for example due to a prior call to connect), this method blocks until the existing connection attempt completes or the timeout is reached. If a prior connection attempt has already failed, then a new connection attempt is started.

Parameters
long timeout	the maximum time to wait
@NonNull TimeUnit unit	the time unit of the timeout argument

Returns
ConnectionResult	the result of the connection

clearDefaultAccountAndReconnect

public abstract PendingResult<Status> clearDefaultAccountAndReconnect()

Clears the account selected by the user and reconnects the client asking the user to pick an account again if useDefaultAccount was set.

Returns
PendingResult<Status>	the pending result is fired once the default account has been cleared, but before the client is reconnected - for that ConnectionCallbacks can be used.

connect

public abstract void connect()

Connects the client to Google Play services. This method returns immediately, and connects to the service in the background. If the connection is successful, ConnectionCallbacks#onConnected is called and enqueued items are executed. On a failure, OnConnectionFailedListener#onConnectionFailed is called.

If the client is already connected or connecting, this method does nothing.

connect

public void connect(int signInMode)

Connects the client to Google Play services using the given sign in mode.

It is an error to make multiple calls to this method passing different modes. Once a mode is selected, all future connect calls must use the same mode.

See also
connect
SIGN_IN_MODE_REQUIRED
SIGN_IN_MODE_OPTIONAL

disconnect

public abstract void disconnect()

Closes the connection to Google Play services. No calls can be made using this client after calling this method. Any method calls that haven't executed yet will be canceled, and their onResult callbacks won't be called.

If the connection to the remote service hasn't been established yet, all enqueued calls will be canceled.

See also
connect

dump

public abstract void dump(String prefix, FileDescriptor fd, PrintWriter writer, String[] args)

Prints the GoogleApiClient's state into the given stream.

Parameters
String prefix	Desired prefix to prepend at each line of output.
FileDescriptor fd	The raw file descriptor that the dump is being sent to.
PrintWriter writer	The PrintWriter to use for writing the dump.
String[] args	Additional arguments to the dump request.

dumpAll

public static void dumpAll(
    String prefix,
    FileDescriptor fd,
    PrintWriter writer,
    String[] args
)

Prints the state of all GoogleApiClients in the current process into the given stream.

This can be used to diagnose lifecycle issues where GoogleApiClients may be unintentionally left in the connected state. Note that the output may include clients that are no longer referenced but have not yet been garbage collected.

Parameters
String prefix	Desired prefix to prepend at each line of output.
FileDescriptor fd	The raw file descriptor that the dump is being sent to.
PrintWriter writer	The PrintWriter to use for writing the dump.
String[] args	Additional arguments to the dump request.

getConnectionResult

public abstract @NonNull ConnectionResult getConnectionResult(@NonNull Api<Object> api)

Returns the ConnectionResult for the GoogleApiClient's connection to the specified API. This method must only be called after connect has been called and before disconnect is called.

This method should be used to check the connection result of an API added via addApiIfAvailable in the event that the overall connection succeeded, but the individual API failed to connect. To check the failure of the overall connection, use addOnConnectionFailedListener.

This method may return stale results if the GoogleApiClient is reconnecting due to a lost network connection. It is guaranteed to return the most recent ConnectionResult from attempting to connect the given API, but will throw an IllegalStateException if called before calling connect, after calling disconnect, or after receiving OnConnectionFailedListener#onConnectionFailed. This method can be used to easily determine why an API failed to connect if it was not available. To determine whether a given API is currently connected (without potential stale results) see hasConnectedApi.

Parameters
@NonNull Api<Object> api	The Api to retrieve the ConnectionResult of. Passing an API that was not registered with the GoogleApiClient results in an IllegalArgumentException.

hasConnectedApi

public abstract boolean hasConnectedApi(@NonNull Api<Object> api)

Returns whether or not this GoogleApiClient has the specified API in a connected state.

Parameters
@NonNull Api<Object> api	The Api to test the connection of.

isConnected

public abstract boolean isConnected()

Checks if the client is currently connected to the service, so that requests to other methods will succeed. Applications should guard client actions caused by the user with a call to this method.

Returns
boolean	true if the client is connected to the service.

isConnecting

public abstract boolean isConnecting()

Checks if the client is attempting to connect to the service.

Returns
boolean	true if the client is attempting to connect to the service.

isConnectionCallbacksRegistered

public abstract boolean isConnectionCallbacksRegistered(
    @NonNull GoogleApiClient.ConnectionCallbacks listener
)

Returns true if the specified listener is currently registered to receive connection events.

Parameters
@NonNull GoogleApiClient.ConnectionCallbacks listener	The listener to check for.

Returns
boolean	true if the specified listener is currently registered to receive connection events.

See also
registerConnectionCallbacks
unregisterConnectionCallbacks

isConnectionFailedListenerRegistered

public abstract boolean isConnectionFailedListenerRegistered(
    @NonNull GoogleApiClient.OnConnectionFailedListener listener
)

Returns true if the specified listener is currently registered to receive connection failed events.

Parameters
@NonNull GoogleApiClient.OnConnectionFailedListener listener	The listener to check for.

Returns
boolean	true if the specified listener is currently registered to receive connection failed events.

See also
registerConnectionFailedListener
unregisterConnectionFailedListener

reconnect

public abstract void reconnect()

Closes the current connection to Google Play services and creates a new connection. Equivalent to calling disconnect followed by connect.

This method closes the current connection then returns immediately and reconnects to the service in the background.

After calling this method, your application will receive ConnectionCallbacks#onConnected if the connection is successful, or OnConnectionFailedListener#onConnectionFailed if the connection failed.

See also
connect
disconnect

registerConnectionCallbacks

public abstract void registerConnectionCallbacks(
    @NonNull GoogleApiClient.ConnectionCallbacks listener
)

Registers a listener to receive connection events from this GoogleApiClient. If the service is already connected, the listener's ConnectionCallbacks#onConnected method will be called immediately. Applications should balance calls to this method with calls to unregisterConnectionCallbacks to avoid leaking resources.

If the specified listener is already registered to receive connection events, this method will not add a duplicate entry for the same listener, but will still call the listener's ConnectionCallbacks#onConnected method if currently connected.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
@NonNull GoogleApiClient.ConnectionCallbacks listener	the listener where the results of the asynchronous connect call are delivered.

registerConnectionFailedListener

public abstract void registerConnectionFailedListener(
    @NonNull GoogleApiClient.OnConnectionFailedListener listener
)

Registers a listener to receive connection failed events from this GoogleApiClient. Unlike registerConnectionCallbacks, if the service is not already connected, the listener's OnConnectionFailedListener#onConnectionFailed method will not be called immediately. Applications should balance calls to this method with calls to unregisterConnectionFailedListener to avoid leaking resources.

If the specified listener is already registered to receive connection failed events, this method will not add a duplicate entry for the same listener.

Note that the order of messages received here may not be stable, so clients should not rely on the order that multiple listeners receive events in.

Parameters
@NonNull GoogleApiClient.OnConnectionFailedListener listener	the listener where the results of the asynchronous connect call are delivered.

stopAutoManage

public abstract void stopAutoManage(@NonNull FragmentActivity lifecycleActivity)

Disconnects the client and stops automatic lifecycle management. Use this before creating a new client (which might be necessary when switching accounts, changing the set of used APIs etc.).

This method must be called from the main thread.

Parameters
@NonNull FragmentActivity lifecycleActivity	the activity managing the client's lifecycle.

Throws
java.lang.IllegalStateException	if called from outside of the main thread.

See also
enableAutoManage

unregisterConnectionCallbacks

public abstract void unregisterConnectionCallbacks(
    @NonNull GoogleApiClient.ConnectionCallbacks listener
)

Removes a connection listener from this GoogleApiClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection events, this method will have no effect.

Parameters
@NonNull GoogleApiClient.ConnectionCallbacks listener	the listener to unregister.

unregisterConnectionFailedListener

public abstract void unregisterConnectionFailedListener(
    @NonNull GoogleApiClient.OnConnectionFailedListener listener
)

Removes a connection failed listener from the GoogleApiClient. Note that removing a listener does not generate any callbacks.

If the specified listener is not currently registered to receive connection failed events, this method will have no effect.

Parameters
@NonNull GoogleApiClient.OnConnectionFailedListener listener	the listener to unregister.