test: rtl/registry.c File Reference

00150 : 00151 00152 This function creates or opens the specified key in the Registry. If 00153 the key does not exist, it is created. If the key already exists, it 00154 is opened. 00155 00156 Arguments: 00157 00158 KeyHandle - Receives a value called a Handle which is used to access 00159 the specified key in the Registration Database. 00160 00161 DesiredAccess - Specifies the Accesses desired 00162 00163 REG_KEY_READ - Generic Read access to key 00164 REG_KEY_QUERY_VALUE - Query Key's value 00165 REG_KEY_WRITE - Generic Write access to key 00166 REG_KEY_SET_VALUE - Set Key's value 00167 00168 ObjectAttributes - Specifies the attributes of the key being opened. 00169 Note that a key name must be specified. If a Root Directory 00170 is specified, the name is relative to the root. The name of the 00171 object must be within the name space allocated to the Registry, that 00172 is, all names beginning "\Registry". RootHandle, if present, must 00173 be a handle to "\", or "\Registry", or a key under "\Registry". 00174 00175 00176 Options - REG_OPTION_READ_FUZZY - Allow Read access on handle even if it is 00177 open for READ_WRITE access. 00178 00179 REG_OPTION_VOLATILE - Object is not to be stored across boots. 00180 00181 Provider - This parameter is reserved for future use and must currently 00182 be set to NULL. It will be used in the future to specify the name of 00183 the provider to be used for operations on this node and its descendant 00184 nodes. 00185 00186 Disposition - This optional parameter is a pointer to a variable that 00187 will receive a value indicating whether a new Registry key was 00188 created or an existing one opened. 00189 00190 REG_CREATED_NEW_KEY - A new Registry Key was created 00191 REG_OPENED_EXISTING_KEY - An existing Registry Key was opened 00192 00193 Return Value: 00194 00195 NTSTATUS - Result code from call. The following are returned 00196 00197 STATUS_SUCCESS - The open was successful. 00198 00199 STATUS_INVALID_PARAMETER - A parameter other that object name was 00200 --*/ 00201 00202 { 00203 RTL_PAGED_CODE(); 00204 00205 if (ARGUMENT_PRESENT(ObjectAttributes)) { 00206 ObjectAttributes->Attributes &= ~(REG_INVALID_ATTRIBUTES); 00207 } 00208 00209 00210 return(NtCreateKey( KeyHandle, 00211 DesiredAccess, 00212 ObjectAttributes, 00213 0, //TitleIndex 00214 NULL, //Class OPTIONAL, 00215 REG_OPTION_NON_VOLATILE, //CreateOptions, 00216 Disposition 00217 ) ); 00218 00219 DBG_UNREFERENCED_PARAMETER( Options ); 00220 DBG_UNREFERENCED_PARAMETER( Provider ); 00221 }

00474 : 00475 00476 This function finds the name of the next sub key of a given key. By 00477 making successive calls, all of the sub keys of a key can be determined. 00478 00479 00480 Arguments: 00481 00482 KeyHandle - Handle of the key whose sub keys are to be enumerated. 00483 00484 SubKeyName - Pointer to a Unicode String in which the name of the sub 00485 key will be returned. 00486 00487 Index - Specifies the (ZERO-based) number of the sub key to be returned. 00488 00489 00490 LastWriteTime - Receives the time stamp that specifies when the key 00491 was last written. 00492 00493 Return Value: 00494 00495 NTSTATUS - Result code 00496 00497 STATUS_SUCCESS - The call succeeded 00498 00499 STATUS_INVALID_PARAMETER - Invalid parameter 00500 00501 STATUS_NO_MORE_ENTRIES - There is no key having the specified index 00502 00503 STATUS_BUFFER_OVERFLOW - The buffer of the output string was not 00504 large enough to hold the next sub-key name. SubKeyName->Length 00505 contains the number of bytes required. 00506 00507 STATUS_NO_MEMORY - There was not sufficient heap to perform the 00508 requested operation. 00509 00510 --*/ 00511 00512 { 00513 NTSTATUS Status; 00514 PKEY_BASIC_INFORMATION KeyInformation = NULL; 00515 ULONG LocalBufferLength, ResultLength; 00516 00517 RTL_PAGED_CODE(); 00518 00519 LocalBufferLength = 0; 00520 if (SubKeyName->MaximumLength > 0) { 00521 00522 LocalBufferLength = SubKeyName->MaximumLength + 00523 FIELD_OFFSET(KEY_BASIC_INFORMATION, Name); 00524 KeyInformation = RtlAllocateHeap( RtlProcessHeap(), 0, 00525 LocalBufferLength 00526 ); 00527 if (KeyInformation == NULL) { 00528 return(STATUS_NO_MEMORY); 00529 } 00530 } 00531 00532 Status = NtEnumerateKey( KeyHandle, 00533 Index, 00534 KeyBasicInformation, //KeyInformationClass 00535 (PVOID)KeyInformation, 00536 LocalBufferLength, 00537 &ResultLength 00538 ); 00539 00540 if (NT_SUCCESS(Status)) { 00541 00542 if ( SubKeyName->MaximumLength >= KeyInformation->NameLength) { 00543 00544 SubKeyName->Length = (USHORT)KeyInformation->NameLength; 00545 00546 RtlMoveMemory( SubKeyName->Buffer, 00547 &KeyInformation->Name[0], 00548 SubKeyName->Length 00549 ); 00550 } else { 00551 Status = STATUS_BUFFER_OVERFLOW; 00552 } 00553 } 00554 00555 // 00556 // Return the length required if we failed due to a small buffer 00557 // 00558 00559 if (Status == STATUS_BUFFER_OVERFLOW) { 00560 SubKeyName->Length = (USHORT)(ResultLength - 00561 FIELD_OFFSET(KEY_BASIC_INFORMATION, Name)); 00562 } 00563 00564 00565 // 00566 // Free up any memory we allocated 00567 // 00568 00569 if (KeyInformation != NULL) { 00570 00571 RtlFreeHeap( RtlProcessHeap(), 0, 00572 KeyInformation 00573 ); 00574 } 00575 00576 00577 return(Status); 00578 00579 DBG_UNREFERENCED_PARAMETER( LastWriteTime ); 00580 00581 } }

00436 : 00437 00438 This function makes a Registry key temporary. The key will be deleted 00439 when the last handle to it is closed. 00440 00441 Arguments: 00442 00443 KeyHandle - Specifies the handle of the Key. This is also the handle 00444 of the key's directory. 00445 00446 Return Value: 00447 00448 NTSTATUS - Standard Nt Result Code 00449 00450 STATUS_INVALID_HANDLE - The specified handle is invalid. 00451 00452 STATUS_ACCESS_DENIED - The specified handle does not specify delet 00453 access. 00454 00455 --*/ 00456 00457 { 00458 RTL_PAGED_CODE(); 00459 00460 return( NtDeleteKey(KeyHandle) ); 00461 }

00079 : 00080 00081 This function opens a key in the Registry. The key must already exist. 00082 00083 Arguments: 00084 00085 KeyHandle - Receives a value called a Handle which is used to access 00086 the specified key in the Registration Database. 00087 00088 DesiredAccess - Specifies the Accesses desired 00089 00090 REG_KEY_READ - Generic Read access to key 00091 REG_KEY_QUERY_VALUE - Query Key's value 00092 REG_KEY_WRITE - Generic Write access to key 00093 REG_KEY_SET_VALUE - Set Key's value 00094 00095 ObjectAttributes - Specifies the attributes of the key being opened. 00096 Note that a key name must be specified. If a Root Directory 00097 is specified, the name is relative to the root. The name of the 00098 object must be within the name space allocated to the Registry, that 00099 is, all names beginning "\Registry". RootHandle, if present, must 00100 be a handle to "\", or "\Registry", or a key under "\Registry". 00101 00102 Options - REG_OPTION_READ_FUZZY - Allow Read access on handle even if 00103 it is open for Read/Write access. 00104 00105 Return Value: 00106 00107 NTSTATUS - Result code from call. The following are returned 00108 00109 STATUS_SUCCESS - The open was successful. 00110 00111 STATUS_INVALID_PARAMETER - A parameter other that object name was 00112 invalid. 00113 00114 STATUS_OBJECT_NAME_INVALID - The key name has invalid syntax 00115 00116 STATUS_OBJECT_NAME_NOT_FOUND - No key of the given name exists 00117 00118 STATUS_ACCESS_DENIED - Caller does not have the requested access 00119 to the specified key. 00120 --*/ 00121 00122 { 00123 RTL_PAGED_CODE(); 00124 00125 if (ARGUMENT_PRESENT(ObjectAttributes)) { 00126 ObjectAttributes->Attributes &= ~(REG_INVALID_ATTRIBUTES); 00127 } 00128 00129 return( NtOpenKey( KeyHandle, 00130 DesiredAccess, 00131 ObjectAttributes 00132 ) ); 00133 00134 DBG_UNREFERENCED_PARAMETER( Options ); 00135 }

00236 : 00237 00238 This function queries the value of a key. 00239 00240 Arguments: 00241 00242 KeyHandle - Handle of a key opened for GENERIC_READ access via NtOpenKey. 00243 00244 KeyValueType - Optional pointer to variable that will receive the 00245 client-defined type of the key value (if any). If no value has been 00246 set for the key, 0 is returned. 00247 00248 KeyValue - Optional pointer to buffer in which part or all of the key's 00249 value (as set on the most recent call to NtSetValueKey) will be 00250 returned. If the key's value is too large to fit into the supplied 00251 buffer, as much of the value as will fit into the buffer will be 00252 returned and the warning STATUS_BUFFER_OVERFLOW is returned. If no 00253 value has ever been set, nothing is returned. If NULL is specified 00254 for this parameter, no Key Value is returned. 00255 00256 KeyValueLength - On input, this optional parameter points to a variable 00257 that contains the length in bytes of the KeyValue buffer (if any). If 00258 no KeyValue buffer is specified, the variable content on entry is 00259 ignored. On return, the referenced variable (if any) receives the 00260 FULL length in bytes of the key value. If the key's value is too 00261 large to fit into the supplied buffer, as much of the value as will 00262 fit into the buffer will be returned and the warning 00263 STATUS_BUFFER_OVERFLOW is returned. 00264 00265 The returned length is intended for use by calling code in allocating 00266 a buffer of sufficient size to hold the key's value. After receiving 00267 STATUS_BUFFER_OVERFLOW from NtQueryValueKey, calling code may make a 00268 subsequent call to NtQueryValueKey with a buffer of size equal to the 00269 length returned by the prior call. 00270 00271 If no value has been set for the key, 0 is returned. 00272 00273 LastWriteTime - Optional parameter to variable which receives a time stamp 00274 specifying the last time that the key was written. 00275 00276 Return Value: 00277 00278 NTSTATUS - Result code 00279 00280 STATUS_SUCCESS - Call was successful 00281 00282 STATUS_INVALID_PARAMETER - Invalid parameter 00283 00284 STATUS_ACCESS_DENIED - Caller does not have GENERIC_READ access to 00285 the specified key 00286 00287 STATUS_BUFFER_OVERFLOW - This is a warning that the key's value 00288 is too large for the buffer specified by the KeyValue and 00289 KeyValueLength parameters. Use the length returned to 00290 determine the size of buffer to allocate for a subsequent 00291 call of NtQueryValueKey. 00292 00293 --*/ 00294 00295 { 00296 00297 UNICODE_STRING NullName; 00298 NTSTATUS Status; 00299 PKEY_VALUE_PARTIAL_INFORMATION ValueInformation; 00300 ULONG ValueLength; 00301 00302 RTL_PAGED_CODE(); 00303 00304 // 00305 // Compute the size of the buffer needed to hold the key value information. 00306 // 00307 00308 ValueLength = 0; 00309 if (ARGUMENT_PRESENT(KeyValueLength)) { 00310 ValueLength = *KeyValueLength; 00311 } 00312 00313 ValueLength += FIELD_OFFSET(KEY_VALUE_PARTIAL_INFORMATION, Data); 00314 ValueInformation = RtlAllocateHeap(RtlProcessHeap(), 0, ValueLength); 00315 if (ValueInformation == NULL) { 00316 return STATUS_INSUFFICIENT_RESOURCES; 00317 } 00318 00319 // 00320 // Query the key value. 00321 // 00322 00323 NullName.Length = 0; 00324 Status = NtQueryValueKey(KeyHandle, 00325 &NullName, 00326 KeyValuePartialInformation, 00327 ValueInformation, 00328 ValueLength, 00329 &ValueLength); 00330 00331 // 00332 // Temporary hack to allow query of "" attribute when it hasn't 00333 // yet been set. 00334 // 00335 00336 if (Status == STATUS_OBJECT_NAME_NOT_FOUND) { 00337 Status = STATUS_SUCCESS; 00338 ValueInformation->DataLength = 0; 00339 ValueInformation->Type = 0; 00340 } 00341 00342 // 00343 // If requested return the key value length and the key type. 00344 // 00345 00346 if (NT_SUCCESS(Status) || (Status == STATUS_BUFFER_OVERFLOW)) { 00347 if (ARGUMENT_PRESENT(KeyValueLength)) { 00348 *KeyValueLength = ValueInformation->DataLength; 00349 } 00350 00351 if (ARGUMENT_PRESENT(KeyValueType)) { 00352 *KeyValueType = ValueInformation->Type; 00353 } 00354 } 00355 00356 // 00357 // If the query was successful and buffer overflow did not occur, then 00358 // return the key value information. 00359 // 00360 00361 if (NT_SUCCESS(Status) && ARGUMENT_PRESENT(KeyValue)) { 00362 RtlMoveMemory(KeyValue, 00363 &ValueInformation->Data[0], 00364 ValueInformation->DataLength); 00365 } 00366 00367 RtlFreeHeap(RtlProcessHeap(), 0, ValueInformation); 00368 return Status; 00369 }

00381 : 00382 00383 This function sets the type and value of a key. 00384 00385 Arguments: 00386 00387 KeyHandle - Specifies a handle of the key whose type and value are to 00388 be set. The key must have been opened with GENERIC_WRITE access. 00389 00390 KeyValueType - This is a value that the client of the registry defines to 00391 distinguish different client-defined types of data value stored 00392 with the key. When setting the value of a key that has previously 00393 had a Type and Value stored, the Type may be changed. 00394 00395 KeyValue - Optional pointer to the data to be optionally stored as the 00396 value of the key. If NULL is specified for this parameter, only 00397 the value type will be written. 00398 00399 KeyValueLength - Specifies the length in bytes of the data to be stored as 00400 the key's value. A zero value indicates that no data is being stored: 00401 if zero is specified, the Value parameter will be ignored. 00402 00403 Return Value: 00404 00405 NTSTATUS - Result code. The following values are returned 00406 00407 STATUS_SUCCESS - The call was successful 00408 00409 STATUS_INVALID_PARAMETER - Invalid Parameter(s) 00410 --*/ 00411 00412 { 00413 UNICODE_STRING NullName; 00414 NullName.Length = 0; 00415 00416 RTL_PAGED_CODE(); 00417 00418 return( NtSetValueKey( KeyHandle, 00419 &NullName, // ValueName 00420 0, // TitleIndex 00421 KeyValueType, 00422 KeyValue, 00423 KeyValueLength 00424 ) ); 00425 }


Defines
#define	REG_INVALID_ATTRIBUTES (OBJ_EXCLUSIVE \| OBJ_PERMANENT)
Functions
NTSTATUS	RtlpNtOpenKey (OUT PHANDLE KeyHandle, IN ACCESS_MASK DesiredAccess, IN POBJECT_ATTRIBUTES ObjectAttributes, IN ULONG Options)
NTSTATUS	RtlpNtCreateKey (OUT PHANDLE KeyHandle, IN ACCESS_MASK DesiredAccess, IN POBJECT_ATTRIBUTES ObjectAttributes, IN ULONG Options, IN PUNICODE_STRING Provider, OUT OPTIONAL PULONG Disposition)
NTSTATUS	RtlpNtQueryValueKey (IN HANDLE KeyHandle, OUT OPTIONAL PULONG KeyValueType, OUT OPTIONAL PVOID KeyValue, IN OUT OPTIONAL PULONG KeyValueLength, OUT OPTIONAL PLARGE_INTEGER LastWriteTime)
NTSTATUS	RtlpNtSetValueKey (IN HANDLE KeyHandle, IN ULONG KeyValueType, IN OPTIONAL PVOID KeyValue, IN ULONG KeyValueLength)
NTSTATUS	RtlpNtMakeTemporaryKey (IN HANDLE KeyHandle)
NTSTATUS	RtlpNtEnumerateSubKey (IN HANDLE KeyHandle, OUT PUNICODE_STRING SubKeyName, IN ULONG Index, OUT PLARGE_INTEGER LastWriteTime)

registry.c File Reference

Defines

Functions

Define Documentation

Function Documentation