SandboxedPdfLoader

Artifact: androidx.pdf:pdf-document-service

Kotlin |Java

class SandboxedPdfLoader : PdfLoader

A PdfLoader implementation that opens PDF documents through a sandboxed Android service.

This class establishes a connection with the PdfDocumentServiceImpl bound service and attempts to load a PDF document using the PdfRenderer. If successful, it returns a SandboxedPdfDocument instance, which provides a remote interface for interacting with the document.

The loading process involves:

Establishing a connection with the service using a PdfServiceConnection.
Opening a ParcelFileDescriptor for the PDF document.
Passing the file descriptor to the service for loading and rendering.
Creating a SandboxedPdfDocument instance upon successful loading.

Summary

Public companion functions
`PdfSandboxHandle`	`startInitialization(context: Context)` Prepares sandboxing PDF resources ahead of any document operations, to reduce latency during the interaction with the `SandboxedPdfLoader` or `PdfDocument`.

Public constructors
`SandboxedPdfLoader(context: Context, coroutineContext: CoroutineContext)` Creates a new `SandboxedPdfLoader` instance.

Public functions
`open suspend PdfDocument`	`openDocument(uri: Uri, password: String?)` Asynchronously opens a `PdfDocument` from the specified `Uri`.
`open suspend PdfDocument`	`openDocument( uri: Uri, fileDescriptor: ParcelFileDescriptor, password: String?, renderParams: RenderParams )` Asynchronously opens a `PdfDocument` from the specified `fileDescriptor`.

Public companion functions

startInitialization

Added in 1.0.0-beta01

fun startInitialization(context: Context): PdfSandboxHandle

Prepares sandboxing PDF resources ahead of any document operations, to reduce latency during the interaction with the SandboxedPdfLoader or PdfDocument.

The returned PdfSandboxHandle represents a session and must be closed by the caller when no longer needed.

Calling this method is optional. Any document operation via SandboxedPdfLoader and PdfDocument will initialize the resources internally on demand, but may experience increased startup time.

Parameters
`context: Context`	A `Context` of component to be associated with pdf session.

Returns
`PdfSandboxHandle`	A `PdfSandboxHandle` representing an active pdf session.

See also
`PdfSandboxHandle`

Public constructors

SandboxedPdfLoader

Added in 1.0.0-beta01

SandboxedPdfLoader(
    context: Context,
    coroutineContext: CoroutineContext = EmptyCoroutineContext
)

Creates a new SandboxedPdfLoader instance.

Parameters

Parameters
`context: Context`	The `Context` required for accessing system services.
`coroutineContext: CoroutineContext = EmptyCoroutineContext`	The `CoroutineContext` used for asynchronous operations. This context is resolved internally to ensure an appropriate `ContinuationInterceptor` is present. If the provided `coroutineContext` already contains a `ContinuationInterceptor`, that interceptor will be used. If the provided `coroutineContext` does not contain a `ContinuationInterceptor`, `Dispatchers.IO` will be automatically added to it to handle I/O-bound tasks such as opening file descriptors and interacting with the PDF service. Providing a `Job` in this `coroutineContext` is an error.

context: Context

The Context required for accessing system services.

coroutineContext: CoroutineContext = EmptyCoroutineContext

The CoroutineContext used for asynchronous operations. This context is resolved internally to ensure an appropriate ContinuationInterceptor is present.

If the provided coroutineContext already contains a ContinuationInterceptor, that interceptor will be used.
If the provided coroutineContext does not contain a ContinuationInterceptor, Dispatchers.IO will be automatically added to it to handle I/O-bound tasks such as opening file descriptors and interacting with the PDF service.
Providing a Job in this coroutineContext is an error.

Public functions

openDocument

open suspend fun openDocument(uri: Uri, password: String? = null): PdfDocument

Asynchronously opens a PdfDocument from the specified Uri.

Parameters
`uri: Uri`	The URI of the PDF document to open.
`password: String? = null`	(Optional) The password to unlock the document if it is encrypted.

Returns
`PdfDocument`	The opened `PdfDocument`.

Throws
`PdfPasswordException`	If the provided password is incorrect.
`IOException`	If an error occurs while opening the document.

openDocument

open suspend fun openDocument(
    uri: Uri,
    fileDescriptor: ParcelFileDescriptor,
    password: String? = null,
    renderParams: RenderParams = RenderParams(renderMode = RenderParams.RENDER_MODE_FOR_DISPLAY)
): PdfDocument

Asynchronously opens a PdfDocument from the specified fileDescriptor. The file descriptor will become owned by the PdfDocument, and it should be closed using the document, unless an exception is thrown.

Parameters
`uri: Uri`	This is used only as a unique identifier for the `PdfDocument`. The source of truth for accessing file contents is in this case the `fileDescriptor`. If you don't have access to the `Uri` which produced the file descriptor, or the file descriptor was not produced by opening a URI, it's acceptable to provide a "fake" one here, so long as the value uniquely identifies the document.
`fileDescriptor: ParcelFileDescriptor`	a `ParcelFileDescriptor` pointing at the PDF content to be opened. Must be seekable.
`password: String? = null`	(Optional) The password to unlock the document if it is encrypted.
`renderParams: RenderParams = RenderParams(renderMode = RenderParams.RENDER_MODE_FOR_DISPLAY)`	(Optional) Represents a set of parameters that will be used to render a page of the document. If not provided, the default `RenderParams` with `RenderParams.renderMode` = `RenderParams.RENDER_MODE_FOR_DISPLAY` will be used.

Returns
`PdfDocument`	The opened `PdfDocument`.

Throws
`PdfPasswordException`	If the provided password is incorrect.
`IOException`	If an error occurs while opening the document.