osl_unmapFile can't work for files bundled inside the .apk on Android

On Android, when an app is installed, arbitrary files bundled in the
app won't be unpacked into actual separate files in the file
system. They will exist only as archive entries in the .apk file
(which is a zip archive).

The SDK tooling puts such files under the /assets folder in the
.apk. The LibreOffice bootstrapping code for Android maps the .apk
file into memory.

osl_openFile() knows about the /assets special case, and uses a
separate abstraction for such memory-mapped files.

Obviously, when producing an .apk, one needs to make sure these
bundled files are not compressed, if one wants to be able to use them
directly from the memory-mapped .apk file. We do that in our test and
sample Android projects.

When mapping such files under /assets , just return a pointer to the
file's location inside the mapped .apk archive.

We can't use the old osl_unmapFile() on such mapped files, as that
would unexpectedly unmap fairly arbitrary pages of the .apk mapping,
wreaking havoc on later use of the same pages.

So, introduce a new osl_unmapMappedFile() function that takes also the
oslFileHandle originally passed to osl_mapFile(). Use this instead in
the few places where the code actually called osl_unmapFile(). Make
sure osl_mapFile() is nonexistent on Android.

1 files changed, 45 insertions, 0 deletions

diff --git a/sal/inc/osl/file.h b/sal/inc/osl/file.h
index cc12b1c616f8..ecf9e60a4d68 100644
--- a/sal/inc/osl/file.h
+++ b/sal/inc/osl/file.h
@@ -680,6 +680,12 @@ typedef void *oslFileHandle;
     @param uFlags [in]
     Specifies the open mode.
 
+    On Android, if the file path is below the /assets folder, the file
+    exists only as a hopefully uncompressed element inside the app
+    package (.apk), which has been mapped into memory as a whole by
+    the LibreOffice Android bootstrapping code. So files "opened" from
+    there aren't actually files in the OS sense.
+
     @return
     osl_File_E_None on success<br>
     osl_File_E_NOMEM not enough memory for allocating structures <br>
@@ -837,6 +843,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileSize(
 
 /** Map a shared file into memory.
 
+    Don't know what the "shared" is supposed to mean there? Also,
+    obviously this API can be used to map *part* of a file into
+    memory, and different parts can be mapped separately even.
+
+    On Android, if the Handle refers to a file that is actually inside
+    the app package (.apk zip archive), no new mapping is created,
+    just a pointer to the file inside the already mapped .apk is
+    returned.
+
     @since UDK 3.2.10
  */
 SAL_DLLPUBLIC oslFileError SAL_CALL osl_mapFile (
@@ -848,8 +863,19 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_mapFile (
 );
 
 
+#ifndef ANDROID
+
 /** Unmap a shared file from memory.
 
+    Ditto here, why do we need to mention "shared"?
+
+    This function just won't work on Android in general where for
+    (uncompressed) files inside the .apk, per SDK conventions in the
+    /assets folder, osl_mapFile() returns a pointer to the file inside
+    the already by LibreOffice Android-specific bootstrapping code
+    mmapped .apk archive. We can't go and randomly munmap part of the
+    .apk archive. So this function is not present on Android.
+
     @since UDK 3.2.10
  */
 SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapFile (
@@ -857,6 +883,25 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapFile (
   sal_uInt64 uLength
 );
 
+#endif
+
+/** Unmap a file segment from memory.
+
+    Like osl_unmapFile(), but takes also the oslFileHandle argument
+    passed to osl_mapFile() when creating this mapping.
+
+    On Android, for files below /assets, i.e. located inside the app
+    archive (.apk), this won't actually unmap anything; all the .apk
+    stays mapped.
+
+    @since UDK 3.6
+ */
+SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapMappedFile (
+  oslFileHandle Handle,
+  void*      pAddr,
+  sal_uInt64 uLength
+);
+
 
 /** Read a number of bytes from a file.