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) 62a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)/* From ppb_var_array_buffer.idl modified Thu Feb 28 09:24:06 2013. */ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_bool.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_macros.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_stdint.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_var.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0 "PPB_VarArrayBuffer;1.0" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPB_VAR_ARRAY_BUFFER_INTERFACE PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @file 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This file defines the <code>PPB_VarArrayBuffer</code> struct providing 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * a way to interact with JavaScript ArrayBuffers. 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @addtogroup Interfaces 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @{ 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with JavaScript ArrayBuffers, which represent a contiguous sequence of 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * bytes. Use <code>PPB_Var</code> to manage the reference count for a 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>VarArrayBuffer</code>. Note that these Vars are not part of the 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * embedding page's DOM, and can only be shared with JavaScript using the 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PostMessage</code> and <code>HandleMessage</code> functions of 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>pp::Instance</code>. 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)struct PPB_VarArrayBuffer_1_0 { 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Create() creates a zero-initialized <code>VarArrayBuffer</code>. 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be created. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code> 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * of the requested size and with a reference count of 1. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) struct PP_Var (*Create)(uint32_t size_in_bytes); 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * bytes. On success, <code>byte_length</code> is set to the length of the 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code> 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * is unchanged (this could happen, for instance, if the given 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>). 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Note that ByteLength() will successfully retrieve the size of an 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * currently mapped. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> whose length should be 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * returned. 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[out] byte_length A variable which is set to the length of the given 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code> on success. 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length); 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Map() maps the <code>ArrayBuffer</code> in to the module's address space 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and returns a pointer to the beginning of the buffer for the given 722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted, 732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * so changes to the underlying memory are not automatically available to 742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * the embedding page. 752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * 762a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * Note that calling Map() can be a relatively expensive operation. Use care 772a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * when calling it in performance-critical code. For example, you should call 782a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) * it only once when looping over an <code>ArrayBuffer</code>. 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Example:</strong> 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @code 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * char* data = (char*)(array_buffer_if.Map(array_buffer_var)); 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * uint32_t byte_length = 0; 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length); 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if (!ok) 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * return DoSomethingBecauseMyVarIsNotAnArrayBuffer(); 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * for (uint32_t i = 0; i < byte_length; ++i) 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * data[i] = 'A'; 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @endcode 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * be returned. 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @return A pointer to the internal buffer for this 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>ArrayBuffer</code>. Returns <code>NULL</code> 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * if the given <code>PP_Var</code> is not of type 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>PP_VARTYPE_ARRAY_BUFFER</code>. 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void* (*Map)(struct PP_Var array); 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * address space. Use this if you want to save memory but might want to call 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Map() to map the buffer again later. The <code>PP_Var</code> remains valid 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and should still be released using <code>PPB_Var</code> when you are done 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with the <code>ArrayBuffer</code>. 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] array The <code>ArrayBuffer</code> to be released. 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void (*Unmap)(struct PP_Var array); 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)typedef struct PPB_VarArrayBuffer_1_0 PPB_VarArrayBuffer; 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @} 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif /* PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ */ 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 120