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
+$path = Get-AnsibleParam -obj $params -name "path" -type "str" -failifempty $true -aliases "key"
-$property = Get-AnsibleParam -obj $params -name "property" -type "str"
+$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 (Test-Path REGISTRY::$hive\$reg_path) {
-    if ($property -eq $null) {
+    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.exists = $true
-        $result.win_reg_stat.sub_keys = $sub_keys
+        $result.sub_keys = $sub_keys
-        $result.win_reg_stat.properties = $property_info
+        $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
+            $propertyObject = Get-PropertyObject -hive $hive -net_hive $net_hive -path $reg_path -property $name
-            $result.win_reg_stat.exists = $true
+            $result.exists = $true
-            $result.win_reg_stat.raw_value = $propertyObject.raw_value
+            $result.raw_value = $propertyObject.raw_value
-            $result.win_reg_stat.value = $propertyObject.value
+            $result.value = $propertyObject.value
-            $result.win_reg_stat.type = $propertyObject.type
+            $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,86 +36,81 @@ 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:
+  path:
-        description:
+    description: The full registry key path including the hive to search for.
-        - The full registry key path including the hive to search for.
+    required: true
-        required: true
+    aliases: [ key ]
-    property:
+  name:
-        description:
+    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.
+    - 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
+    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
+    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
-    property: CommonFilesDir
+    name: CommonFilesDir
   register: common_files_dir
 '''
 
 RETURN = r'''
 changed:
-    description: Whether anything was changed.
+  description: Whether anything was changed.
-    returned: always
+  returned: always
-    type: boolean
+  type: boolean
-    sample: True
+  sample: True
-win_reg_stat:
+exists:
-    description: Information about the registry key or property specified.
+  description: States whether the registry key/property exists.
-    returned: success
+  returned: success and path/property exists
-    type: dictionary
+  type: boolean
-    contains:
+  sample: True
-        exists:
+properties:
-             description: States whether the registry key/property exists.
+  description: A list of all the properties and their values in the key.
-             returned: success and path/property exists
+  returned: success, path exists and property not specified
-             type: boolean
+  type: list
-             sample: True
+  sample: [
-        properties:
+    "binary_property" : {
-            description: A list of all the properties and their values in the key.
+      "raw_value": ["0x01", "0x16"],
-            returned: success, path exists and property not specified
+      "type": "REG_BINARY",
-            type: list
+      "value": [1, 22]
-            sample: [
+    },
-                "binary_property" : {
+    "multi_string_property" : {
-                    "raw_value": ["0x01", "0x16"],
+      "raw_value": ["a", "b"],
-                    "type": "REG_BINARY",
+      "type": "REG_MULTI_SZ",
-                    "value": [1, 22]
+      "value": ["a", "b"]
-                },
+    }
-                "multi_string_property" : {
+    ]
-                    "raw_value": ["a", "b"],
+sub_keys:
-                    "type": "REG_MULTI_SZ",
+  description: A list of all the sub keys of the key specified.
-                    "value": ["a", "b"]
+  returned: success, path exists and property not specified
-                }
+  type: list
-            ]
+  sample: [
-        sub_keys:
+    "AppHost",
-            description: A list of all the sub keys of the key specified.
+    "Casting",
-            returned: success, path exists and property not specified
+    "DateTime"
-            type: list
+  ]
-            sample: [
+raw_value:
-                "AppHost",
+  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.
-                "Casting",
+    REG_NONE, this value is a hex string in the 0x format.
-                "DateTime"
+  returned: success, path/property exists and property specified
-            ]
+  type: string
-        raw_value:
+  sample: '%ProgramDir%\\Common Files'
-            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.
+type:
-              REG_NONE, this value is a hex string in the 0x format.
+  description: The property type.
-            returned: success, path/property exists and property specified
+  returned: success, path/property exists and property specified
-            type: string
+  type: string
-            sample: '%ProgramDir%\\Common Files'
+  sample: "REG_EXPAND_SZ"
-        type:
+value:
-            description: The property type.
+  description: The value of the property.
-            returned: success, path/property exists and property specified
+  returned: success, path/property exists and property specified
-            type: string
+  type: string
-            sample: "REG_EXPAND_SZ"
+  sample: 'C:\\Program Files\\Common Files'
-        value:
-            description: The value of the property.
-            returned: success, path/property exists and property specified
-            type: string
-            sample: 'C:\\Program Files\\Common Files'
 '''

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,44 +25,43 @@
   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
-        exists: true
+      properties:
-        properties:
+        binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
-          binary: { raw_value: ["0x01", "0x16"], type: 'REG_BINARY', value: [1, 22] }
+        dword: { raw_value: 1, type: 'REG_DWORD', value: 1 }
-          dword: { raw_value: 1, type: 'REG_DWORD', value: 1 }
+        expand: { raw_value: '%windir%\dir', type: 'REG_EXPAND_SZ', value: "{{win_dir_value.stdout_lines[0]}}\\dir" }
-          expand: { raw_value: '%windir%\dir', type: 'REG_EXPAND_SZ', value: "{{win_dir_value.stdout_lines[0]}}\\dir" }
+        multi: { raw_value: ['a, b', 'c'], type: 'REG_MULTI_SZ', value: ['a, b', 'c'] }
-          multi: { raw_value: ['a, b', 'c'], type: 'REG_MULTI_SZ', value: ['a, b', 'c'] }
+        qword: { raw_value: 1, type: 'REG_QWORD', value: 1 }
-          qword: { raw_value: 1, type: 'REG_QWORD', value: 1 }
+        string: { raw_value: 'test', type: 'REG_SZ', value: 'test' }
-          string: { raw_value: 'test', type: 'REG_SZ', value: 'test' }
+      sub_keys:
-        sub_keys:
+      - nest1
-        - nest1
+      - nest2
-        - nest2
 
 - name: validate test
   assert:
@@ -67,21 +71,20 @@
 
 - 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
-        exists: true
+      properties:
-        properties:
+        none: { raw_value: [], type: 'REG_NONE', value: [] }
-          none: { raw_value: [], type: 'REG_NONE', value: [] }
+        none1: { raw_value: ["0x00"], type: 'REG_NONE', value: [0] }
-          none1: { raw_value: ["0x00"], type: 'REG_NONE', value: [0] }
+        string1: { raw_value: '', type: 'REG_SZ', value: '' }
-          string1: { raw_value: '', type: 'REG_SZ', value: '' }
+        string2: { raw_value: 'abc123', type: 'REG_SZ', value: 'abc123' }
-          string2: { raw_value: 'abc123', type: 'REG_SZ', value: 'abc123' }
+      sub_keys: []
-        sub_keys: []
 
 - name: validate test
   assert:
@@ -90,17 +93,16 @@
 
 - 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
-        exists: true
+      properties: {}
-        properties: {}
+      sub_keys: []
-        sub_keys: []
   register: expected
 
 - name: validate test
@@ -110,15 +112,14 @@
 
 - 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
-        exists: false
 
 - name: validate test
   assert:
@@ -127,19 +128,18 @@
 
 - name: get string property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: string
+    name: string
   register: actual
 
 - name: set expected string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: 'test'
-        raw_value: 'test'
+      type: 'REG_SZ'
-        type: 'REG_SZ'
+      value: 'test'
-        value: 'test'
 
 - name: validate test
   assert:
@@ -148,19 +148,18 @@
 
 - name: get expand string property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: expand
+    name: expand
   register: actual
 
 - name: set expected expand string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: '%windir%\dir'
-        raw_value: '%windir%\dir'
+      type: 'REG_EXPAND_SZ'
-        type: 'REG_EXPAND_SZ'
+      value: "{{win_dir_value.stdout_lines[0]}}\\dir"
-        value: "{{win_dir_value.stdout_lines[0]}}\\dir"
 
 - name: validate test
   assert:
@@ -169,19 +168,18 @@
 
 - name: get multi string property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: multi
+    name: multi
   register: actual
 
 - name: set expected multi string property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: ['a, b', 'c']
-        raw_value: ['a, b', 'c']
+      type: 'REG_MULTI_SZ'
-        type: 'REG_MULTI_SZ'
+      value: ['a, b', 'c']
-        value: ['a, b', 'c']
 
 - name: validate test
   assert:
@@ -190,19 +188,18 @@
 
 - name: get binary property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: binary
+    name: binary
   register: actual
 
 - name: set expected binary property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: ["0x01", "0x16"]
-        raw_value: ["0x01", "0x16"]
+      type: 'REG_BINARY'
-        type: 'REG_BINARY'
+      value: [1, 22]
-        value: [1, 22]
 
 - name: validate test
   assert:
@@ -211,19 +208,18 @@
 
 - name: get dword property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: dword
+    name: dword
   register: actual
 
 - name: set expected dword property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: 1
-        raw_value: 1
+      type: 'REG_DWORD'
-        type: 'REG_DWORD'
+      value: 1
-        value: 1
 
 - name: validate test
   assert:
@@ -232,19 +228,18 @@
 
 - name: get qword property
   win_reg_stat:
-    key: HKCU:\Test\nested
+    path: HKCU:\Test\nested
-    property: qword
+    name: qword
   register: actual
 
 - name: set expected qword property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: 1
-        raw_value: 1
+      type: 'REG_QWORD'
-        type: 'REG_QWORD'
+      value: 1
-        value: 1
 
 - name: validate test
   assert:
@@ -253,19 +248,18 @@
 
 - name: get none property
   win_reg_stat:
-    key: HKCU:\Test\single
+    path: HKCU:\Test\single
-    property: none
+    name: none
   register: actual
 
 - name: set expected none property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: []
-        raw_value: []
+      type: 'REG_NONE'
-        type: 'REG_NONE'
+      value: []
-        value: []
 
 - name: validate test
   assert:
@@ -274,19 +268,18 @@
 
 - name: get none with value property
   win_reg_stat:
-    key: HKCU:\Test\single
+    path: HKCU:\Test\single
-    property: none1
+    name: none1
   register: actual
 
 - name: set expected none with value property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: true
-        exists: true
+      raw_value: ["0x00"]
-        raw_value: ["0x00"]
+      type: 'REG_NONE'
-        type: 'REG_NONE'
+      value: [0]
-        value: [0]
 
 - name: validate test
   assert:
@@ -295,16 +288,15 @@
 
 - name: get non-existance property
   win_reg_stat:
-    key: HKCU:\Test\single
+    path: HKCU:\Test\single
-    property: doesnotexist
+    name: doesnotexist
   register: actual
 
 - name: set expected non-existance property
   set_fact:
     expected:
       changed: false
-      win_reg_stat:
+      exists: false
-        exists: false
 
 - name: validate test
   assert:
@@ -313,5 +305,5 @@
 
 - name: remove registry entry
   win_regedit:
-    key: HKCU:\Test
+    path: HKCU:\Test
     state: absent