ppapi/proxy/var_serialization_rules.h

   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_PROXY_VAR_SERIALIZATION_RULES_H_
   6 #define PPAPI_PROXY_VAR_SERIALIZATION_RULES_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "ppapi/c/pp_var.h"
  10
  11 #include <string>
  12
  13 namespace ppapi {
  14 namespace proxy {
  15
  16 // Encapsulates the rules for serializing and deserializing vars to and from
  17 // the local process. The renderer and the plugin process each have separate
  18 // bookkeeping rules.
  19 class VarSerializationRules : public base::RefCounted<VarSerializationRules> {
  20  public:
  21   // Caller-owned calls --------------------------------------------------------
  22   //
  23   // A caller-owned call is when doing a function call with a "normal" input
  24   // argument. The caller has a reference to the var, and the caller is
  25   // responsible for freeing that reference.
  26
  27   // Prepares the given var for sending to the remote process. For object vars,
  28   // the returned var will contain the id valid for the host process.
  29   // Otherwise, the returned var is valid in the local process.
  30   virtual PP_Var SendCallerOwned(const PP_Var& var) = 0;
  31
  32   // When receiving a caller-owned variable, normally we don't have to do
  33   // anything. However, in the case of strings, we need to deserialize the
  34   // string from IPC, call the function, and then destroy the temporary string.
  35   // These two functions handle that process.
  36   //
  37   // BeginReceiveCallerOwned takes a var from IPC and returns a new var
  38   // representing the input in the local process.
  39   //
  40   // EndReceiveCallerOwned releases the reference count in the Var tracker for
  41   // the object or string that was added to the tracker. (Note, if the recipient
  42   // took a reference to the Var, it will remain in the tracker after
  43   // EndReceiveCallerOwned).
  44   virtual PP_Var BeginReceiveCallerOwned(const PP_Var& var) = 0;
  45   virtual void EndReceiveCallerOwned(const PP_Var& var) = 0;
  46
  47   // Passing refs -------------------------------------------------------------
  48   //
  49   // A pass-ref transfer is when ownership of a reference is passed from
  50   // one side to the other. Normally, this happens via return values and
  51   // output arguments, as for exceptions. The code generating the value
  52   // (the function returning it in the case of a return value) will AddRef
  53   // the var on behalf of the consumer of the value. Responsibility for
  54   // Release is on the consumer (the caller of the function in the case of a
  55   // return value).
  56
  57   // Creates a var in the context of the local process from the given
  58   // deserialized var. The input var should be the result of calling
  59   // SendPassRef in the remote process. The return value is the var valid in
  60   // the host process for object vars. Otherwise, the return value is a var
  61   // which is valid in the local process.
  62   virtual PP_Var ReceivePassRef(const PP_Var& var) = 0;
  63
  64   // Prepares a var to be sent to the remote side. One local reference will
  65   // be passed to the remote side. Call Begin* before doing the send and End*
  66   // after doing the send
  67   //
  68   // For object vars, the return value from BeginSendPassRef will be the var
  69   // valid for the host process. Otherwise, it is a var that is valid in the
  70   // local process. This same var must be passed to EndSendPassRef.
  71   virtual PP_Var BeginSendPassRef(const PP_Var& var) = 0;
  72   virtual void EndSendPassRef(const PP_Var& var) = 0;
  73
  74   // ---------------------------------------------------------------------------
  75
  76   virtual void ReleaseObjectRef(const PP_Var& var) = 0;
  77
  78  protected:
  79   VarSerializationRules() {}
  80   virtual ~VarSerializationRules() {}
  81
  82  private:
  83   friend class base::RefCounted<VarSerializationRules>;
  84 };
  85
  86 }  // namespace proxy
  87 }  // namespace ppapi
  88
  89 #endif  // PPAPI_PROXY_VAR_SERIALIZATION_RULES_H_