Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="module-winsound.html" /> | |
13 | <link rel="prev" href="module-msvcrt.html" /> | |
14 | <link rel="parent" href="node822.html" /> | |
15 | <link rel="next" href="handle-object.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>22.2 _winreg - Windows registry access</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="22.1.3 Other Functions" | |
25 | href="msvcrt-other.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="22. MS Windows Specific" | |
28 | href="node822.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="22.2.1 Registry Handle Objects" | |
31 | href="handle-object.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="msvcrt-other.html">22.1.3 Other Functions</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="node822.html">22. MS Windows Specific</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="handle-object.html">22.2.1 Registry Handle Objects</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION0024200000000000000000"> | |
56 | 22.2 <tt class="module">_winreg</tt> - | |
57 | Windows registry access</A> | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | <A NAME="module-winreg"></A> | |
62 | <p class="availability">Availability: <span | |
63 | class="platform">Windows</span>.</p> | |
64 | ||
65 | <P> | |
66 | ||
67 | <span class="versionnote">New in version 2.0.</span> | |
68 | ||
69 | <P> | |
70 | These functions expose the Windows registry API to Python. Instead of | |
71 | using an integer as the registry handle, a handle object is used to | |
72 | ensure that the handles are closed correctly, even if the programmer | |
73 | neglects to explicitly close them. | |
74 | ||
75 | <P> | |
76 | This module exposes a very low-level interface to the Windows | |
77 | registry; it is expected that in the future a new <code>winreg</code> | |
78 | module will be created offering a higher-level interface to the | |
79 | registry API. | |
80 | ||
81 | <P> | |
82 | This module offers the following functions: | |
83 | ||
84 | <P> | |
85 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
86 | <td><nobr><b><tt id='l2h-5256' xml:id='l2h-5256' class="function">CloseKey</tt></b>(</nobr></td> | |
87 | <td><var>hkey</var>)</td></tr></table></dt> | |
88 | <dd> | |
89 | Closes a previously opened registry key. | |
90 | The hkey argument specifies a previously opened key. | |
91 | ||
92 | <P> | |
93 | Note that if <var>hkey</var> is not closed using this method, (or the | |
94 | <tt class="method">handle.Close()</tt> closed when the <var>hkey</var> object is | |
95 | destroyed by Python. | |
96 | </dl> | |
97 | ||
98 | <P> | |
99 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
100 | <td><nobr><b><tt id='l2h-5257' xml:id='l2h-5257' class="function">ConnectRegistry</tt></b>(</nobr></td> | |
101 | <td><var>computer_name, key</var>)</td></tr></table></dt> | |
102 | <dd> | |
103 | Establishes a connection to a predefined registry handle on | |
104 | another computer, and returns a <i class="dfn">handle object</i> | |
105 | ||
106 | <P> | |
107 | <var>computer_name</var> is the name of the remote computer, of the | |
108 | form <code>r"\\computername"</code>. If <code>None</code>, the local computer | |
109 | is used. | |
110 | ||
111 | <P> | |
112 | <var>key</var> is the predefined handle to connect to. | |
113 | ||
114 | <P> | |
115 | The return value is the handle of the opened key. | |
116 | If the function fails, an <tt class="exception">EnvironmentError</tt> exception is | |
117 | raised. | |
118 | </dl> | |
119 | ||
120 | <P> | |
121 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
122 | <td><nobr><b><tt id='l2h-5258' xml:id='l2h-5258' class="function">CreateKey</tt></b>(</nobr></td> | |
123 | <td><var>key, sub_key</var>)</td></tr></table></dt> | |
124 | <dd> | |
125 | Creates or opens the specified key, returning a <i class="dfn">handle object</i> | |
126 | ||
127 | <P> | |
128 | <var>key</var> is an already open key, or one of the predefined | |
129 | <tt class="constant">HKEY_*</tt> constants. | |
130 | ||
131 | <P> | |
132 | <var>sub_key</var> is a string that names the key this method opens | |
133 | or creates. | |
134 | ||
135 | <P> | |
136 | If <var>key</var> is one of the predefined keys, <var>sub_key</var> may | |
137 | be <code>None</code>. In that case, the handle returned is the same key handle | |
138 | passed in to the function. | |
139 | ||
140 | <P> | |
141 | If the key already exists, this function opens the existing key | |
142 | ||
143 | <P> | |
144 | The return value is the handle of the opened key. | |
145 | If the function fails, an <tt class="exception">EnvironmentError</tt> exception is | |
146 | raised. | |
147 | </dl> | |
148 | ||
149 | <P> | |
150 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
151 | <td><nobr><b><tt id='l2h-5259' xml:id='l2h-5259' class="function">DeleteKey</tt></b>(</nobr></td> | |
152 | <td><var>key, sub_key</var>)</td></tr></table></dt> | |
153 | <dd> | |
154 | Deletes the specified key. | |
155 | ||
156 | <P> | |
157 | <var>key</var> is an already open key, or any one of the predefined | |
158 | <tt class="constant">HKEY_*</tt> constants. | |
159 | ||
160 | <P> | |
161 | <var>sub_key</var> is a string that must be a subkey of the key | |
162 | identified by the <var>key</var> parameter. This value must not be | |
163 | <code>None</code>, and the key may not have subkeys. | |
164 | ||
165 | <P> | |
166 | <em>This method can not delete keys with subkeys.</em> | |
167 | ||
168 | <P> | |
169 | If the method succeeds, the entire key, including all of its values, | |
170 | is removed. If the method fails, an <tt class="exception">EnvironmentError</tt> | |
171 | exception is raised. | |
172 | </dl> | |
173 | ||
174 | <P> | |
175 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
176 | <td><nobr><b><tt id='l2h-5260' xml:id='l2h-5260' class="function">DeleteValue</tt></b>(</nobr></td> | |
177 | <td><var>key, value</var>)</td></tr></table></dt> | |
178 | <dd> | |
179 | Removes a named value from a registry key. | |
180 | ||
181 | <P> | |
182 | <var>key</var> is an already open key, or one of the predefined | |
183 | <tt class="constant">HKEY_*</tt> constants. | |
184 | ||
185 | <P> | |
186 | <var>value</var> is a string that identifies the value to remove. | |
187 | </dl> | |
188 | ||
189 | <P> | |
190 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
191 | <td><nobr><b><tt id='l2h-5261' xml:id='l2h-5261' class="function">EnumKey</tt></b>(</nobr></td> | |
192 | <td><var>key, index</var>)</td></tr></table></dt> | |
193 | <dd> | |
194 | Enumerates subkeys of an open registry key, returning a string. | |
195 | ||
196 | <P> | |
197 | <var>key</var> is an already open key, or any one of the predefined | |
198 | <tt class="constant">HKEY_*</tt> constants. | |
199 | ||
200 | <P> | |
201 | <var>index</var> is an integer that identifies the index of the key to | |
202 | retrieve. | |
203 | ||
204 | <P> | |
205 | The function retrieves the name of one subkey each time it | |
206 | is called. It is typically called repeatedly until an | |
207 | <tt class="exception">EnvironmentError</tt> exception | |
208 | is raised, indicating, no more values are available. | |
209 | </dl> | |
210 | ||
211 | <P> | |
212 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
213 | <td><nobr><b><tt id='l2h-5262' xml:id='l2h-5262' class="function">EnumValue</tt></b>(</nobr></td> | |
214 | <td><var>key, index</var>)</td></tr></table></dt> | |
215 | <dd> | |
216 | Enumerates values of an open registry key, returning a tuple. | |
217 | ||
218 | <P> | |
219 | <var>key</var> is an already open key, or any one of the predefined | |
220 | <tt class="constant">HKEY_*</tt> constants. | |
221 | ||
222 | <P> | |
223 | <var>index</var> is an integer that identifies the index of the value | |
224 | to retrieve. | |
225 | ||
226 | <P> | |
227 | The function retrieves the name of one subkey each time it is | |
228 | called. It is typically called repeatedly, until an | |
229 | <tt class="exception">EnvironmentError</tt> exception is raised, indicating | |
230 | no more values. | |
231 | ||
232 | <P> | |
233 | The result is a tuple of 3 items: | |
234 | ||
235 | <P> | |
236 | <div class="center"><table class="realtable"> | |
237 | <thead> | |
238 | <tr> | |
239 | <th class="center">Index</th> | |
240 | <th class="left" >Meaning</th> | |
241 | </tr> | |
242 | </thead> | |
243 | <tbody> | |
244 | <tr><td class="center" valign="baseline"><tt class="constant">0</tt></td> | |
245 | <td class="left" >A string that identifies the value name</td></tr> | |
246 | <tr><td class="center" valign="baseline"><tt class="constant">1</tt></td> | |
247 | <td class="left" >An object that holds the value data, and whose | |
248 | type depends on the underlying registry type</td></tr> | |
249 | <tr><td class="center" valign="baseline"><tt class="constant">2</tt></td> | |
250 | <td class="left" >An integer that identifies the type of the value data</td></tr></tbody> | |
251 | </table></div> | |
252 | ||
253 | <P> | |
254 | </dl> | |
255 | ||
256 | <P> | |
257 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
258 | <td><nobr><b><tt id='l2h-5263' xml:id='l2h-5263' class="function">FlushKey</tt></b>(</nobr></td> | |
259 | <td><var>key</var>)</td></tr></table></dt> | |
260 | <dd> | |
261 | Writes all the attributes of a key to the registry. | |
262 | ||
263 | <P> | |
264 | <var>key</var> is an already open key, or one of the predefined | |
265 | <tt class="constant">HKEY_*</tt> constants. | |
266 | ||
267 | <P> | |
268 | It is not necessary to call RegFlushKey to change a key. | |
269 | Registry changes are flushed to disk by the registry using its lazy | |
270 | flusher. Registry changes are also flushed to disk at system | |
271 | shutdown. Unlike <tt class="function">CloseKey()</tt>, the <tt class="function">FlushKey()</tt> method | |
272 | returns only when all the data has been written to the registry. | |
273 | An application should only call <tt class="function">FlushKey()</tt> if it requires absolute | |
274 | certainty that registry changes are on disk. | |
275 | ||
276 | <P> | |
277 | <em>If you don't know whether a <tt class="function">FlushKey()</tt> call is required, it | |
278 | probably isn't.</em> | |
279 | ||
280 | <P> | |
281 | </dl> | |
282 | ||
283 | <P> | |
284 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
285 | <td><nobr><b><tt id='l2h-5264' xml:id='l2h-5264' class="function">RegLoadKey</tt></b>(</nobr></td> | |
286 | <td><var>key, sub_key, file_name</var>)</td></tr></table></dt> | |
287 | <dd> | |
288 | Creates a subkey under the specified key and stores registration | |
289 | information from a specified file into that subkey. | |
290 | ||
291 | <P> | |
292 | <var>key</var> is an already open key, or any of the predefined | |
293 | <tt class="constant">HKEY_*</tt> constants. | |
294 | ||
295 | <P> | |
296 | <var>sub_key</var> is a string that identifies the sub_key to load | |
297 | ||
298 | <P> | |
299 | <var>file_name</var> is the name of the file to load registry data from. | |
300 | This file must have been created with the <tt class="function">SaveKey()</tt> function. | |
301 | Under the file allocation table (FAT) file system, the filename may not | |
302 | have an extension. | |
303 | ||
304 | <P> | |
305 | A call to LoadKey() fails if the calling process does not have the | |
306 | <tt class="constant">SE_RESTORE_PRIVILEGE</tt> privilege. Note that privileges | |
307 | are different than permissions - see the Win32 documentation for | |
308 | more details. | |
309 | ||
310 | <P> | |
311 | If <var>key</var> is a handle returned by <tt class="function">ConnectRegistry()</tt>, | |
312 | then the path specified in <var>fileName</var> is relative to the | |
313 | remote computer. | |
314 | ||
315 | <P> | |
316 | The Win32 documentation implies <var>key</var> must be in the | |
317 | <tt class="constant">HKEY_USER</tt> or <tt class="constant">HKEY_LOCAL_MACHINE</tt> tree. | |
318 | This may or may not be true. | |
319 | </dl> | |
320 | ||
321 | <P> | |
322 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
323 | <td><nobr><b><tt id='l2h-5265' xml:id='l2h-5265' class="function">OpenKey</tt></b>(</nobr></td> | |
324 | <td><var>key, sub_key</var><big>[</big><var>, res<code> = 0</code></var><big>]</big><var></var><big>[</big><var>, sam<code> = <tt class="constant">KEY_READ</tt></code></var><big>]</big><var></var>)</td></tr></table></dt> | |
325 | <dd> | |
326 | Opens the specified key, returning a <i class="dfn">handle object</i> | |
327 | ||
328 | <P> | |
329 | <var>key</var> is an already open key, or any one of the predefined | |
330 | <tt class="constant">HKEY_*</tt> constants. | |
331 | ||
332 | <P> | |
333 | <var>sub_key</var> is a string that identifies the sub_key to open | |
334 | ||
335 | <P> | |
336 | <var>res</var> is a reserved integer, and must be zero. The default is zero. | |
337 | ||
338 | <P> | |
339 | <var>sam</var> is an integer that specifies an access mask that describes | |
340 | the desired security access for the key. Default is <tt class="constant">KEY_READ</tt> | |
341 | ||
342 | <P> | |
343 | The result is a new handle to the specified key | |
344 | ||
345 | <P> | |
346 | If the function fails, <tt class="exception">EnvironmentError</tt> is raised. | |
347 | </dl> | |
348 | ||
349 | <P> | |
350 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
351 | <td><nobr><b><tt id='l2h-5266' xml:id='l2h-5266' class="function">OpenKeyEx</tt></b>(</nobr></td> | |
352 | <td><var></var>)</td></tr></table></dt> | |
353 | <dd> | |
354 | The functionality of <tt class="function">OpenKeyEx()</tt> is provided via | |
355 | <tt class="function">OpenKey()</tt>, by the use of default arguments. | |
356 | </dl> | |
357 | ||
358 | <P> | |
359 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
360 | <td><nobr><b><tt id='l2h-5267' xml:id='l2h-5267' class="function">QueryInfoKey</tt></b>(</nobr></td> | |
361 | <td><var>key</var>)</td></tr></table></dt> | |
362 | <dd> | |
363 | Returns information about a key, as a tuple. | |
364 | ||
365 | <P> | |
366 | <var>key</var> is an already open key, or one of the predefined | |
367 | <tt class="constant">HKEY_*</tt> constants. | |
368 | ||
369 | <P> | |
370 | The result is a tuple of 3 items: | |
371 | ||
372 | <P> | |
373 | <div class="center"><table class="realtable"> | |
374 | <thead> | |
375 | <tr> | |
376 | <th class="center">Index</th> | |
377 | <th class="left" >Meaning</th> | |
378 | </tr> | |
379 | </thead> | |
380 | <tbody> | |
381 | <tr><td class="center" valign="baseline"><tt class="constant">0</tt></td> | |
382 | <td class="left" >An integer giving the number of sub keys this key has.</td></tr> | |
383 | <tr><td class="center" valign="baseline"><tt class="constant">1</tt></td> | |
384 | <td class="left" >An integer giving the number of values this key has.</td></tr> | |
385 | <tr><td class="center" valign="baseline"><tt class="constant">2</tt></td> | |
386 | <td class="left" >A long integer giving when the key was last modified (if | |
387 | available) as 100's of nanoseconds since Jan 1, 1600.</td></tr></tbody> | |
388 | </table></div> | |
389 | </dl> | |
390 | ||
391 | <P> | |
392 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
393 | <td><nobr><b><tt id='l2h-5268' xml:id='l2h-5268' class="function">QueryValue</tt></b>(</nobr></td> | |
394 | <td><var>key, sub_key</var>)</td></tr></table></dt> | |
395 | <dd> | |
396 | Retrieves the unnamed value for a key, as a string | |
397 | ||
398 | <P> | |
399 | <var>key</var> is an already open key, or one of the predefined | |
400 | <tt class="constant">HKEY_*</tt> constants. | |
401 | ||
402 | <P> | |
403 | <var>sub_key</var> is a string that holds the name of the subkey with which | |
404 | the value is associated. If this parameter is <code>None</code> or empty, the | |
405 | function retrieves the value set by the <tt class="function">SetValue()</tt> method | |
406 | for the key identified by <var>key</var>. | |
407 | ||
408 | <P> | |
409 | Values in the registry have name, type, and data components. This | |
410 | method retrieves the data for a key's first value that has a NULL name. | |
411 | But the underlying API call doesn't return the type, Lame Lame Lame, | |
412 | DO NOT USE THIS!!! | |
413 | </dl> | |
414 | ||
415 | <P> | |
416 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
417 | <td><nobr><b><tt id='l2h-5269' xml:id='l2h-5269' class="function">QueryValueEx</tt></b>(</nobr></td> | |
418 | <td><var>key, value_name</var>)</td></tr></table></dt> | |
419 | <dd> | |
420 | Retrieves the type and data for a specified value name associated with | |
421 | an open registry key. | |
422 | ||
423 | <P> | |
424 | <var>key</var> is an already open key, or one of the predefined | |
425 | <tt class="constant">HKEY_*</tt> constants. | |
426 | ||
427 | <P> | |
428 | <var>value_name</var> is a string indicating the value to query. | |
429 | ||
430 | <P> | |
431 | The result is a tuple of 2 items: | |
432 | ||
433 | <P> | |
434 | <div class="center"><table class="realtable"> | |
435 | <thead> | |
436 | <tr> | |
437 | <th class="center">Index</th> | |
438 | <th class="left" >Meaning</th> | |
439 | </tr> | |
440 | </thead> | |
441 | <tbody> | |
442 | <tr><td class="center" valign="baseline"><tt class="constant">0</tt></td> | |
443 | <td class="left" >The value of the registry item.</td></tr> | |
444 | <tr><td class="center" valign="baseline"><tt class="constant">1</tt></td> | |
445 | <td class="left" >An integer giving the registry type for this value.</td></tr></tbody> | |
446 | </table></div> | |
447 | </dl> | |
448 | ||
449 | <P> | |
450 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
451 | <td><nobr><b><tt id='l2h-5270' xml:id='l2h-5270' class="function">SaveKey</tt></b>(</nobr></td> | |
452 | <td><var>key, file_name</var>)</td></tr></table></dt> | |
453 | <dd> | |
454 | Saves the specified key, and all its subkeys to the specified file. | |
455 | ||
456 | <P> | |
457 | <var>key</var> is an already open key, or one of the predefined | |
458 | <tt class="constant">HKEY_*</tt> constants. | |
459 | ||
460 | <P> | |
461 | <var>file_name</var> is the name of the file to save registry data to. | |
462 | This file cannot already exist. If this filename includes an extension, | |
463 | it cannot be used on file allocation table (FAT) file systems by the | |
464 | <tt class="method">LoadKey()</tt>, <tt class="method">ReplaceKey()</tt> or | |
465 | <tt class="method">RestoreKey()</tt> methods. | |
466 | ||
467 | <P> | |
468 | If <var>key</var> represents a key on a remote computer, the path | |
469 | described by <var>file_name</var> is relative to the remote computer. | |
470 | The caller of this method must possess the <tt class="constant">SeBackupPrivilege</tt> | |
471 | security privilege. Note that privileges are different than permissions | |
472 | - see the Win32 documentation for more details. | |
473 | ||
474 | <P> | |
475 | This function passes NULL for <var>security_attributes</var> to the API. | |
476 | </dl> | |
477 | ||
478 | <P> | |
479 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
480 | <td><nobr><b><tt id='l2h-5271' xml:id='l2h-5271' class="function">SetValue</tt></b>(</nobr></td> | |
481 | <td><var>key, sub_key, type, value</var>)</td></tr></table></dt> | |
482 | <dd> | |
483 | Associates a value with a specified key. | |
484 | ||
485 | <P> | |
486 | <var>key</var> is an already open key, or one of the predefined | |
487 | <tt class="constant">HKEY_*</tt> constants. | |
488 | ||
489 | <P> | |
490 | <var>sub_key</var> is a string that names the subkey with which the value | |
491 | is associated. | |
492 | ||
493 | <P> | |
494 | <var>type</var> is an integer that specifies the type of the data. | |
495 | Currently this must be <tt class="constant">REG_SZ</tt>, meaning only strings are | |
496 | supported. Use the <tt class="function">SetValueEx()</tt> function for support for | |
497 | other data types. | |
498 | ||
499 | <P> | |
500 | <var>value</var> is a string that specifies the new value. | |
501 | ||
502 | <P> | |
503 | If the key specified by the <var>sub_key</var> parameter does not exist, | |
504 | the SetValue function creates it. | |
505 | ||
506 | <P> | |
507 | Value lengths are limited by available memory. Long values (more than | |
508 | 2048 bytes) should be stored as files with the filenames stored in | |
509 | the configuration registry. This helps the registry perform | |
510 | efficiently. | |
511 | ||
512 | <P> | |
513 | The key identified by the <var>key</var> parameter must have been | |
514 | opened with <tt class="constant">KEY_SET_VALUE</tt> access. | |
515 | </dl> | |
516 | ||
517 | <P> | |
518 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
519 | <td><nobr><b><tt id='l2h-5272' xml:id='l2h-5272' class="function">SetValueEx</tt></b>(</nobr></td> | |
520 | <td><var>key, value_name, reserved, type, value</var>)</td></tr></table></dt> | |
521 | <dd> | |
522 | Stores data in the value field of an open registry key. | |
523 | ||
524 | <P> | |
525 | <var>key</var> is an already open key, or one of the predefined | |
526 | <tt class="constant">HKEY_*</tt> constants. | |
527 | ||
528 | <P> | |
529 | <var>sub_key</var> is a string that names the subkey with which the | |
530 | value is associated. | |
531 | ||
532 | <P> | |
533 | <var>type</var> is an integer that specifies the type of the data. | |
534 | This should be one of the following constants defined in this module: | |
535 | ||
536 | <P> | |
537 | <div class="center"><table class="realtable"> | |
538 | <thead> | |
539 | <tr> | |
540 | <th class="left" >Constant</th> | |
541 | <th class="left" >Meaning</th> | |
542 | </tr> | |
543 | </thead> | |
544 | <tbody> | |
545 | <tr><td class="left" valign="baseline"><tt class="constant">REG_BINARY</tt></td> | |
546 | <td class="left" >Binary data in any form.</td></tr> | |
547 | <tr><td class="left" valign="baseline"><tt class="constant">REG_DWORD</tt></td> | |
548 | <td class="left" >A 32-bit number.</td></tr> | |
549 | <tr><td class="left" valign="baseline"><tt class="constant">REG_DWORD_LITTLE_ENDIAN</tt></td> | |
550 | <td class="left" >A 32-bit number in little-endian format.</td></tr> | |
551 | <tr><td class="left" valign="baseline"><tt class="constant">REG_DWORD_BIG_ENDIAN</tt></td> | |
552 | <td class="left" >A 32-bit number in big-endian format.</td></tr> | |
553 | <tr><td class="left" valign="baseline"><tt class="constant">REG_EXPAND_SZ</tt></td> | |
554 | <td class="left" >Null-terminated string containing references | |
555 | to environment variables ("<tt class="samp">%PATH%</tt>").</td></tr> | |
556 | <tr><td class="left" valign="baseline"><tt class="constant">REG_LINK</tt></td> | |
557 | <td class="left" >A Unicode symbolic link.</td></tr> | |
558 | <tr><td class="left" valign="baseline"><tt class="constant">REG_MULTI_SZ</tt></td> | |
559 | <td class="left" >A sequence of null-terminated strings, | |
560 | terminated by two null characters. (Python handles | |
561 | this termination automatically.)</td></tr> | |
562 | <tr><td class="left" valign="baseline"><tt class="constant">REG_NONE</tt></td> | |
563 | <td class="left" >No defined value type.</td></tr> | |
564 | <tr><td class="left" valign="baseline"><tt class="constant">REG_RESOURCE_LIST</tt></td> | |
565 | <td class="left" >A device-driver resource list.</td></tr> | |
566 | <tr><td class="left" valign="baseline"><tt class="constant">REG_SZ</tt></td> | |
567 | <td class="left" >A null-terminated string.</td></tr></tbody> | |
568 | </table></div> | |
569 | ||
570 | <P> | |
571 | <var>reserved</var> can be anything - zero is always passed to the | |
572 | API. | |
573 | ||
574 | <P> | |
575 | <var>value</var> is a string that specifies the new value. | |
576 | ||
577 | <P> | |
578 | This method can also set additional value and type information for the | |
579 | specified key. The key identified by the key parameter must have been | |
580 | opened with <tt class="constant">KEY_SET_VALUE</tt> access. | |
581 | ||
582 | <P> | |
583 | To open the key, use the <tt class="function">CreateKeyEx()</tt> or | |
584 | <tt class="function">OpenKey()</tt> methods. | |
585 | ||
586 | <P> | |
587 | Value lengths are limited by available memory. Long values (more than | |
588 | 2048 bytes) should be stored as files with the filenames stored in | |
589 | the configuration registry. This helps the registry perform efficiently. | |
590 | </dl> | |
591 | ||
592 | <P> | |
593 | ||
594 | <p><br /></p><hr class='online-navigation' /> | |
595 | <div class='online-navigation'> | |
596 | <!--Table of Child-Links--> | |
597 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> | |
598 | ||
599 | <UL CLASS="ChildLinks"> | |
600 | <LI><A href="handle-object.html">22.2.1 Registry Handle Objects</a> | |
601 | </ul> | |
602 | <!--End of Table of Child-Links--> | |
603 | </div> | |
604 | ||
605 | <DIV CLASS="navigation"> | |
606 | <div class='online-navigation'> | |
607 | <p></p><hr /> | |
608 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
609 | <tr> | |
610 | <td class='online-navigation'><a rel="prev" title="22.1.3 Other Functions" | |
611 | href="msvcrt-other.html"><img src='../icons/previous.png' | |
612 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
613 | <td class='online-navigation'><a rel="parent" title="22. MS Windows Specific" | |
614 | href="node822.html"><img src='../icons/up.png' | |
615 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
616 | <td class='online-navigation'><a rel="next" title="22.2.1 Registry Handle Objects" | |
617 | href="handle-object.html"><img src='../icons/next.png' | |
618 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
619 | <td align="center" width="100%">Python Library Reference</td> | |
620 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
621 | href="contents.html"><img src='../icons/contents.png' | |
622 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
623 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
624 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
625 | <td class='online-navigation'><a rel="index" title="Index" | |
626 | href="genindex.html"><img src='../icons/index.png' | |
627 | border='0' height='32' alt='Index' width='32' /></A></td> | |
628 | </tr></table> | |
629 | <div class='online-navigation'> | |
630 | <b class="navlabel">Previous:</b> | |
631 | <a class="sectref" rel="prev" href="msvcrt-other.html">22.1.3 Other Functions</A> | |
632 | <b class="navlabel">Up:</b> | |
633 | <a class="sectref" rel="parent" href="node822.html">22. MS Windows Specific</A> | |
634 | <b class="navlabel">Next:</b> | |
635 | <a class="sectref" rel="next" href="handle-object.html">22.2.1 Registry Handle Objects</A> | |
636 | </div> | |
637 | </div> | |
638 | <hr /> | |
639 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
640 | </DIV> | |
641 | <!--End of Navigation Panel--> | |
642 | <ADDRESS> | |
643 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
644 | </ADDRESS> | |
645 | </BODY> | |
646 | </HTML> |