test: rtl/registry.c File Reference

Main Page | Class Hierarchy | Class List | File List | Class Members | File Members

# registry.c File Reference

`#include "ntrtlp.h"`

Go to the source code of this file.

## 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)

## Define Documentation

#define REG_INVALID_ATTRIBUTES (OBJ_EXCLUSIVE | OBJ_PERMANENT)

| Definition at line 55 of file rtl/registry.c. Referenced by RtlpNtCreateKey(), and RtlpNtOpenKey().

## Function Documentation

NTSTATUS RtlpNtCreateKey | ( | OUT PHANDLE | KeyHandle,
|  | IN ACCESS_MASK | DesiredAccess,
|  | IN POBJECT_ATTRIBUTES | ObjectAttributes,
|  | IN ULONG | Options,
|  | IN PUNICODE_STRING | Provider,
|  | OUT OPTIONAL PULONG | Disposition
| ) |

Definition at line 139 of file rtl/registry.c.

References NtCreateKey(), NULL, ObjectAttributes, REG_INVALID_ATTRIBUTES, and RTL_PAGED_CODE.

    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 }

NTSTATUS RtlpNtEnumerateSubKey | ( | IN HANDLE | KeyHandle,
|  | OUT PUNICODE_STRING | SubKeyName,
|  | IN ULONG | Index,
|  | OUT PLARGE_INTEGER | LastWriteTime
| ) |

Definition at line 465 of file rtl/registry.c.

References Index, Name, NT_SUCCESS, NtEnumerateKey(), NTSTATUS(), NULL, RTL_PAGED_CODE, RtlAllocateHeap, RtlFreeHeap, Status, and USHORT.

    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 }
    }

NTSTATUS RtlpNtMakeTemporaryKey | ( | IN HANDLE | KeyHandle | ) |

Definition at line 430 of file rtl/registry.c.

References NtDeleteKey(), and RTL_PAGED_CODE.

    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 }

NTSTATUS RtlpNtOpenKey | ( | OUT PHANDLE | KeyHandle,
|  | IN ACCESS_MASK | DesiredAccess,
|  | IN POBJECT_ATTRIBUTES | ObjectAttributes,
|  | IN ULONG | Options
| ) |

Definition at line 70 of file rtl/registry.c.

References NtOpenKey(), ObjectAttributes, REG_INVALID_ATTRIBUTES, and RTL_PAGED_CODE.

    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 }

NTSTATUS RtlpNtQueryValueKey | ( | IN HANDLE | KeyHandle,
|  | OUT OPTIONAL PULONG | KeyValueType,
|  | OUT OPTIONAL PVOID | KeyValue,
|  | IN OUT OPTIONAL PULONG | KeyValueLength,
|  | OUT OPTIONAL PLARGE_INTEGER | LastWriteTime
| ) |

Definition at line 226 of file rtl/registry.c.

References NT_SUCCESS, NtQueryValueKey(), NTSTATUS(), NULL, RTL_PAGED_CODE, RtlAllocateHeap, RtlFreeHeap, and Status.

Referenced by RtlInitializeRXact().

    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 }

NTSTATUS RtlpNtSetValueKey | ( | IN HANDLE | KeyHandle,
|  | IN ULONG | KeyValueType,
|  | IN OPTIONAL PVOID | KeyValue,
|  | IN ULONG | KeyValueLength
| ) |

Definition at line 372 of file rtl/registry.c.

References NtSetValueKey(), and RTL_PAGED_CODE.

    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 }