reactos/media/doc/win32k_refs.txt

   1 References:
   2 -----------
   3
   4 window -> desktop
   5 window -> class
   6
   7 thread_input -> thread
   8
   9 thread -> process
  10 process -> winsta
  11 thread -> desktop
  12 desktop -> winsta
  13 winsta -> session
  14
  15 NOTE:   Message queue has 1:1 relationship with (w32)thread and need no ref. count.
  16         -If the (w32)thread is destroyed, so is the message queue.
  17         -If the (w32)thread exist, so does the message queue.
  18         So if you want the queue to hang around, you reference the thread instead.
  19
  20 ^ This is wrong, one can attach message queue to different thread using
  21 AttachThreadInput. The number of threads sharing a queue is stored in the
  22 message queue structure and can be considered a reference count. Also on
  23 Windows systems there is maintained a global list of thread attachments.
  24
  25 Above references create following dependencies:
  26 -----------------------------------------------
  27
  28 window -> desktop -> winsta -> session
  29 window -> class
  30
  31 thread -> process -> winsta -> session
  32 thread -> desktop -> winsta -> session
  33
  34 process -> winsta -> session
  35
  36 NtUser/NtGdi/win32k syscalls
  37 ----------------------------
  38
  39 A process and/or thread automatically gets converted to a GUI thread /
  40 process when the first syscall from the shadow service table is called (ie.
  41 any NtUser* or NtGdi* call). GUI threads have bigger kernel stack (FIXME:
  42 not the case on ReactOS yet) and have associated storage for the Win32
  43 structures. The conversion itself happens in the syscall handler and the
  44 win32k callbacks (registered with PsEstablishWin32Callouts) are called
  45 accordingly.
  46
  47 A process automatically establishes a connection to a window station on the
  48 GUI thread conversion.  The Win32 process initialization callback routine
  49 also creates and initializes the W32PROCESS structure and associates it with
  50 the process.
  51
  52 Similary for thread the callback routine automatically assigns a desktop
  53 when the thread is converted to GUI thread. The thread also gets a W32THREAD
  54 structure, a message queue and a thread input structures.
  55
  56 Beware that there is an exception to these rules and that's WinLogon. Since
  57 at the time the process starts no window stations or desktops exist, none
  58 are assigned to the the initial thread / process. The first Win32k calls
  59 the thread does are to create the window station and desktop and to associate
  60 them with itself.
  61
  62 FIXME: At the time of this writing there's a second exception, a "primitive
  63 message queue" thread in CSRSS that is created before any window stations
  64 exist and is used to capture keyboard input in console mode. Eventually we
  65 should get rid of it and replace is with hidden window w/ focus or something
  66 similar.
  67
  68 Generally this means that when you are in a Win32k syscall function (other
  69 than the window station or desktop functions) you can be 100% sure that the
  70 following exists:
  71
  72 - Process window station
  73 - Win32 process structure
  74 - Win32 thread structure
  75 - Thread message queue
  76 - Thread input
  77 - Thread desktop
  78
  79 There is no need to validate any of these values, because they MUST EXIST!