1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2018, Varun Chopra (@chopraaa) <v@chopraaa.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_partition
10short_description: Creates, changes and removes partitions on Windows Server
11description:
12  - The M(community.windows.win_partition) module can create, modify or delete a partition on a disk
13options:
14  state:
15    description:
16      - Used to specify the state of the partition. Use C(absent) to specify if a partition should be removed
17        and C(present) to specify if the partition should be created or updated.
18    type: str
19    choices: [ absent, present]
20    default: present
21  drive_letter:
22    description:
23      - Used for accessing partitions if I(disk_number) and I(partition_number) are not provided.
24      - Use C(auto) for automatically assigning a drive letter, or a letter A-Z for manually assigning a drive letter to a new partition.
25        If not specified, no drive letter is assigned when creating a new partition.
26    type: str
27  disk_number:
28    description:
29      - Disk number is mandatory for creating new partitions.
30      - A combination of I(disk_number) and I(partition_number) can be used to specify the partition instead of I(drive_letter) if required.
31    type: int
32  partition_number:
33    description:
34      - Used in conjunction with I(disk_number) to uniquely identify a partition.
35    type: int
36  partition_size:
37    description:
38      - Specify size of the partition in B, KB, KiB, MB, MiB, GB, GiB, TB or TiB. Use -1 to specify maximum supported size.
39      - Partition size is mandatory for creating a new partition but not for updating or deleting a partition.
40      - The decimal SI prefixes kilo, mega, giga, tera, etc., are powers of 10^3 = 1000. The binary prefixes kibi, mebi, gibi, tebi, etc.
41        respectively refer to the corresponding power of 2^10 = 1024.
42        Thus, a gigabyte (GB) is 1000000000 (1000^3) bytes while 1 gibibyte (GiB) is 1073741824 (1024^3) bytes.
43    type: str
44  read_only:
45    description:
46      - Make the partition read only, restricting changes from being made to the partition.
47    type: bool
48  active:
49    description:
50      - Specifies if the partition is active and can be used to start the system. This property is only valid when the disk's partition style is MBR.
51    type: bool
52  hidden:
53    description:
54      - Hides the target partition, making it undetectable by the mount manager.
55    type: bool
56  offline:
57    description:
58      - Sets the partition offline.
59      - Adding a mount point (such as a drive letter) will cause the partition to go online again.
60    type: bool
61    required: no
62  mbr_type:
63    description:
64      - Specify the partition's MBR type if the disk's partition style is MBR.
65      - This only applies to new partitions.
66      - This does not relate to the partitions file system formatting.
67    type: str
68    choices: [ fat12, fat16, extended, huge, ifs, fat32 ]
69  gpt_type:
70    description:
71      - Specify the partition's GPT type if the disk's partition style is GPT.
72      - This only applies to new partitions.
73      - This does not relate to the partitions file system formatting.
74    type: str
75    choices: [ system_partition, microsoft_reserved, basic_data, microsoft_recovery ]
76
77notes:
78  - A minimum Operating System Version of 6.2 is required to use this module. To check if your OS is compatible, see
79    U(https://docs.microsoft.com/en-us/windows/desktop/sysinfo/operating-system-version).
80  - This module cannot be used for removing the drive letter associated with a partition, initializing a disk or, file system formatting.
81  - Idempotence works only if you're specifying a drive letter or other unique attributes such as a combination of disk number and partition number.
82  - For more information, see U(https://msdn.microsoft.com/en-us/library/windows/desktop/hh830524.aspx).
83author:
84  - Varun Chopra (@chopraaa) <v@chopraaa.com>
85'''
86
87EXAMPLES = r'''
88- name: Create a partition with drive letter D and size 5 GiB
89  community.windows.win_partition:
90    drive_letter: D
91    partition_size: 5 GiB
92    disk_number: 1
93
94- name: Resize previously created partition to it's maximum size and change it's drive letter to E
95  community.windows.win_partition:
96    drive_letter: E
97    partition_size: -1
98    partition_number: 1
99    disk_number: 1
100
101- name: Delete partition
102  community.windows.win_partition:
103    disk_number: 1
104    partition_number: 1
105    state: absent
106'''
107
108RETURN = r'''
109#
110'''
111