docs: Document altosui "Graph Data" button
[fw/altos] / ao-tools / altosui / Instdrv / NSIS / Contrib / InstDrv / Readme.txt
1 InstDrv.dll version 0.2 - Installs or Removes Device Drivers\r
2 ------------------------------------------------------------\r
3 \r
4 \r
5 The plugin helps you to create NSIS scripts for installing device drivers or\r
6 removing them again. It can count installed device instances, create new ones\r
7 or delete all supported device. InstDrv works on Windows 2000 or later.\r
8 \r
9 \r
10 \r
11 InstDrv::InitDriverSetup devClass drvHWID\r
12 Return: result\r
13 \r
14 To start processing a driver, first call this function. devClass is the GUID\r
15 of the device class the driver supports, drvHWID is the device hardware ID. If\r
16 you don't know what these terms mean, you may want to take a look at the\r
17 Windows DDK. This function returns an empty string on success, otherwise an\r
18 error message.\r
19 \r
20 InitDriverSetup has to be called every time after the plugin dll has been\r
21 (re-)loaded, or if you want to switch to a different driver.\r
22 \r
23 \r
24 \r
25 InstDrv::CountDevices\r
26 Return: number\r
27 \r
28 This call returns the number of installed and supported devices of the driver.\r
29 \r
30 \r
31 \r
32 InstDrv::CreateDevice\r
33 Return: result\r
34 \r
35 To create a new deviced node which the driver has to support, use this\r
36 function. You may even call it multiple times for more than one instance. The\r
37 return value is the Windows error code (in hex). Use CreateDevice before\r
38 installing or updating the driver itself.\r
39 \r
40 \r
41 \r
42 InstDrv::InstallDriver infPath\r
43 Return: result\r
44         reboot\r
45 \r
46 InstallDriver installs or updates a device driver as specified in the .inf\r
47 setup script. It returns a Windows error code (in hex) and, on success, a flag\r
48 signalling if a system reboot is required.\r
49 \r
50 \r
51 \r
52 InstDrv::DeleteOemInfFiles\r
53 Return: result\r
54         oeminf\r
55         oempnf\r
56 \r
57 DeleteOemInfFiles tries to clean up the Windows inf directory by deleting the\r
58 oemXX.inf and oemXX.pnf files associated with the drivers. It returns a\r
59 Windows error code (in hex) and, on success, the names of the deleted files.\r
60 This functions requires that at least one device instance is still present.\r
61 So, call it before you remove the devices itself. You should also call it\r
62 before updating a driver. This avoids that the inf directory gets slowly\r
63 messed up with useless old setup scripts (which does NOT really accelerate\r
64 Windows). The error code which comes up when no device is installed is\r
65 "00000103".\r
66 \r
67 \r
68 \r
69 InstDrv::RemoveAllDevices\r
70 Return: result\r
71         reboot\r
72 \r
73 This functions deletes all devices instances the driver supported. It returns\r
74 a Windows error code (in hex) and, on success, a flag signalling if the system\r
75 needs to be rebooted. You additionally have to remove the driver binaries from\r
76 the system paths.\r
77 \r
78 \r
79 \r
80 InstDrv::StartSystemService serviceName\r
81 Return: result\r
82 \r
83 Call this function to start the provided system service. The function blocks\r
84 until the service is started or the system reported a timeout. The return value\r
85 is the Windows error code (in hex).\r
86 \r
87 \r
88 \r
89 InstDrv::StopSystemService serviceName\r
90 Return: result\r
91 \r
92 This function tries to stop the provided system service. It blocks until the\r
93 service has been shut down or the system reported a timeout. The return value\r
94 is the Windows error code (in hex).\r
95 \r
96 \r
97 \r
98 Example.nsi\r
99 \r
100 The example script installs or removes the virtual COM port driver of IrCOMM2k\r
101 (2.0.0-alpha8, see The driver and its setup script\r
102 are only included for demonstration purposes, they do not work without the\r
103 rest of IrCOMM2k (but they also do not cause any harm).\r
104 \r
105 \r
106 \r
107 Building the Source Code\r
108 \r
109 To build the plugin from the source code, some include files and libraries\r
110 which come with the Windows DDK are required.\r
111 \r
112 \r
113 \r
114 History\r
115 \r
116  0.2    - fixed bug when calling InitDriverSetup the second time\r
117         - added StartSystemService and StopSystemService\r
118 \r
119  0.1    - first release\r
120 \r
121 \r
122 \r
123 License\r
124 \r
125 Copyright © 2003 Jan Kiszka (\r
126 \r
127 This software is provided 'as-is', without any express or implied\r
128 warranty. In no event will the authors be held liable for any damages\r
129 arising from the use of this software.\r
130 \r
131 Permission is granted to anyone to use this software for any purpose,\r
132 including commercial applications, and to alter it and redistribute\r
133 it freely, subject to the following restrictions:\r
134 \r
135 1. The origin of this software must not be misrepresented; \r
136    you must not claim that you wrote the original software.\r
137    If you use this software in a product, an acknowledgment in the\r
138    product documentation would be appreciated but is not required.\r
139 2. Altered versions must be plainly marked as such,\r
140    and must not be misrepresented as being the original software.\r
141 3. This notice may not be removed or altered from any distribution.\r