1 // Copyright (c) 2011 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 CONTENT_RENDERER_PEPPER_NPAPI_GLUE_H_ 6 #define CONTENT_RENDERER_PEPPER_NPAPI_GLUE_H_ 7 8 #include "base/basictypes.h" 9 #include "base/memory/scoped_ptr.h" 10 #include "content/common/content_export.h" 11 #include "ppapi/c/pp_module.h" 12 #include "ppapi/c/pp_var.h" 13 14 struct NPObject; 15 typedef struct _NPVariant NPVariant; 16 typedef void* NPIdentifier; 17 18 namespace content { 19 20 class PepperPluginInstanceImpl; 21 class PluginObject; 22 23 // Utilities ------------------------------------------------------------------- 24 25 // Converts the given PP_Var to an NPVariant, returning true on success. 26 // False means that the given variant is invalid. In this case, the result 27 // NPVariant will be set to a void one. 28 // 29 // The contents of the PP_Var will be copied unless the PP_Var corresponds to 30 // an object. 31 bool PPVarToNPVariant(PP_Var var, NPVariant* result); 32 33 // Returns a PP_Var that corresponds to the given NPVariant. The contents of 34 // the NPVariant will be copied unless the NPVariant corresponds to an 35 // object. This will handle all Variant types including POD, strings, and 36 // objects. 37 // 38 // The returned PP_Var will have a refcount of 1, this passing ownership of 39 // the reference to the caller. This is suitable for returning to a plugin. 40 PP_Var NPVariantToPPVar(PepperPluginInstanceImpl* instance, 41 const NPVariant* variant); 42 43 // Returns a NPIdentifier that corresponds to the given PP_Var. The contents 44 // of the PP_Var will be copied. Returns 0 if the given PP_Var is not a a 45 // string or integer type. 46 NPIdentifier PPVarToNPIdentifier(PP_Var var); 47 48 // Returns a PP_Var corresponding to the given identifier. In the case of 49 // a string identifier, the returned string will have a reference count of 1. 50 PP_Var NPIdentifierToPPVar(NPIdentifier id); 51 52 // Helper function to create a PP_Var of type object that contains the given 53 // NPObject for use byt he given module. Calling this function multiple times 54 // given the same module + NPObject results in the same PP_Var, assuming that 55 // there is still a PP_Var with a reference open to it from the previous 56 // call. 57 // 58 // The instance is necessary because we can have different instances pointing to 59 // the same NPObject, and we want to keep their refs separate. 60 // 61 // If no ObjectVar currently exists corresponding to the NPObject, one is 62 // created associated with the given module. 63 // 64 // Note: this could easily be changed to take a PP_Instance instead if that 65 // makes certain calls in the future easier. Currently all callers have a 66 // PluginInstance so that's what we use here. 67 CONTENT_EXPORT PP_Var 68 NPObjectToPPVar(PepperPluginInstanceImpl* instance, NPObject* object); 69 70 // This version creates a default v8::Context rather than using the one from 71 // the container of |instance|. It is only for use in unit tests, where we don't 72 // have a real container for |instance|. 73 CONTENT_EXPORT PP_Var NPObjectToPPVarForTest(PepperPluginInstanceImpl* instance, 74 NPObject* object); 75 76 // PPResultAndExceptionToNPResult ---------------------------------------------- 77 78 // Convenience object for converting a PPAPI call that can throw an exception 79 // and optionally return a value, back to the NPAPI layer which expects a 80 // NPVariant as a result. 81 // 82 // Normal usage is that you will pass the result of exception() to the 83 // PPAPI function as the exception output parameter. Then you will either 84 // call SetResult with the result of the PPAPI call, or 85 // CheckExceptionForNoResult if the PPAPI call doesn't return a PP_Var. 86 // 87 // Both SetResult and CheckExceptionForNoResult will throw an exception to 88 // the JavaScript library if the plugin reported an exception. SetResult 89 // will additionally convert the result to an NPVariant and write it to the 90 // output parameter given in the constructor. 91 class PPResultAndExceptionToNPResult { 92 public: 93 // The object_var parameter is the object to associate any exception with. 94 // It may not be NULL. 95 // 96 // The np_result parameter is the NPAPI result output parameter. This may be 97 // NULL if there is no NPVariant result (like for HasProperty). If this is 98 // specified, you must call SetResult() to set it. If it is not, you must 99 // call CheckExceptionForNoResult to do the exception checking with no result 100 // conversion. 101 PPResultAndExceptionToNPResult(NPObject* object_var, NPVariant* np_result); 102 103 ~PPResultAndExceptionToNPResult(); 104 105 // Returns true if an exception has been set. 106 bool has_exception() const { return exception_.type != PP_VARTYPE_UNDEFINED; } 107 108 // Returns a pointer to the exception. You would pass this to the PPAPI 109 // function as the exception parameter. If it is set to non-void, this object 110 // will take ownership of destroying it. 111 PP_Var* exception() { return &exception_; } 112 113 // Returns true if everything succeeded with no exception. This is valid only 114 // after calling SetResult/CheckExceptionForNoResult. 115 bool success() const { return success_; } 116 117 // Call this with the return value of the PPAPI function. It will convert 118 // the result to the NPVariant output parameter and pass any exception on to 119 // the JS engine. It will update the success flag and return it. 120 bool SetResult(PP_Var result); 121 122 // Call this after calling a PPAPI function that could have set the 123 // exception. It will pass the exception on to the JS engine and update 124 // the success flag. 125 // 126 // The success flag will be returned. 127 bool CheckExceptionForNoResult(); 128 129 // Call this to ignore any exception. This prevents the DCHECK from failing 130 // in the destructor. 131 void IgnoreException(); 132 133 private: 134 // Throws the current exception to JS. The exception must be set. 135 void ThrowException(); 136 137 NPObject* object_var_; // Non-owning ref (see constructor). 138 NPVariant* np_result_; // Output value, possibly NULL (see constructor). 139 PP_Var exception_; // Exception set by the PPAPI call. We own a ref to it. 140 bool success_; // See the success() function above. 141 bool checked_exception_; // SetResult/CheckExceptionForNoResult was called. 142 143 DISALLOW_COPY_AND_ASSIGN(PPResultAndExceptionToNPResult); 144 }; 145 146 // PPVarArrayFromNPVariantArray ------------------------------------------------ 147 148 // Converts an array of NPVariants to an array of PP_Var, and scopes the 149 // ownership of the PP_Var. This is used when converting argument lists from 150 // WebKit to the plugin. 151 class PPVarArrayFromNPVariantArray { 152 public: 153 PPVarArrayFromNPVariantArray(PepperPluginInstanceImpl* instance, 154 size_t size, 155 const NPVariant* variants); 156 ~PPVarArrayFromNPVariantArray(); 157 158 PP_Var* array() { return array_.get(); } 159 160 private: 161 size_t size_; 162 scoped_ptr<PP_Var[]> array_; 163 164 DISALLOW_COPY_AND_ASSIGN(PPVarArrayFromNPVariantArray); 165 }; 166 167 // PPVarFromNPObject ----------------------------------------------------------- 168 169 // Converts an NPObject tp PP_Var, and scopes the ownership of the PP_Var. This 170 // is used when converting 'this' pointer from WebKit to the plugin. 171 class PPVarFromNPObject { 172 public: 173 PPVarFromNPObject(PepperPluginInstanceImpl* instance, NPObject* object); 174 ~PPVarFromNPObject(); 175 176 PP_Var var() const { return var_; } 177 178 private: 179 const PP_Var var_; 180 181 DISALLOW_COPY_AND_ASSIGN(PPVarFromNPObject); 182 }; 183 184 // NPObjectAccessorWithIdentifier ---------------------------------------------- 185 186 // Helper class for our NPObject wrapper. This converts a call from WebKit 187 // where it gives us an NPObject and an NPIdentifier to an easily-accessible 188 // ObjectVar (corresponding to the NPObject) and PP_Var (corresponding to the 189 // NPIdentifier). 190 // 191 // If the NPObject or identifier is invalid, we'll set is_valid() to false. 192 // The caller should check is_valid() before doing anything with the class. 193 // 194 // JS can't have integer functions, so when dealing with these, we don't want 195 // to allow integer identifiers. The calling code can decode if it wants to 196 // allow integer identifiers (like for property access) or prohibit them 197 // (like for method calling) by setting |allow_integer_identifier|. If this 198 // is false and the identifier is an integer, we'll set is_valid() to false. 199 // 200 // Getting an integer identifier in this case should be impossible. V8 201 // shouldn't be allowing this, and the Pepper Var calls from the plugin are 202 // supposed to error out before calling into V8 (which will then call us back). 203 // Aside from an egregious error, the only time this could happen is an NPAPI 204 // plugin calling us. 205 class NPObjectAccessorWithIdentifier { 206 public: 207 NPObjectAccessorWithIdentifier(NPObject* object, 208 NPIdentifier identifier, 209 bool allow_integer_identifier); 210 ~NPObjectAccessorWithIdentifier(); 211 212 // Returns true if both the object and identifier are valid. 213 bool is_valid() const { 214 return object_ && identifier_.type != PP_VARTYPE_UNDEFINED; 215 } 216 217 PluginObject* object() { return object_; } 218 PP_Var identifier() const { return identifier_; } 219 220 private: 221 PluginObject* object_; 222 PP_Var identifier_; 223 224 DISALLOW_COPY_AND_ASSIGN(NPObjectAccessorWithIdentifier); 225 }; 226 227 // TryCatch -------------------------------------------------------------------- 228 229 // Instantiate this object on the stack to catch V8 exceptions and pass them 230 // to an optional out parameter supplied by the plugin. 231 class TryCatch { 232 public: 233 // The given exception may be NULL if the consumer isn't interested in 234 // catching exceptions. If non-NULL, the given var will be updated if any 235 // exception is thrown (so it must outlive the TryCatch object). 236 TryCatch(PP_Var* exception); 237 ~TryCatch(); 238 239 // Returns true is an exception has been thrown. This can be true immediately 240 // after construction if the var passed to the constructor is non-void. 241 bool has_exception() const { return has_exception_; } 242 243 // Sets the given exception. If an exception has been previously set, this 244 // function will do nothing (normally you want only the first exception). 245 void SetException(const char* message); 246 247 private: 248 static void Catch(void* self, const char* message); 249 250 // True if an exception has been thrown. Since the exception itself may be 251 // NULL if the plugin isn't interested in getting the exception, this will 252 // always indicate if SetException has been called, regardless of whether 253 // the exception itself has been stored. 254 bool has_exception_; 255 256 // May be null if the consumer isn't interesting in catching exceptions. 257 PP_Var* exception_; 258 }; 259 260 } // namespace content 261 262 #endif // CONTENT_RENDERER_PEPPER_NPAPI_GLUE_H_ 263