/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
/**
* This file defines the PPB_VarArrayBuffer
struct providing
* a way to interact with JavaScript ArrayBuffers.
*/
label Chrome {
M18 = 1.0
};
/**
* The PPB_VarArrayBuffer
interface provides a way to interact
* with JavaScript ArrayBuffers, which represent a contiguous sequence of
* bytes. Use PPB_Var
to manage the reference count for a
* VarArrayBuffer
. Note that these Vars are not part of the
* embedding page's DOM, and can only be shared with JavaScript using the
* PostMessage
and HandleMessage
functions of
* pp::Instance
.
*/
[macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"]
interface PPB_VarArrayBuffer {
/**
* Create() creates a zero-initialized VarArrayBuffer
.
*
* @param[in] size_in_bytes The size of the ArrayBuffer
to
* be created.
*
* @return A PP_Var
representing a VarArrayBuffer
* of the requested size and with a reference count of 1.
*/
PP_Var Create([in] uint32_t size_in_bytes);
/**
* ByteLength() retrieves the length of the VarArrayBuffer
in
* bytes. On success, byte_length
is set to the length of the
* given ArrayBuffer
var. On failure, byte_length
* is unchanged (this could happen, for instance, if the given
* PP_Var
is not of type PP_VARTYPE_ARRAY_BUFFER
).
* Note that ByteLength() will successfully retrieve the size of an
* ArrayBuffer
even if the ArrayBuffer
is not
* currently mapped.
*
* @param[in] array The ArrayBuffer
whose length should be
* returned.
*
* @param[out] byte_length A variable which is set to the length of the given
* ArrayBuffer
on success.
*
* @return PP_TRUE
on success, PP_FALSE
on failure.
*/
PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length);
/**
* Map() maps the ArrayBuffer
in to the module's address space
* and returns a pointer to the beginning of the buffer for the given
* ArrayBuffer PP_Var
. Note that calling Map() can be a
* relatively expensive operation. Use care when calling it in
* performance-critical code. For example, you should call it only once when
* looping over an ArrayBuffer
.
*
* Example:
*
* @code
* char* data = (char*)(array_buffer_if.Map(array_buffer_var));
* uint32_t byte_length = 0;
* PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
* if (!ok)
* return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
* for (uint32_t i = 0; i < byte_length; ++i)
* data[i] = 'A';
* @endcode
*
* @param[in] array The ArrayBuffer
whose internal buffer should
* be returned.
*
* @return A pointer to the internal buffer for this
* ArrayBuffer
. Returns NULL
* if the given PP_Var
is not of type
* PP_VARTYPE_ARRAY_BUFFER
.
*/
mem_t Map([in] PP_Var array);
/**
* Unmap() unmaps the given ArrayBuffer
var from the module
* address space. Use this if you want to save memory but might want to call
* Map() to map the buffer again later. The PP_Var
remains valid
* and should still be released using PPB_Var
when you are done
* with the ArrayBuffer
.
*
* @param[in] array The ArrayBuffer
to be released.
*/
void Unmap([in] PP_Var array);
};