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#ifndef PPAPI_CPP_ARRAY_OUTPUT_H_ 6#define PPAPI_CPP_ARRAY_OUTPUT_H_ 7 8#include <vector> 9 10#include "ppapi/c/pp_array_output.h" 11#include "ppapi/c/pp_resource.h" 12#include "ppapi/cpp/logging.h" 13#include "ppapi/cpp/pass_ref.h" 14#include "ppapi/cpp/var.h" 15 16namespace pp { 17 18// Converts the given array of PP_Resources into an array of the requested 19// C++ resource types, passing ownership of a reference in the process. 20// 21// This is used to convert output arrays of resources that the browser has 22// generated into the more convenient C++ wrappers for those resources. The 23// initial "PassRef" parameter is there to emphasize what happens to the 24// reference count of the input resource and to match the resource constructors 25// that look the same. 26template<typename ResourceObjectType> 27inline void ConvertPPResourceArrayToObjects( 28 PassRef, 29 const std::vector<PP_Resource>& input, 30 std::vector<ResourceObjectType>* output) { 31 output->resize(0); 32 output->reserve(input.size()); 33 for (size_t i = 0; i < input.size(); i++) 34 output->push_back(ResourceObjectType(PASS_REF, input[i])); 35} 36 37// Non-templatized base class for the array output conversion. It provides the 38// C implementation of a PP_ArrayOutput whose callback function is implemented 39// as a virtual call on a derived class. Do not use directly, use one of the 40// derived classes below. 41class ArrayOutputAdapterBase { 42 public: 43 ArrayOutputAdapterBase() { 44 pp_array_output_.GetDataBuffer = 45 &ArrayOutputAdapterBase::GetDataBufferThunk; 46 pp_array_output_.user_data = this; 47 } 48 virtual ~ArrayOutputAdapterBase() {} 49 50 const PP_ArrayOutput& pp_array_output() { return pp_array_output_; } 51 52 protected: 53 virtual void* GetDataBuffer(uint32_t element_count, 54 uint32_t element_size) = 0; 55 56 private: 57 static void* GetDataBufferThunk(void* user_data, 58 uint32_t element_count, 59 uint32_t element_size); 60 61 PP_ArrayOutput pp_array_output_; 62 63 // Disallow copying and assignment. This will do the wrong thing for most 64 // subclasses. 65 ArrayOutputAdapterBase(const ArrayOutputAdapterBase&); 66 ArrayOutputAdapterBase& operator=(const ArrayOutputAdapterBase&); 67}; 68 69// This adapter provides functionality for implementing a PP_ArrayOutput 70// structure as writing to a given vector object. 71// 72// This is generally used internally in the C++ wrapper objects to 73// write into an output parameter supplied by the plugin. If the element size 74// that the browser is writing does not match the size of the type we're using 75// this will assert and return NULL (which will cause the browser to fail the 76// call). 77// 78// Example that allows the browser to write into a given vector: 79// void DoFoo(std::vector<int>* results) { 80// ArrayOutputAdapter<int> adapter(results); 81// ppb_foo->DoFoo(adapter.pp_array_output()); 82// } 83template<typename T> 84class ArrayOutputAdapter : public ArrayOutputAdapterBase { 85 public: 86 ArrayOutputAdapter(std::vector<T>* output) : output_(output) {} 87 88 protected: 89 // Two-step init for the "with storage" version below. 90 ArrayOutputAdapter() : output_(NULL) {} 91 void set_output(std::vector<T>* output) { output_ = output; } 92 93 // ArrayOutputAdapterBase implementation. 94 virtual void* GetDataBuffer(uint32_t element_count, uint32_t element_size) { 95 if (element_count == 0) 96 return NULL; 97 PP_DCHECK(element_size == sizeof(T)); 98 if (element_size != sizeof(T)) 99 return NULL; 100 output_->resize(element_count); 101 return &(*output_)[0]; 102 } 103 104 private: 105 std::vector<T>* output_; 106}; 107 108// This adapter provides functionality for implementing a PP_ArrayOutput 109// structure as writing resources to a given vector object. 110// 111// When returning an array of resources, the browser will write PP_Resources 112// via a PP_ArrayOutput. This code will automatically convert the PP_Resources 113// to the given wrapper type, (as long as that wrapper type supports the 114// correct constructor). The ownership of the resources that the browser passed 115// to us will be transferred to the C++ wrapper object. 116// 117// Conversion of the PP_Resources to the C++ wrapper object occurs in the 118// destructor. This object is intended to be used on the stack in a C++ wrapper 119// object for a call. 120// 121// Example: 122// void GetFiles(std::vector<pp::FileRef>* results) { 123// ResourceArrayOutputAdapter<pp::FileRef> adapter(results); 124// ppb_foo->DoFoo(adapter.pp_array_output()); 125// } 126template<typename T> 127class ResourceArrayOutputAdapter : public ArrayOutputAdapterBase { 128 public: 129 explicit ResourceArrayOutputAdapter(std::vector<T>* output) 130 : output_(output) { 131 output_->resize(0); 132 } 133 virtual ~ResourceArrayOutputAdapter() { 134 ConvertPPResourceArrayToObjects(PASS_REF, intermediate_output_, output_); 135 } 136 137 protected: 138 // Two-step init for the "with storage" version below. 139 ResourceArrayOutputAdapter() : output_(NULL) {} 140 void set_output(T* output) { output_ = output; } 141 142 // ArrayOutputAdapterBase implementation. 143 virtual void* GetDataBuffer(uint32_t element_count, 144 uint32_t element_size) { 145 if (element_count == 0) 146 return NULL; 147 PP_DCHECK(element_size == sizeof(PP_Resource)); 148 if (element_size != sizeof(PP_Resource)) 149 return NULL; 150 intermediate_output_.resize(element_count); 151 return &intermediate_output_[0]; 152 } 153 154 private: 155 std::vector<PP_Resource> intermediate_output_; 156 std::vector<T>* output_; 157}; 158 159// This adapter is like the ArrayOutputAdapter except that it also contains 160// the underlying std::vector that will be populated (rather than writing it to 161// an object passed into the constructor). 162// 163// This is used by the CompletionCallbackFactory system to collect the output 164// parameters from an async function call. The collected data is then passed to 165// the plugins callback function. 166// 167// You can also use it directly if you want to have an array output and aren't 168// using the CompletionCallbackFactory. For example, if you're calling a 169// PPAPI function DoFoo that takes a PP_OutputArray that is supposed to be 170// writing integers, do this: 171// 172// ArrayOutputAdapterWithStorage<int> adapter; 173// ppb_foo->DoFoo(adapter.pp_output_array()); 174// const std::vector<int>& result = adapter.output(); 175template<typename T> 176class ArrayOutputAdapterWithStorage : public ArrayOutputAdapter<T> { 177 public: 178 ArrayOutputAdapterWithStorage() { 179 this->set_output(&output_storage_); 180 } 181 182 std::vector<T>& output() { return output_storage_; } 183 184 private: 185 std::vector<T> output_storage_; 186}; 187 188// This adapter is like the ArrayOutputAdapterWithStorage except this 189// additionally converts PP_Var structs to pp::Var objects. 190// 191// You can also use it directly if you want to have an array output and aren't 192// using the CompletionCallbackFactory. For example, if you're calling a 193// PPAPI function GetVars that takes a PP_OutputArray that is supposed to be 194// writing PP_Vars, do this: 195// 196// VarArrayOutputAdapterWithStorage adapter; 197// ppb_foo->GetVars(adapter.pp_output_array()); 198// const std::vector<pp::Var>& result = adapter.output(). 199// 200// This one is non-inline since it's not templatized. 201class VarArrayOutputAdapterWithStorage : public ArrayOutputAdapter<PP_Var> { 202 public: 203 VarArrayOutputAdapterWithStorage(); 204 virtual ~VarArrayOutputAdapterWithStorage(); 205 206 // Returns the final array of resource objects, converting the PP_Vars 207 // written by the browser to pp::Var objects. 208 // 209 // This function should only be called once or we would end up converting 210 // the array more than once, which would mess up the refcounting. 211 std::vector<Var>& output(); 212 213 private: 214 // The browser will write the PP_Vars into this array. 215 std::vector<PP_Var> temp_storage_; 216 217 // When asked for the output, the resources above will be converted to the 218 // C++ resource objects in this array for passing to the calling code. 219 std::vector<Var> output_storage_; 220}; 221 222// This adapter is like the ArrayOutputAdapterWithStorage except this 223// additionally converts PP_Resources to C++ wrapper objects of the given type. 224// 225// You can also use it directly if you want to have an array output and aren't 226// using the CompletionCallbackFactory. For example, if you're calling a 227// PPAPI function GetFiles that takes a PP_OutputArray that is supposed to be 228// writing PP_Resources cooresponding to FileRefs, do this: 229// 230// ResourceArrayOutputAdapterWithStorage<FileRef> adapter; 231// ppb_foo->GetFiles(adapter.pp_output_array()); 232// std::vector<FileRef> result = adapter.output(). 233template<typename T> 234class ResourceArrayOutputAdapterWithStorage 235 : public ArrayOutputAdapter<PP_Resource> { 236 public: 237 ResourceArrayOutputAdapterWithStorage() { 238 set_output(&temp_storage_); 239 } 240 241 virtual ~ResourceArrayOutputAdapterWithStorage() { 242 if (!temp_storage_.empty()) { 243 // An easy way to release the resource references held by this object. 244 output(); 245 } 246 } 247 248 // Returns the final array of resource objects, converting the PP_Resources 249 // written by the browser to resource objects. 250 // 251 // This function should only be called once or we would end up converting 252 // the array more than once, which would mess up the refcounting. 253 std::vector<T>& output() { 254 PP_DCHECK(output_storage_.empty()); 255 256 ConvertPPResourceArrayToObjects(PASS_REF, temp_storage_, &output_storage_); 257 temp_storage_.clear(); 258 return output_storage_; 259 } 260 261 private: 262 // The browser will write the PP_Resources into this array. 263 std::vector<PP_Resource> temp_storage_; 264 265 // When asked for the output, the resources above will be converted to the 266 // C++ resource objects in this array for passing to the calling code. 267 std::vector<T> output_storage_; 268}; 269 270} // namespace pp 271 272#endif // PPAPI_CPP_ARRAY_OUTPUT_H_ 273