.. versionadded:: 2017.7.0

    Returns a detailed list of available updates or a summary. If download or
    install is True the same list will be downloaded and/or installed.

    Args:

        software (bool):
            Include software updates in the results (default is True)

        drivers (bool):
            Include driver updates in the results (default is False)

        summary (bool):
            - True: Return a summary of updates available for each category.
            - False (default): Return a detailed list of available updates.

        skip_installed (bool):
            Skip installed updates in the results (default is False)

        download (bool):
            (Overrides reporting functionality) Download the list of updates
            returned by this function. Run this function first with
            ``download=False`` to see what will be downloaded, then set
            ``download=True`` to download the updates.

        install (bool):
            (Overrides reporting functionality) Install the list of updates
            returned by this function. Run this function first with
            ``install=False`` to see what will be installed, then set
            ``install=True`` to install the updates.

        categories (list):
            Specify the categories to list. Must be passed as a list. All
            categories returned by default.

            Categories include the following:

            * Critical Updates
            * Definition Updates
            * Drivers (make sure you set drivers=True)
            * Feature Packs
            * Security Updates
            * Update Rollups
            * Updates
            * Update Rollups
            * Windows 7
            * Windows 8.1
            * Windows 8.1 drivers
            * Windows 8.1 and later drivers
            * Windows Defender

        severities (list):
            Specify the severities to include. Must be passed as a list. All
            severities returned by default.

            Severities include the following:

            * Critical
            * Important

    Returns:

        dict: Returns a dict containing either a summary or a list of updates:

        .. code-block:: cfg

            List of Updates:
            {'<GUID>': {'Title': <title>,
                        'KB': <KB>,
                        'GUID': <the globally unique identifier for the update>
                        'Description': <description>,
                        'Downloaded': <has the update been downloaded>,
                        'Installed': <has the update been installed>,
                        'Mandatory': <is the update mandatory>,
                        'UserInput': <is user input required>,
                        'EULAAccepted': <has the EULA been accepted>,
                        'Severity': <update severity>,
                        'NeedsReboot': <is the update installed and awaiting reboot>,
                        'RebootBehavior': <will the update require a reboot>,
                        'Categories': [ '<category 1>',
                                        '<category 2>',
                                        ...]
                        }
            }

            Summary of Updates:
            {'Total': <total number of updates returned>,
             'Available': <updates that are not downloaded or installed>,
             'Downloaded': <updates that are downloaded but not installed>,
             'Installed': <updates installed (usually 0 unless installed=True)>,
             'Categories': { <category 1>: <total for that category>,
                             <category 2>: <total for category 2>,
                             ... }
            }

    CLI Examples:

    .. code-block:: bash

        # Normal Usage (list all software updates)
        salt '*' win_wua.list

        # List all updates with categories of Critical Updates and Drivers
        salt '*' win_wua.list categories=['Critical Updates','Drivers']

        # List all Critical Security Updates
        salt '*' win_wua.list categories=['Security Updates'] severities=['Critical']

        # List all updates with a severity of Critical
        salt '*' win_wua.list severities=['Critical']

        # A summary of all available updates
        salt '*' win_wua.list summary=True

        # A summary of all Feature Packs and Windows 8.1 Updates
        salt '*' win_wua.list categories=['Feature Packs','Windows 8.1'] summary=True

def list(software=True,
         drivers=False,
         summary=False,
         skip_installed=True,
         categories=None,
         severities=None,
         download=False,
         install=False):
    '''
    .. versionadded:: 2017.7.0

    Returns a detailed list of available updates or a summary. If download or
    install is True the same list will be downloaded and/or installed.

    Args:

        software (bool):
            Include software updates in the results (default is True)

        drivers (bool):
            Include driver updates in the results (default is False)

        summary (bool):
            - True: Return a summary of updates available for each category.
            - False (default): Return a detailed list of available updates.

        skip_installed (bool):
            Skip installed updates in the results (default is False)

        download (bool):
            (Overrides reporting functionality) Download the list of updates
            returned by this function. Run this function first with
            ``download=False`` to see what will be downloaded, then set
            ``download=True`` to download the updates.

        install (bool):
            (Overrides reporting functionality) Install the list of updates
            returned by this function. Run this function first with
            ``install=False`` to see what will be installed, then set
            ``install=True`` to install the updates.

        categories (list):
            Specify the categories to list. Must be passed as a list. All
            categories returned by default.

            Categories include the following:

            * Critical Updates
            * Definition Updates
            * Drivers (make sure you set drivers=True)
            * Feature Packs
            * Security Updates
            * Update Rollups
            * Updates
            * Update Rollups
            * Windows 7
            * Windows 8.1
            * Windows 8.1 drivers
            * Windows 8.1 and later drivers
            * Windows Defender

        severities (list):
            Specify the severities to include. Must be passed as a list. All
            severities returned by default.

            Severities include the following:

            * Critical
            * Important

    Returns:

        dict: Returns a dict containing either a summary or a list of updates:

        .. code-block:: cfg

            List of Updates:
            {'<GUID>': {'Title': <title>,
                        'KB': <KB>,
                        'GUID': <the globally unique identifier for the update>
                        'Description': <description>,
                        'Downloaded': <has the update been downloaded>,
                        'Installed': <has the update been installed>,
                        'Mandatory': <is the update mandatory>,
                        'UserInput': <is user input required>,
                        'EULAAccepted': <has the EULA been accepted>,
                        'Severity': <update severity>,
                        'NeedsReboot': <is the update installed and awaiting reboot>,
                        'RebootBehavior': <will the update require a reboot>,
                        'Categories': [ '<category 1>',
                                        '<category 2>',
                                        ...]
                        }
            }

            Summary of Updates:
            {'Total': <total number of updates returned>,
             'Available': <updates that are not downloaded or installed>,
             'Downloaded': <updates that are downloaded but not installed>,
             'Installed': <updates installed (usually 0 unless installed=True)>,
             'Categories': { <category 1>: <total for that category>,
                             <category 2>: <total for category 2>,
                             ... }
            }

    CLI Examples:

    .. code-block:: bash

        # Normal Usage (list all software updates)
        salt '*' win_wua.list

        # List all updates with categories of Critical Updates and Drivers
        salt '*' win_wua.list categories=['Critical Updates','Drivers']

        # List all Critical Security Updates
        salt '*' win_wua.list categories=['Security Updates'] severities=['Critical']

        # List all updates with a severity of Critical
        salt '*' win_wua.list severities=['Critical']

        # A summary of all available updates
        salt '*' win_wua.list summary=True

        # A summary of all Feature Packs and Windows 8.1 Updates
        salt '*' win_wua.list categories=['Feature Packs','Windows 8.1'] summary=True
    '''
    # Create a Windows Update Agent instance
    wua = salt.utils.win_update.WindowsUpdateAgent()

    # Search for Update
    updates = wua.available(skip_installed=skip_installed, software=software,
                            drivers=drivers, categories=categories,
                            severities=severities)

    ret = {}

    # Download
    if download or install:
        ret['Download'] = wua.download(updates)

    # Install
    if install:
        ret['Install'] = wua.install(updates)

    if not ret:
        return updates.summary() if summary else updates.list()

    return ret