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

# Copyright (c) 2021, Cisco Systems
# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION = r"""
---
module: images_v1_info
short_description: Information module for Images V1
description:
- Get all Images V1.
- >
   A list of available images for the specified site is provided. The default value of the site is set to global. The
   list includes images that have been imported onto the disk, as well as the latest and suggested images from
   Cisco.com.
version_added: '6.15.0'
extends_documentation_fragment:
  - cisco.dnac.module_info
author: Rafael Campos (@racampos)
options:
  headers:
    description: Additional headers.
    type: dict
  siteId:
    description:
    - >
      SiteId query parameter. Site identifier to get the list of all available products under the site. The
      default value is the global site. See https //developer.cisco.com/docs/dna-center/get-site for `siteId`.
    type: str
  productNameOrdinal:
    description:
    - >
      ProductNameOrdinal query parameter. The product name ordinal is a unique value for each network device
      product. The productNameOrdinal can be obtained from the response of API
      `/dna/intent/api/v1/siteWiseProductNames`.
    type: float
  supervisorProductNameOrdinal:
    description:
    - >
      SupervisorProductNameOrdinal query parameter. The supervisor engine module ordinal is a unique value for
      each supervisor module. The `supervisorProductNameOrdinal` can be obtained from the response of API
      `/dna/intent/api/v1/siteWiseProductNames`.
    type: float
  imported:
    description:
    - >
      Imported query parameter. When the value is set to `true`, it will include physically imported images.
      Conversely, when the value is set to `false`, it will include image records from the cloud. The identifier
      for cloud images can be utilized to download images from Cisco.com to the disk.
    type: bool
  name:
    description:
    - >
      Name query parameter. Filter with software image or add-on name. Supports partial case-insensitive search. A
      minimum of 3 characters is required for the search.
    type: str
  version:
    description:
    - >
      Version query parameter. Filter with image version. Supports partial case-insensitive search. A minimum of 3
      characters is required for the search.
    type: str
  golden:
    description:
    - >
      Golden query parameter. When set to `true`, it will retrieve the images marked as tagged golden. When set to
      `false`, it will retrieve the images marked as not tagged golden.
    type: bool
  integrity:
    description:
    - >
      Integrity query parameter. Filter with verified images using Integrity Verification Available values
      UNKNOWN, VERIFIED.
    type: str
  hasAddonImages:
    description:
    - >
      HasAddonImages query parameter. When set to `true`, it will retrieve the images which have add-on images.
      When set to `false`, it will retrieve the images which do not have add-on images.
    type: bool
  isAddonImages:
    description:
    - >
      IsAddonImages query parameter. When set to `true`, it will retrieve the images that an add-on image. When
      set to `false`, it will retrieve the images that are not add-on images.
    type: bool
  offset:
    description:
    - >
      Offset query parameter. The first record to show for this page; the first record is numbered 1. The minimum
      value is 1.
    type: float
  limit:
    description:
    - >
      Limit query parameter. The number of records to show for this page. The minimum and maximum values are 1 and
      500, respectively.
    type: float
requirements:
- dnacentersdk >= 2.4.9
- python >= 3.5
seealso:
- name: Cisco DNA Center documentation for Software Image Management (SWIM) ReturnsListOfSoftwareImagesV1
  description: Complete reference of the ReturnsListOfSoftwareImagesV1 API.
  link: https://developer.cisco.com/docs/dna-center/#!returns-list-of-software-images
notes:
  - SDK Method used are
    software_image_management_swim.SoftwareImageManagementSwim.returns_list_of_software_images_v1,

  - Paths used are
    get /dna/intent/api/v1/images,

"""

EXAMPLES = r"""
- name: Get all Images V1
  cisco.dnac.images_v1_info:
    dnac_host: "{{dnac_host}}"
    dnac_username: "{{dnac_username}}"
    dnac_password: "{{dnac_password}}"
    dnac_verify: "{{dnac_verify}}"
    dnac_port: "{{dnac_port}}"
    dnac_version: "{{dnac_version}}"
    dnac_debug: "{{dnac_debug}}"
    headers: "{{my_headers | from_json}}"
    siteId: string
    productNameOrdinal: 0
    supervisorProductNameOrdinal: 0
    imported: True
    name: string
    version: string
    golden: True
    integrity: string
    hasAddonImages: True
    isAddonImages: True
    offset: 0
    limit: 0
  register: result

"""
RETURN = r"""
dnac_response:
  description: A dictionary or list with the response returned by the Cisco DNAC Python SDK
  returned: always
  type: dict
  sample: >
    {
      "response": [
        {
          "id": "string",
          "imported": true,
          "name": "string",
          "version": "string",
          "imageType": "string",
          "recommended": "string",
          "ciscoLatest": true,
          "integrityStatus": "string",
          "isAddonImage": true,
          "hasAddonImages": true,
          "goldenTaggingDetails": [
            {
              "deviceRoles": [
                "string"
              ],
              "deviceTags": [
                "string"
              ],
              "inheritedSiteId": "string",
              "inheritedSiteName": "string"
            }
          ],
          "productNames": [
            {
              "id": "string",
              "productName": "string",
              "productNameOrdinal": 0,
              "supervisorProductName": "string",
              "supervisorProductNameOrdinal": 0
            }
          ],
          "isGoldenTagged": true
        }
      ],
      "version": "string"
    }
"""
