1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2017, Jon Hawkesworth (@jhawkesworth) <jhawkesworth@protonmail.com>
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_msg
10short_description: Sends a message to logged in users on Windows hosts
11description:
12    - Wraps the msg.exe command in order to send messages to Windows hosts.
13options:
14  to:
15    description:
16      - Who to send the message to. Can be a username, sessionname or sessionid.
17    type: str
18    default: '*'
19  display_seconds:
20    description:
21      - How long to wait for receiver to acknowledge message, in seconds.
22    type: int
23    default: 10
24  wait:
25    description:
26      - 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.
27        However, if I(wait) is C(yes), the message is sent to each logged on user in turn, waiting for the user to either press 'ok' or for
28        the timeout to elapse before moving on to the next user.
29    type: bool
30    default: 'no'
31  msg:
32    description:
33      - The text of the message to be displayed.
34      - The message must be less than 256 characters.
35    type: str
36    default: Hello world!
37notes:
38   - This module must run on a windows host, so ensure your play targets windows
39     hosts, or delegates to a windows host.
40   - Messages are only sent to the local host where the module is run.
41   - The module does not support sending to users listed in a file.
42   - Setting wait to C(yes) can result in long run times on systems with many logged in users.
43seealso:
44- module: community.windows.win_say
45- module: community.windows.win_toast
46author:
47- Jon Hawkesworth (@jhawkesworth)
48'''
49
50EXAMPLES = r'''
51- name: Warn logged in users of impending upgrade
52  community.windows.win_msg:
53    display_seconds: 60
54    msg: Automated upgrade about to start.  Please save your work and log off before {{ deployment_start_time }}
55'''
56
57RETURN = r'''
58msg:
59    description: Test of the message that was sent.
60    returned: changed
61    type: str
62    sample: Automated upgrade about to start.  Please save your work and log off before 22 July 2016 18:00:00
63display_seconds:
64    description: Value of display_seconds module parameter.
65    returned: success
66    type: str
67    sample: 10
68rc:
69    description: The return code of the API call.
70    returned: always
71    type: int
72    sample: 0
73runtime_seconds:
74    description: How long the module took to run on the remote windows host.
75    returned: success
76    type: str
77    sample: 22 July 2016 17:45:51
78sent_localtime:
79    description: local time from windows host when the message was sent.
80    returned: success
81    type: str
82    sample: 22 July 2016 17:45:51
83wait:
84    description: Value of wait module parameter.
85    returned: success
86    type: bool
87    sample: false
88'''
89