Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
| 16 | namespace 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. |
| 26 | template<typename ResourceObjectType> |
| 27 | inline 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. |
| 41 | class 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 | // } |
| 83 | template<typename T> |
| 84 | class 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 | // } |
| 126 | template<typename T> |
| 127 | class 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(); |
| 175 | template<typename T> |
| 176 | class ArrayOutputAdapterWithStorage : public ArrayOutputAdapter<T> { |
| 177 | public: |
| 178 | ArrayOutputAdapterWithStorage() { |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 179 | this->set_output(&output_storage_); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
| 201 | class 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(). |
| 233 | template<typename T> |
| 234 | class 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 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 270 | } // namespace pp |
| 271 | |
| 272 | #endif // PPAPI_CPP_ARRAY_OUTPUT_H_ |