The Tor Browser: security/sandbox/win/src/shared_handles.h@b8a032363ba2 (annotated)

security/sandbox/win/src/shared_handles.h@b8a032363ba2 (annotated)

security/sandbox/win/src/shared_handles.h

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

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

The Tor Browser / annotate

security/sandbox/win/src/shared_handles.h@b8a032363ba2 (annotated)

security/sandbox/win/src/shared_handles.h