More general code cleanup for readability.

[wine/multimedia.git] / ipc / dde.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Written by Michael Veksler.
%% May be freely redistributed as long as this header is unchanged.
%% The file be modified as long as there will be appropriate comment
%% containing the Author and a description.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentstyle{article}
\renewcommand{\thepage}{}
\newcommand{\Wine}{Wine}
\newcommand{\WINE}{{\em WINdows Emulator}}
\newcommand{\DDE}{{\em Dynamic Data Exchange}}
\newcommand{\windoz}{MS-Win\-dows}
\newcommand{\fname}[1]{{\tt #1}}
\newcommand{\libwine}{\fname{libwine.a}}
\title{DDE\footnote{DDE is \DDE\ mechanism provided by \windoz.
    (Appendix~\protect\ref{sec:DDE}).
    }
  \ capability for \Wine\footnote{\Wine\ (\WINE) Runs \windoz\
    programs under UNIX\@. (Appendix~\protect\ref{sec:Wine}).
    }
}
\author{Michael Veksler 11678223}
%%\date{Aug 6, 1995}
\begin{document}
\maketitle
\vfill
\abstract{\Wine{} provides an environment for running or compiling
  \windoz{} applications for UNIX clones (such as Linux).
  \Wine{} is not yet finished and lacks many basic important features.
  One of the missing features is DDE\@. DDE implementation
  (especially for \libwine) requires
  UNIX IPC\footnote{IPC - Inter-Process Communication}. This Project
  introduces the IPC mechanism into \Wine{}, thus allowing DDE to work
  between different \Wine{} processes.}


\vfill
{\LARGE
  \begin{itemize}
    \item[Instructor:] Avner Lottem
    \item[Done for:] Technion- Israel Institute of Technology,\\
      Electrical Engineering software lab$^{\mbox{\small\copyright}}$.
  \end{itemize}
  }
\vfill

\newpage
\renewcommand{\thepage}{\roman{page}}
\setcounter{page}{1}
\begin{center}
    {\LARGE Table Of Contents}
\end{center}
\tableofcontents

\newpage
\renewcommand{\thepage}{\arabic{page}}
\setcounter{page}{1}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% end of title
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}

\subsection{The project}
The purpose of the project is to add DDE capabilities into \Wine.
The project enables \Wine{} DDE client-server applications communication.
This involved messing around with:
\begin{itemize}
  \item \windoz\ message mechanism.
  \item \windoz\ memory management.
  \item \windoz\ task management.
  \item UNIX messages among  \Wine\ processes.
  \item Exchanging (sharing) UNIX memory.
\end{itemize}

\subsection{Problem description}
DDE is essentially a communication protocol between \windoz\
tasks. Implementing this protocol requires communication among
\Wine{} processes and among tasks in one process (each \Wine{} process
can contain several tasks). Since \Wine\ already provides
communication among internal tasks, this project provides communication
between \Wine\ processes. 

Different \Wine\ processes should be able to send \windoz\ messages
and to pass \windoz\ memory handles. There also has to be a
synchronization mechanism between the processes (\windoz\ applications
make assumptions about task switching - and don't use semaphores, or
any \windoz\ equivalent).

Passing messages is a bit tricky. \windoz\ gives a feedback about the
success of a message (fails if the window does not exist).
In case of SendMessage (see Appendix~\ref{sec:WindozMsg}), the process
will have to halt until the message has been processed.
In case of PostMessage, things are simpler - only the existence of the
recipient has to be checked.

\windoz\ switches tasks only when certain system calls are used (such
as delivering or polling messages). \windoz\ applications rely on this
behavior. The problem arises when two applications run on different
\Wine\ processes. Since UNIX preempts processes there is no guaranty
that the UNIX task will occur at the correct place (in respect of the
application).
One one hand is the need for compatibility (no UNIX ``current''
execution), and on the other hand is performance and stability.

Another problem is passing handles between \Wine\ processes. \windoz\
applications pass atoms\footnote{See appendix~\ref{sec:WhatAreAtoms}},
memory handles and window handles. These handles have to be allocated
globally (in shared memory) or translated on the fly.


If a process dies from ``unnatural causes'' (e.g.\ kill $-9$). It will
leave garbage in memory and other IPC handles will start floating
around. There should be some way to collect this garbage.

\subsection{Solutions}
\label{sec:ProjSolutions}
\Wine\ uses Sys-V IPC mechanism (See
Appendix~\ref{sec:SysV-IPC}). This allows sharing data and passing
data between processes (The alternatives are not that good in that
respect - see Appendix~\ref{DDE-Alternatives}).
The shared data contains only essential information (performance or
compatibility). The minimum is kept on shared memory in order to get
maximum stability (\windoz\ is known as an unstable system, \Wine\
should not imitate \windoz\ in this respect).

Communications are done by Sys-V messages and UNIX signals (a signal
wakes \Wine\ up and the message passes the data). Sys-V messages are
used for carrying \windoz\ messages, as well as synchronization
information. There are 3 types of messages: sent, posted and ack.
Ack message is used for synchronization as well as for returning error
codes (In case sending/posting messages fail). When a message is sent,
the sending process will block until \Wine's {\em ack}{} message is
received.

Synchronization between \Wine\ processes is divided into 2 categories,
in both cases the sender of a message waits for an ack message:
\begin{enumerate}
  \item Sent messages - Wait until the recipient delivers ack message.
    (When the recipient finished message processing) 
  \item Posted message - The recipient will send ack only during
    task switching instructions (like PostMessage, GetMessage, Yield,
    etc.). This way nothing will be done after PostMessage until it is
    safe. 
\end{enumerate}

There is no real \Wine\ server. Every \Wine\ process has to handle
it's end. This approach somehow resembles a distributed OS\@. This
introduces some problems (Resources might not be freed in case of a
crash). On the other hand this ``distributed OS'' approach simplifies
installation and use, and improves performance.

Atoms are stored on shared memory, so every two \Wine\ processes will
be in sync in this respect (atom 5 will mean the same on both
processes). Shared memory handles are stored on shared memory as
well. Shared memory handles are not from the same range as local
memory handles (\windoz\ requires an plication to declare about it's
shared memory). Since local memory handles have different range they
can be allocated locally (without any sync requirements - handle x may
appear on 10 different \Wine\ processes and address different data).

Window handles are allocated locally. This approach gives stability,
but window handles are no longer unique (same handle may appear
on different processes). This requires on the fly window handle
translation. When an \windoz\ message is transfered, \Wine\ will
translate any contained window handle. The sender translates the
handle to a global (unique) handle, the receiver translates the global
handle to the local window handle.

Collecting the garbage of dead processes is done in two cases:
\begin{enumerate}
  \item When setting up a new \Wine\ process: If no \Wine\ process is
    running and shared memory is floating around all the IPC stuff is
    deleted. 
  \item When sending a message: If the recipient is dead it's IPC
    handles are deleted.
\end{enumerate}



\section{The software}

\subsection{DDE project structure}
Old \Wine\ functions call the new DDE functions whenever needed.
(e.g.\ when sending a DDE message, the original SendMessage function calls
DDE\_SendMessage). This approach minimizes changes to original \Wine{}
code. The new code was written in C. The new capabilities where written
as much as possible in OOP\footnote{OOP stands for Object Oriented
Programming}{} style.

Currently DDE uses Sys-V IPC mechanism, for it's operation.


\paragraph{Major OOP objects and files:}

\begin{table}[h]
    \begin{center}
        \leavevmode
        \begin{tabular}{|l|p{20em}|} \hline
            Object           & Description \\ \hline
            shm\_block       & shared memory block operations. \\
            shm\_main\_block & (derived from shm\_block.) Things all
                               DDE applications need access to. \\
            shm\_fragment    & Allocation of in-block fragments. \\
            shm\_semaph      & Semaphore operations. \\
            dde\_proc        & Process and DDE message handling. \\
            dde\_mem         & Front end of DDE memory handling
                               (Interface of DDE to outer world). \\
            dde\_atom        & Handling global atoms. \\ 
            bit\_array       & Array of bits. It has atomic
                               operations, so bits can be used instead
                               of semaphores. \\ \hline
        \end{tabular}
        \caption{Objects constructing the DDE extension.}
        \label{tab:ObjList}
    \end{center}
\end{table}

Table~\ref{tab:ObjList}{} lists the objects used in the DDE code.
The following rules apply to objects:

\begin{itemize} 
  \item Object names that begin with {\em dde\_$\cdots$}{} are the front
    end. These objects are working directly with the rest of
    \Wine. Objects that start with {\em shm\_$\cdots$}{} are the back
    end. These objects provide services for the rest of the
    implementation. 
  \item The objects are stored in file with the same name as the object.
    (e.g.\ dde\_mem is stored in dde\_mem.c and dde\_mem.h).
  \item For each object there is a test file (that partially tests it).
    The name of this file is object's name with the word ``test''
    (e.g.\ dde\_mem object has dde\_mem\_test.c).
  \item dde.h file has declarations used by dde\_proc and external DDE
    users.
\end{itemize}
    

\subsection{Major algorithms}

\paragraph{Delivering messages:}
\label{sec:DeliveringMessages}
\windoz\ messages are passed using Sys-V IPC messages. Processing
starts with SendMessage() or PostMessage() \windoz\ system
functions:
\begin{enumerate}
  \item SendMessage and PostMessage call the DDE functions (same names
    prefixed with DDE\_). If the DDE functions pass, don't go any
    further. If it fails try to process the message in the
    conventional way. 
  \item The DDE message functions call DDE\_DoMessage, which is
    the main DDE message processing function. From now on there is no
    difference between sending and posting messages (from initiator's
    point of view).
  \item If the message is not a DDE message or the recipient is not
    remote, fail and return to original message functions.
  \item Bring the message to a format suitable for IPC delivery. The
    format includes:
    \begin{itemize}
      \item message type (sent or posted).
      \item Sender window handle (translated to global window id.)
      \item Other message ingredients (msg, lParam).
    \end{itemize}
  \item Deliver the message to every recipients using
    DDE\_DoOneMessage. There might be many recipients in case of a
    broadcast (when the ``recipient'' window is -1). 
  \item DDE\_DoOneMessage delivers the message and waits for response.
    Fail if timeout is reached.
\end{enumerate}


\paragraph{Receiving messages:}
Messages from other \Wine\ processes are received. Processing start
from DDE\_GetRemoteMessage():
\begin{enumerate}
  \item DDE\_GetRemoteMessage is called whenever wine is going to wait
    or receive X-windows message. If wine is sleeping (waiting for X),
    it will waken by a SIGUSR2 signal. In this case the handler will
    siglongjmp() out of the select() function.
  \item If no remote message is pending in the message queue - exit.
    (Sys-V message queue holds the remote messages until they are
    read).
  \item If the message is broadcasted, goto stage~\ref{BroadcastAlgo}.
  \item Translate the global window handle of the recipient to local
    handle. 
  \item Do this if the message was sent. Send the message to the
    recipient window. Reply with ack to the sender. (Reply with the
    return code of the SendMessage function). {\em \bf Return}\ with
    positive return value.
  \item Post the message.
  \item If PostMessage fails - send failing ack message. 
  \item If PostMessage passes, add the message data into a FIFO\@. This
    FIFO contains all messages that have to be acknowledged (who's
    sender is waiting for ack). Whenever internal task switch occurs,
    a item from this FIFO is popped out and an ack message is sent.  
  \item \label{BroadcastAlgo} Iterate through the local windows and
    deliver the message to every one of them.
  \item Send a positive ack message.
\end{enumerate}

\paragraph{Allocating memory:}
Shared memory allocation is divided into two categories: internal wine
and \windoz\ application. The memory used by \windoz\ applications is
allocated in two phases - allocate internal wine, and then prepare all
the stuff needed by \windoz.

The internal allocation (DDE\_malloc):
\begin{enumerate}
  \item Try to allocate big enough memory fragment in allocated shared
    memory. 
  \item If fragment could not be allocated, allocate a new shared
    memory block. Allocate the memory fragment.
  \item Allocate a shared memory handle (call the dde\_alloc\_handle() 
    function). The allocated handle is from a range used only by
    shared memory handles. This allocation function is used only for
    shared DDE memory.
  \item Write the handle in the data structure. Also write the
    relative location of this handle (Pointer location is useless since
    it differs from one \Wine\ process to another).
    This information is written in the main shared memory block.    
\end{enumerate}
When a fragment is allocated, it is removed from the list of free
memory.

Allocation for \windoz\ applications (this is done in GlobalAlloc):
\begin{enumerate}
  \item Do the internal allocation (instead of malloc in the local
    allocation). 
  \item Everything else is the same as with local memory. A segment is
    allocated for the new memory, and it's data is kept in the data
    structure. 
\end{enumerate}


\paragraph{Atoms:}
Atoms have pretty simple algorithms operating on them. Since atoms are
supposed to give a unique number for each string - atoms are
implemented as hash tables. The id of the atom is the entry in the
hash table. The disadvantage of this approach is that there is a limit
on the number of atoms, the big advantages are simplicity and
speed.

Since implementing a hash tables is strait forward, I will not
discuss it in depth. This hash table has two hash functions - primary
and secondary. When searching for an item (for deletion, addition, or
a seek) the following steps are taken:
\begin{enumerate}
  \item The primary hash function returns the first entry.
  \item \label{AtomHashLoop}
    If the entry is empty or no unchecked entries {\bf \em fail}.
  \item If the entry is correct, {\bf \em success!!!}.
  \item Add the result of secondary hash function to the item index.
  \item Goto step~\ref{AtomHashLoop}.
\end{enumerate}


\subsection{Major data structures}
There are two kinds of data structure, local and shared. The local
data structures are strait forward and will not be discussed in
detail.

The shared data structures have four level hierarchy. Each level
depend on the other and can not exist without it. Most structures have
much less than four levels.

\paragraph{Level one data structure - the main block:}
This data structure is part of the shm\_main\_block object. It
contains essential information needed by all \Wine\ processes. : 
\begin{enumerate}
  \item Semaphore identifier used for locking the data structure.
  \item A table containing information about \Wine\ processes.
  \item Relative pointers to atoms.
  \item A table containing window information.
  \item Tables with global memory handles.
\end{enumerate}

The first level is allocated and initialized when \Wine\ calls a DDE
function the first time. DDE functions are: global memory allocation,
global atoms or DDE messages. 

The first level data structure contains the second level data
structure. 


\paragraph{Atom element (level two):}
Each element is allocated dynamically (the size of the string is
unknown). The allocation is gained from the shm\_fragment object (each
atom is an instance of that object). Each atom contains:
\begin{enumerate}
  \item Count of links. Each allocation of the atom establishes a new
    link and each deallocation deletes one link (until all links are
    removed). 
  \item The string of the atom. The string ends with a null character.
\end{enumerate}

\paragraph{Wine processes data (level two):}
(part of the dde\_proc object) :
\begin{enumerate}
  \item pid (\Wine\ process id).
  \item Message queue id.
  \item Semaphore used for locking process's data structure.
  \item Sys-V shared memory id of the first block in the chain of
    process's blocks.
\end{enumerate}


\paragraph{Window information (level two):}
This is part of the dde\_proc object. The index of array entry
specifies the window handle. Each entry contains:
\begin{enumerate}
  \item The process index of the \Wine\ process running this window.
  \item The local window handle of this window (remember that each DDE
    window has different global and local handles).
\end{enumerate}


\paragraph{Global memory handles (Level two):}
(part of bit\_array and dde\_mem objects):
\begin{enumerate}
  \item A bit array contains '1' in every entry that refers to
    used global memory handle.
  \item Array of handles contains handle data. Each entry refers
    to a global memory handle (The index is a function of the
    handle).  The data includes: 1) Sys-V shared memory handles 2)
    offset into the memory block. 
\end{enumerate}

\paragraph{Block allocation data structure (Level three):}
This data structure a part of the shm\_block object. It is local to
each shared memory block, so every memory block has it's own data
structure. The shared memory blocks are organized in chains grouped by
processes (each DDE process has one and only one chain): 
\begin{enumerate}
  \item The id of the next shared memory block in the chain.
  \item The size of the block.
  \item Number of free bytes in the block.
  \item The index of the owner process.
  \item The first item in the free list (a linked list of free items).
\end{enumerate}


\paragraph{Fragment allocation (Level four):}
This data is a part of the shm\_fragment object. It is a part of the shared
memory allocation mechanism. Every fragment is a part of shared memory
block. Each fragments contain:
\begin{enumerate}
  \item The size of the fragment (for allocating and freeing this
    fragment). 
  \item A union that contains one of:
    \begin{itemize}
      \item data - if it is allocated.
      \item offset of the next free fragment (if it is a member of the
        free list).
    \end{itemize}
\end{enumerate}


\paragraph{Local reference to global memory:}
Global memory blocks are referenced from local memory. This is used
for storing pointers that refer to the memory block. It contains:
\begin{enumerate}
  \item next item in the list.
  \item shared memory block id.
  \item Owner process.
  \item Pointer to the data.
\end{enumerate}

\paragraph{Local mirroring of global handles:}
Global handles require local segments handles (when they are locked).
These segments have to be deleted when the handle is freed.
There is a minimal mirroring of handles in the original tables of
wine, this information is stored the way local handles have always
been stored.

\subsection{Interface and IO}
The DDE section of wine has several interfaces to different entities:
\begin{enumerate}
  \item User debug information.
  \item Interface between several \Wine\ processes.
  \item Interface to the `old' code of \Wine.
\end{enumerate}


\paragraph{User debug information:}
The debug information is written according to \Wine's
conventions. This means that dprintf\_$\cdots$ macros are used to
print the debug information. (These macros allow runtime or compile time
disabling of a any sort of debug information).

In some cases the dprintf\_$\cdots$ macros are not powerful enough. In
those cases the following construct is used instead:
\begin{verbatim}
    if (debugging_dde) {
      /* print whatever is needed for dde debugging */
    }
\end{verbatim}


\paragraph{Interface between \Wine\ processes:}
The interface between processes includes:
\begin{itemize}
  \item Message delivery (see Section~\ref{sec:DeliveringMessages}).
  \item Sharing \windoz\ constructs (atoms, memory, window
    handles).
  \item Synchronization among different \Wine\ processes so it will
    appear to a \windoz\ as if there is only one process.
\end{itemize}

\paragraph{Interface to the rest of \Wine:}
Most of the interface has been minimized to an additional few lines in
the original functions. The hook for DDE are in the following
locations:
\begin{itemize}
  \item Global atoms functions - these are called directly from
    \windoz\ applications. 
  \item Message delivery - a hook calls the DDE functions from the
    original message delivery functions.
  \item Initialization - Every PeekMessage() call a DDE function to
    check if the current window has DDE management (by sending
    a dummy WM\_DDE\_INITIATE message).
  \item Waiting on messages - The original code for waiting on X
    messages was enhanced to wait on DDE messages as well. This
    includes aborting sleeps when SIGUSR2 signal is sent. The actual
    test for DDE messages is done in the DDE code.
\end{itemize}

\subsection{Major functions and their role}
\paragraph{Message delivery functions:}
\begin{itemize}
  \item DDE\_SendMessage and DDE\_PostMessage - hooks used by original
    \Wine's SendMessage and PostMessage. They return true if the
    message could be successfully sent to a remote \Wine\ process.
    Only in this case SendMessage and PostMessage stop further
    processing.
  \item DDE\_DoMessage - Try to post or send a message to another
    \Wine\ process. This function can do broadcasting as well as
    sending. (A message is `broadcasted' if it is delivered to every
    window on the system).
  \item DDE\_DoOneMessage - Deliver a message to a given wine
    {\bf process}.
  \item dde\_proc\_send\_ack - Send ack message to \Wine\
    process. The input window handle is used for detecting the
    process.
  \item get\_ack - wait for ack or timeout.
\end{itemize}

\paragraph{Memory allocation functions:}
\begin{itemize}
  \item DDE\_malloc - Allocate a shared memory fragment. This function
    also allocates global memory handle.
  \item DDE\_GlobalFree - Free a shared memory fragment according to
    it's handle. And free the handle.
  \item DDE\_SyncHandle - synchronize the global handles mirrored
    locally. Delete any outdated handles, or remap reallocated
    handles. 
  \item DDE\_mem\_init - initialize or attach the main shared memory
    block, and relevant local data structures.
  \item shm\_delete\_all - delete all IPC stuff related to this
    process. Kill the main memory block if appropriate.
\end{itemize}


\section{Software testing}
The testing of this module was a substantial part of the
development. Testing revealed bugs just as they where created.

\subsection{Testing methods utilized}
\label{sec:TestMethod}
Two major testing methods where used:
\begin{enumerate}
  \item Running DDE \windoz\ applications. The applications used are
    DDE demonstration applications. This applications seem to show 
    precisely what DDE is all about. The applications used where:
    ddepop1.exe (server), showpop1.exe (client). These
    applications come with \windoz\ programming manual by Charles
    Petzold \cite{bib:WinManual}. 
  \item Running standalone DDE objects linked with a test
    object. Every object was tested this way. Some objects had to be
    linked with a stub that emulated \Wine's functions. The stub is
    pretty poor with dde\_mem object since this object requires hard
    to emulate functionalities (things like allocating a segment).

    For some objects the coverage seems to be perfect (100\%). For
    some object the coverage is poor. The objects with massive stub
    usage suffer from this (especially dde\_mem).
\end{enumerate}

\subsection{input for testing}
Most of the testing described in section~\ref{sec:TestMethod} has no
input. Most of the testing knowledge is in the test objects
themselves. There are two exceptions to this rule:
\begin{enumerate}
  \item The \windoz\ applications described in
    section~\ref{sec:TestMethod} - which are essentially an input to
    the software. These applications can't be distributed since it
    will be a \copyright{} violation.
  \item A trace file which is used for comparing test's output with
    the expected trace result. This trace file is used for
    shm\_fragment validation. This file is implementation Dependants
    and should be updated whenever the object is rewritten. When
    updating the trace, it should be inspected manually before it is
    released. 
\end{enumerate}

\subsection{usage instructions}

\paragraph{Running the DDE applications:}
To test the DDE applications one must run:
\begin{verbatim}
   prompt> wine /full-path/ddepop1.exe > /dev/null &
\end{verbatim}
Wait for the server window to pop up (A tiny window should appear at
the lower left corner of your screen). Then activate the client by
typing: 
\begin{verbatim}
   prompt> wine /full-path/showpop1.exe > /dev/null 
\end{verbatim}
The server updates ``USA population'' data every 5 seconds. The client
asks for a hot link (i.e.\ it sends a WM\_DDE\_ADVISE on every
item). From that point on the server updates the client of any
population change.


\paragraph{Running the object tests:}
The {\em run\_tests}{} script is provided to automate the object
tests. Every object test is run and the script checks for results. At
the end the script prints a nice summary table.

Invoking tests outside the {\em run\_tests}{} script is not as simple
as it may look. Every test has differently looking output.
\begin{itemize}
  \item dde\_atom\_test - The executable is run. It passes if no
    errors are printed at the bottom. 
  \item dde\_mem\_test - The same as for dde\_atom\_test.
  \item shm\_semaph\_test - The same as for dde\_atom\_test.
  \item bit\_array\_test -  The same as for dde\_atom\_test.
  \item shm\_fragment\_test - After the executable is run,  the output
    has to be compared with TEST\_FRAGMENT.std 
  \item dde\_proc\_test - This actually runs as a client and as a
    server. To activate the server one should write:
\begin{verbatim}
  prompt> dde_proc_test 1 > server.log
\end{verbatim}
    Then the client has to be activated within five seconds by
    writing:
\begin{verbatim}
  prompt> dde_proc_test > client.log
\end{verbatim}
    The log files should contain:
    \begin{description}
      \item[server.log:] Should contain traces of received
        WM\_DDE\_INITIATE message, and ack sent for it. (Pretty much
        the same what  {\em run\_tests}{} does).  
      \item[client.log:] Should contain traces of sending
        WM\_DDE\_INITIATE and then receiving an ack message.
    \end{description}
    No `timeout' traces should be present in the log files.

\end{itemize}


\section{Summary}
\subsection{Software limitations}
\begin{itemize}
  \item Only most fundamental memory management functions where
    written. This means that the following functions will not work:
    \begin{itemize}
      \item GlobalReAlloc
      \item GlobalSize - two line fix.
      \item GlobalFlags - two line fix.
      \item LockSegment - two line fix.
      \item UnlockSegment - two line fix.
      \item GlobalFreeAll - will not free DDE memory.
      \item GlobalPageLock - two line fix.
      \item GlobalPageUnlock - two line fix.
      \item GlobalFix - two line fix.
      \item GlobalUnfix - two line fix.
    \end{itemize}
  \item Non DDE messages to remote windows will not work. This is
    currently only a sanity check, it may be removed in the future.
  \item Message sending has a timeout limit. This is incompatible with
    \windoz. This limit increases stability of a singe \Wine\ process.
  \item Synchronization mechanism between wine processes is not
    perfect. It was not proved theoretically. I never saw it fail.
\end{itemize}

\subsection{Concluding Remarks}
This extension to \Wine{} enables further development of \windoz\ IPC
support. Things like OLE can be extended using these features -
although some modifications might be inevitable.

The most important contribution of this project is the support for
\libwine{}. Any \windoz\ application compiled under UNIX and linked to
\libwine{} will need the IPC mechanism provided by this project.

During the progress of the project it got a bit outdated. During that
time \Wine{} started to handle tasks internally, so the external IPC
was no longer needed for the emulator configuration of
wine. Nevertheless the support of IPC for \libwine will never
be obsolete.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Appendixes
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\appendix

\section{\Wine}
\label{sec:Wine}
\Wine\ stand for {\em WINdows Emulator}. It is an X-windows - UNIX 
application (Linux and FreeBSD). \Wine\ emulates \windoz\  environment
for the \windoz\  applications. It has two uses:
\begin{enumerate}
  \item Run \windoz\  binary code (compiled under \windoz).
  \item To be used as a toolkit for compiling \windoz\ applications
    under UNIX. (The \libwine\ library is provided)
\end{enumerate}
For emulation, only  Intel-Architecture CPU (386, 486, Pentium) are
supported. \libwine\ Toolkit should run on any platforms, but it was not
tested. \Wine\ is still in alpha state, and does not support all \windoz\
capabilities yet.


\section{Messages under \windoz}
\label{sec:WindozMsg}
Messages are the means of communication to a user window (from another
window or from \windoz\ itself).
Messages can be delivered in two ways:
\begin{itemize}
  \item Messages can be sent. The sent message enters the window handler
    asynchronously (The handler may be reentered many times).
    A window sending the message waits for the recipient to process
    the message and return an exit code.
  \item Messages can be posted. The posted message enters a queue, and
    it's up to the recipient to process it. If the recipient ignores
    it, the message might be eventually sent to the recipient from
    WinMain handler.
\end{itemize}

\section{DDE}
\label{sec:DDE}
DDE stands for \DDE\@. DDE is an \windoz\ 
protocol used for data exchange between applications.
It has synchronous and asynchronous operation modes.
DDE mechanism is based on messages, atoms
(Section~\ref{sec:WhatAreAtoms}) and shared memory.

DDE applications are divided roughly into two classes: servers AND
clients. Clients have the initiative, they try to connect to the
server. Servers only maintain an existing DDE link.


\subsection{DDE Messages}
\paragraph{DDE message format}:

\label{sec:DDEMessageFormat}

DDE messages contain the following fields.
\begin{description}
  \item[wnd] The recipient of this message ($-1$ if every window
    should receive).
  \item[msg]    The ID of the message.
  \item[wParam] Who sent this message.
  \item[lParam] 32 bit parameter, divided into two 16 bit words.
    Usually, the lower 16 bits contain a memory handle. The handle
    points to some extra DATA about this message.
    
\end{description}

\paragraph{Available messages:}
\begin{description}
  \item[WM\_DDE\_INITIATE]
    This message is sent by the client to the whole ``world''.
    {\em lParam}{} contains the two atoms used for passing the topic and
    application information.

    Every server application checks if this message refers to it
    (According to the Application and the Topic atoms).


  \item[WM\_DDE\_ACK]
    This is a generic response to various events
    (one of them is WM\_DDE\_INITIATE).
    The low part of {\em lParam}{} passes extra information, such as
    success/failure.

  \item[WM\_DDE\_TERMINATE]
    Kill the DDE link.


  \item[WM\_DDE\_ADVISE]
    Tell the server to inform the client of any updates.


  \item[WM\_DDE\_UNADVISE]
    Stop the WM\_DDE\_UNADVISE mode.


  \item[WM\_DDE\_DATA]
    Transfer data handle (note that the data handle must be globally allocated
    with the GMEM\_DDESHARE flag).

  \item[WM\_DDE\_REQUEST]
    Request a data item from the server. This message is used in a
    cold link. {\em lParam}{} contains an atom describing the desired
    item, and a WORD describing the wanted data format.
  \item[WM\_DDE\_POKE]
    The client gives the server new data.
  \item[WM\_DDE\_EXECUTE]
    The client asks the server to execute a procedure (according to a
    command string).

\end{description}

\subsection{Atoms}
\label{sec:WhatAreAtoms}
Atoms are represented by numbers. Every atom maps uniquely to a string
(i.e.\ two atoms can't map to the same string).
There are two types of atoms - local and global. The local are visible
only to the application that created them. Global atoms are seen by all
\windoz\  applications.

Functions:
\begin{description}
  \item[AddAtom(str)]   create a local atom that maps to ``str''.
    If it exists, increment the allocation-counter,
    and return the atom.
  \item[DeleteAtom(atom)] decrement the allocation-counter.  When it
    reaches zero the atom, will be deleted.
  \item[FindAtom(str)]  Find the atom that maps to this string (if exist).
    
  \item[GetAtomName(\ldots)] Find the string that this atom points to.
\end{description}

NOTE:
\begin{description}
  \item[Global atoms] Add ``Global'' before the listed names to get Global
    atom functions.
  \item[Case sensitivity] All atom operations ignore case.
\end{description}


\section{DDE under \Wine\ - Alternatives}
\label{DDE-Alternatives}
There where three possible approaches for this project. I have chosen
System-V IPC, but it can be easily changed.

\subsection{IPC - Inter-Process Communication}
\label{sec:SysV-IPC}

The IPC mechanism was originated from System-V UNIX\@. This mechanism
allows complicate communication between two process (on the same machine). 
IPC includes the following capabilities:
\begin{enumerate}
  \item Shared Memory (shm) - can be shared among few processes and users.
  \item Semaphores (These semaphores allow grouped operations - i.e.\ 
    operations gathered as an atomic operation).
  \item Message Queues (allow few messages at a time).
\end{enumerate}

The advantages of IPC over the other variants are:
\begin{itemize}
  \item Memory access speed is good. (after the memory was attached).
  \item Easy to block critical code (don't enter critical code from two
    processes at the same time)
\end{itemize}
Disadvantages of IPC:
\begin{itemize}
  \item Impossible to communicate to other machine.
  \item Requires complex mechanism to wait both for X and IPC messages.
\end{itemize}

\subsection{X-Windows Communication mechanisms}
The advantages of X-Windows Communication over the other variants are:
\begin{itemize}
  \item Possible to communicate to other machines.
  \item No need for additional mechanism that will wait both for X and DDE\@.
  \item Many of the required capabilities are already there.
\end{itemize}
Disadvantages of X-windows communication:
\begin{itemize}
  \item {\em Slow}\ and complex memory access.
  \item May be hard to avoid two applications from entering critical
    code at the same time.
\end{itemize}

\subsection{BSD Sockets}
The advantages of Sockets are:
\begin{itemize}
  \item Possible to communicate to other machines.
  \item No need for complex mechanism that will wait both for X and
    DDE\@. (can use one ``select'' on X-windows socket in concert with
    the DDE socket).
\end{itemize}
Disadvantages of socket are:
\begin{itemize}
  \item {\em Slow}{} and complex memory access. (note that mmap on a
    descriptor does not work for Linux 0.99).
  \item May be hard to avoid two applications from entering critical
    code at the same time.
\end{itemize}

\subsection{Why was it written in C? Pros and cons.}
Advantages of C:

\begin{itemize}
  \item History- \Wine{} is already written in C.
  \item Portability- not all systems have C++.
  \item Speed- C++ sometimes makes it very difficult to write fast code.
  \item Maintenance- More programmers know C than C++. 
\end{itemize}

Advantages of C++:

\begin{itemize}
  \item smaller code - Templates allow Smaller and more readable code.
  \item Maintenance - It is easier to add and modify code in C++ (than in C).
  \item Verification - Functionality can be verified and debugged for
    individual objects.
\end{itemize}

I have decided to use C. Most of C++ advantages can be acquired
by using OOP methodologies. OOP methods that require inline functions
can't be used (without performance impact). GCC supports inline functions,
but this solution is not compatible.



\section{\Wine\ basics}
\subsection{How it runs}
\Wine\ works in the following order:
\begin{enumerate}
  \item \Wine\ loads the \windoz\  application into it's memory.
    (in the process it, links
    DLL's\footnote{DLL (Dynamically Linked Library) is linked on load-time.}
    creates 16-bit segments).
  \item \windoz\  code is executed.
\end{enumerate}

\section{bibliography}
\begin{thebibliography}{99}
  \bibitem{bib:WinManual} Charles Petzold {\em  Programming
      Windows~3.1}{} - 1992. \\ 
    On cover: {\em the Microsoft guide to writing applications for
      windows~3.1}. \\
    Published by {\em Microsoft press}. 
\end{thebibliography}


\newpage


\end{document}