mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-08 06:12:51 +00:00
Added win_find module (#19144)
This commit is contained in:
Jordan Borean
committed by
John R Barker
John R Barker
parent
57a5490c41
commit
1ce5fcf061
347
lib/ansible/modules/windows/win_find.ps1
Normal file
347
lib/ansible/modules/windows/win_find.ps1
Normal file
@@ -0,0 +1,347 @@
|
||||
#!powershell
|
||||
# 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/>.
|
||||
|
||||
# WANT_JSON
|
||||
# POWERSHELL_COMMON
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
$params = Parse-Args -arguments $args -supports_check_mode $true
|
||||
|
||||
$paths = Get-AnsibleParam -obj $params -name 'paths' -failifempty $true
|
||||
|
||||
$age = Get-AnsibleParam -obj $params -name 'age' -failifempty $false -default $null
|
||||
$age_stamp = Get-AnsibleParam -obj $params -name 'age_stamp' -failifempty $false -default 'mtime' -ValidateSet 'mtime','ctime','atime'
|
||||
$file_type = Get-AnsibleParam -obj $params -name 'file_type' -failifempty $false -default 'file' -ValidateSet 'file','directory'
|
||||
$follow = Get-AnsibleParam -obj $params -name 'follow' -type "bool" -failifempty $false -default $false
|
||||
$hidden = Get-AnsibleParam -obj $params -name 'hidden' -type "bool" -failifempty $false -default $false
|
||||
$patterns = Get-AnsibleParam -obj $params -name 'patterns' -failifempty $false -default $null
|
||||
$recurse = Get-AnsibleParam -obj $params -name 'recurse' -type "bool" -failifempty $false -default $false
|
||||
$size = Get-AnsibleParam -obj $params -name 'size' -failifempty $false -default $null
|
||||
$use_regex = Get-AnsibleParam -obj $params -name 'use_regex' -type "bool" -failifempty $false -default $false
|
||||
$get_checksum = Get-AnsibleParam -obj $params -name 'get_checksum' -type "bool" -failifempty $false -default $true
|
||||
$checksum_algorithm = Get-AnsibleParam -obj $params -name 'checksum_algorithm' -failifempty $false -default 'sha1' -ValidateSet 'md5', 'sha1', 'sha256', 'sha384', 'sha512'
|
||||
|
||||
$result = @{
|
||||
files = @()
|
||||
warnings = @()
|
||||
examined = 0
|
||||
matched = 0
|
||||
changed = $false
|
||||
}
|
||||
|
||||
# C# code to determine link target, copied from http://chrisbensen.blogspot.com.au/2010/06/getfinalpathnamebyhandle.html
|
||||
$symlink_util = @"
|
||||
using System;
|
||||
using System.Text;
|
||||
using Microsoft.Win32.SafeHandles;
|
||||
using System.ComponentModel;
|
||||
using System.Runtime.InteropServices;
|
||||
|
||||
namespace Ansible.Command {
|
||||
public class SymLinkHelper {
|
||||
private const int FILE_SHARE_WRITE = 2;
|
||||
private const int CREATION_DISPOSITION_OPEN_EXISTING = 3;
|
||||
private const int FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
|
||||
|
||||
[DllImport("kernel32.dll", EntryPoint = "GetFinalPathNameByHandleW", CharSet = CharSet.Unicode, SetLastError = true)]
|
||||
public static extern int GetFinalPathNameByHandle(IntPtr handle, [In, Out] StringBuilder path, int bufLen, int flags);
|
||||
|
||||
[DllImport("kernel32.dll", EntryPoint = "CreateFileW", CharSet = CharSet.Unicode, SetLastError = true)]
|
||||
public static extern SafeFileHandle CreateFile(string lpFileName, int dwDesiredAccess,
|
||||
int dwShareMode, IntPtr SecurityAttributes, int dwCreationDisposition, int dwFlagsAndAttributes, IntPtr hTemplateFile);
|
||||
|
||||
public static string GetSymbolicLinkTarget(System.IO.DirectoryInfo symlink) {
|
||||
SafeFileHandle directoryHandle = CreateFile(symlink.FullName, 0, 2, System.IntPtr.Zero, CREATION_DISPOSITION_OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, System.IntPtr.Zero);
|
||||
if(directoryHandle.IsInvalid)
|
||||
throw new Win32Exception(Marshal.GetLastWin32Error());
|
||||
|
||||
StringBuilder path = new StringBuilder(512);
|
||||
int size = GetFinalPathNameByHandle(directoryHandle.DangerousGetHandle(), path, path.Capacity, 0);
|
||||
|
||||
if (size<0)
|
||||
throw new Win32Exception(Marshal.GetLastWin32Error()); // The remarks section of GetFinalPathNameByHandle mentions the return being prefixed with "\\?\" // More information about "\\?\" here -> http://msdn.microsoft.com/en-us/library/aa365247(v=VS.85).aspx
|
||||
if (path[0] == '\\' && path[1] == '\\' && path[2] == '?' && path[3] == '\\')
|
||||
return path.ToString().Substring(4);
|
||||
else
|
||||
return path.ToString();
|
||||
}
|
||||
}
|
||||
}
|
||||
"@
|
||||
Add-Type -TypeDefinition $symlink_util
|
||||
|
||||
Function Assert-Age($info) {
|
||||
$valid_match = $true
|
||||
|
||||
if ($age -ne $null) {
|
||||
$seconds_per_unit = @{'s'=1; 'm'=60; 'h'=3600; 'd'=86400; 'w'=604800}
|
||||
$seconds_pattern = '^(-?\d+)(s|m|h|d|w)?$'
|
||||
$match = $age -match $seconds_pattern
|
||||
if ($match) {
|
||||
[int]$specified_seconds = $matches[1]
|
||||
if ($matches[2] -eq $null) {
|
||||
$chosen_unit = 's'
|
||||
} else {
|
||||
$chosen_unit = $matches[2]
|
||||
}
|
||||
|
||||
$abs_seconds = $specified_seconds * ($seconds_per_unit.$chosen_unit)
|
||||
$epoch = New-Object -Type DateTime -ArgumentList 1970, 1, 1, 0, 0, 0, 0
|
||||
if ($age_stamp -eq 'mtime') {
|
||||
$age_comparison = $epoch.AddSeconds($info.lastwritetime)
|
||||
} elseif ($age_stamp -eq 'ctime') {
|
||||
$age_comparison = $epoch.AddSeconds($info.creationtime)
|
||||
} elseif ($age_stamp -eq 'atime') {
|
||||
$age_comparison = $epoch.AddSeconds($info.lastaccesstime)
|
||||
}
|
||||
|
||||
if ($specified_seconds -ge 0) {
|
||||
$start_date = (Get-Date).AddSeconds($abs_seconds * -1)
|
||||
if ($age_comparison -lt $start_date) {
|
||||
$valid_match = $false
|
||||
}
|
||||
} else {
|
||||
$start_date = (Get-Date).AddSeconds($abs_seconds)
|
||||
if ($age_comparison -gt $start_date) {
|
||||
$valid_match = $false
|
||||
}
|
||||
}
|
||||
} else {
|
||||
Fail-Json $result "failed to process age"
|
||||
}
|
||||
}
|
||||
|
||||
$valid_match
|
||||
}
|
||||
|
||||
Function Assert-FileType($info) {
|
||||
$valid_match = $true
|
||||
|
||||
if ($file_type -eq 'directory' -and $info.isdir -eq $false) {
|
||||
$valid_match = $false
|
||||
}
|
||||
if ($file_type -eq 'file' -and $info.isdir -eq $true) {
|
||||
$valid_match = $false
|
||||
}
|
||||
|
||||
$valid_match
|
||||
}
|
||||
|
||||
Function Assert-Hidden($info) {
|
||||
$valid_match = $true
|
||||
|
||||
if ($hidden -eq $true -and $info.ishidden -eq $false) {
|
||||
$valid_match = $false
|
||||
}
|
||||
if ($hidden -eq $false -and $info.ishidden -eq $true) {
|
||||
$valid_match = $false
|
||||
}
|
||||
|
||||
$valid_match
|
||||
}
|
||||
|
||||
Function Assert-Pattern($info) {
|
||||
$valid_match = $false
|
||||
|
||||
if ($patterns -ne $null) {
|
||||
foreach ($pattern in $patterns) {
|
||||
if ($use_regex -eq $true) {
|
||||
# Use -match for regex matching
|
||||
if ($info.filename -match $pattern) {
|
||||
$valid_match = $true
|
||||
}
|
||||
} else {
|
||||
# Use -like for wildcard matching
|
||||
if ($info.filename -like $pattern) {
|
||||
$valid_match = $true
|
||||
}
|
||||
}
|
||||
}
|
||||
} else {
|
||||
$valid_match = $true
|
||||
}
|
||||
|
||||
$valid_match
|
||||
}
|
||||
|
||||
Function Assert-Size($info) {
|
||||
$valid_match = $true
|
||||
|
||||
if ($size -ne $null) {
|
||||
$bytes_per_unit = @{'b'=1; 'k'=1024; 'm'=1024*1024; 'g'=1024*1024*1024; 't'=1024*1024*1024*1024}
|
||||
$size_pattern = '^(-?\d+)(b|k|m|g|t)?$'
|
||||
$match = $size -match $size_pattern
|
||||
if ($match) {
|
||||
[int]$specified_size = $matches[1]
|
||||
if ($matches[2] -eq $null) {
|
||||
$chosen_byte = 'b'
|
||||
} else {
|
||||
$chosen_byte = $matches[2]
|
||||
}
|
||||
|
||||
$abs_size = $specified_size * ($bytes_per_unit.$chosen_byte)
|
||||
if ($specified_size -ge 0) {
|
||||
if ($info.size -lt $abs_size) {
|
||||
$valid_match = $false
|
||||
}
|
||||
} else {
|
||||
if ($info.size -gt $abs_size * -1) {
|
||||
$valid_match = $false
|
||||
}
|
||||
}
|
||||
} else {
|
||||
Fail-Json $result "failed to process size"
|
||||
}
|
||||
}
|
||||
|
||||
$valid_match
|
||||
}
|
||||
|
||||
Function Assert-FileStat($info) {
|
||||
$age_match = Assert-Age -info $info
|
||||
$file_type_match = Assert-FileType -info $info
|
||||
$hidden_match = Assert-Hidden -info $info
|
||||
$pattern_match = Assert-Pattern -info $info
|
||||
$size_match = Assert-Size -info $info
|
||||
|
||||
if ($age_match -and $file_type_match -and $hidden_match -and $pattern_match -and $size_match) {
|
||||
$info
|
||||
} else {
|
||||
$false
|
||||
}
|
||||
}
|
||||
|
||||
Function Get-FileStat($file) {
|
||||
$epoch = New-Object -Type DateTime -ArgumentList 1970, 1, 1, 0, 0, 0, 0
|
||||
$access_control = $file.GetAccessControl()
|
||||
$attributes = @()
|
||||
foreach ($attribute in ($file.Attributes -split ',')) {
|
||||
$attributes += $attribute.Trim()
|
||||
}
|
||||
|
||||
$file_stat = @{
|
||||
isreadonly = $attributes -contains 'ReadOnly'
|
||||
ishidden = $attributes -contains 'Hidden'
|
||||
isarchive = $attributes -contains 'Archive'
|
||||
attributes = $file.Attributes.ToString()
|
||||
owner = $access_control.Owner
|
||||
lastwritetime = (New-TimeSpan -Start $epoch -End $file.LastWriteTime).TotalSeconds
|
||||
creationtime = (New-TimeSpan -Start $epoch -End $file.CreationTime).TotalSeconds
|
||||
lastaccesstime = (New-TimeSpan -Start $epoch -End $file.LastAccessTime).TotalSeconds
|
||||
path = $file.FullName
|
||||
filename = $file.Name
|
||||
}
|
||||
|
||||
$islink = $false
|
||||
$isdir = $false
|
||||
$isshared = $false
|
||||
|
||||
if ($attributes -contains 'ReparsePoint') {
|
||||
# TODO: Find a way to differenciate between soft and junction links
|
||||
$islink = $true
|
||||
$isdir = $true
|
||||
|
||||
# Try and get the symlink source, can result in failure if link is broken
|
||||
try {
|
||||
$lnk_source = [Ansible.Command.SymLinkHelper]::GetSymbolicLinkTarget($file)
|
||||
$file_stat.lnk_source = $lnk_source
|
||||
} catch {}
|
||||
} elseif ($file.PSIsContainer) {
|
||||
$isdir = $true
|
||||
|
||||
$share_info = Get-WmiObject -Class Win32_Share -Filter "Path='$($file.Fullname -replace '\\', '\\')'"
|
||||
if ($share_info -ne $null) {
|
||||
$isshared = $true
|
||||
$file_stat.sharename = $share_info.Name
|
||||
}
|
||||
|
||||
#$dir_files_sum = Get-ChildItem $file.FullName -Recurse | Measure-Object -property length -sum
|
||||
$dir_files_sum = Get-ChildItem $file.FullName -Recurse
|
||||
|
||||
if ($dir_files_sum -eq $null -or ($dir_files_sum.PSObject.Properties.name -contains 'length' -eq $false)) {
|
||||
$file_stat.size = 0
|
||||
} else {
|
||||
$file_stat.size = ($dir_files_sum | Measure-Object -property length -sum).Sum
|
||||
}
|
||||
} else {
|
||||
$file_stat.size = $file.length
|
||||
$file_stat.extension = $file.Extension
|
||||
|
||||
if ($get_checksum) {
|
||||
$checksum = Get-FileChecksum -path $path -algorithm $checksum_algorithm
|
||||
$file_stat.checksum = $checksum
|
||||
}
|
||||
}
|
||||
|
||||
$file_stat.islink = $islink
|
||||
$file_stat.isdir = $isdir
|
||||
$file_stat.isshared = $isshared
|
||||
|
||||
Assert-FileStat -info $file_stat
|
||||
}
|
||||
|
||||
Function Get-FilesInFolder($path) {
|
||||
$items = @()
|
||||
foreach ($item in (Get-ChildItem -Force -Path $path -ErrorAction SilentlyContinue)) {
|
||||
if ($item.PSIsContainer -and $recurse) {
|
||||
if (($item.Attributes -like '*ReparsePoint*' -and $follow) -or ($item.Attributes -notlike '*ReparsePoint*')) {
|
||||
# File is a link and we want to follow a link OR file is not a link
|
||||
$items += $item.FullName
|
||||
$items += Get-FilesInFolder -path $item.FullName
|
||||
} else {
|
||||
# File is a link but we don't want to follow a link
|
||||
$items += $item.FullName
|
||||
}
|
||||
} else {
|
||||
$items += $item.FullName
|
||||
}
|
||||
}
|
||||
|
||||
$items
|
||||
}
|
||||
|
||||
$paths_to_check = @()
|
||||
foreach ($path in $paths) {
|
||||
if (Test-Path $path) {
|
||||
if ((Get-Item -Force $path).PSIsContainer) {
|
||||
$paths_to_check += Get-FilesInFolder -path $path
|
||||
} else {
|
||||
Fail-Json $result "Argument path $path is a file not a directory"
|
||||
}
|
||||
} else {
|
||||
Fail-Json $result "Argument path $path does not exist cannot get information on"
|
||||
}
|
||||
}
|
||||
$paths_to_check = $paths_to_check | Select -Unique
|
||||
|
||||
foreach ($path in $paths_to_check) {
|
||||
$file = Get-Item -Force -Path $path
|
||||
$info = Get-FileStat -file $file
|
||||
$new_examined = $result.examined + 1
|
||||
$result.examined = $new_examined
|
||||
|
||||
if ($info -ne $false) {
|
||||
$files = $result.Files
|
||||
$files += $info
|
||||
|
||||
$new_matched = $result.matched + 1
|
||||
$result.matched = $new_matched
|
||||
$result.files = $files
|
||||
}
|
||||
}
|
||||
|
||||
Exit-Json $result
|
||||
323
lib/ansible/modules/windows/win_find.py
Normal file
323
lib/ansible/modules/windows/win_find.py
Normal file
@@ -0,0 +1,323 @@
|
||||
#!/usr/bin/python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# (c) 2016, Ansible, inc
|
||||
#
|
||||
# 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/>.
|
||||
#
|
||||
|
||||
ANSIBLE_METADATA = {'status': ['preview'],
|
||||
'supported_by': 'community',
|
||||
'version': '1.0'}
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
module: win_find
|
||||
version_added: "2.3"
|
||||
short_description: return a list of files based on specific criteria
|
||||
description:
|
||||
- Return a list of files based on specified criteria.
|
||||
- Multiple criteria are AND'd together.
|
||||
options:
|
||||
age:
|
||||
description:
|
||||
- Select files or folders whose age is equal to or greater than
|
||||
the specified tim. Use a negative age to find files equal to or
|
||||
less than the specified time. You can choose seconds, minues,
|
||||
hours, days or weeks by specifying the first letter of an of
|
||||
those words (e.g., "1w").
|
||||
required: false
|
||||
age_stamp:
|
||||
description:
|
||||
- Choose the file property against which we compare C(age). The
|
||||
default attribute we compare with is last modification time.
|
||||
required: false
|
||||
default: mtime
|
||||
choices: ['atime', 'mtime', 'ctime']
|
||||
checksum_algorithm:
|
||||
description:
|
||||
- Algorithm to determine the checksum of a file. Will throw an error
|
||||
if the host is unable to use specified algorithm.
|
||||
required: false
|
||||
default: sha1
|
||||
choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512']
|
||||
file_type:
|
||||
description: Type of file to search for
|
||||
required: false
|
||||
default: file
|
||||
choices: ['file', 'directory']
|
||||
follow:
|
||||
description:
|
||||
- Set this to true to follow symlinks in the path. This needs to
|
||||
be used in conjunction with C(recurse).
|
||||
required: false
|
||||
default: false
|
||||
choices: ['true', 'false']
|
||||
get_checksum:
|
||||
description:
|
||||
- Whether to return a checksum of the file in the return info (default sha1),
|
||||
use C(checksum_algorithm) to change from the default.
|
||||
required: false
|
||||
default: true
|
||||
choices: ['true', 'false']
|
||||
hidden:
|
||||
description: Set this to include hidden files or folders
|
||||
required: false
|
||||
default: false
|
||||
choices: ['true', 'false']
|
||||
paths:
|
||||
description:
|
||||
- List of paths of directories to search for files or folders in.
|
||||
This can be supplied as a single path or a list of paths.
|
||||
required: true
|
||||
patterns:
|
||||
description:
|
||||
- One or more (powershell or regex) patterns to compare filenames
|
||||
with. The type of pattern matching is controlled by C(use_regex)
|
||||
option. The patterns retrict the list of files or folders to be
|
||||
returned based on the filenames. For a file to be matched it
|
||||
only has to match with one pattern in a list provided.
|
||||
required: false
|
||||
recurse:
|
||||
description:
|
||||
- Will recursively descend into the directory looking for files
|
||||
or folders
|
||||
required: false
|
||||
default: false
|
||||
choices: ['true', 'false']
|
||||
size:
|
||||
description:
|
||||
- Select files or folders whose size is equal to or greater than
|
||||
the specified size. Use a negative value to find files equal to
|
||||
or less than the specified size. You can specify the size with
|
||||
a suffix of the byte type i.e. kilo = k, mega = m... Size is not
|
||||
evaluated for symbolic links.
|
||||
required: false
|
||||
default: false
|
||||
use_regex:
|
||||
description:
|
||||
- Will set patterns to run as a regex check if true
|
||||
required: false
|
||||
default: false
|
||||
choices: ['true', 'false']
|
||||
author: "Jordan Borean (@jborean93)"
|
||||
'''
|
||||
|
||||
EXAMPLES = r'''
|
||||
# Find files in path
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
|
||||
# Find hidden files in path
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
hidden: True
|
||||
|
||||
# Find files in multiple paths
|
||||
- win_find:
|
||||
paths: ['C:\temp', 'D:\temp']
|
||||
|
||||
# Find files in directory while searching recursively
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
recurse: True
|
||||
|
||||
# Find files in directory while following symlinks
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
recurse: True
|
||||
follow: True
|
||||
|
||||
# Find files with .log and .out extension using powershell wildcards
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
patterns: ['*.log', '*.out']
|
||||
|
||||
# Find files in path based on regex pattern
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
patterns: "out_\d{8}-\d{6}.log"
|
||||
|
||||
# Find files older than 1 day
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
age: 86400
|
||||
|
||||
# Find files older than 1 day based on create time
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
age: 86400
|
||||
age_stamp: ctime
|
||||
|
||||
# Find files older than 1 day with unit syntax
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
age: 1d
|
||||
|
||||
# Find files newer than 1 hour
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
age: -3600
|
||||
|
||||
# Find files newer than 1 hour with unit syntax
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
age: -1h
|
||||
|
||||
# Find files larger than 1MB
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
size: 1048576
|
||||
|
||||
# Find files larger than 1GB with unit syntax
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
size: 1g
|
||||
|
||||
# Find files smaller than 1MB
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
size: -1048576
|
||||
|
||||
# Find files smaller than 1GB with unit syntax
|
||||
- win_find:
|
||||
paths: D:\temp
|
||||
size: -1g
|
||||
|
||||
# Find folders/symlinks in multiple paths
|
||||
- win_find:
|
||||
paths: ['C:\temp', 'D:\temp']
|
||||
file_type: directory
|
||||
|
||||
# Find files and return SHA256 checksum of files found
|
||||
- win_find:
|
||||
paths: C:\temp
|
||||
get_checksum: True
|
||||
checksum_algorithm: sha256
|
||||
|
||||
# Find files and do not return the checksum
|
||||
- win_find:
|
||||
path: C:\temp
|
||||
get_checksum: False
|
||||
'''
|
||||
|
||||
RETURN = r'''
|
||||
changed:
|
||||
description: Whether anything was chagned
|
||||
returned: always
|
||||
type: boolean
|
||||
sample: True
|
||||
examined:
|
||||
description: The number of files/folders that was checked
|
||||
returned: always
|
||||
type: int
|
||||
sample: 10
|
||||
matched:
|
||||
description: The number of files/folders that match the criteria
|
||||
returns: always
|
||||
type: int
|
||||
sample: 2
|
||||
files:
|
||||
description: Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched
|
||||
returned: success
|
||||
type: dictionary
|
||||
contains:
|
||||
attributes:
|
||||
description: attributes of the file at path in raw form
|
||||
returned: success, path exists
|
||||
type: string
|
||||
sample: "Archive, Hidden"
|
||||
checksum:
|
||||
description: The checksum of a file based on checksum_algorithm specified
|
||||
returned: success, path exists, path is a file, get_checksum == True
|
||||
type: string
|
||||
sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98
|
||||
creationtime:
|
||||
description: the create time of the file represented in seconds since epoch
|
||||
returned: success, path exists
|
||||
type: float
|
||||
sample: 1477984205.15
|
||||
extension:
|
||||
description: the extension of the file at path
|
||||
returned: success, path exists, path is a file
|
||||
type: string
|
||||
sample: ".ps1"
|
||||
isarchive:
|
||||
description: if the path is ready for archiving or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
isdir:
|
||||
description: if the path is a directory or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
ishidden:
|
||||
description: if the path is hidden or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
islink:
|
||||
description: if the path is a symbolic link or junction or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
isreadonly:
|
||||
description: if the path is read only or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
isshared:
|
||||
description: if the path is shared or not
|
||||
returned: success, path exists
|
||||
type: boolean
|
||||
sample: True
|
||||
lastaccesstime:
|
||||
description: the last access time of the file represented in seconds since epoch
|
||||
returned: success, path exists
|
||||
type: float
|
||||
sample: 1477984205.15
|
||||
lastwritetime:
|
||||
description: the last modification time of the file represented in seconds since epoch
|
||||
returned: success, path exists
|
||||
type: float
|
||||
sample: 1477984205.15
|
||||
lnk_source:
|
||||
description: the target of the symbolic link, will return null if not a link or the link is broken
|
||||
return: success, path exists, path is a symbolic link
|
||||
type: string
|
||||
sample: C:\temp
|
||||
owner:
|
||||
description: the owner of the file
|
||||
returned: success, path exists
|
||||
type: string
|
||||
sample: BUILTIN\Administrators
|
||||
path:
|
||||
description: the full absolute path to the file
|
||||
returned: success, path exists
|
||||
type: string
|
||||
sample: BUILTIN\Administrators
|
||||
sharename:
|
||||
description: the name of share if folder is shared
|
||||
returned: success, path exists, path is a directory and isshared == True
|
||||
type: string
|
||||
sample: file-share
|
||||
size:
|
||||
description: the size in bytes of a file or folder
|
||||
returned: success, path exists, path is not a link
|
||||
type: int
|
||||
sample: 1024
|
||||
'''
|
||||
Reference in New Issue
Block a user