Add msilib documentation.

Doc/lib/lib.tex

@@ -446,6 +446,7 @@ and how to embed it in other applications.
 \input{libsunaudio}
 
 \input{windows}                 % MS Windows ONLY
+\input{libmsilib}
 \input{libmsvcrt}
 \input{libwinreg}
 \input{libwinsound}

Doc/lib/libmsilib.tex

@@ -0,0 +1,485 @@
+\section{\module{msilib} ---
+         Read and write Microsoft Installer files}
+
+\declaremodule{standard}{msilib}
+  \platform{Windows}
+\modulesynopsis{Creation of Microsoft Installer files, and CAB files.}
+\moduleauthor{Martin v. L\"owis}{martin@v.loewis.de}
+\sectionauthor{Martin v. L\"owis}{martin@v.loewis.de}
+
+\index{msi}
+
+\versionadded{2.5}
+
+The \module{msilib} supports the creation of Microsoft Installer
+(\code{.msi}) files.  Because these files often contain an embedded
+``cabinet'' file (\code{.cab}), it also exposes an API to create
+CAB files. Support for reading \code{.cab} files is currently not
+implemented; read support for the \code{.msi} database is possible.
+
+This package aims to provide complete access to all tables in an
+\code{.msi} file, therefore, it is a fairly low-level API. Two
+primary applications of this package are the \module{distutils}
+command \code{bdist_msi}, and the creation of Python installer
+package itself (although that currently uses a different version
+of \code{msilib}).
+
+The package contents can be roughly split into four parts:
+low-level CAB routines, low-level MSI routines, higher-level
+MSI routines, and standard table structures.
+
+\begin{funcdesc}{FCICreate}{cabname, files}
+  Create a new CAB file named \var{cabname}. \var{files} must
+  be a list of tuples, each containing the name of the file on
+  disk, and the name of the file inside the CAB file.
+
+  The files are added to the CAB file in the order they have
+  in the list. All files are added into a single CAB file,
+  using the MSZIP compression algorithm.
+
+  Callbacks to Python for the various steps of MSI creation
+  are currently not exposed.
+\end{funcdesc}
+
+\begin{funcdesc}{UUIDCreate}{}
+  Return the string representation of a new unique identifier.
+  This wraps the Windows API functions \code{UuidCreate} and
+  \code{UuidToString}.
+\end{funcdesc}
+
+\begin{funcdesc}{OpenDatabase}{path, persist}
+  Return a new database object by calling MsiOpenDatabase.  
+  \var{path} is the file name of the
+  MSI file; persist can be one of the constants 
+  \code{MSIDBOPEN_CREATEDIRECT}, \code{MSIDBOPEN_CREATE},
+  \code{MSIDBOPEN_DIRECT}, \code{MSIDBOPEN_READONLY}, or
+  \code{MSIDBOPEN_TRANSACT}, and may include the flag
+  \code{MSIDBOPEN_PATCHFILE}. See the Microsoft documentation for
+  the meaning of these flags; depending on the flags,
+  an existing database is opened, or a new one created.
+\end{funcdesc}
+
+\begin{funcdesc}{CreateRecord}{count}
+  Return a new record object by calling MSICreateRecord.
+  \var{count} is the number of fields of the record.
+\end{funcdesc}
+
+\begin{funcdesc}{init_database}{name, schema, ProductName, ProductCode, ProductVersion, Manufacturer}
+  Create and return a new database \var{name}, initialize it 
+  with \var{schema},  and set the properties \var{ProductName},
+  \var{ProductCode}, \var{ProductVersion}, and \var{Manufacturer}.
+
+  \var{schema} must be a module object containing \code{tables} and
+  \code{_Validation_records} attributes; typically,
+  \module{msilib.schema} should be used.
+
+  The database will contain just the schema and the validation
+  records when this function returns.
+\end{funcdesc}
+
+\begin{funcdesc}{add_data}{database, records}
+  Add all \var{records} to \var{database}.  \var{records} should
+  be a list of tuples, each one containing all fields of a record
+  according to the schema of the table.  For optional fields,
+  \code{None} can be passed.
+
+  Field values can be int or long numbers, strings, or instances
+  of the Binary class.
+\end{funcdesc}
+
+\begin{classdesc}{Binary}{filename}
+  Represents entries into the Binary table; inserting such
+  an object using \function{add_data} reads the file named
+  \var{filename} into the table.
+\end{classdesc}
+
+\begin{funcdesc}{add_tables}{database, module}
+  Add all table content from \var{module} to \var{database}.
+  \var{module} must contain an attribute \var{tables}
+  listing all tables for which content should be added,
+  and one attribute per table that has the actual content.
+
+  This is typically used to install the sequence 
+\end{funcdesc}
+
+\begin{funcdesc}{add_stream}{database, name, path}
+  Add the file \var{path} into the \code{_Stream} table
+  of \var{database}, with the stream name \var{name}.
+\end{funcdesc}
+
+\begin{funcdesc}{gen_uuid}{}
+  Return a new UUID, in the format that MSI typically
+  requires (i.e. in curly braces, and with all hexdigits
+  in upper-case).
+\end{funcdesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/devnotes/winprog/fcicreate.asp]{FCICreateFile}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidcreate.asp]{UuidCreate}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp]{UuidToString}{}
+\end{seealso}
+
+\subsection{Database Objects\label{database-objects}}
+
+\begin{methoddesc}{OpenView}{sql}
+  Return a view object, by calling MSIDatabaseOpenView.
+  \var{sql} is the SQL statement to execute.
+\end{methoddesc}
+
+\begin{methoddesc}{Commit}{}
+  Commit the changes pending in the current transaction,
+  by calling MSIDatabaseCommit.
+\end{methoddesc}
+
+\begin{methoddesc}{GetSummaryInformation}{count}
+  Return a new summary information object, by calling
+  MsiGetSummaryInformation.  \var{count} is the maximum number of
+  updated values.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp]{MSIOpenView}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp]{MSIDatabaseCommit}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp]{MSIGetSummaryInformation}{}
+\end{seealso}
+
+\subsection{View Objects\label{view-objects}}
+
+\begin{methoddesc}{Execute}{\optional{params=None}}
+  Execute the SQL query of the view, through MSIViewExecute.
+  \var{params} is an optional record describing actual values
+  of the parameter tokens in the query.
+\end{methoddesc}
+
+\begin{methoddesc}{GetColumnInfo}{kind}
+  Return a record describing the columns of the view, through
+  calling MsiViewGetColumnInfo. \var{kind} can be either
+  \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}
+\end{methoddesc}
+
+\begin{methoddesc}{Fetch}{}
+  Return a result record of the query, through calling
+  MsiViewFetch.
+\end{methoddesc}
+
+\begin{methoddesc}{Modify}{kind, data}
+  Modify the view, by calling MsiViewModify. \var{kind}
+  can be one of  \code{MSIMODIFY_SEEK}, \code{MSIMODIFY_REFRESH},
+  \code{MSIMODIFY_INSERT}, \code{MSIMODIFY_UPDATE}, \code{MSIMODIFY_ASSIGN},
+  \code{MSIMODIFY_REPLACE}, \code{MSIMODIFY_MERGE}, \code{MSIMODIFY_DELETE},
+  \code{MSIMODIFY_INSERT_TEMPORARY}, \code{MSIMODIFY_VALIDATE},
+  \code{MSIMODIFY_VALIDATE_NEW}, \code{MSIMODIFY_VALIDATE_FIELD}, or
+  \code{MSIMODIFY_VALIDATE_DELETE}.
+
+  \var{data} must be a record describing the new data.
+\end{methoddesc}
+
+\begin{methoddesc}{Close}{}
+  Close the view, through MsiViewClose.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp]{MsiViewExecute}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp]{MSIViewGetColumnInfo}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewfetch.asp]{MsiViewFetch}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewmodify.asp]{MsiViewModify}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp]{MsiViewClose}{}
+\end{seealso}
+
+\subsection{Summary Information Objects\label{summary-objects}}
+
+\begin{methoddesc}{GetProperty}{field}
+  Return a property of the summary, through MsiSummaryInfoGetProperty.
+  \var{field} is the name of the property, and can be one of the
+  constants
+  \code{PID_CODEPAGE}, \code{PID_TITLE}, \code{PID_SUBJECT},
+  \code{PID_AUTHOR}, \code{PID_KEYWORDS}, \code{PID_COMMENTS},
+  \code{PID_TEMPLATE}, \code{PID_LASTAUTHOR}, \code{PID_REVNUMBER},
+  \code{PID_LASTPRINTED}, \code{PID_CREATE_DTM}, \code{PID_LASTSAVE_DTM},
+  \code{PID_PAGECOUNT}, \code{PID_WORDCOUNT}, \code{PID_CHARCOUNT},
+  \code{PID_APPNAME}, or \code{PID_SECURITY}.
+\end{methoddesc}
+
+\begin{methoddesc}{GetPropertyCount}{}
+  Return the number of summary properties, through
+  MsiSummaryInfoGetPropertyCount.
+\end{methoddesc}
+
+\begin{methoddesc}{SetProperty}{field, value}
+  Set a property through MsiSummaryInfoSetProperty. \var{field}
+  can have the same values as in \method{GetProperty}, \var{value}
+  is the new value of the property. Possible value types are integer
+  and string.
+\end{methoddesc}
+
+\begin{methoddesc}{Persist}{}
+  Write the modified properties to the summary information stream,
+  using MsiSummaryInfoPersist.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp]{MsiSummaryInfoGetProperty}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp]{MsiSummaryInfoGetPropertyCount}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp]{MsiSummaryInfoSetProperty}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp]{MsiSummaryInfoPersist}{}
+\end{seealso}
+
+\subsection{Record Objects\label{record-objects}}
+
+\begin{methoddesc}{GetFieldCount}{}
+  Return the number of fields of the record, through MsiRecordGetFieldCount.
+\end{methoddesc}
+
+\begin{methoddesc}{SetString}{field, value}
+  Set \var{field} to \var{value} through MsiRecordSetString.
+  \var{field} must be an integer; \var{value} a string.
+\end{methoddesc}
+
+\begin{methoddesc}{SetStream}{field, value}
+  Set \var{field} to the contents of the file named \var{value},
+  through MsiRecordSetStream.
+  \var{field} must be an integer; \var{value} a string.
+\end{methoddesc}
+
+\begin{methoddesc}{SetInteger}{field, value}
+  Set \var{field} to \var{value} through MsiRecordSetInteger.
+  Both \var{field} and \var{value} must be an integers.
+\end{methoddesc}
+
+\begin{methoddesc}{ClearData}{}
+  Set all fields of the record to 0, through MsiRecordClearData.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp]{MsiRecordGetFieldCount}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp]{MsiRecordSetString}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstream.asp]{MsiRecordSetStream}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetinteger.asp]{MsiRecordSetInteger}{}
+  \seetitle[http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordclear.asp]{MsiRecordClear}{}
+\end{seealso}
+
+\subsection{Errors\label{msi-errors}}
+
+All wrappers around MSI functions raise \exception{MsiError};
+the string inside the exception will contain more detail.
+
+\subsection{CAB Objects\label{cab}}
+
+\begin{classdesc}{CAB}{name}
+  The class \class{CAB} represents a CAB file. During MSI construction,
+  files will be added simultaneously to the \code{Files} table, and
+  to a CAB file. Then, when all files have been added, the CAB file
+  can be written, then added to the MSI file.
+
+  \var{name} is the name of the CAB file in the MSI file.
+\end{classdesc}
+
+\begin{methoddesc}[CAB]{append}{full, logical}
+  Add the file with the pathname \var{full} to the CAB file,
+  under the name \var{logical}. If there is already a file
+  named \var{logical}, a new file name is created.
+
+  Return the index of the file in the CAB file, and the
+  new name of the file inside the CAB file.
+\end{methoddesc}
+
+\begin{methoddesc}[CAB]{append}{database}
+  Generate a CAB file, add it as a stream to the MSI file,
+  put it into the \code{Media} table, and remove the generated
+  file from the disk.
+\end{methoddesc}
+
+\subsection{Directory Objects\label{msi-directory}}
+
+\begin{classdesc}{Directory}{database, cab, basedir, physical, 
+                  logical, default, component, \optional{flags}}
+  Create a new directory in the Directory table. There is a current
+  component at each point in time for the directory, which is either
+  explicitly created through start_component, or implicitly when files
+  are added for the first time. Files are added into the current
+  component, and into the cab file.  To create a directory, a base
+  directory object needs to be specified (can be None), the path to
+  the physical directory, and a logical directory name.  Default
+  specifies the DefaultDir slot in the directory table. componentflags
+  specifies the default flags that new components get.
+\end{classdesc}
+
+\begin{methoddesc}[Directory]{start_component}{\optional{component\optional{,
+      feature\optional{, flags\optional{, keyfile\optional{, uuid}}}}}}
+  Add an entry to the Component table, and make this component the
+  current for this directory. If no component name is given, the
+  directory name is used. If no feature is given, the current feature
+  is used. If no flags are given, the directory's default flags are
+  used. If no keyfile is given, the KeyPath is left null in the
+  Component table.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{add_file}{file\optional{, src\optional{,
+      version\optional{, language}}}}
+  Add a file to the current component of the directory, starting a new
+  one one if there is no current component. By default, the file name
+  in the source and the file table will be identical. If the src file
+  is specified, it is interpreted relative to the current
+  directory. Optionally, a version and a language can be specified for
+  the entry in the File table.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{glob}{pattern\optional{, exclude}}
+  Add a list of files to the current component as specified in the glob
+  pattern. Individual files can be excluded in the exclude list.
+\end{methoddesc}
+
+\begin{methoddesc}[Directory]{remove_pyc}{}
+  Remove .pyc/.pyo files on uninstall
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp]{Directory Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp]{File Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp]{Component Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp]{FeatureComponents Table}{}
+\end{seealso}
+
+
+\subsection{Features\label{features}}
+
+\begin{classdesc}{Feature}{database, id, title, desc, display\optional{,
+    level=1\optional{, parent\optional\{, directory\optional{, 
+    attributes=0}}}}
+
+  Add a new record to the \code{Feature} table, using the values
+  \var{id}, \var{parent.id}, \var{title}, \var{desc}, \var{display},
+  \var{level}, \var{directory}, and \var{attributes}. The resulting
+  feature object can be passed to the \method{start_component} method
+  of \class{Directory}.
+\end{classdesc}
+
+\begin{methoddesc}[Feature]{set_current}{}
+  Make this feature the current feature of \module{msilib}.
+  New components are automatically added to the default feature,
+  unless a feature is explicitly specified.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp]{Feature Table}{}
+\end{seealso}
+
+\subsection{GUI classes\label{msi-gui}}
+
+\module{msilib} provides several classes that wrap the GUI tables in
+an MSI database. However, no standard user interface is provided; use
+\module{bdist_msi} to create MSI files with a user-interface for
+installing Python packages.
+
+\begin{classdesc}{Control}{dlg, name}
+  Base class of the dialog controls. \var{dlg} is the dialog object
+  the control belongs to, and \var{name} is the control's name.
+\end{classdesc}
+
+\begin{methoddesc}[Control]{event}{event, argument\optional{, 
+   condition = ``1''\optional{, ordering}}}
+
+  Make an entry into the \code{ControlEvent} table for this control.
+\end{methoddesc}
+
+\begin{methoddesc}[Control]{mapping}{event, attribute}
+  Make an entry into the \code{EventMapping} table for this control.
+\end{methoddesc}
+
+\begin{methoddesc}[Control]{condition}{action, condition}
+  Make an entry into the \code{ControlCondition} table for this control.
+\end{methoddesc}
+
+
+\begin{classdesc}{RadioButtonGroup}{dlg, name, property}
+  Create a radio button control named \var{name}. \var{property}
+  is the installer property that gets set when a radio button
+  is selected.
+\end{classdesc}
+
+\begin{methoddesc}[RadioButtonGroup]{add}{name, x, y, width, height, text
+                                          \optional{, value}}
+  Add a radio button named \var{name} to the group, at the
+  coordinates \var{x}, \var{y}, \var{width}, \var{height}, and
+  with the label \var{text}. If \var{value} is omitted, it
+  defaults to \var{name}.
+\end{methoddesc}
+           
+\begin{classdesc}{Dialog}{db, name, x, y, w, h, attr, title, first, 
+    default, cancel}
+  Return a new Dialog object. An entry in the \code{Dialog} table
+  is made, with the specified coordinates, dialog attributes, title,
+  name of the first, default, and cancel controls.
+\end{classdesc}
+
+\begin{methoddesc}[Dialog]{control}{name, type, x, y, width, height, 
+                  attributes, property, text, control_next, help}
+  Return a new Control object. An entry in the \code{Control} table
+  is made with the specified parameters.
+
+  This is a generic method; for specific types, specialized methods
+  are provided.
+\end{methoddesc}
+
+
+\begin{methoddesc}[Dialog]{text}{name, x, y, width, height, attributes, text}
+  Add and return a \code{Text} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{bitmap}{name, x, y, width, height, text}
+  Add and return a \code{Bitmap} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{line}{name, x, y, width, height}
+  Add and return a \code{Line} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{pushbutton}{name, x, y, width, height, attributes, 
+                                 text, next_control}
+  Add and return a \code{PushButton} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{radiogroup}{name, x, y, width, height, 
+                                 attributes, property, text, next_control}
+  Add and return a \code{RadioButtonGroup} control.
+\end{methoddesc}
+
+\begin{methoddesc}[Dialog]{checkbox}{name, x, y, width, height, 
+                                 attributes, property, text, next_control}
+  Add and return a \code{CheckBox} control.
+\end{methoddesc}
+
+\begin{seealso}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp]{Dialog Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp]{Control Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp]{Control Types}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp]{ControlCondition Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/controlevent_table.asp]{ControlEvent Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/eventmapping_table.asp]{EventMapping Table}{}
+  \seetitle[http://msdn.microsoft.com/library/en-us/msi/setup/radiobutton_table.asp]{RadioButton Table}{}
+\end{seealso}
+
+\subsection{Precomputed tables\label{msi-tables}}
+
+\module{msilib} provides a few subpackages that contain
+only schema and table definitions. Currently, these definitions
+are based on MSI version 2.0.
+
+\begin{datadesc}{schema}
+  This is the standard MSI schema for MSI 2.0, with the
+  \var{tables} variable providing a list of table definitions,
+  and \var{_Validation_records} providing the data for
+  MSI validation.
+\end{datadesc}
+
+\begin{datadesc}{sequence}
+  This module contains table contents for the standard sequence
+  tables: \var{AdminExecuteSequence}, \var{AdminUISequence},
+  \var{AdvtExecuteSequence}, \var{InstallExecuteSequence}, and
+  \var{InstallUISequence}.
+\end{datadesc}
+
+\begin{datadesc}{text}
+  This module contains definitions for the UIText and ActionText
+  tables, for the standard installer actions.
+\end{datadesc}