sandbox/win/src/shared_handles.h

   1 // Copyright (c) 2010 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 SANDBOX_SRC_SHARED_HANDLES_H__
   6 #define SANDBOX_SRC_SHARED_HANDLES_H__
   7
   8 #include "base/basictypes.h"
   9
  10 #ifndef HANDLE
  11 // We can provide our own windows compatilble handle definition, but
  12 // in general we want to rely on the client of this api to include
  13 // the proper windows headers. Note that we don't want to bring the
  14 // whole <windows.h> into scope if we don't have to.
  15 typedef void* HANDLE;
  16 #endif
  17
  18 namespace sandbox {
  19
  20 // SharedHandles is a simple class to stash and find windows object handles
  21 // given a raw block of memory which is shared between two processes.
  22 // It addresses the need to communicate a handle value between two windows
  23 // processes given that they are already sharing some memory.
  24 //
  25 // This class is not exposed directly to users of the sanbox API, instead
  26 // we expose the wrapper methods TargetProcess::TransferHandle( ) and
  27 // TargetServices::GetTransferHandle()
  28 //
  29 // Use it for a small number of items, since internaly uses linear seach
  30 //
  31 // The use is very simple. Given a shared memory between proces A and B:
  32 // process A:
  33 //  HANDLE handle = SomeFunction(..);
  34 //  SharedHandles shared_handes;
  35 //  shared_handles.Init(memory)
  36 //  shared_handles.SetHandle(3, handle);
  37 //
  38 // process B:
  39 //  SharedHandles shared_handes;
  40 //  shared_handles.Init(memory)
  41 //  HANDLE handle = shared_handles.GetHandle(3);
  42 //
  43 // Note that '3' in this example is a unique id, that must be agreed before
  44 // transfer
  45 //
  46 // Note2: While this class can be used in a single process, there are
  47 // better alternatives such as STL
  48 //
  49 // Note3: Under windows a kernel object handle in one process does not
  50 // make sense for another process unless there is a DuplicateHandle( )
  51 // call involved which this class DOES NOT do that for you.
  52 //
  53 // Note4: Under windows, shared memory when created is initialized to
  54 // zeros always. If you are not using shared memory it is your responsability
  55 // to zero it for the setter process and to copy it to the getter process.
  56 class SharedHandles {
  57  public:
  58   SharedHandles();
  59
  60   // Initializes the shared memory for use.
  61   // Pass the shared memory base and size. It will internally compute
  62   // how many handles can it store. If initialization fails the return value
  63   // is false.
  64   bool Init(void* raw_mem, size_t size_bytes);
  65
  66   // Sets a handle in the shared memory for transfer.
  67   // Parameters:
  68   // tag : an integer, different from zero that uniquely identfies the
  69   // handle to transfer.
  70   // handle: the handle value associated with 'tag' to tranfer
  71   // Returns false if there is not enough space in the shared memory for
  72   // this handle.
  73   bool SetHandle(uint32 tag, HANDLE handle);
  74
  75   // Gets a handle previously stored by SetHandle.
  76   // Parameters:
  77   // tag: an integer different from zero that uniquely identfies the handle
  78   // to retrieve.
  79   // *handle: output handle value if the call was succesful.
  80   // If a handle with the provided tag is not found the return value is false.
  81   // If the tag is found the return value is true.
  82   bool GetHandle(uint32 tag, HANDLE* handle);
  83
  84  private:
  85   // A single item is the tuple handle/tag
  86   struct SharedItem {
  87     uint32 tag;
  88     void* item;
  89   };
  90
  91   // SharedMem is used to layout the memory as an array of SharedItems
  92   struct SharedMem {
  93     size_t max_items;
  94     SharedItem* items;
  95   };
  96
  97   // Finds an Item tuple provided the handle tag.
  98   // Uses linear search because we expect the number of handles to be
  99   // small (say less than ~100).
 100   SharedItem* FindByTag(uint32 tag);
 101
 102   SharedMem shared_;
 103   DISALLOW_COPY_AND_ASSIGN(SharedHandles);
 104 };
 105
 106 }  // namespace sandbox
 107
 108 #endif  // SANDBOX_SRC_SHARED_HANDLES_H__