blob: a6741ee941cdd2543b075f62ac2bbaf6c2aa2b6a [file] [log] [blame]
// 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 be untouched 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_