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
13namespace ppapi {
14namespace 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.
19class 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_
90