.. versionadded:: 2017.7.0

    List updates that match the passed criteria. This allows for more filter
    options than :func:`list`. Good for finding a specific GUID or KB.

    Args:

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

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

        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 updates that are already installed. Default is False.

        skip_hidden (bool):
            Skip updates that have been hidden. Default is True.

        skip_mandatory (bool):
            Skip mandatory updates. Default is False.

        skip_reboot (bool):
            Skip updates that require a reboot. Default is False.

        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.available

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

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

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

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

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

def available(software=True,
              drivers=True,
              summary=False,
              skip_installed=True,
              skip_hidden=True,
              skip_mandatory=False,
              skip_reboot=False,
              categories=None,
              severities=None,):
    '''
    .. versionadded:: 2017.7.0

    List updates that match the passed criteria. This allows for more filter
    options than :func:`list`. Good for finding a specific GUID or KB.

    Args:

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

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

        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 updates that are already installed. Default is False.

        skip_hidden (bool):
            Skip updates that have been hidden. Default is True.

        skip_mandatory (bool):
            Skip mandatory updates. Default is False.

        skip_reboot (bool):
            Skip updates that require a reboot. Default is False.

        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.available

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

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

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

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

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

    # Create a Windows Update Agent instance
    wua = salt.utils.win_update.WindowsUpdateAgent()

    # Look for available
    updates = wua.available(
        skip_hidden=skip_hidden, skip_installed=skip_installed,
        skip_mandatory=skip_mandatory, skip_reboot=skip_reboot,
        software=software, drivers=drivers, categories=categories,
        severities=severities)

    # Return results as Summary or Details
    return updates.summary() if summary else updates.list()