Core PPAPI proxy files. This includes the dispatcher which is the control point

on each end of the IPC channel. It includes the IPC message definitions. It
also includes the base class for the interface proxying, and the core resource
and var tracking.

BUG=none
TEST=none
Review URL: http://codereview.chromium.org/4229002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@64869 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 85 insertions, 0 deletions

diff --git a/ppapi/proxy/var_serialization_rules.h b/ppapi/proxy/var_serialization_rules.h
new file mode 100644
index 0000000..bf00547
--- /dev/null
+++ b/ppapi/proxy/var_serialization_rules.h
@@ -0,0 +1,85 @@
+// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef PPAPI_PROXY_VAR_SERIALIZATION_RULES_H_
+#define PPAPI_PROXY_VAR_SERIALIZATION_RULES_H_
+
+#include "ppapi/c/pp_var.h"
+
+#include <string>
+
+namespace pp {
+namespace proxy {
+
+// Encapsulates the rules for serializing and deserializing vars to and from
+// the local process. The renderer and the plugin process each have separate
+// bookkeeping rules.
+class VarSerializationRules {
+ public:
+  virtual ~VarSerializationRules() {}
+
+  // Caller-owned calls --------------------------------------------------------
+  //
+  // A caller-owned call is when doing a function call with a "normal" input
+  // argument. The caller has a reference to the var, and the caller is
+  // responsible for freeing that reference.
+
+  // Prepares the given var for sending to the callee. If the var is a string,
+  // the value of that string will be placed in *str_val. If the var is not
+  // a string, str_val will beuntouched and may be NULL.
+  virtual void SendCallerOwned(const PP_Var& var, std::string* str_val) = 0;
+
+  // When receiving a caller-owned variable, normally we don't have to do
+  // anything. However, in the case of strings, we need to deserialize the
+  // string from IPC, create a new PP_Var string in the local process, call the
+  // function, and then destroy the temporary string. These two functions
+  // handle that process
+  //
+  // BeginReceiveCallerOwned takes a var from IPC and an optional pointer to
+  // the deserialized string (which will be used only when var is a
+  // VARTYPE_STRING and may be NULL otherwise) and returns a new var
+  // representing the input in the local process. The output will be the same
+  // as the input except for strings.
+  //
+  // EndReceiveCallerOwned destroys the string created by Begin* and does
+  // nothing otherwise. It should be called with the result of Begin*.
+  virtual PP_Var BeginReceiveCallerOwned(const PP_Var& var,
+                                         const std::string* str_val) = 0;
+  virtual void EndReceiveCallerOwned(const PP_Var& var) = 0;
+
+  // Passinag refs -------------------------------------------------------------
+  //
+  // A pass-ref transfer is when ownership of a reference is passed from
+  // onen side to the other. Normally, this happens via return values and
+  // output arguments, as for exceptions. The code generating the value
+  // (the function returning it in the case of a return value) will AddRef
+  // the var on behalf of the consumer of the value. Responsibility for
+  // Release is on the consumer (the caller of the function in the case of a
+  // return value).
+
+  // Creates a var in the context of the local process from the given
+  // deserialized var and deserialized string (which will be used only when var
+  // is a VARTYPE_STRING and may be NULL otherwise). The input var/string
+  // should be the result of calling SendPassRef in the remote process.
+  virtual PP_Var ReceivePassRef(const PP_Var& var,
+                                const std::string& str_val) = 0;
+
+  // Prepares a var to be sent to the remote side. One local reference will
+  // be passed to the remote side. Call Begin* before doing the send and End*
+  // after doing the send. See SendCallerOwned for a description of the string.
+  virtual void BeginSendPassRef(const PP_Var& var, std::string* str_val) = 0;
+  virtual void EndSendPassRef(const PP_Var& var) = 0;
+
+  // ---------------------------------------------------------------------------
+
+  virtual void ReleaseObjectRef(const PP_Var& var) = 0;
+
+ protected:
+  VarSerializationRules() {}
+};
+
+}  // namespace proxy
+}  // namespace pp
+
+#endif  // PPAPI_PROXY_VAR_SERIALIZATION_RULES_H_