Custom action library, initial version

installer/src/installer-lib/session.h

+/**
+ * \file session.h The "install session" is the context for all custom installation behavior.
+ */
+
+#ifndef SESSION_H
+#define SESSION_H
+
+#include "property.h"
+#include "record.h"

[Wladimir Palant, 2013/10/29 08:49:26]

You should forward-declare the classes instead of the includes here (best
practices, not creating unnecessary dependencies).

[Eric, 2013/10/29 14:00:58]

"record.h" I think is some dead code I forgot to remove. I'll have to test that.

"property.h" is necessary for the friend declaration.

+
+#include <string>
+#include "windows.h"
+#include "msi.h"
+
+//-----------------------------------------------------------------------------------------
+// Session
+//-----------------------------------------------------------------------------------------
+/**
+ * A Windows Installer session
+ *
+ * Always instantiate an instance of this class at the start of each custom action.
+ * Copy and assignment are disabled, so session objects are always passed by reference. 
+ *
+ * This class is the base for both immediate and deferred custom actions.
+ * Immediate custom actions always have an installer database associated with them; deferred actions never do.
+ * Both immediate and deferred actions may be executed synchronously or asynchronously; this class is silent about any difference.
+ *
+ * \par Notes
+ *   This class is patterned after WcaInitialize/WcaFinalize of the WiX custom action library.
+ *   There are two things that class does that this one does not.
+ *   - Extract the file version information from the DLL using GetModuleFileName* and GetFileVersionInfo* system calls.
+ *   - Set a "global atom" (a Windows system object) to store the logging state, later to be accessed by deferred actions.
+ */
+class Session {
+public:
+  /**
+   * Destructor.
+   */
+  ~Session() ;
+
+  /**
+   * Write a message to the installation log.
+   */
+  void log( std::wstring message ) ;
+
+protected:
+  /**
+   * Ordinary constructor is protected; public constructors are all in subclasses.
+   * The MSI system uses a single handle type for all types of sessions. This handle is here in this base class.
+   *
+   * \param[in] handle
+   *    Handle for the Windows Installer session provided as an argument to a custom action.
+   * \param[in] name
+   *    The name of the custom action, used for logging.
+   */
+  Session( MSIHANDLE handle, std::wstring name ) ;
+
+protected:
+  /**
+   * Handle for the Windows Installer session.
+   */
+  MSIHANDLE handle ;
+
+private:
+  /**
+   * Prefix for log messages. Contains the name of the custom action.
+   */
+  std::wstring log_prefix ;
+
+  /**
+   * Private copy constructor is declared but not defined.
+   */
+  Session( const Session & ) ;
+
+  /**
+   * Private assignment operator is declared but not defined.
+   */
+  Session & operator=( const Session & ) ;
+
+  /**
+   * The Property class requires access to the session handle.
+   */
+  friend Property::Property( Session & session, std::wstring name ) ;

[Wladimir Palant, 2013/10/29 08:49:26]

The main purpose of this class is holding the session handle - getting access to
it shouldn't be that complicated. I suggest having a public cast overload:

operator MSIHANDLE()
{
  return handle;
}

Side-note: you have one friend declaration in the Session class, the other in
the Immediate_Session class for some reason.

[Eric, 2013/10/29 14:00:58]

Well, it's a design goal of mine to hide the handles entirely. Lifetime
management of these things isn't consistent (see comment on a previous file),
and so my preference was to make the right thing happen in the class code rather
than exposing them at all.

[Wladimir Palant, 2013/10/29 15:06:38]

Lifetime management is easily solved - either you create an AutoMSIHandle
wrapper for the handle or not (the latter being an exception, for the hInstall
handle of the custom action only). As I said, I don't see the value of having a
class to abstract away a single MSI call (and we have a dozen of such classes
here). IMHO that design goal is flawed.

+};
+
+//-----------------------------------------------------------------------------------------
+// Immediate_Session
+//-----------------------------------------------------------------------------------------
+/**
+ * Session for immediate custom actions.
+ *
+ * Access to the installer database is by passing a reference to a class of this subtype to a Database constructor.
+ */
+class Immediate_Session : public Session
+{
+public:
+  /**
+   * Ordinary constructor.
+   *
+   * \param[in] handle
+   *    Handle for the Windows Installer session provided as an argument to a custom action.
+   * \param[in] name
+   *    The name of the custom action, used for logging.
+   */
+  Immediate_Session( MSIHANDLE handle, std::wstring name ) ;
+
+private:
+  /*
+   * Allow helper function for Installation_Database constructor to have access to the handle.
+   */
+  friend MSIHANDLE get_active_database( Immediate_Session & session ) ;
+};
+
+
+//-----------------------------------------------------------------------------------------
+// Deferred_Session
+//-----------------------------------------------------------------------------------------
+/**
+ * Session for deferred custom actions.
+ *
+ * There's much less context information easily available from a deferred custom action.
+ *
+ * /sa MDSN "Deferred Execution Custom Actions"
+ *     http://msdn.microsoft.com/en-us/library/windows/desktop/aa368268%28v=vs.85%29.aspx
+ *     for general information.
+ *
+ * /sa MSDN "Obtaining Context Information for Deferred Execution Custom Actions"
+ *     http://msdn.microsoft.com/en-us/library/windows/desktop/aa370543%28v=vs.85%29.aspx
+ *     lists the API calls available.
+ */
+class Deferred_Session : public Session
+{
+public:
+  /**
+   * Ordinary constructor.
+   *
+   * \param[in] handle
+   *    Handle for the Windows Installer session provided as an argument to a custom action.
+   * \param[in] name
+   *    The name of the custom action, used for logging.
+   */
+  Deferred_Session( MSIHANDLE handle, std::wstring name ) ;
+};

[Wladimir Palant, 2013/10/29 08:49:26]

As with the Database object, I'm not a fan of the complexity here - I don't see
why we need a class hierarchy rather than a single Session object (or even an
AutoMSIHandle object).

+
+
+//-----------------------------------------------------------------------------------------
+// Commit_Session
+//-----------------------------------------------------------------------------------------
+/**
+ * The session for a commit custom action. NOT IMPLEMENTED.
+ *
+ * \sa MSDN "Commit Custom Actions" http://msdn.microsoft.com/en-us/library/windows/desktop/aa367991%28v=vs.85%29.aspx
+ */
+class Commit_Session
+{
+};
+
+//-----------------------------------------------------------------------------------------
+// Rollback_Session
+//-----------------------------------------------------------------------------------------
+/**
+ * The session for a rollback custom action. NOT IMPLEMENTED.
+ *
+ * \sa MSDN "Rollback Custom Actions" http://msdn.microsoft.com/en-us/library/windows/desktop/aa371369%28v=vs.85%29.aspx
+ */
+class Rollback_Session
+{
+};
+
+#endif