From 1c2e8fde292623303facdcec54cf8ec49066ed7c Mon Sep 17 00:00:00 2001 From: jhawkesworth Date: Wed, 1 Mar 2017 14:16:33 +0000 Subject: [PATCH] Add win_msg module (#22008) * new implementation of win_msg. TODO tests * added check_mode. Get-AnsibleParam for parameters. Default msg is now 'Hello world!'. Use hash for $results. Re-ordered some parameters alphabetically. Documentation now in raw strings. Removed spurious required: false. Added metadata. * Keep pep8 checks happy * Really keep pep8 checks happy this time * update Changelog.md * make bracket style internally consistent * added units to display_seconds description --- CHANGELOG.md | 1 + lib/ansible/modules/windows/win_msg.ps1 | 63 ++++++++++++++++ lib/ansible/modules/windows/win_msg.py | 98 +++++++++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 lib/ansible/modules/windows/win_msg.ps1 create mode 100644 lib/ansible/modules/windows/win_msg.py diff --git a/CHANGELOG.md b/CHANGELOG.md index f57e65a2ee..15a4ac498d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -263,6 +263,7 @@ Ansible Changes By Release * win_dns_client * win_domain_membership * win_find + * win_msg * win_path * win_psexec * win_reg_stat diff --git a/lib/ansible/modules/windows/win_msg.ps1 b/lib/ansible/modules/windows/win_msg.ps1 new file mode 100644 index 0000000000..4d5c2946bd --- /dev/null +++ b/lib/ansible/modules/windows/win_msg.ps1 @@ -0,0 +1,63 @@ +#!powershell +# This file is part of Ansible +# +# Copyright 2016, Jon Hawkesworth (@jhawkesworth) +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# WANT_JSON +# POWERSHELL_COMMON + +$stopwatch = [system.diagnostics.stopwatch]::startNew() + +$params = Parse-Args $args -supports_check_mode $true +$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false + +$display_seconds = Get-AnsibleParam -obj $params -name display_seconds -default "10" -failifempty $False -resultobj $result +$msg = Get-AnsibleParam -obj $params -name msg -default "Hello world!" -resultobj $result +$to = Get-AnsibleParam -obj $params -name to -default "*" -failifempty $False -resultobj $result +$wait = Get-AnsibleParam -obj $params -name wait -default $False -failifempty $False -resultobj $result + +$result = @{ + changed = $false +} + + +$msg_args = @($to, "/TIME:$display_seconds") + +If ($wait) { + $msg_args += "/W" +} + +$msg_args += $msg +if (-not $check_mode) { + $ret = & msg.exe $msg_args 2>&1 + $result.rc = $LASTEXITCODE +} + +$endsend_at = Get-Date| Out-String +$stopwatch.Stop() + +$result.changed = $True +$result.display_seconds = $display_seconds +$result.msg = $msg +$result.runtime_seconds = $stopwatch.Elapsed.TotalSeconds +$result.sent_localtime = $endsend_at.Trim() +$result.wait = $wait + +If (-not $result.rc -eq 0 ) { + Fail-Json $result "$ret" +} + +Exit-Json $result diff --git a/lib/ansible/modules/windows/win_msg.py b/lib/ansible/modules/windows/win_msg.py new file mode 100644 index 0000000000..627e9df58c --- /dev/null +++ b/lib/ansible/modules/windows/win_msg.py @@ -0,0 +1,98 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# (c) 2017, Jon Hawkesworth (@jhawkesworth) +# +# This file is part of Ansible +# +# Ansible is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# Ansible is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with Ansible. If not, see . + +# this is a windows documentation stub. actual code lives in the .ps1 +# file of the same name + +ANSIBLE_METADATA = {'status': ['preview'], + 'supported_by': 'community', + 'version': '1.0'} + +DOCUMENTATION = r''' +--- +module: win_msg +version_added: "2.3" +short_description: Sends a message to logged in users on Windows hosts. +description: + - Wraps the msg.exe command in order to send messages to Windows hosts. +options: + to: + description: + - Who to send the message to. Can be a username, sessionname or sessionid. + default: '*' + display_seconds: + description: + - How long to wait for receiver to acknowledge message, in seconds. + default: 10 + wait: + description: + - Whether to wait for users to respond. Module will only wait for the number of seconds specified in display_seconds or 10 seconds if not specified. + However, if I(wait) is true, the message is sent to each logged on user in turn, waiting for the user to either press 'ok' or for + the timeout to elapse before moving on to the next user. + required: false + default: false + msg: + description: + - The text of the message to be displayed. + default: Hello world! +author: "Jon Hawkesworth (@jhawkesworth)" +notes: + - This module must run on a windows host, so ensure your play targets windows + hosts, or delegates to a windows host. + - Messages are only sent to the local host where the module is run. + - The module does not support sending to users listed in a file. + - Setting wait to true can result in long run times on systems with many logged in users. +''' + +EXAMPLES = r''' + # Warn logged in users of impending upgrade + win_msg: + display_seconds: 60 + msg: "Automated upgrade about to start. Please save your work and log off before {{ deployment_start_time }}" +''' + +RETURN = r''' +msg: + description: Test of the message that was sent. + returned: changed + type: string + sample: "Automated upgrade about to start. Please save your work and log off before 22 July 2016 18:00:00" +display_seconds: + description: Value of display_seconds module parameter. + returned: success + type: string + sample: 10 +runtime_seconds: + description: How long the module took to run on the remote windows host. + returned: success + type: string + sample: 22 July 2016 17:45:51 +sent_localtime: + description: local time from windows host when the message was sent. + returned: success + type: string + sample: 22 July 2016 17:45:51 +wait: + description: Value of wait module parameter. + returned: success + type: boolean + sample: false +''' +