PrivacySandboxInterface.kt
/*
* Copyright 2022 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.privacysandbox.tools
import java.util.concurrent.CancellationException
/**
* Annotated interfaces used by the app to communicate with the SDK in the Privacy Sandbox.
*
* Functions in a [PrivacySandboxInterface] annotated interface must obey the following rules:
* - Functions with return values must suspend
* - Parameter types may be primitives, [PrivacySandboxValue], [PrivacySandboxCallback],
* [PrivacySandboxInterface], or lists of primitives or [PrivacySandboxValue]. Nullable types
* are allowed.
* - Return types may be primitives, [PrivacySandboxValue], [PrivacySandboxInterface], or lists
* of primitives or [PrivacySandboxValue]. Nullable types are allowed.
*
* Suspend functions operate as follows:
* - The main thread is used by default
* - App cancellations are propagated to SDK coroutines
* - Cancellation exceptions thrown by SDKs are packaged and rethrown as valid
* [CancellationException]s
*
* Additionally, all exceptions thrown by SDK suspend function implementations are wrapped and
* rethrown to app developers as `PrivacySandboxException` with a full stack trace. Errors in
* non-suspend functions will not be rethrown.
*
* [PrivacySandboxInterface] annotated interfaces may not extend any interface except for
* [androidx.privacysandbox.ui.core.SandboxedUiAdapter], which can be used to provide SDK content in
* an app's UI. These interfaces may also have any other functions that are normally allowed.
*
* Usage example:
* ```
* @PrivacySandboxInterface
* interface MyInterface {
* suspend fun doSomething(request: Request): Response
* suspend fun getMyInterface(input: MyInterface): MyInterface
* suspend fun getNullableInterface(input: MySecondInterface): MySecondInterface?
* fun setListener(listener: MyCallback)
* fun appendValue(x: Int)
* }
* ```
*/
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS)
public annotation class PrivacySandboxInterface