Changes between Initial Version and Version 1 of OpenVPNMSICA

Timestamp:

02/24/19 18:45:11 (5 years ago)

Author:

rozmansi

Comment:

--

OpenVPNMSICA

@@ +1 @@
+{{{
+#!rst
+OpenVPN MSI CA Developer Documentation
+======================================
+
+This document describes some basic overview of *openvpnmsica.dll* for developers.
+
+Consider the *openvpnmsica.dll* as a collection of functions (aka "Custom Actions") the MSI installer calls to perform tasks that are not implemented by stock MSI actions.
+
+Some functions are completely stand-alone.
+
+- ``FindSystemInfo()`` and ``FindTAPInterfaces()`` are sequenced in the MSI package to execute early. They perform some tests MSI is too limited to do itself and set various MSI properties accordingly. Later, those MSI properties are used to form conditions in MSI. Like which version of the driver to install, should *OpenVPNServ* feature be selected to install or not, etc.
+- The ``CloseOpenVPNGUI()`` and ``StartOpenVPNGUI()`` do just what they say immediately when called.
+
+Then there are other functions that form an ``<evaluation, execute, commit, rollback>`` tuple. The ``<EvaluateTAPInterfaces(), ProcessDeferredAction(), ProcessDeferredAction(), ProcessDeferredAction()>`` is an example of those. They are sequenced in the MSI package like this:
+
+1. ``EvaluateTAPInterfaces()`` executes in the first pass. It runs in the current user context and it doesn't touch user's computer in any way. Well, it just prepares a list of TAP-interface-related operations to be executed and saves it in a temporary file. The list contains operations like: *"install TAP interface X"*, *"delete TAP interface X"*, *"rename TAP interface X to Y"*, *"delete file X"*, etc. Operations are implemented in *msica_op.h* and *msica_op.c*.
+
+2. ``ProcessDeferredAction()`` runs in the so-called deferred MSI execution pass run by Windows Installer service as the *SYSTEM* user. It loads the list of operations from the temporary file and executes them one by one.
+
+   Let's look at a sample operation *"delete file X"*. Normally, this operation does not really delete the file X. It renames it to Y instead, while adding *"delete file Y"* operation to a separate commit list tail, and inserting *"move file Y to X"* to a rollback list head. Unless MSI rollback is explicitly disabled - in this case, it just deletes the file immediately and doesn't touch commit/rollback lists.
+
+   After all operations on the list are executed, the newly created commit and rollback operation lists are saved to separate temporary files.
+
+3. After the installation succeeds, the MSI calls all deferred commit actions: This time, the ``ProcessDeferredAction()`` is called with the commit list filename as the action parameter.
+
+   Should the installation fail, the MSI calls all deferred rollback actions in reverse order: This time, the ``ProcessDeferredAction()`` would be called with the rollback list filename as the action parameter.
+
+Since execution, commit and rollback list files are of the same syntax, the same ``ProcessDeferredAction()`` function is reused. The only detail worth noting is that when ``ProcessDeferredAction()`` detects it is run in the commit/rollback pass it disables the MSI rollback: this makes all sequenced operations execute immediately and no longer bother with commit/rollback lists.
+}}}