# SandboxedPdfLoader

Artifact: [androidx.pdf:pdf-document-service](https://developer.android.com/jetpack/androidx/releases/pdf) [View Source](https://cs.android.com/search?q=file:androidx/pdf/SandboxedPdfLoader.kt+class:androidx.pdf.SandboxedPdfLoader) Added in [1.0.0-beta01](https://developer.android.com/jetpack/androidx/releases/pdf#1.0.0-beta01)

*** ** * ** ***


```
class SandboxedPdfLoader : PdfLoader
```

<br />

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/pdf/PdfLoader` implementation that opens PDF documents through a sandboxed Android service.

This class establishes a connection with the bound service and attempts to load a PDF document using the `https://developer.android.com/reference/android/graphics/pdf/PdfRenderer.html`. If successful, it returns a `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfDocument` instance, which provides a remote interface for interacting with the document.

The loading process involves:

1. Establishing a connection with the service using a .

2. Opening a `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` for the PDF document.

3. Passing the file descriptor to the service for loading and rendering.

4. Creating a `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfDocument` instance upon successful loading.

## Summary

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfSandboxHandle` | `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader#startInitialization(android.content.Context)(context: https://developer.android.com/reference/android/content/Context.html)` Prepares sandboxing PDF resources ahead of any document operations, to reduce latency during the interaction with the `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader` or `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader#SandboxedPdfLoader(android.content.Context,kotlin.coroutines.CoroutineContext)(context: https://developer.android.com/reference/android/content/Context.html, coroutineContext: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html)` Creates a new `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader` instance. |

| ### Public functions |
|---|---|
| `open suspend https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` | `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader#openDocument(android.net.Uri,kotlin.String)(uri: https://developer.android.com/reference/android/net/Uri.html, password: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?)` Asynchronously opens a `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` from the specified `https://developer.android.com/reference/android/net/Uri.html`. |
| `open suspend https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` | `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader#openDocument(android.net.Uri,android.os.ParcelFileDescriptor,kotlin.String,androidx.pdf.RenderParams)( uri: https://developer.android.com/reference/android/net/Uri.html, fileDescriptor: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html, password: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html?, renderParams: https://developer.android.com/reference/kotlin/androidx/pdf/RenderParams )` Asynchronously opens a `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` from the specified `https://developer.android.com/reference/kotlin/androidx/pdf/PdfLoader#openDocument(android.net.Uri,android.os.ParcelFileDescriptor,kotlin.String,androidx.pdf.RenderParams)`. |

## Public companion functions

### startInitialization

Added in [1.0.0-beta01](https://developer.android.com/jetpack/androidx/releases/pdf#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 `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader` or `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`.

The returned `https://developer.android.com/reference/kotlin/androidx/pdf/PdfSandboxHandle` represents a session and must be closed by the caller when no longer needed.

Calling this method is optional. Any document operation via `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader` and `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` will initialize the resources internally on demand, but may experience increased startup time.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | A `https://developer.android.com/reference/android/content/Context.html` of component to be associated with pdf session. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfSandboxHandle` | A `https://developer.android.com/reference/kotlin/androidx/pdf/PdfSandboxHandle` representing an active pdf session. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfSandboxHandle` |   |

## Public constructors

### SandboxedPdfLoader

Added in [1.0.0-beta01](https://developer.android.com/jetpack/androidx/releases/pdf#1.0.0-beta01)

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

Creates a new `https://developer.android.com/reference/kotlin/androidx/pdf/SandboxedPdfLoader` instance.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | The `https://developer.android.com/reference/android/content/Context.html` required for accessing system services. |
| `coroutineContext: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html = EmptyCoroutineContext` | The `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-coroutine-context/index.html` used for asynchronous operations. This context is resolved internally to ensure an appropriate `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-continuation-interceptor/index.html` is present. - If the provided `coroutineContext` already contains a `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-continuation-interceptor/index.html`, that interceptor will be used. - If the provided `coroutineContext` does not contain a `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.coroutines/-continuation-interceptor/index.html`, `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-i-o.html` 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 `https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html` in this `coroutineContext` is an error. |

## Public functions

### openDocument

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

Asynchronously opens a `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` from the specified `https://developer.android.com/reference/android/net/Uri.html`.

| Parameters |
|---|---|
| `uri: https://developer.android.com/reference/android/net/Uri.html` | The URI of the PDF document to open. |
| `password: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | (Optional) The password to unlock the document if it is encrypted. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` | The opened `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfPasswordException` | If the provided password is incorrect. |
| `https://developer.android.com/reference/java/io/IOException.html` | 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 `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` from the specified `https://developer.android.com/reference/kotlin/androidx/pdf/PdfLoader#openDocument(android.net.Uri,android.os.ParcelFileDescriptor,kotlin.String,androidx.pdf.RenderParams)`. The file descriptor will become owned by the `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`, and it should be closed using the document, unless an exception is thrown.

| Parameters |
|---|---|
| `uri: https://developer.android.com/reference/android/net/Uri.html` | This is used only as a unique identifier for the `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`. The source of truth for accessing file contents is in this case the `https://developer.android.com/reference/kotlin/androidx/pdf/PdfLoader#openDocument(android.net.Uri,android.os.ParcelFileDescriptor,kotlin.String,androidx.pdf.RenderParams)`. If you don't have access to the `https://developer.android.com/reference/android/net/Uri.html` 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: https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` | a `https://developer.android.com/reference/android/os/ParcelFileDescriptor.html` pointing at the PDF content to be opened. Must be seekable. |
| `password: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html? = null` | (Optional) The password to unlock the document if it is encrypted. |
| `renderParams: https://developer.android.com/reference/kotlin/androidx/pdf/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 `https://developer.android.com/reference/kotlin/androidx/pdf/RenderParams` with `https://developer.android.com/reference/kotlin/androidx/pdf/RenderParams#renderMode()` = `https://developer.android.com/reference/kotlin/androidx/pdf/RenderParams#RENDER_MODE_FOR_DISPLAY()` will be used. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument` | The opened `https://developer.android.com/reference/kotlin/androidx/pdf/PdfDocument`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/pdf/PdfPasswordException` | If the provided password is incorrect. |
| `https://developer.android.com/reference/java/io/IOException.html` | If an error occurs while opening the document. |