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