michael@0: // Copyright (c) 2010 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: #ifndef SANDBOX_SRC_SHARED_HANDLES_H__
michael@0: #define SANDBOX_SRC_SHARED_HANDLES_H__
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: 
michael@0: #ifndef HANDLE
michael@0: // We can provide our own windows compatilble handle definition, but
michael@0: // in general we want to rely on the client of this api to include
michael@0: // the proper windows headers. Note that we don't want to bring the
michael@0: // whole <windows.h> into scope if we don't have to.
michael@0: typedef void* HANDLE;
michael@0: #endif
michael@0: 
michael@0: namespace sandbox {
michael@0: 
michael@0: // SharedHandles is a simple class to stash and find windows object handles
michael@0: // given a raw block of memory which is shared between two processes.
michael@0: // It addresses the need to communicate a handle value between two windows
michael@0: // processes given that they are already sharing some memory.
michael@0: //
michael@0: // This class is not exposed directly to users of the sanbox API, instead
michael@0: // we expose the wrapper methods TargetProcess::TransferHandle( ) and
michael@0: // TargetServices::GetTransferHandle()
michael@0: //
michael@0: // Use it for a small number of items, since internaly uses linear seach
michael@0: //
michael@0: // The use is very simple. Given a shared memory between proces A and B:
michael@0: // process A:
michael@0: //  HANDLE handle = SomeFunction(..);
michael@0: //  SharedHandles shared_handes;
michael@0: //  shared_handles.Init(memory)
michael@0: //  shared_handles.SetHandle(3, handle);
michael@0: //
michael@0: // process B:
michael@0: //  SharedHandles shared_handes;
michael@0: //  shared_handles.Init(memory)
michael@0: //  HANDLE handle = shared_handles.GetHandle(3);
michael@0: //
michael@0: // Note that '3' in this example is a unique id, that must be agreed before
michael@0: // transfer
michael@0: //
michael@0: // Note2: While this class can be used in a single process, there are
michael@0: // better alternatives such as STL
michael@0: //
michael@0: // Note3: Under windows a kernel object handle in one process does not
michael@0: // make sense for another process unless there is a DuplicateHandle( )
michael@0: // call involved which this class DOES NOT do that for you.
michael@0: //
michael@0: // Note4: Under windows, shared memory when created is initialized to
michael@0: // zeros always. If you are not using shared memory it is your responsability
michael@0: // to zero it for the setter process and to copy it to the getter process.
michael@0: class SharedHandles {
michael@0:  public:
michael@0:   SharedHandles();
michael@0: 
michael@0:   // Initializes the shared memory for use.
michael@0:   // Pass the shared memory base and size. It will internally compute
michael@0:   // how many handles can it store. If initialization fails the return value
michael@0:   // is false.
michael@0:   bool Init(void* raw_mem, size_t size_bytes);
michael@0: 
michael@0:   // Sets a handle in the shared memory for transfer.
michael@0:   // Parameters:
michael@0:   // tag : an integer, different from zero that uniquely identfies the
michael@0:   // handle to transfer.
michael@0:   // handle: the handle value associated with 'tag' to tranfer
michael@0:   // Returns false if there is not enough space in the shared memory for
michael@0:   // this handle.
michael@0:   bool SetHandle(uint32 tag, HANDLE handle);
michael@0: 
michael@0:   // Gets a handle previously stored by SetHandle.
michael@0:   // Parameters:
michael@0:   // tag: an integer different from zero that uniquely identfies the handle
michael@0:   // to retrieve.
michael@0:   // *handle: output handle value if the call was succesful.
michael@0:   // If a handle with the provided tag is not found the return value is false.
michael@0:   // If the tag is found the return value is true.
michael@0:   bool GetHandle(uint32 tag, HANDLE* handle);
michael@0: 
michael@0:  private:
michael@0:   // A single item is the tuple handle/tag
michael@0:   struct SharedItem {
michael@0:     uint32 tag;
michael@0:     void* item;
michael@0:   };
michael@0: 
michael@0:   // SharedMem is used to layout the memory as an array of SharedItems
michael@0:   struct SharedMem {
michael@0:     size_t max_items;
michael@0:     SharedItem* items;
michael@0:   };
michael@0: 
michael@0:   // Finds an Item tuple provided the handle tag.
michael@0:   // Uses linear search because we expect the number of handles to be
michael@0:   // small (say less than ~100).
michael@0:   SharedItem* FindByTag(uint32 tag);
michael@0: 
michael@0:   SharedMem shared_;
michael@0:   DISALLOW_COPY_AND_ASSIGN(SharedHandles);
michael@0: };
michael@0: 
michael@0: }  // namespace sandbox
michael@0: 
michael@0: #endif  // SANDBOX_SRC_SHARED_HANDLES_H__