summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libmsilib.tex
blob: 1e044f4907ca056679ea3ec3a84f802667a4f430 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
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 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}{OpenView}{sql}
  Return a view object, by calling \cfunction{MSIDatabaseOpenView}.
  \var{sql} is the SQL statement to execute.
\end{methoddesc}

\begin{methoddesc}{Commit}{}
  Commit the changes pending in the current transaction,
  by calling \cfunction{MSIDatabaseCommit}.
\end{methoddesc}

\begin{methoddesc}{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}{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}{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}{Fetch}{}
  Return a result record of the query, through calling
  \cfunction{MsiViewFetch}.
\end{methoddesc}

\begin{methoddesc}{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}{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}{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}{GetPropertyCount}{}
  Return the number of summary properties, through
  \cfunction{MsiSummaryInfoGetPropertyCount}.
\end{methoddesc}

\begin{methoddesc}{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}{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}{GetFieldCount}{}
  Return the number of fields of the record, through \cfunction{MsiRecordGetFieldCount}.
\end{methoddesc}

\begin{methoddesc}{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}{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}{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}{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, 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{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}