diff options
Diffstat (limited to 'Doc/lib/libmsilib.tex')
| -rw-r--r-- | Doc/lib/libmsilib.tex | 485 |
1 files changed, 0 insertions, 485 deletions
diff --git a/Doc/lib/libmsilib.tex b/Doc/lib/libmsilib.tex deleted file mode 100644 index 075103aae9..0000000000 --- a/Doc/lib/libmsilib.tex +++ /dev/null @@ -1,485 +0,0 @@ -\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 appear - 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 \cfunction{UuidCreate} and - \cfunction{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; \var{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 \cfunction{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 in 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 tables. -\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}[Database]{OpenView}{sql} - Return a view object, by calling \cfunction{MSIDatabaseOpenView}. - \var{sql} is the SQL statement to execute. -\end{methoddesc} - -\begin{methoddesc}[Database]{Commit}{} - Commit the changes pending in the current transaction, - by calling \cfunction{MSIDatabaseCommit}. -\end{methoddesc} - -\begin{methoddesc}[Database]{GetSummaryInformation}{count} - Return a new summary information object, by calling - \cfunction{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}[View]{Execute}{\optional{params=None}} - Execute the SQL query of the view, through \cfunction{MSIViewExecute}. - \var{params} is an optional record describing actual values - of the parameter tokens in the query. -\end{methoddesc} - -\begin{methoddesc}[View]{GetColumnInfo}{kind} - Return a record describing the columns of the view, through - calling \cfunction{MsiViewGetColumnInfo}. \var{kind} can be either - \code{MSICOLINFO_NAMES} or \code{MSICOLINFO_TYPES}. -\end{methoddesc} - -\begin{methoddesc}[View]{Fetch}{} - Return a result record of the query, through calling - \cfunction{MsiViewFetch}. -\end{methoddesc} - -\begin{methoddesc}[View]{Modify}{kind, data} - Modify the view, by calling \cfunction{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}[View]{Close}{} - Close the view, through \cfunction{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}[SummaryInformation]{GetProperty}{field} - Return a property of the summary, through \cfunction{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}[SummaryInformation]{GetPropertyCount}{} - Return the number of summary properties, through - \cfunction{MsiSummaryInfoGetPropertyCount}. -\end{methoddesc} - -\begin{methoddesc}[SummaryInformation]{SetProperty}{field, value} - Set a property through \cfunction{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}[SummaryInformation]{Persist}{} - Write the modified properties to the summary information stream, - using \cfunction{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}[Record]{GetFieldCount}{} - Return the number of fields of the record, through \cfunction{MsiRecordGetFieldCount}. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetString}{field, value} - Set \var{field} to \var{value} through \cfunction{MsiRecordSetString}. - \var{field} must be an integer; \var{value} a string. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetStream}{field, value} - Set \var{field} to the contents of the file named \var{value}, - through \cfunction{MsiRecordSetStream}. - \var{field} must be an integer; \var{value} a string. -\end{methoddesc} - -\begin{methoddesc}[Record]{SetInteger}{field, value} - Set \var{field} to \var{value} through \cfunction{MsiRecordSetInteger}. - Both \var{field} and \var{value} must be an integer. -\end{methoddesc} - -\begin{methoddesc}[Record]{ClearData}{} - Set all fields of the record to 0, through \cfunction{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, file, 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]{commit}{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{componentflags}} - 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 \method{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 \code{None}), the path to - the physical directory, and a logical directory name. \var{default} - specifies the DefaultDir slot in the directory table. \var{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 component for this directory. If no component name is given, the - directory name is used. If no \var{feature} is given, the current feature - is used. If no \var{flags} are given, the directory's default flags are - used. If no \var{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 if there is no current component. By default, the file name - in the source and the file table will be identical. If the \var{src} file - is specified, it is interpreted relative to the current - directory. Optionally, a \var{version} and a \var{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 \var{exclude} list. -\end{methoddesc} - -\begin{methoddesc}[Directory]{remove_pyc}{} - Remove \code{.pyc}/\code{.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 \class{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 \class{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} |