1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.pdf;
18 
19 import android.graphics.Bitmap;
20 import android.graphics.Rect;
21 import android.graphics.pdf.content.PdfPageGotoLinkContent;
22 import android.graphics.pdf.content.PdfPageImageContent;
23 import android.graphics.pdf.content.PdfPageLinkContent;
24 import android.graphics.pdf.content.PdfPageTextContent;
25 import android.graphics.pdf.models.PageMatchBounds;
26 import android.graphics.pdf.models.selection.PageSelection;
27 import android.graphics.pdf.models.selection.SelectionBoundary;
28 import android.os.ParcelFileDescriptor;
29 import androidx.pdf.models.Dimensions;
30 
31 /** Remote interface for interacting with a PDF document */
32 @JavaPassthrough(annotation="@androidx.annotation.RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY)")
33 interface PdfDocumentRemote {
34     /**
35      * Opens a PDF document from the given ParcelFileDescriptor.
36      *
37      * @param pfd The ParcelFileDescriptor containing the PDF data.
38      * @param password The password to unlock the PDF, or null if not required.
39      * @return A status code indicating the result of the operation (see {@link PdfStatus}).
40      */
openPdfDocument(in ParcelFileDescriptor pfd, String password)41     int openPdfDocument(in ParcelFileDescriptor pfd, String password);
42 
43     /**
44      * Gets the total number of pages in the document.
45      *
46      * @return The number of pages.
47      */
numPages()48     int numPages();
49 
50 
51     /**
52      * Gets the dimensions (width and height) of the specified page.
53      *
54      * @param pageNum The page number (0-based).
55      * @return A Dimensions object containing the width and height of the page.
56      */
getPageDimensions(int pageNum)57     Dimensions getPageDimensions(int pageNum);
58 
59     /**
60      * Renders the specified page of the PDF document into a Bitmap.
61      *
62      * @param pageNum The zero-based page number to render.
63      * @param width The desired width of the resulting Bitmap.
64      * @param height The desired height of the resulting Bitmap.
65      * @return A Bitmap representation of the specified page, or null if an error occurs.
66      */
getPageBitmap(int pageNum, int width, int height)67     Bitmap getPageBitmap(int pageNum, int width, int height);
68 
69     /**
70      * Renders a tile of the specified page into a Bitmap.
71      *
72      * <p>This method is useful for rendering large PDF pages in chunks to avoid excessive
73      * memory consumption.</p>
74      *
75      * @param pageNum The zero-based page number to render.
76      * @param tileWidth The width of the tile to render.
77      * @param tileHeight The height of the tile to render.
78      * @param pageWidth The width of the whole PDF page.
79      * @param pageHeight The height of the whole PDF page.
80      * @param offsetX The horizontal offset of the tile within the page.
81      * @param offsetY The vertical offset of the tile within the page.
82      * @return A Bitmap representation of the specified tile, or null if an error occurs.
83      */
getTileBitmap(int pageNum, int tilewidth, int tileHeight, int pageWidth, int pageHeight, int offsetX, int offsetY)84     Bitmap getTileBitmap(int pageNum, int tilewidth, int tileHeight, int pageWidth, int pageHeight, int offsetX, int offsetY);
85 
86     /**
87      * Gets the text content of the specified page.
88      *
89      * @param pageNum The page number (0-based).
90      * @return A list of {@link PdfPageTextContent} on the page.
91      */
getPageText(int pageNum)92     List<PdfPageTextContent> getPageText(int pageNum);
93 
94     /**
95      * Searches the specified page for the given query and returns the matching regions.
96      *
97      * @param pageNum The page number (0-based).
98      * @param query The search query string.
99      * @return A list of {@link PageMatchBounds} objects representing the matching regions.
100      */
searchPageText(int pageNum, String query)101     List<PageMatchBounds> searchPageText(int pageNum, String query);
102 
103     /**
104      * Selects text on the specified page based on the given selection boundaries.
105      *
106      * @param pageNum The page number (0-based).
107      * @param start The starting boundary of the selection.
108      * @param stop The ending boundary of the selection.
109      * @return The {@link PageSelection} result.
110      */
selectPageText(int pageNum, in SelectionBoundary start, in SelectionBoundary stop)111     PageSelection selectPageText(int pageNum, in SelectionBoundary start, in SelectionBoundary stop);
112 
113     /**
114      * Gets a list of external links present on the specified page.
115      *
116      * @param pageNum The page number (0-based).
117      * @return A list of all external link {@link PdfPageLinkContent} objects on the page.
118      */
getPageExternalLinks(int pageNum)119     List<PdfPageLinkContent> getPageExternalLinks(int pageNum);
120 
121     /**
122      * Gets a list of "Go To" links and bookmarks present on the specified page.
123      *
124      * @param pageNum The page number (0-based).
125      * @return A list of all "GoTo" link {@link PdfPageGotoLinkContent} objects on the page.
126      */
getPageGotoLinks(int pageNum)127     List<PdfPageGotoLinkContent> getPageGotoLinks(int pageNum);
128 
129     /**
130      * Gets the image content of the specified page.
131      *
132      * @param pageNum The page number (0-based).
133      * @return A list of {@link PdfPageImageContent} on the page.
134      */
getPageImageContent(int pageNum)135     List<PdfPageImageContent> getPageImageContent(int pageNum);
136 
137     /**
138      * Checks if the PDF is linearized (optimized for fast web viewing).
139      *
140      * @return True if the PDF is linearized, false otherwise.
141      */
isPdfLinearized()142     boolean isPdfLinearized();
143 
144     /**
145      * Gets the type of form present in the document.
146      *
147      * @return The form type.
148      */
getFormType()149     int getFormType();
150 
151     /**
152      * Releases resources associated with the specified page.
153      *
154      * @param pageNum The page number (0-based) to release.
155      */
releasePage(int pageNum)156     void releasePage(int pageNum);
157 
158     /**
159      * Closes the currently open PDF document and releases associated resources.
160      *
161      * <p>This method should be called when the client is finished working with the
162      * PDF document to ensure proper cleanup.</p>
163      */
closePdfDocument()164     void closePdfDocument();
165 }