Package org.mozilla.geckoview

Class IPProtectionController

Object

org.mozilla.geckoview.IPProtectionController

public class IPProtectionController
extends Object

Controller for managing IP protection state.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	IPProtectionController.AuthProvider	Embedder-provided hooks for authentication.
static class	IPProtectionController.Country	A country available in the proxy serverlist.
static interface	IPProtectionController.Delegate	Delegate for receiving IP protection state notifications.
static class	IPProtectionController.EnrollResult	Holds the result of an enrollment attempt.
static interface	IPProtectionController.GpiProvider	Embedder-provided hooks for Google Play Integrity authentication.
static class	IPProtectionController.IPProxyException	Exception type for IP proxy errors.
static class	IPProtectionController.ProxyState	Holds the current IP proxy state and any associated error.
static @interface	IPProtectionController.ServiceState	The possible states of the IP protection service.
static class	IPProtectionController.UsageInfo	Holds information about the current IP proxy usage.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	SERVICE_STATE_OPTED_OUT	The user has opted out from using VPN.
static final int	SERVICE_STATE_READY	The service is ready to be activated.
static final int	SERVICE_STATE_UNAUTHENTICATED	The user is signed out but eligible.
static final int	SERVICE_STATE_UNAVAILABLE	The user is not eligible or still not signed in.
static final int	SERVICE_STATE_UNINITIALIZED	The service has not been initialized yet.

Method Summary

Modifier and Type	Method	Description
GeckoResult<Void>	activate()	Activates the IP proxy by user action, in a non-private context, using the recommended location.
GeckoResult<Void>	activate(boolean userAction, boolean inPrivateBrowsing, String country)	Activates the IP proxy.
GeckoResult<Void>	deactivate()	Deactivates the IP proxy.
GeckoResult<IPProtectionController.EnrollResult>	enroll()	Triggers enrollment via the active auth provider.
IPProtectionController.AuthProvider	getAuthProvider()	Gets the IPProtectionController.AuthProvider for this instance.
GeckoResult<Void>	getCountryList()	Requests the list of countries available in the proxy serverlist.
IPProtectionController.Delegate	getDelegate()	Gets the IPProtectionController.Delegate for this instance.
IPProtectionController.GpiProvider	getGpiProvider()	Gets the IPProtectionController.GpiProvider for this instance.
GeckoResult<IPProtectionController.ProxyState>	getProxyState()	Gets the current IP proxy state.
GeckoResult<Integer>	getServiceState()	Gets the current IP protection service state.
GeckoResult<Void>	init()	Initializes the IP protection service.
GeckoResult<Void>	notifySignInStateChanged(boolean signedIn)	Notifies the IP protection service of a sign-in state change.
GeckoResult<Void>	refreshUsage()	Requests a refresh of the proxy usage information.
void	setAuthProvider(IPProtectionController.AuthProvider provider)	Sets the IPProtectionController.AuthProvider used to supply authentication tokens.
void	setDelegate(IPProtectionController.Delegate delegate)	Sets the IPProtectionController.Delegate for this instance.
void	setGpiProvider(IPProtectionController.GpiProvider provider)	Sets the IPProtectionController.GpiProvider used to handle Google Play Integrity warm-up and token requests.
GeckoResult<Void>	uninit()	Uninitializes the IP protection service, resetting the controller to its initial state.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SERVICE_STATE_UNINITIALIZED

public static final int SERVICE_STATE_UNINITIALIZED

The service has not been initialized yet.

See Also:

• Constant Field Values

SERVICE_STATE_UNAVAILABLE

public static final int SERVICE_STATE_UNAVAILABLE

The user is not eligible or still not signed in.

See Also:

• Constant Field Values

SERVICE_STATE_UNAUTHENTICATED

public static final int SERVICE_STATE_UNAUTHENTICATED

The user is signed out but eligible.

See Also:

• Constant Field Values

SERVICE_STATE_OPTED_OUT

public static final int SERVICE_STATE_OPTED_OUT

The user has opted out from using VPN.

See Also:

• Constant Field Values

SERVICE_STATE_READY

public static final int SERVICE_STATE_READY

The service is ready to be activated.

See Also:

• Constant Field Values

Method Details

init

@HandlerThread
@NonNull
public GeckoResult<Void> init()

Initializes the IP protection service.

Returns:

A GeckoResult that resolves when initialization completes.

setDelegate

@UiThread
public void setDelegate(@Nullable
 IPProtectionController.Delegate delegate)

Sets the IPProtectionController.Delegate for this instance.

Parameters:

delegate - The IPProtectionController.Delegate instance.

getDelegate

@UiThread
@Nullable
public IPProtectionController.Delegate getDelegate()

Gets the IPProtectionController.Delegate for this instance.

Returns:

The IPProtectionController.Delegate instance.

setAuthProvider

@UiThread
public void setAuthProvider(@Nullable
 IPProtectionController.AuthProvider provider)

Sets the IPProtectionController.AuthProvider used to supply authentication tokens. Pass null to clear the provider.

The provider governs token retrieval only. Sign-in state must be signalled separately via notifySignInStateChanged(boolean).

Requires init() to have been called; otherwise the JS-side listeners that consume the provider have not yet been registered.

Parameters:

provider - The IPProtectionController.AuthProvider, or null to clear.

getAuthProvider

@UiThread
@Nullable
public IPProtectionController.AuthProvider getAuthProvider()

Gets the IPProtectionController.AuthProvider for this instance.

Returns:

The IPProtectionController.AuthProvider instance, or null if none is set.

setGpiProvider

@UiThread
public void setGpiProvider(@Nullable
 IPProtectionController.GpiProvider provider)

Sets the IPProtectionController.GpiProvider used to handle Google Play Integrity warm-up and token requests. Pass null to clear the provider.

Parameters:

provider - The IPProtectionController.GpiProvider, or null to clear.

getGpiProvider

@UiThread
@Nullable
public IPProtectionController.GpiProvider getGpiProvider()

Gets the IPProtectionController.GpiProvider for this instance.

Returns:

The IPProtectionController.GpiProvider instance, or null if none is set.

notifySignInStateChanged

@UiThread
@NonNull
public GeckoResult<Void> notifySignInStateChanged(boolean signedIn)

Notifies the IP protection service of a sign-in state change. The service recomputes its state and may transition in or out of SERVICE_STATE_UNAUTHENTICATED.

Announcing a signed-in user requires an IPProtectionController.AuthProvider to be set via setAuthProvider(AuthProvider) beforehand, since the service immediately queries tokens through the provider. Announcing a signed-out user does not require a provider. If the precondition is violated, the returned GeckoResult is rejected with IllegalStateException.

Requires init() to have been called; otherwise the JS-side listeners that consume the event have not yet been registered.

Parameters:

signedIn - Whether the embedding app currently has a signed-in user.

Returns:

A GeckoResult that resolves once the JS side has acknowledged the event, or rejects with IllegalStateException if signedIn is true and no IPProtectionController.AuthProvider has been set.

uninit

@HandlerThread
@NonNull
public GeckoResult<Void> uninit()

Uninitializes the IP protection service, resetting the controller to its initial state.

Returns:

A GeckoResult that resolves when uninitialization completes.

getServiceState

@HandlerThread
@NonNull
public GeckoResult<Integer> getServiceState()

Gets the current IP protection service state.

Returns:

A GeckoResult that resolves to one of the IPProtectionController.ServiceState constants.

getCountryList

@HandlerThread
@NonNull
public GeckoResult<Void> getCountryList()

Requests the list of countries available in the proxy serverlist. The list is delivered asynchronously via IPProtectionController.Delegate.onCountryListChanged(List), which is also invoked whenever the underlying serverlist changes.

Returns:

A GeckoResult that resolves once the request has been processed.

getProxyState

@HandlerThread
@NonNull
public GeckoResult<IPProtectionController.ProxyState> getProxyState()

Gets the current IP proxy state.

Returns:

A GeckoResult that resolves to a IPProtectionController.ProxyState.

activate

@HandlerThread
@NonNull
public GeckoResult<Void> activate()

Activates the IP proxy by user action, in a non-private context, using the recommended location.

Returns:

A GeckoResult that resolves when activated, or rejects with an IPProtectionController.IPProxyException describing the failure.

activate

@HandlerThread
@NonNull
public GeckoResult<Void> activate(boolean userAction,
 boolean inPrivateBrowsing,
 @Nullable
 String country)

Activates the IP proxy.

If the proxy is already active, calling this again with a different country switches the active connection to a server in that country without tearing down the proxy.

Parameters:

userAction - Whether activation was triggered by an explicit user action, as opposed to a system action.

inPrivateBrowsing - Whether activation was triggered from a private browsing context.

country - The ISO 3166-1 alpha-2 code of the country to route through, or null to use the recommended location.

Returns:

A GeckoResult that resolves when activated, or rejects with an IPProtectionController.IPProxyException describing the failure.

enroll

@HandlerThread
@NonNull
public GeckoResult<IPProtectionController.EnrollResult> enroll()

Triggers enrollment via the active auth provider.

Returns:

A GeckoResult that resolves to an IPProtectionController.EnrollResult describing whether the user is now enrolled and entitled, and the error string if not.

deactivate

@HandlerThread
@NonNull
public GeckoResult<Void> deactivate()

Deactivates the IP proxy.

Returns:

A GeckoResult that resolves when deactivated, or rejects with an IPProtectionController.IPProxyException if an unexpected error occurs.

refreshUsage

@HandlerThread
@NonNull
public GeckoResult<Void> refreshUsage()

Requests a refresh of the proxy usage information. The updated usage will be delivered asynchronously via IPProtectionController.Delegate.onUsageChanged(UsageInfo).

Returns:

A GeckoResult that resolves when the refresh request has been processed, or rejects with an IPProtectionController.IPProxyException if an unexpected error occurs.