Wait for VM state to reach poweredoff when state: shutdownguest (#31669)

This change adds the optional wait_for_state_change argument to the
vmware_guest, vmware_guest_powerstate module, which allows for module
completion to be blocked when using the shutdownguest state until the
VM has reached the poweredoff state.

Fixes: #28498

Signed-off-by: Jim Gu <heming.gu@mercurygate.com>
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/cloud/vmware/vmware_guest.py

@@ -156,6 +156,13 @@ options:
     - "vmware-tools needs to be installed on given virtual machine in order to work with this parameter."
     default: 'no'
     type: bool
+  state_change_timeout:
+    description:
+    - If the C(state) is set to C(shutdownguest), by default the module will return immediately after sending the shutdown signal.
+    - If this argument is set to a positive integer, the module will instead wait for the VM to reach the poweredoff state.
+    - The value sets a timeout in seconds for the module to wait for the state change.
+    default: 0
+    version_added: '2.6'
   snapshot_src:
     description:
     - Name of the existing snapshot to use to create a clone of a VM.
@@ -1994,6 +2001,7 @@ def main():
         esxi_hostname=dict(type='str'),
         cluster=dict(type='str'),
         wait_for_ip_address=dict(type='bool', default=False),
+        state_change_timeout=dict(type='int', default=0),
         snapshot_src=dict(type='str'),
         linked_clone=dict(type='bool', default=False),
         networks=dict(type='list', default=[]),
@@ -2054,7 +2062,7 @@ def main():
                 )
                 module.exit_json(**result)
             # set powerstate
-            tmp_result = set_vm_power_state(pyv.content, vm, module.params['state'], module.params['force'])
+            tmp_result = set_vm_power_state(pyv.content, vm, module.params['state'], module.params['force'], module.params['state_change_timeout'])
             if tmp_result['changed']:
                 result["changed"] = True
             if not tmp_result["failed"]: