win_reg_stat change the module parameters for standardisation (#22732)

lib/ansible/modules/windows/win_reg_stat.ps1

@@ -19,14 +19,13 @@
 
 $ErrorActionPreference = "Stop"
 
-$params = Parse-Args $args -supports_check_mode $true
+$params = Parse-Args -arguments $args -supports_check_mode $true
 
-$key = Get-AnsibleParam -obj $params -name "key" -type "str" -failifempty $true
-$property = Get-AnsibleParam -obj $params -name "property" -type "str"
+$path = Get-AnsibleParam -obj $params -name "path" -type "str" -failifempty $true -aliases "key"
+$name = Get-AnsibleParam -obj $params -name "name" -type "str" -aliases "entry","value"
 
 $result = @{
     changed = $false
-    win_reg_stat = @{}
 }
 
 Function Get-NetHiveName($hive) {
@@ -94,57 +93,57 @@ Function Test-RegistryProperty($hive, $path, $property) {
 }
 
 # Will validate the key parameter to make sure it matches known format
-if ($key -match "^([a-zA-Z_]*):\\(.*)$") {
+if ($path -match "^([a-zA-Z_]*):\\(.*)$") {
     $hive = $matches[1]
-    $path = $matches[2]
+    $reg_path = $matches[2]
 } else {
-    Fail-Json $result "key does not match format 'HIVE:\KEY_PATH'"
+    Fail-Json $result "path does not match format 'HIVE:\KEY_PATH'"
 }
 
 # Used when getting the actual REG_EXPAND_SZ value as well as checking the hive is a known value
 $net_hive = Get-NetHiveName -hive $hive
 if ($net_hive -eq 'unsupported') {
-    Fail-Json $result "the hive in key is '$hive'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
+    Fail-Json $result "the hive in path is '$hive'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
 }
 
-if (Test-Path REGISTRY::$hive\$path) {
-    if ($property -eq $null) {
+if (Test-Path REGISTRY::$hive\$reg_path) {
+    if ($name -eq $null) {
         $property_info = @{}
-        $properties = Get-ItemProperty REGISTRY::$hive\$path
+        $properties = Get-ItemProperty REGISTRY::$hive\$reg_path
 
         foreach ($property in $properties.PSObject.Properties) {
             # Powershell adds in some metadata we need to filter out
-            $real_property = Test-RegistryProperty -hive $hive -path $path -property $property.Name
+            $real_property = Test-RegistryProperty -hive $hive -path $reg_path -property $property.Name
             if ($real_property -eq $true) {
-                $property_object = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property.Name 
+                $property_object = Get-PropertyObject -hive $hive -net_hive $net_hive -path $reg_path -property $property.Name 
                 $property_info.Add($property.Name, $property_object)
             }
         }
 
         $sub_keys = @()
-        $sub_keys_raw = Get-ChildItem REGISTRY::$hive\$path -ErrorAction SilentlyContinue
+        $sub_keys_raw = Get-ChildItem REGISTRY::$hive\$reg_path -ErrorAction SilentlyContinue
 
         foreach ($sub_key in $sub_keys_raw) {
             $sub_keys += $sub_key.PSChildName
         }
 
-        $result.win_reg_stat.exists = $true
-        $result.win_reg_stat.sub_keys = $sub_keys
-        $result.win_reg_stat.properties = $property_info
+        $result.exists = $true
+        $result.sub_keys = $sub_keys
+        $result.properties = $property_info
     } else {
-        $exists = Test-RegistryProperty -hive $hive -path $path -property $property
+        $exists = Test-RegistryProperty -hive $hive -path $reg_path -property $name
         if ($exists -eq $true) {
-            $propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $path -property $property
-            $result.win_reg_stat.exists = $true
-            $result.win_reg_stat.raw_value = $propertyObject.raw_value
-            $result.win_reg_stat.value = $propertyObject.value
-            $result.win_reg_stat.type = $propertyObject.type
+            $propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $reg_path -property $name
+            $result.exists = $true
+            $result.raw_value = $propertyObject.raw_value
+            $result.value = $propertyObject.value
+            $result.type = $propertyObject.type
         } else {
-            $result.win_reg_stat.exists = $false
+            $result.exists = $false
         }
     }
 } else {
-    $result.win_reg_stat.exists = $false
+    $result.exists = $false
 }
 
 Exit-Json $result

lib/ansible/modules/windows/win_reg_stat.py

@@ -36,28 +36,28 @@ description:
 - It also returns the sub keys and properties of the key specified.
 - If specifying a property name through I(property), it will return the information specific for that property.
 options:
-    key:
-        description:
-        - The full registry key path including the hive to search for.
+  path:
+    description: The full registry key path including the hive to search for.
     required: true
-    property:
+    aliases: [ key ]
+  name:
     description:
     - The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified.
     required: false
-
+    aliases: [ entry, value, property ]
 author: "Jordan Borean (@jborean93)"
 '''
 
 EXAMPLES = r'''
 # Obtain information about a registry key using short form
 - win_reg_stat:
-    key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
+    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
   register: current_version
 
 # Obtain information about a registry key property
 - win_reg_stat:
-    key: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
-    property: CommonFilesDir
+    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
+    name: CommonFilesDir
   register: common_files_dir
 '''
 
@@ -67,17 +67,12 @@ changed:
   returned: always
   type: boolean
   sample: True
-win_reg_stat:
-    description: Information about the registry key or property specified.
-    returned: success
-    type: dictionary
-    contains:
-        exists:
+exists:
   description: States whether the registry key/property exists.
   returned: success and path/property exists
   type: boolean
   sample: True
-        properties:
+properties:
   description: A list of all the properties and their values in the key.
   returned: success, path exists and property not specified
   type: list
@@ -93,7 +88,7 @@ win_reg_stat:
       "value": ["a", "b"]
     }
     ]
-        sub_keys:
+sub_keys:
   description: A list of all the sub keys of the key specified.
   returned: success, path exists and property not specified
   type: list
@@ -102,18 +97,18 @@ win_reg_stat:
     "Casting",
     "DateTime"
   ]
-        raw_value:
+raw_value:
   description: Returns the raw value of the registry property, REG_EXPAND_SZ has no string expansion, REG_BINARY or REG_NONE is in hex 0x format.
     REG_NONE, this value is a hex string in the 0x format.
   returned: success, path/property exists and property specified
   type: string
   sample: '%ProgramDir%\\Common Files'
-        type:
+type:
   description: The property type.
   returned: success, path/property exists and property specified
   type: string
   sample: "REG_EXPAND_SZ"
-        value:
+value:
   description: The value of the property.
   returned: success, path/property exists and property specified
   type: string

test/integration/targets/win_reg_stat/tasks/main.yml

@@ -1,4 +1,9 @@
 ---
+- name: test
+  win_file:
+    path: "{{win_output_dir}}"
+    state: absent
+
 - name: make sure win output dir exists
   win_file:
     path: "{{win_output_dir}}"
@@ -20,33 +25,32 @@
   win_command: powershell.exe $env:windir
   register: win_dir_value
 
-- name: expect failure when not passing in key option
+- name: expect failure when not passing in path option
   win_reg_stat:
-    property: a
+    name: a
   register: actual
-  failed_when: "actual.msg != 'Missing required argument: key'"
+  failed_when: "actual.msg != 'Missing required argument: path'"
 
 - name: expect failure when passing in an invalid hive
   win_reg_stat:
-    key: ABCD:\test
+    path: ABCD:\test
   register: actual
-  failed_when: actual.msg != "the hive in key is 'ABCD'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
+  failed_when: actual.msg != "the hive in path is 'ABCD'; must be 'HKCR', 'HKCC', 'HKCU', 'HKLM' or 'HKU'"
 
 - name: get known nested reg key structure for testing with short hive form
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
   register: actual_short
 
 - name: get known nested reg key structure for testing with quoted yaml
   win_reg_stat:
-    key: "HKCU:\\Test\\nested"
+    path: "HKCU:\\Test\\nested"
   register: actual_quoted
 
 - name: set expected value for reg structure
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       properties:
         binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
@@ -67,14 +71,13 @@
 
 - name: get known reg key with no sub keys but some properties
   win_reg_stat:
-    key: HKCU:\Test\single
+    path: HKCU:\Test\single
   register: actual
 
 - name: set expected value for reg key with no sub keys but some properties
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       properties:
         none: { raw_value: [], type: 'REG_NONE', value: [] }
@@ -90,14 +93,13 @@
 
 - name: get known reg key without sub keys and properties
   win_reg_stat:
-    key: HKCU:\Test\nested\nest2
+    path: HKCU:\Test\nested\nest2
   register: actual
 
 - name: set expected value for reg key without sub keys or properties
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       properties: {}
       sub_keys: []
@@ -110,14 +112,13 @@
 
 - name: get non-existant reg key
   win_reg_stat:
-    key: HKCU:\Test\Thispathwillneverexist
+    path: HKCU:\Test\Thispathwillneverexist
   register: actual
 
 - name: set expected value for non-existant reg key
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: false
 
 - name: validate test
@@ -127,15 +128,14 @@
 
 - name: get string property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: string
+    path: HKCU:\Test\nested
+    name: string
   register: actual
 
 - name: set expected string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: 'test'
       type: 'REG_SZ'
@@ -148,15 +148,14 @@
 
 - name: get expand string property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: expand
+    path: HKCU:\Test\nested
+    name: expand
   register: actual
 
 - name: set expected expand string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: '%windir%\dir'
       type: 'REG_EXPAND_SZ'
@@ -169,15 +168,14 @@
 
 - name: get multi string property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: multi
+    path: HKCU:\Test\nested
+    name: multi
   register: actual
 
 - name: set expected multi string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: ['a, b', 'c']
       type: 'REG_MULTI_SZ'
@@ -190,15 +188,14 @@
 
 - name: get binary property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: binary
+    path: HKCU:\Test\nested
+    name: binary
   register: actual
 
 - name: set expected binary property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: ["0x01", "0x16"]
       type: 'REG_BINARY'
@@ -211,15 +208,14 @@
 
 - name: get dword property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: dword
+    path: HKCU:\Test\nested
+    name: dword
   register: actual
 
 - name: set expected dword property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: 1
       type: 'REG_DWORD'
@@ -232,15 +228,14 @@
 
 - name: get qword property
   win_reg_stat:
-    key: HKCU:\Test\nested
-    property: qword
+    path: HKCU:\Test\nested
+    name: qword
   register: actual
 
 - name: set expected qword property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: 1
       type: 'REG_QWORD'
@@ -253,15 +248,14 @@
 
 - name: get none property
   win_reg_stat:
-    key: HKCU:\Test\single
-    property: none
+    path: HKCU:\Test\single
+    name: none
   register: actual
 
 - name: set expected none property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: []
       type: 'REG_NONE'
@@ -274,15 +268,14 @@
 
 - name: get none with value property
   win_reg_stat:
-    key: HKCU:\Test\single
-    property: none1
+    path: HKCU:\Test\single
+    name: none1
   register: actual
 
 - name: set expected none with value property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: true
       raw_value: ["0x00"]
       type: 'REG_NONE'
@@ -295,15 +288,14 @@
 
 - name: get non-existance property
   win_reg_stat:
-    key: HKCU:\Test\single
-    property: doesnotexist
+    path: HKCU:\Test\single
+    name: doesnotexist
   register: actual
 
 - name: set expected non-existance property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
       exists: false
 
 - name: validate test
@@ -313,5 +305,5 @@
 
 - name: remove registry entry
   win_regedit:
-    key: HKCU:\Test
+    path: HKCU:\Test
     state: absent