1/* Copyright (c) 2013 The Chromium Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 7/** 8 * This file defines methods for use with a PPB_FileIO resource that may become 9 * stable in the future. For now, they can be used only in plugins with DEV 10 * permissions. 11 */ 12 13label Chrome { 14 M31 = 0.1 15}; 16 17/** 18 * The PP_FileMapProtection values indicate the permissions requested for the 19 * file mapping. These should be used in a uint32_t bitfield. 20 */ 21[assert_size(4)] 22 enum PP_FileMapProtection { 23 /** Requests read access to the mapped address. */ 24 PP_FILEMAPPROTECTION_READ = 1u << 0, 25 26 /** Requests write access to the mapped address. */ 27 PP_FILEMAPPROTECTION_WRITE = 1u << 1 28}; 29 30/** 31 * The PP_FileMapFlags contain flag values for use with Map(). 32 */ 33[assert_size(4)] 34 enum PP_FileMapFlags { 35 /** 36 * Requests a shared mapping. If this flag is set, changes written to the 37 * memory region will be reflected in the underlying file and will thus 38 * eventually be visible to other processes which have opened the file. The 39 * file may not actually be updated until Unmap() is called. This is only 40 * valid if the PPB_FileIO resource was opened with write permission. 41 */ 42 PP_FILEMAPFLAG_SHARED = 1u << 0, 43 44 /** 45 * Requests a copy-on-write mapping. If this flag is set, changes are not 46 * written to the underlying file, but only in the memory of the process 47 * (copy-on-write). 48 */ 49 PP_FILEMAPFLAG_PRIVATE = 1u << 1, 50 51 /** 52 * Forces Map() to map the file contents at the provided |address|. If Map() 53 * can not comply, Map() will fail. 54 */ 55 PP_FILEMAPFLAG_FIXED = 1u << 2 56}; 57 58/** 59 * PPB_FileIO_Dev contains functions that are usable with PPB_FileIO resources 60 * but aren't yet considered stable yet and thus are not supported for general 61 * NaCl or PNaCl apps yet. Features here are being tested and refined for 62 * possible future inclusion in (stable) PPB_FileIO. 63 */ 64interface PPB_FileIO_Dev { 65 /** 66 * Map() maps the contents from an offset of the file into memory. 67 * 68 * @param[in] file_io A PP_Resource corresponding to a file. 69 * @param[in] length The number of bytes to map. 70 * @param[in] map_protection A bitfield containing values from 71 * PP_FileMapProtection, indicating what memory operations should be permitted 72 * on the mapped region. 73 * @param[in] map_flags A bitfield containing values from 74 * PP_FileMapFlags, providing options for the behavior of Map. If the region 75 * is to be writeable, then exactly one of PP_FILEMAPFLAG_SHARED or 76 * PP_FILEMAPFLAG_PRIVATE must be set. 77 * @param[in] offset The offset into the file. Must be a multiple of the 78 * Map page size as returned by GetMapPageSize. 79 * @param[inout] address The value of |*address|, if non-NULL, will be used as 80 * a hint to determine where in memory the file should be mapped. If the value 81 * is NULL, the host operating system will choose |address|. Upon 82 * Map() completing, |*address| will contain the actual memory location at 83 * which the file was mapped. If the plugin provides a non-NULL |*address|, it 84 * must be a multiple of the map page size as returned by GetMapPageSize(). 85 * @param[in] callback A PP_CompletionCallback to be called upon 86 * completion of Map(). 87 * 88 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 89 */ 90 int32_t Map([in] PP_Resource file_io, 91 [in] int64_t length, 92 [in] uint32_t map_protection, 93 [in] uint32_t map_flags, 94 [in] int64_t offset, 95 [inout] mem_ptr_t address, 96 [in] PP_CompletionCallback callback); 97 98 /** 99 * Unmap() deletes the mapping of the specified address address to a 100 * file io. The specified address must have been retrieved with 101 * Map(). 102 * @param[in] file_io A PP_Resource corresponding to a file. 103 * @param[in] address The starting address of the address in memory to 104 * be unmapped. 105 * @param[in] length The length of the region to unmap. 106 */ 107 void Unmap(PP_Resource file_io, mem_t address, int64_t length); 108 109 /** 110 * GetMapPageSize() returns the size of pages that Map() uses. Returns 0 on 111 * failure. 112 */ 113 [on_failure=0] 114 int64_t GetMapPageSize(PP_Resource file_io); 115}; 116 117