![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to readme.wri CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / mssetup|
Return to readme.wri CVS log | Up to [WindowsNT SDKs] / mstools / mssetup |
1.1.1.2 ! root 1: 1� � �I � � � � � � � README.WRI 1.1 root 2: 3: This file contains extra information about the MS Setup 2.0 Toolkit. This information is provided as an update to the User's Manual. 4: 5: 6: Topics: 1.1.1.2 ! root 7: ! 8: The New 32-bit C-Language Interface ! 9: Win32 Specific Setup Procedures ! 10: User Manual Updates - Chapter 3 - Creating a Setup Script 1.1 root 11: User Manual Updates - Chapter 4 - Using the Disk Layout Utilities 12: User Manual Updates - Chapter 5 - Script Procedures 13: Command Line Arguments to the Setup Toolkit 14: Notes about MS-TEST include file optimizations 15: 1.1.1.2 ! root 16: The New 32-bit C-Language Interface ! 17: ! 18: The 32-bit Micorosoft Setup Toolkit features a new C-Language style interface, which allows Setup programs to be written entirely in C. This allows setup programs to perform additional functionality on Windows NT, such as manipulating the registry, through the use of Win32 APIs. While all of the documentation provided refers to the BASIC Setup Toolkit, the migration to C is quite easy. All of the function definitions have remained the same, so that function names and parameter lists are identical to their original BASIC definitions. For actual C prototypes, refer to the setupapi.h file included in the \MSSETUP\INCLUDE directory. When writing a C setup routine, the following three issues must be kept in mind: ! 19: ! 20: 1) You must call InitSetupToolkit(szCmdLineArgs) early in program ! 21: before any other toolkit calls are made (e.g. near top of ! 22: WinMain()). This will return -1 if a Usage message was ! 23: generated. ! 24: 2) You must call EndSetupToolkit() before exiting if InitSetupToolkit() ! 25: has already been called. ! 26: 3) You must supply a VOID SetupError(INT) routine which will be called by ! 27: Toolkit when error conditions are encountered; it probably ! 28: should call EndSetupToolkit() and then exit(0). Argument will be ! 29: either STFQUIT (when user chooses Cancel\Quit from Copy Files ! 30: Progress Indicator) or STFERR. ! 31: ! 32: For further information, please see the \MSSETUP\SAMPLE directory. This provides a brief setup example, which uses the new C-Interface. ! 33: ! 34: Win32 Specific Setup Procedures ! 35: ! 36: New Functions - expansions of 16-bit functionality ! 37: All of the following have been exapnded to correspond to their Win32 equivalents, refer to the Win32 API Help file for further information. ! 38: ! 39: CreateRegKeyEx() ! 40: CreateRegKeyValueEx() ! 41: DeleteRegKeyEx() ! 42: DoesRegKeyExistEx() ! 43: GetRegKeyValueEx() ! 44: SetRegKeyValueEx() ! 45: CreateProgmanGroupEx() ! 46: CreateProgmanItemEx() ! 47: ShowProgmanGroupEx() ! 48: HasFPPMathChip() ! 49: ! 50: Deleted Functions ! 51: ExitExecRestart() ! 52: RestartListEmpty() ! 53: SetRestartDir() ! 54: GetConfigLastDrive() ! 55: GetConfigNumBuffers() ! 56: GetConfigNumFiles() ! 57: GetConfigRamdriveSize() ! 58: GetConfigSmartdrvSize() ! 59: GetDOSMajorVersion() ! 60: GetDOSMinorVersion() ! 61: SearchForLocationForSharedFile() ! 62: ! 63: NOTE: The MSCPYDIS (Microsoft Copy Disincentive) dll has not been provided. Application writers are encouraged to provide their own Copy Disincentive dialogs. ! 64: ! 65: User Manual Updates - Chapter 3 - Creating a Setup Script ! 66: ! 67: Modifying SETUP.LST to Match Your Script File -- ! 68: ! 69: The [Params] section now accepts an optional line with the key Require31 which should be followed by a string. If the user is running a version of Windows earlier than 3.1, the string will be displayed and the program will immediately end. ! 70: 1.1 root 71: 72: User Manual Updates - Chapter 4 - Using the Disk Layout Utilities 73: 74: Built-in compression algorithm in DSKLAYT2.EXE -- 75: 76: DSKLAYT2.EXE is now built with a compression tool incorporated. By specifying '-ZI' on the command line, this internal compression will be used instead of whatever COMPRESS.EXE tool you might otherwise specify with the -Z switch. The built in compression results in better compression ratios than the SDK compress tool, particularly on binary files such as EXEs and DLLs. The compression time is noticably slower, but the decompression time is only a little slower and usually not significant when reading from floppy drives. The files compressed by this tool are recognized by all the components of the MS Setup Toolkit. This means both as source files referenced in the .INF and as Setup components listed in the .LST file. FILES COMPRESSED WITH THIS INTERNAL TOOL ARE NOT RECOGNIZED BY THE WINDOWS' CONTROL PANEL OR LZEXPAND.DLL. SO DO NOT USE THIS COMPRESSION FOR FONTS, PRINTER DRIVERS, ETC. 77: 78: Having to mix compression schemes can be troublesome; we suggest you have a batch file to launch DSKLAYT2.EXE initially with the '-ZI' option, then remove the special files from the compress directory, and then call DSKLAYT2.EXE again with '-Z COMPRESS.EXE' which will compress only these special files with the SDK compression tool. 79: 80: Command line arguments for Layout and INF file -- 81: 82: When specifying a Layout file and/or an INF file on the command line to DSKLAYT2.EXE, do not use just a drive letter and filename (e.g. "c:project.lyt"). Either use just the filename or a complete path which includes the drive letter, colon, root backslash, any necessary subdirectories, and the filename. The latter method is the most foolproof. 83: 84: Comments about the Layout file format -- 85: 86: The format of the Layout file generated by DSKLAYT.EXE and read by DSKLAYT2.EXE is very restrictive, and we very strongly suggest that users should use DSKLAYT.EXE rather than their favorite editor to modify these files. The file description lines are sorted alphabetically, and each attribute field is required and has a limited number of valid values. Prefixes and contractions are not recognized. Extra whitespace is not expected. The tools may not handle syntax errors gracefully. If you do edit a Layout file directly, we strongly suggest you keep backup copies of the tool generated files. 87: 88: Comments about size checking problems -- 89: 90: If you specify that a source file is to be compressed when it is layed out, but that it is not to be decompressed at installation time, then at installation time you will get an error message claiming that files have been corrupted because the size of the file written doesn't match the size listed in the INF file description line. This is because the Disk Layout Utility uses the size of the original source file to fill the SIZE field of the INF file description line. There are several work arounds to this: 91: You can manually compress your source file in the source tree (so it is compressed before the Disk Layout Utility even sees it), and then turn off compression at layout time for this file. 92: You can manually fix up the SIZE entry in the generated INF file to be that of the compressed file. You will have to do this each time after you run DSKLAYT2.EXE. 93: Your script can call SetSizeCheckMode(scmOff), but this may mask real errors. 94: 95: 96: User Manual Updates - Chapter 5 - Script Procedures 97: 98: Changes to Lookup Table (pages 5-1 to 5-3) -- 99: 100: The section 'Query the user's environment' (page 5-3) should also include the API GetWindowsDir. 101: 102: 103: Modified API -- 104: 105: CopyFile subroutine 106: Arguments cmo% 107: cmoOverwrite is not a valid flag for this argument. This API will always overwrite an existing file. Use the function DoesFileExist() if you do not want to overwrite an existing destination file. cmoTimeStamp is not useful for this routine; the destination file will always be stamped with the current system time. 108: 109: CreateIniKeyValue subroutine 110: Arguments szKey$ 111: Defines the name of the symbol you want to create. If szKey$ already exists and you do not specify cmoOverwrite for the command option flag, this subroutine will do nothing. (It will not fail, it will not display any message, it will just return without taking any action.) 112: 1.1.1.2 ! root 113: CreateProgmanItem subroutine ! 114: Arguments szOther$ ! 115: The acceptable value for this argument is dependent on the version of Windows the end-user is running. ! 116: Windows 3.0: ! 117: [IconPath [, IconIndex [, xPos, yPos]]] ! 118: Windows 3.1: ! 119: [IconPath [, IconIndex [, xPos, yPos [, DefDir [, HotKey [, fMinimize]]]]]] ! 120: Further information on the arguments can be found in Microsoft Windows 3.1 Software Development Kit Programmer's Reference, Volume 1: Overview, Chapter 17: Shell Dynamic Data Exchange Interface, Section 2.5: AddItem. ! 121: 1.1 root 122: DoMsgBox(...) function 123: Arguments wType% 124: SETUPAPI.INC only defines MB_OK, MB_ICONHAND, and MB_TASKMODAL as CONST expressions. If you use any other constants, you will need to define them either in your .MST script or appropriate .INC include file. You can look them up in your WINDOWS.H to find the value they are #defined to, and then add a line such as: 125: CONST MB_YESNO = 4 126: 1.1.1.2 ! root 127: GetCopyListCost(...) function ! 128: Comments If the user is running STACKER (a hard-disk compression utility), this function will return incorrect values because STACKER is fooling DOS about available disk space. If you call this function and you notify the user that there is not enough space when it fails, then you should allow the user to override the notification and continue anyway. ! 129: ! 130: GetProcessorType( ) function ! 131: Return Value Added the return value five(5) for NT-R4000. ! 132: ! 133: GetWindowsMode( ) function ! 134: Return Value Added the return value three(3) for NT-Win. 1.1 root 135: 136: Broken APIs -- 137: 138: RemoveDir subroutine 139: This API was broken late in the development cycle and the problem was discovered too late to fix. If you need to remove an existing directory, write your own routine in a DLL (we suggest putting it in the MSCUISTF.DLL) and prototype it in your .MST script or an appropriate .INC include file. Sorry for the inconvenience. 140: 141: 142: Missing APIs -- 143: 1.1.1.2 ! root 144: AddSrcFileWithAttribsToCopyList function ! 145: Integer% = AddSrcFileWithAttribsToCopyList (szSection$, szKey$, szSrc$, szDest$) ! 146: Adds a file operation to the copy list but uses a fully specified source name and a fully specified destination filename. The src-filename, date, size, version, and language attributes come from the source file. The append, decompress, remove and root attribute fields are set to off. The rename attribute field comes from the destination file. The remaining attribute fields are taken from the specified INF line (szSection and szKey). ! 147: Arguments szSection$ ! 148: INF section label of appropriate file description line. ! 149: szKey$ ! 150: INF reference key of appropriate file description line. ! 151: szSrc$ ! 152: Full path to file to add to the copy list. ! 153: szDest$ ! 154: Full path to file to create/replace. ! 155: ! 156: FFileInUse function ! 157: Integer% = FFileInUse (szFile$) ! 158: Determines whether a specified file is in use - either loaded in memory by Windows (EXEs and DLLs) or possibly by OpenFile() from another task. ! 159: Arguments szFile$ ! 160: Specifies the full path of the file to query. ! 161: Return Value 0 if the file is not in use; non-zero otherwise. ! 162: ! 163: ! 164: ForceRestartOn subroutine ! 165: ForceRestartOn ! 166: Forces the function RestartListEmpty() to return 0 which will cause ExitExecRestart() to occur on Windows 3.1 systems even if the Toolkit did not try to replace a SYSTEM file which was in use. ! 167: ! 168: 1.1 root 169: GetExistingFOTFileForTTF function 170: Integer% = GetExistingFOTFileForTTF (szTTFFile$, szBuf$, cbBuf%) 171: Determines whether a specified TrueType Font (TTF) file has an associated FOT file. This is done by extracting the TypeFace name from the TTF file, querying the WIN.INI [fonts] section to determine if there is a FOT file listed, and if there is, extracting the path to the TTF file actually associated with the FOT file and checking to see if it is the same as the specified TTF file. 172: Arguments szTTFFile$ 173: Specifies the full path of the TTF file to query. 174: szBuf$ 175: Buffer to store path to associated FOT file if one is found. 176: cbBuf% 177: Size of szBuf$. If the return value is longer than this, it will be truncated. 178: Return Value 0 if no associated FOT file otherwise the length of the buffer needed to hold the full path to the FOT file associated with the specified TTF file (return may be greater than, less than or equal to cbBuf%). 179: 180: 181: MakeListFromSectionDate subroutine 182: Exactly like MakeListFromSectionKeys except it produces a list of date fields from an INF section of file description lines. Split files (those with APPEND fields) are not duplicated but rather the field of the final piece is returned. 183: 184: MakeListFromSectionFilename subroutine 185: Exactly like MakeListFromSectionKeys except it produces a list of destination filename fields from an INF section of file description lines. Split files (those with APPEND fields) are not duplicated but rather the destination of the initial piece is returned. 186: 187: MakeListFromSectionSize subroutine 188: Exactly like MakeListFromSectionKeys except it produces a list of size fields from an INF section of file description lines. Split files (those with APPEND fields) are summed together and returned as one entry. 189: 190: MakeListFromSectionVersion subroutine 191: Exactly like MakeListFromSectionKeys except it produces a list of version fields from an INF section of file description lines. Split files (those with APPEND fields) are not duplicated but rather the field of the initial piece is returned. 192: 193: PrependToPath subroutine 194: PrependToPath (szSrc$, szDest$, szDir$, cmo%) 195: Copies szSrc$ to szDest$ and adds szDir$ to any PATH statements found in the file. 196: Arguments szSrc$ 197: Full path of file to read as source. 198: szDest$ 199: Full path of file to create as destination. 200: szDir$ 201: Full directory path to add to any PATH statements. 202: cmo% 203: cmoOverwrite, cmoVital, cmoNone, or cmoAll. 204: Comments If the first line of the file is not a PATH statement, then a simple statement of the form 'SET PATH=<szDir$>' is always added to szDest$ as the first line. For every PATH statement encountered which does not include %PATH%, szDir$ is added to the front of the value associated with PATH. So 'SET PATH=...' becomes 'SET PATH=<szDir$>;...'. There is no attempt to check if szDir$ is already on the PATH or if adding to the PATH will make it too long and create problems for DOS. These checks should be done prior to calling this routine by calling GetEnvVariableValue. 205: 206: SetSizeCheckMode function 207: Integer% = SetSizeCheckMode (scmMode%) 208: Determines whether File Copying will check the resulting length against the SIZE field of the INF file description line during CopyFilesInCopyList. 209: Arguments scmMode% 210: Specifies what the new mode is. Acceptable values are scmOff, scmOnIgnore, and scmOnFatal. 211: Return Value The previous value of the Size Check Mode. 212: Comments scmOff will disable all size checking; scmOnIgnore will generate an error message for mismatches, but the user will be able to ignore this error and continue; scmOnFatal generates an error message that only allows the user to abort. 213: 214: 215: 216: Command Line Arguments to the Setup Toolkit 217: 218: Command line arguments can be passed to the Setup BASIC script by calling _MSTEST.EXE with /C "<command line arguments>" which will set the initial value for the Setup BASIC script global string variable COMMAND$. This is exactly what SETUP.EXE (the bootstrapper program) does. If you look at the CmdLine line in the SETUP.LST, you will see it has the form _MSTEST SAMPLE1.MST /C "/S %s %s". The first %s gets replaced by the original source directory and so the /S switch specifies the source directory to the Setup Toolkit (by default it uses the Current Working Directory which would be incorrect after SETUP.EXE has bootstrapped the setup files to a hard drive.) The second %s is replaced by any command line arguments passed to SETUP.EXE. 219: 220: There are several command line arguments to the Setup Toolkit which you will find useful during development and for the end-user: 221: /? will generate a usage message. 222: /S <src-dir> can be used to set the value of the symbol STF_SRCDIR. This can be very useful during script development when you run _MSTEST.EXE directly rather than through the SETUP.EXE. You can create a network image of your product that does not yet include the Setup files (which will change as you develop them). You can use the /S switch to point at you network image sources without having to copy the new Setup files into the image. 223: /Z <srcfile> <destfile> will copy (and decompress if necessary) one file and then exit the setup program back to Windows. 224: /Y <srcfile> <destfile> will copy (and decompress if necessary) one file but will append to an existing <destfile> and then exit back to Windows. <destfile> must already exist. This will be required if the end-user is manually recreating a split file. 225: /W <srcfile> <destfile> will copy (and decompress if necessary) one file and then exit Windows and return all the way back to DOS. This can be used by a batch file to verify a disk image build has correctly compressed files. 226: /A will cause the symbol STF_MODE to be set to the value "ADMIN". The default value of STF_MODE is "NORMAL". The /A switch is meant to signify that a Network Administrator intends to install your product as a Shared installation on a network node such that several workstations will run the network image without having to physically copied the files to the hard drives of the workstations. You need to inform your clients if you support this mode and your script needs to react accordingly. 227: /N will cause the symbol STF_MODE to be set to the value "NETWORK". This is intended as the second phase of the Shared Application installation. You may want to dispense with this argument and instead have the Admin phase create a special marker such as a particular INI file in the network location which will mean any subsequent installs run from that network image will result in Workstation mode setups. Or you can modify the SETUP.LST file after the Administrator phase to automatically specify this flag. 228: 229: You may specify your own command line arguments, but your MST script must process them out of the COMMAND$ global string variable before you call $INCLUDE 'setupapi.inc', otherwise the unrecognized arguments will generate a Usage message and cause Setup to abort. Also be careful not to remove Setup Toolkit arguments (particularly the /S set). 230: 231: 232: 233: Notes about MS-TEST include file optimizations 234: 235: Just before shipping your product, you can save disk space and execution startup time by editting the MS-TEST include files (.INC) to remove all DEBUG code and unused APIs. Be careful while undertaking the latter that you do not remove too much too fast. The MS-TEST parser will inform you if you do remove too much. Always keep a backup copy of the latest versions of the files that successfully compiled. 236: 237: The symbol table will support string values to a length of 8192 characters, but there is a constant defined in SETUPAPI.INC which further limits this length to 512 characters. If you find this limit is too restrictive, you can relax it by editting the SETUPAPI.INC file (search for cbSymValMax). 238: 1.1.1.2 ! root 239: tstrapper program) does. If you look at the CmdLine line in the SETUP.LST, you will see it has the form _MSTEST SAMPLE1.MS� � w & s & o && l | i ~ f � a � ] � X � ��� U [ ! 240: Q l ! 241: N & & && && & & & & l ! 242: w I r K �� o q k u h � c � ��� ` � \ > X C T � P & & & && & & && � � w � s � o � k z g � c � _ � [ W R S ^ O j K � & & & & & & j { w � s p H l T h ^ d � a � ] � Y � U � Q $ M � & & & & & & $ / w � s p � l � h � e ` ��5 ] � Y � U � Q � O & & & && & & & & � � x � t � p � l � h � d K ` Z \ � X � T P 2 M � O & & & & & & 2 ; w < s B o { k � g � c � _ [ [ y X � T � P � L � & & & � k w � t � p � l � h �! d " a " ] o# Y �# V �# R �# N � & & & & & & �# �# x �# t $$ p L$ m �% i �% f $& b �' ^ �' Z �' V �' R -( N � & & & & & & -( 3( w n( s t( o �( k �( g �( c �( ` ) \ �) X �) T �) P �) L � & & & �) �) w �) s * o :* l J* h + d 3+ a u+ ] �, Y &- U - Q - M � & & & & & & - A- w G- s �- o �- k �- g �- c �- _ �- [ �. W �. T �. P / L � & & & / �/ w �/ u �/ r 0 n !0 j 1 f 1 d )1 a 51 ] M1 Y �1 U 2 S '2 P & && & && & && '2 32 w K2 s 3 o 3 m 63 j e3 f �3 b �3 ^ �3 Z �3 V �3 R �3 N '2 P & & && & �3 '4 w -4 s c4 o g4 k �4 g �4 c �6 _ �6 [ �6 W �6 T !7 P �7 L '2 & & & & �7 �7 w �7 s �7 o �7 k �7 g &8 c 8 _ 8 [ 8 W 8 S $8 O '8 K '2 & & & & & '8 38 w `8 s h8 o i8 k o8 g �8 c �8 _ 9 [ 9 W Y9 S �9 N �9 J '2 && & & & & & �9 �9 w �9 s : o T: k \: g t: c }: _ �: [ �: W �: S �: O �: K '2 & & & & & & �: ; w ; s ; o Y; k [; g �; c �; _ 1< [ 3< W h< S q< O �< K '2 & & & & & & �< �< w = s (= o T= k ^= g �= c �= _ �= [ �= W l> S n> O �> K '2 & & & & & & �> �> w S? s j? o �? k �? g �? c �? _ R@ [ i@ W 5A S 7A O NA K '2 & & & & & & NA VA w nA s uA o �A k �A g �A c �A _ �A [ �A W %C S 'C O >C K '2 & & & & & & >C FC w ^C s gC o �D k �D g �E c �E _ �E [ �E W {F S }F O �F K '2 & & & & & & �F �F v #G r *G n :G j >G f NG b SG ^ �G Z �G V �H R �H N WI J '2 & & & & & && WI cI w uI s �I o �I k >G f NG b SG ^ �G Z �G V �H R �H N WI J '2 & & & & & &� � ��� ��& ��& ��& ��#& ��&& ��K& p l& p �& p �& p p L p | p ~ ��� ��� ��y �� ! 243: < �0�y { ��� �� ��F ��Z ��� ��� �� ��\ ��� ��� �� �� �� ��� ��� ��� ��� ��� ��� ��0�� � ��� ��� ��� ��� ��� �� ! 244: �� ! 245: ��1 ! 246: ��G ! 247: ��Y ! 248: ��[ ! 249: ��n ! 250: ��� ! 251: ��� ! 252: ��� ! 253: ��� ! 254: ��� ! 255: ��� ! 256: ��& ��0�& ��0 ��F ��h ��j �� �� p I p K ��} �� ��q ��s ��u ��� e � ��� ! 257: � 1.1 root 258: < �`� 1.1.1.2 ! root 259: < �`�� � ��� ��x ��z ��� ��� ��� �� ��^ ��` ��� ��� ��� ��� �� �� �� ��� p �`� ! 260: < �0�� z p � p � ��� �� �� ��3 ��5 ��� ��� ��� ��� ��� ��� ��� �� g g �< � ! 261: < �0� 2 ��D ��Y r [ r y ��� ��� i i 0 i > i � i i i k i � ��� ���! ` < �< �< ��! �! r �! r " p m# e o# \ �# Z �# O �# F �# D > i � i i &<< � ! 262: < �`�&<< � ! 263: < �`�&<< � �# "$ p $$ g 4$ ��6$ ��L$ ���% ^ �% ���% ���% ���% ���% ��$& ���' U ! 264: < < �< �< � ! 265: < �`� �' �' y -( p 5( g n( ^ v( U �( L �( C �( : �( ���% < < �< < �< < �< &< �( �( �� ) ���) r �) ���) i * ^ * �� * ��:* ��J* �� + U + ��+ ��3+ ��< � ! 266: < �`�< < �3+ u+ ���, r - ��A- i I- ` �- W �- N �- E �. : J* ! 267: < �`�< < �< < �< < � �. �. ���. ���. ���/ r �/ r �/ ��1 i 1 ��)1 ���1 ` 2 ��'2 ��3 W 3 �� �< h&< h&< h&< h& 3 63 ��e3 ���3 r �3 p �3 g �3 ^ '4 U /4 L c4 C �1 ` 2 ��'< < �< < �< &<< � c4 i4 r �4 i �6 ^ �6 ���6 ��!7 ���7 U �7 ��'8 L `8 �� 2 ��'< < < � ! 268: < �`�< < � ! 269: `8 S9 p U9 ��W9 ��Y9 ���9 ���9 ��t< ��v< ���< �� = e �> e S? e R@ e 5A e %C e (E e 1.1 root 270: < ��� 1.1.1.2 ! root 271: < �`�(E *E p �F n �F n �F n �F n �F n �F n XH n ZH n �I n �I n �I n R@ e 5A e %C e (E e 1.1 root 272: < �&< 1.1.1.2 ! root 273: < ��� & 0Arial u �/ r 0 n !0 j 1 f 1 d )1 a 51 ] M1 Y �1 U 2 S '2 P & && & && & &&
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.