rest25/library/msilib.rst => rest262/library/msilib.rst
n1- 
2:mod:`msilib` --- Read and write Microsoft Installer files
3==========================================================
4
5.. module:: msilib
6   :platform: Windows
7   :synopsis: Creation of Microsoft Installer files, and CAB files.
8.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
9.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
37
38   The files are added to the CAB file in the order they appear in the list. All
39   files are added into a single CAB file, using the MSZIP compression algorithm.
40
41   Callbacks to Python for the various steps of MSI creation are currently not
42   exposed.
43
44
n45-.. function:: UUIDCreate()
n44+.. function:: UuidCreate()
46
47   Return the string representation of a new unique identifier. This wraps the
48   Windows API functions :cfunc:`UuidCreate` and :cfunc:`UuidToString`.
49
50
51.. function:: OpenDatabase(path, persist)
52
53   Return a new database object by calling MsiOpenDatabase.   *path* is the file
62.. function:: CreateRecord(count)
63
64   Return a new record object by calling :cfunc:`MSICreateRecord`. *count* is the
65   number of fields of the record.
66
67
68.. function:: init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)
69
n70-   Create and return a new database *name*, initialize it  with *schema*,  and set
n69+   Create and return a new database *name*, initialize it with *schema*, and set
71   the properties *ProductName*, *ProductCode*, *ProductVersion*, and
72   *Manufacturer*.
73
74   *schema* must be a module object containing ``tables`` and
75   ``_Validation_records`` attributes; typically, :mod:`msilib.schema` should be
76   used.
77
78   The database will contain just the schema and the validation records when this
79   function returns.
80
81
n82-.. function:: add_data(database, records)
n81+.. function:: add_data(database, table, records)
83
n84-   Add all *records* to *database*.  *records* should be a list of tuples, each one
n83+   Add all *records* to the table named *table* in *database*.
85-   containing all fields of a record according to the schema of the table.  For
84+ 
85+   The *table* argument must be one of the predefined tables in the MSI schema,
86+   e.g. ``'Feature'``, ``'File'``, ``'Component'``, ``'Dialog'``, ``'Control'``,
87+   etc.
88+ 
89+   *records* should be a list of tuples, each one containing all fields of a
90+   record according to the schema of the table.  For optional fields,
86-   optional fields, ``None`` can be passed.
91+   ``None`` can be passed.
87
88   Field values can be int or long numbers, strings, or instances of the Binary
89   class.
90
91
92.. class:: Binary(filename)
93
94   Represents entries in the Binary table; inserting such an object using
123   `UuidToString <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
124
125.. _database-objects:
126
127Database Objects
128----------------
129
130
n131-.. method:: XXX Class.OpenView(sql)
n136+.. method:: Database.OpenView(sql)
132
133   Return a view object, by calling :cfunc:`MSIDatabaseOpenView`. *sql* is the SQL
134   statement to execute.
135
136
n137-.. method:: XXX Class.Commit()
n142+.. method:: Database.Commit()
138
139   Commit the changes pending in the current transaction, by calling
140   :cfunc:`MSIDatabaseCommit`.
141
142
n143-.. method:: XXX Class.GetSummaryInformation(count)
n148+.. method:: Database.GetSummaryInformation(count)
144
145   Return a new summary information object, by calling
146   :cfunc:`MsiGetSummaryInformation`.  *count* is the maximum number of updated
147   values.
148
149
150.. seealso::
151
n152-   `MSIOpenView <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiopenview.asp>`_
n157+   `MSIDatabaseOpenView <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
153   `MSIDatabaseCommit <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
154   `MSIGetSummaryInformation <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
155
156.. _view-objects:
157
158View Objects
159------------
160
161
n162-.. method:: XXX Class.Execute([params=None])
n167+.. method:: View.Execute(params)
163
n164-   Execute the SQL query of the view, through :cfunc:`MSIViewExecute`. *params* is
n169+   Execute the SQL query of the view, through :cfunc:`MSIViewExecute`. If
165-   an optional record describing actual values of the parameter tokens in the
170+   *params* is not ``None``, it is a record describing actual values of the
166-   query.
171+   parameter tokens in the query.
167
168
n169-.. method:: XXX Class.GetColumnInfo(kind)
n174+.. method:: View.GetColumnInfo(kind)
170
171   Return a record describing the columns of the view, through calling
172   :cfunc:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or
173   ``MSICOLINFO_TYPES``.
174
175
n176-.. method:: XXX Class.Fetch()
n181+.. method:: View.Fetch()
177
178   Return a result record of the query, through calling :cfunc:`MsiViewFetch`.
179
180
n181-.. method:: XXX Class.Modify(kind, data)
n186+.. method:: View.Modify(kind, data)
182
183   Modify the view, by calling :cfunc:`MsiViewModify`. *kind* can be one of
184   ``MSIMODIFY_SEEK``, ``MSIMODIFY_REFRESH``, ``MSIMODIFY_INSERT``,
185   ``MSIMODIFY_UPDATE``, ``MSIMODIFY_ASSIGN``, ``MSIMODIFY_REPLACE``,
186   ``MSIMODIFY_MERGE``, ``MSIMODIFY_DELETE``, ``MSIMODIFY_INSERT_TEMPORARY``,
187   ``MSIMODIFY_VALIDATE``, ``MSIMODIFY_VALIDATE_NEW``,
188   ``MSIMODIFY_VALIDATE_FIELD``, or ``MSIMODIFY_VALIDATE_DELETE``.
189
190   *data* must be a record describing the new data.
191
192
n193-.. method:: XXX Class.Close()
n198+.. method:: View.Close()
194
195   Close the view, through :cfunc:`MsiViewClose`.
196
197
198.. seealso::
199
200   `MsiViewExecute <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
201   `MSIViewGetColumnInfo <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
204   `MsiViewClose <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msiviewclose.asp>`_
205
206.. _summary-objects:
207
208Summary Information Objects
209---------------------------
210
211
n212-.. method:: XXX Class.GetProperty(field)
n217+.. method:: SummaryInformation.GetProperty(field)
213
214   Return a property of the summary, through :cfunc:`MsiSummaryInfoGetProperty`.
215   *field* is the name of the property, and can be one of the constants
216   ``PID_CODEPAGE``, ``PID_TITLE``, ``PID_SUBJECT``, ``PID_AUTHOR``,
217   ``PID_KEYWORDS``, ``PID_COMMENTS``, ``PID_TEMPLATE``, ``PID_LASTAUTHOR``,
218   ``PID_REVNUMBER``, ``PID_LASTPRINTED``, ``PID_CREATE_DTM``,
219   ``PID_LASTSAVE_DTM``, ``PID_PAGECOUNT``, ``PID_WORDCOUNT``, ``PID_CHARCOUNT``,
220   ``PID_APPNAME``, or ``PID_SECURITY``.
221
222
n223-.. method:: XXX Class.GetPropertyCount()
n228+.. method:: SummaryInformation.GetPropertyCount()
224
225   Return the number of summary properties, through
226   :cfunc:`MsiSummaryInfoGetPropertyCount`.
227
228
n229-.. method:: XXX Class.SetProperty(field, value)
n234+.. method:: SummaryInformation.SetProperty(field, value)
230
231   Set a property through :cfunc:`MsiSummaryInfoSetProperty`. *field* can have the
232   same values as in :meth:`GetProperty`, *value* is the new value of the property.
233   Possible value types are integer and string.
234
235
n236-.. method:: XXX Class.Persist()
n241+.. method:: SummaryInformation.Persist()
237
238   Write the modified properties to the summary information stream, using
239   :cfunc:`MsiSummaryInfoPersist`.
240
241
242.. seealso::
243
244   `MsiSummaryInfoGetProperty <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
247   `MsiSummaryInfoPersist <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
248
249.. _record-objects:
250
251Record Objects
252--------------
253
254
n255-.. method:: XXX Class.GetFieldCount()
n260+.. method:: Record.GetFieldCount()
256
257   Return the number of fields of the record, through
258   :cfunc:`MsiRecordGetFieldCount`.
259
260
n266+.. method:: Record.GetInteger(field)
267+ 
268+   Return the value of *field* as an integer where possible.  *field* must
269+   be an integer.
270+ 
271+ 
272+.. method:: Record.GetString(field)
273+ 
274+   Return the value of *field* as a string where possible.  *field* must
275+   be an integer.
276+ 
277+ 
261-.. method:: XXX Class.SetString(field, value)
278+.. method:: Record.SetString(field, value)
262
263   Set *field* to *value* through :cfunc:`MsiRecordSetString`. *field* must be an
264   integer; *value* a string.
265
266
n267-.. method:: XXX Class.SetStream(field, value)
n284+.. method:: Record.SetStream(field, value)
268
269   Set *field* to the contents of the file named *value*, through
270   :cfunc:`MsiRecordSetStream`. *field* must be an integer; *value* a string.
271
272
n273-.. method:: XXX Class.SetInteger(field, value)
n290+.. method:: Record.SetInteger(field, value)
274
275   Set *field* to *value* through :cfunc:`MsiRecordSetInteger`. Both *field* and
276   *value* must be an integer.
277
278
n279-.. method:: XXX Class.ClearData()
n296+.. method:: Record.ClearData()
280
281   Set all fields of the record to 0, through :cfunc:`MsiRecordClearData`.
282
283
284.. seealso::
285
286   `MsiRecordGetFieldCount <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
287   `MsiRecordSetString <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
309   The class :class:`CAB` represents a CAB file. During MSI construction, files
310   will be added simultaneously to the ``Files`` table, and to a CAB file. Then,
311   when all files have been added, the CAB file can be written, then added to the
312   MSI file.
313
314   *name* is the name of the CAB file in the MSI file.
315
316
n317-.. method:: CAB.append(full, logical)
n334+   .. method:: append(full, file, logical)
318
n319-   Add the file with the pathname *full* to the CAB file, under the name *logical*.
n336+      Add the file with the pathname *full* to the CAB file, under the name
320-   If there is already a file named *logical*, a new file name is created.
337+      *logical*.  If there is already a file named *logical*, a new file name is
338+      created.
321
n322-   Return the index of the file in the CAB file, and the new name of the file
n340+      Return the index of the file in the CAB file, and the new name of the file
323-   inside the CAB file.
341+      inside the CAB file.
324
325
n326-.. method:: CAB.append(database)
n344+   .. method:: commit(database)
327
n328-   Generate a CAB file, add it as a stream to the MSI file, put it into the
n346+      Generate a CAB file, add it as a stream to the MSI file, put it into the
329-   ``Media`` table, and remove the generated file from the disk.
347+      ``Media`` table, and remove the generated file from the disk.
330
331
332.. _msi-directory:
333
334Directory Objects
335-----------------
336
337
342   :meth:`start_component`, or implicitly when files are added for the first time.
343   Files are added into the current component, and into the cab file.  To create a
344   directory, a base directory object needs to be specified (can be ``None``), the
345   path to the physical directory, and a logical directory name.  *default*
346   specifies the DefaultDir slot in the directory table. *componentflags* specifies
347   the default flags that new components get.
348
349
n350-.. method:: Directory.start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
n368+   .. method:: start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
351
n352-   Add an entry to the Component table, and make this component the current
n370+      Add an entry to the Component table, and make this component the current
353-   component for this directory. If no component name is given, the directory name
371+      component for this directory. If no component name is given, the directory
354-   is used. If no *feature* is given, the current feature is used. If no *flags*
372+      name is used. If no *feature* is given, the current feature is used. If no
355-   are given, the directory's default flags are used. If no *keyfile* is given, the
373+      *flags* are given, the directory's default flags are used. If no *keyfile*
356-   KeyPath is left null in the Component table.
374+      is given, the KeyPath is left null in the Component table.
357
358
n359-.. method:: Directory.add_file(file[, src[, version[, language]]])
n377+   .. method:: add_file(file[, src[, version[, language]]])
360
n361-   Add a file to the current component of the directory, starting a new one if
n379+      Add a file to the current component of the directory, starting a new one
362-   there is no current component. By default, the file name in the source and the
380+      if there is no current component. By default, the file name in the source
363-   file table will be identical. If the *src* file is specified, it is interpreted
381+      and the file table will be identical. If the *src* file is specified, it
364-   relative to the current directory. Optionally, a *version* and a *language* can
382+      is interpreted relative to the current directory. Optionally, a *version*
365-   be specified for the entry in the File table.
383+      and a *language* can be specified for the entry in the File table.
366
367
n368-.. method:: Directory.glob(pattern[, exclude])
n386+   .. method:: glob(pattern[, exclude])
369
n370-   Add a list of files to the current component as specified in the glob pattern.
n388+      Add a list of files to the current component as specified in the glob
371-   Individual files can be excluded in the *exclude* list.
389+      pattern.  Individual files can be excluded in the *exclude* list.
372
373
n374-.. method:: Directory.remove_pyc()
n392+   .. method:: remove_pyc()
375
n376-   Remove ``.pyc``/``.pyo`` files on uninstall.
n394+      Remove ``.pyc``/``.pyo`` files on uninstall.
377
378
379.. seealso::
380
381   `Directory Table <http://msdn.microsoft.com/library/en-us/msi/setup/directory_table.asp>`_
382   `File Table <http://msdn.microsoft.com/library/en-us/msi/setup/file_table.asp>`_
383   `Component Table <http://msdn.microsoft.com/library/en-us/msi/setup/component_table.asp>`_
384   `FeatureComponents Table <http://msdn.microsoft.com/library/en-us/msi/setup/featurecomponents_table.asp>`_
392.. class:: Feature(database, id, title, desc, display[, level=1[, parent[, directory[,  attributes=0]]]])
393
394   Add a new record to the ``Feature`` table, using the values *id*, *parent.id*,
395   *title*, *desc*, *display*, *level*, *directory*, and *attributes*. The
396   resulting feature object can be passed to the :meth:`start_component` method of
397   :class:`Directory`.
398
399
n400-.. method:: Feature.set_current()
n418+   .. method:: set_current()
401
n402-   Make this feature the current feature of :mod:`msilib`. New components are
n420+      Make this feature the current feature of :mod:`msilib`. New components are
403-   automatically added to the default feature, unless a feature is explicitly
421+      automatically added to the default feature, unless a feature is explicitly
404-   specified.
422+      specified.
405
406
407.. seealso::
408
409   `Feature Table <http://msdn.microsoft.com/library/en-us/msi/setup/feature_table.asp>`_
410
411.. _msi-gui:
412
419
420
421.. class:: Control(dlg, name)
422
423   Base class of the dialog controls. *dlg* is the dialog object the control
424   belongs to, and *name* is the control's name.
425
426
n427-.. method:: Control.event(event, argument[,  condition = ``1''[, ordering]])
n445+   .. method:: event(event, argument[,  condition=1[, ordering]])
428
n429-   Make an entry into the ``ControlEvent`` table for this control.
n447+      Make an entry into the ``ControlEvent`` table for this control.
430
431
n432-.. method:: Control.mapping(event, attribute)
n450+   .. method:: mapping(event, attribute)
433
n434-   Make an entry into the ``EventMapping`` table for this control.
n452+      Make an entry into the ``EventMapping`` table for this control.
435
436
n437-.. method:: Control.condition(action, condition)
n455+   .. method:: condition(action, condition)
438
n439-   Make an entry into the ``ControlCondition`` table for this control.
n457+      Make an entry into the ``ControlCondition`` table for this control.
440
441
442.. class:: RadioButtonGroup(dlg, name, property)
443
444   Create a radio button control named *name*. *property* is the installer property
445   that gets set when a radio button is selected.
446
447
n448-.. method:: RadioButtonGroup.add(name, x, y, width, height, text [, value])
n466+   .. method:: add(name, x, y, width, height, text [, value])
449
n450-   Add a radio button named *name* to the group, at the coordinates *x*, *y*,
n468+      Add a radio button named *name* to the group, at the coordinates *x*, *y*,
451-   *width*, *height*, and with the label *text*. If *value* is omitted, it defaults
469+      *width*, *height*, and with the label *text*. If *value* is omitted, it
452-   to *name*.
470+      defaults to *name*.
453
454
455.. class:: Dialog(db, name, x, y, w, h, attr, title, first,  default, cancel)
456
457   Return a new :class:`Dialog` object. An entry in the ``Dialog`` table is made,
458   with the specified coordinates, dialog attributes, title, name of the first,
459   default, and cancel controls.
460
461
n462-.. method:: Dialog.control(name, type, x, y, width, height,  attributes, property, text, control_next, help)
n480+   .. method:: control(name, type, x, y, width, height,  attributes, property, text, control_next, help)
463
n464-   Return a new :class:`Control` object. An entry in the ``Control`` table is made
n482+      Return a new :class:`Control` object. An entry in the ``Control`` table is
465-   with the specified parameters.
483+      made with the specified parameters.
466
n467-   This is a generic method; for specific types, specialized methods are provided.
n485+      This is a generic method; for specific types, specialized methods are
486+      provided.
468
469
n470-.. method:: Dialog.text(name, x, y, width, height, attributes, text)
n489+   .. method:: text(name, x, y, width, height, attributes, text)
471
n472-   Add and return a ``Text`` control.
n491+      Add and return a ``Text`` control.
473
474
n475-.. method:: Dialog.bitmap(name, x, y, width, height, text)
n494+   .. method:: bitmap(name, x, y, width, height, text)
476
n477-   Add and return a ``Bitmap`` control.
n496+      Add and return a ``Bitmap`` control.
478
479
n480-.. method:: Dialog.line(name, x, y, width, height)
n499+   .. method:: line(name, x, y, width, height)
481
n482-   Add and return a ``Line`` control.
n501+      Add and return a ``Line`` control.
483
484
n485-.. method:: Dialog.pushbutton(name, x, y, width, height, attributes,  text, next_control)
n504+   .. method:: pushbutton(name, x, y, width, height, attributes,  text, next_control)
486
n487-   Add and return a ``PushButton`` control.
n506+      Add and return a ``PushButton`` control.
488
489
n490-.. method:: Dialog.radiogroup(name, x, y, width, height,  attributes, property, text, next_control)
n509+   .. method:: radiogroup(name, x, y, width, height,  attributes, property, text, next_control)
491
n492-   Add and return a ``RadioButtonGroup`` control.
n511+      Add and return a ``RadioButtonGroup`` control.
493
494
n495-.. method:: Dialog.checkbox(name, x, y, width, height,  attributes, property, text, next_control)
n514+   .. method:: checkbox(name, x, y, width, height,  attributes, property, text, next_control)
496
n497-   Add and return a ``CheckBox`` control.
n516+      Add and return a ``CheckBox`` control.
498
499
500.. seealso::
501
502   `Dialog Table <http://msdn.microsoft.com/library/en-us/msi/setup/dialog_table.asp>`_
503   `Control Table <http://msdn.microsoft.com/library/en-us/msi/setup/control_table.asp>`_
504   `Control Types <http://msdn.microsoft.com/library/en-us/msi/setup/controls.asp>`_
505   `ControlCondition Table <http://msdn.microsoft.com/library/en-us/msi/setup/controlcondition_table.asp>`_
530   *InstallExecuteSequence*, and *InstallUISequence*.
531
532
533.. data:: text
534
535   This module contains definitions for the UIText and ActionText tables, for the
536   standard installer actions.
537
t557+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op