15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This file defines the <code>PPB_VarArrayBuffer</code> struct providing 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * a way to interact with JavaScript ArrayBuffers. 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)label Chrome { 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) M18 = 1.0 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with JavaScript ArrayBuffers, which represent a contiguous sequence of 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * bytes. Use <code>PPB_Var</code> to manage the reference count for a 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>VarArrayBuffer</code>. Note that these Vars are not part of the 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * embedding page's DOM, and can only be shared with JavaScript using the 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PostMessage</code> and <code>HandleMessage</code> functions of 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>pp::Instance</code>. 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)[macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"] 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)interface PPB_VarArrayBuffer { 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Create() creates a zero-initialized <code>VarArrayBuffer</code>. 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be created. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * of the requested size and with a reference count of 1. 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Var Create([in] uint32_t size_in_bytes); 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * bytes. On success, <code>byte_length</code> is set to the length of the 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * is unchanged (this could happen, for instance, if the given 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Note that ByteLength() will successfully retrieve the size of an 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * currently mapped. 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> whose length should be 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * returned. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[out] byte_length A variable which is set to the length of the given 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code> on success. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length); 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Map() maps the <code>ArrayBuffer</code> in to the module's address space 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and returns a pointer to the beginning of the buffer for the given 602a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted, 612a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * so changes to the underlying memory are not automatically available to 622a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * the embedding page. 632a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * 642a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Note that calling Map() can be a relatively expensive operation. Use care 652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * when calling it in performance-critical code. For example, you should call 662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * it only once when looping over an <code>ArrayBuffer</code>. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Example:</strong> 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @code 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * uint32_t byte_length = 0; 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if (!ok) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * for (uint32_t i = 0; i < byte_length; ++i) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * data[i] = 'A'; 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @endcode 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be returned. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A pointer to the internal buffer for this 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code>. Returns <code>NULL</code> 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if the given <code>PP_Var</code> is not of type 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_VARTYPE_ARRAY_BUFFER</code>. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) mem_t Map([in] PP_Var array); 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * address space. Use this if you want to save memory but might want to call 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Map() to map the buffer again later. The <code>PP_Var</code> remains valid 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and should still be released using <code>PPB_Var</code> when you are done 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with the <code>ArrayBuffer</code>. 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> to be released. 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Unmap([in] PP_Var array); 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 102