#!/usr/bin/python
# -*- coding: utf-8 -*-

# (c) 2015, Matt Davis <mdavis_ansible@rolpdog.com>
#
# 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 <http://www.gnu.org/licenses/>.

# this is a windows documentation stub.  actual code lives in the .ps1
# file of the same name

ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['preview'],
                    'supported_by': 'core'}


DOCUMENTATION = r'''
---
module: win_updates
version_added: "2.0"
short_description: Download and install Windows updates
description:
    - Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client
options:
    category_names:
        description:
        - A scalar or list of categories to install updates from
        required: false
        default: ["CriticalUpdates","SecurityUpdates","UpdateRollups"]
        choices:
        - Application
        - Connectors
        - CriticalUpdates
        - DefinitionUpdates
        - DeveloperKits
        - FeaturePacks
        - Guidance
        - SecurityUpdates
        - ServicePacks
        - Tools
        - UpdateRollups
        - Updates
    state:
        description:
        - Controls whether found updates are returned as a list or actually installed.
        - This module also supports Ansible check mode, which has the same effect as setting state=searched
        required: false
        default: installed
        choices:
        - installed
        - searched
    log_path:
        description:
        - If set, C(win_updates) will append update progress to the specified file. The directory must already exist.
        required: false
author: "Matt Davis (@mattdavispdx)"
notes:
- C(win_updates) must be run by a user with membership in the local Administrators group
- C(win_updates) will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc)
- C(win_updates) does not manage reboots, but will signal when a reboot is required with the reboot_required return value.
- C(win_updates) can take a significant amount of time to complete (hours, in some cases).
  Performance depends on many factors, including OS version, number of updates, system load, and update server load.
- C(win_updates) runs the module as a scheduled task, this task is set to start and continue to run even if the Windows host
  swaps to battery power. This behaviour was changed from Ansible 2.4, before this the scheduled task would fail to start on
  battery power.
'''

EXAMPLES = r'''
# Install all security, critical, and rollup updates
- win_updates:
    category_names:
      - SecurityUpdates
      - CriticalUpdates
      - UpdateRollups

# Install only security updates
- win_updates:
    category_names: SecurityUpdates

# Search-only, return list of found updates (if any), log to c:\ansible_wu.txt
- win_updates:
    category_names: SecurityUpdates
    state: searched
    log_path: c:\ansible_wu.txt
'''

RETURN = r'''
reboot_required:
    description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot)
    returned: success
    type: boolean
    sample: True

updates:
    description: List of updates that were found/installed
    returned: success
    type: complex
    sample:
    contains:
        title:
            description: Display name
            returned: always
            type: string
            sample: "Security Update for Windows Server 2012 R2 (KB3004365)"
        kb:
            description: A list of KB article IDs that apply to the update
            returned: always
            type: list of strings
            sample: [ '3004365' ]
        id:
            description: Internal Windows Update GUID
            returned: always
            type: string (guid)
            sample: "fb95c1c8-de23-4089-ae29-fd3351d55421"
        installed:
            description: Was the update successfully installed
            returned: always
            type: boolean
            sample: True
        failure_hresult_code:
            description: The HRESULT code from a failed update
            returned: on install failure
            type: boolean
            sample: 2147942402

found_update_count:
    description: The number of updates found needing to be applied
    returned: success
    type: int
    sample: 3
installed_update_count:
    description: The number of updates successfully installed
    returned: success
    type: int
    sample: 2
failed_update_count:
    description: The number of updates that failed to install
    returned: always
    type: int
    sample: 0
'''