1/* Copyright (c) 2012 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 * This file defines the <code>PPB_VarArrayBuffer</code> struct providing
8 * a way to interact with JavaScript ArrayBuffers.
9 */
10
11label Chrome {
12  M18 = 1.0
13};
14
15/**
16 * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact
17 * with JavaScript ArrayBuffers, which represent a contiguous sequence of
18 * bytes. Use <code>PPB_Var</code> to manage the reference count for a
19 * <code>VarArrayBuffer</code>. Note that these Vars are not part of the
20 * embedding page's DOM, and can only be shared with JavaScript using the
21 * <code>PostMessage</code> and <code>HandleMessage</code> functions of
22 * <code>pp::Instance</code>.
23 */
24[macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"]
25interface PPB_VarArrayBuffer {
26  /**
27   * Create() creates a zero-initialized <code>VarArrayBuffer</code>.
28   *
29   * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to
30   * be created.
31   *
32   * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code>
33   * of the requested size and with a reference count of 1.
34   */
35  PP_Var Create([in] uint32_t size_in_bytes);
36
37  /**
38   * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
39   * bytes. On success, <code>byte_length</code> is set to the length of the
40   * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code>
41   * is unchanged (this could happen, for instance, if the given
42   * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>).
43   * Note that ByteLength() will successfully retrieve the size of an
44   * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not
45   * currently mapped.
46   *
47   * @param[in] array The <code>ArrayBuffer</code> whose length should be
48   * returned.
49   *
50   * @param[out] byte_length A variable which is set to the length of the given
51   * <code>ArrayBuffer</code> on success.
52   *
53   * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure.
54   */
55  PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length);
56
57  /**
58   * Map() maps the <code>ArrayBuffer</code> in to the module's address space
59   * and returns a pointer to the beginning of the buffer for the given
60   * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted,
61   * so changes to the underlying memory are not automatically available to
62   * the embedding page.
63   *
64   * Note that calling Map() can be a relatively expensive operation. Use care
65   * when calling it in performance-critical code. For example, you should call
66   * it only once when looping over an <code>ArrayBuffer</code>.
67   *
68   * <strong>Example:</strong>
69   *
70   * @code
71   * char* data = (char*)(array_buffer_if.Map(array_buffer_var));
72   * uint32_t byte_length = 0;
73   * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
74   * if (!ok)
75   *   return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
76   * for (uint32_t i = 0; i < byte_length; ++i)
77   *   data[i] = 'A';
78   * @endcode
79   *
80   * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should
81   * be returned.
82   *
83   * @return A pointer to the internal buffer for this
84   * <code>ArrayBuffer</code>. Returns <code>NULL</code>
85   * if the given <code>PP_Var</code> is not of type
86   * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
87   */
88  mem_t Map([in] PP_Var array);
89
90  /**
91   * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module
92   * address space. Use this if you want to save memory but might want to call
93   * Map() to map the buffer again later. The <code>PP_Var</code> remains valid
94   * and should still be released using <code>PPB_Var</code> when you are done
95   * with the <code>ArrayBuffer</code>.
96   *
97   * @param[in] array The <code>ArrayBuffer</code> to be released.
98   */
99  void Unmap([in] PP_Var array);
100};
101
102