The IFTPItem interface is a representation of a folder/file. More...

import "sfFTPLib.idl";

Public Member Functions
HRESULT	IsValidAttribute ([in] FTPItemAttribute attribute, [out, retval] VARIANT_BOOL *retval)
	Checks if a specific attribute is available for this item.

Properties
BSTR	Name `[get, set]`
	Sets or retrieves the name of the item.
ItemType	Type `[get, set]`
	Sets or retrieves the type of the item.
BSTR	Owner `[get, set]`
	Sets or retrieves the owner of the item.
BSTR	Group `[get, set]`
	Sets or retrieves the group of the item.
ULONGLONG	Size `[get, set]`
	Sets or retrieves the size of the item in bytes.
long	SizeLo `[get]`
	Retrieves the lower 32 bits of the file size.
long	SizeHi `[get]`
	Retrieves the upper 32 bits of the file size.
FILETIME	ModifyTime `[get, set]`
	Sets or retrieves the item's last modification time (FILETIME format).
VARIANT	ModifyTimeAsDate `[get, set]`
FILETIME	AccessTime `[get, set]`
	Sets or retrieves the item's last access time (FILETIME format).
FILETIME	CreateTime `[get, set]`
	Sets or retrieves the item's creation time (FILETIME format).
FILETIME	CTime `[get, set]`
	Sets or retrieves the item's metadata change time (Unix ctime).
VARIANT	CreateTimeAsDate `[get, set]`
VARIANT	AccessTimeAsDate `[get, set]`
VARIANT	CTimeAsDate `[get, set]`
long	AttributeBits `[get, set]`
	Sets or retrieves the file attribute flags.
long	ValidAttributeBits `[get, set]`
	Sets or retrieves the mask of valid file attributes.
long	UnixFilePermissions `[get, set]`
	Sets or retrieves the Unix file permissions.
ULONGLONG	AllocationSize `[get, set]`
	Sets or retrieves the number of bytes allocated for the item on the disk.
BSTR	MimeType `[get, set]`
BSTR	LinkPoint `[get, set]`
	Sets or retrieves the target path of a symbolic link.
BSTR	Unique `[get, set]`
VARIANT_BOOL	UTC `[get, set]`
	Indicates whether the item's timestamps are in Coordinated Universal Time (UTC).
long	TimePrecision `[get, set]`

Detailed Description

The IFTPItem interface is a representation of a folder/file.

Member Function Documentation

◆ IsValidAttribute()

HRESULT IFTPItem::IsValidAttribute	(	[in] FTPItemAttribute	attribute,
		[out, retval] VARIANT_BOOL *	retval )

Checks if a specific attribute is available for this item.

This method determines if the IFTPItem object contains valid data for the specified FTPItemAttribute.

Parameters

[in]	attribute	The FTPItemAttribute to validate.
[out]	retval	Pointer to a VARIANT_BOOL that receives the result: VARIANT_TRUE: The attribute contains valid data for this item. VARIANT_FALSE: The attribute is not set or is unavailable.

Property Documentation

◆ AccessTime

FILETIME IFTPItem::AccessTime

getsetproperty

Sets or retrieves the item's last access time (FILETIME format).

This property stores the timestamp of when the item was last accessed, utilizing the low-level Windows FILETIME structure.

Set (Put): Updates the access timestamp using a raw FILETIME struct.
Get: Retrieves the current access timestamp.

Note: Scripting Compatibility: Languages such as VBScript, JavaScript, and PowerShell may not support raw structures. For these environments, use the AccessTimeAsDate property instead.

Parameters

[in]	newValue	The FILETIME structure containing the new access time.
[out]	retval	Pointer to a FILETIME structure that receives the current access time.

◆ AccessTimeAsDate

VARIANT IFTPItem::AccessTimeAsDate

getsetproperty

◆ AllocationSize

ULONGLONG IFTPItem::AllocationSize

getsetproperty

Sets or retrieves the number of bytes allocated for the item on the disk.

This property represents the physical space consumed by the file, which is often larger than the logical Size due to file system block alignment (cluster size) or pre-allocation.

Distinction:

Size : The actual number of bytes of data in the file (Logical Size).
AllocationSize: The amount of disk space reserved for the file (Physical Size).

Protocol Reference: This corresponds to the allocation-size field defined in Section 7.4 of the IETF SSH File Transfer Protocol (SFTP) draft.

Note: Scripting & Legacy Compatibility: Environments such as VBScript, VB6, and Classic ASP do not natively support the ULONGLONG (64-bit unsigned) data type.

Parameters

[in]	newValue	The number of allocated bytes.
[out]	retval	Pointer to a ULONGLONG that receives the current allocation size.

◆ AttributeBits

long IFTPItem::AttributeBits

getsetproperty

Sets or retrieves the file attribute flags.

This property contains a bitmask representing the file's attributes (e.g., Read-Only, Hidden, System, Archive).

Protocol Reference: These bits correspond to the attrib-bits field defined in Section 7.9 of the IETF SSH File Transfer Protocol (SFTP) draft.

Relationship with ValidAttributeBits: Before relying on a specific flag in this property, you must check the corresponding bit in ValidAttributeBits to ensure the server actually provided a value for that attribute.

Parameters

[in]	newValue	The integer bitmask containing the new attributes.
[out]	retval	Pointer to a long that receives the current attribute bitmask.

◆ CreateTime

FILETIME IFTPItem::CreateTime

getsetproperty

Sets or retrieves the item's creation time (FILETIME format).

This property stores the timestamp of when the item was created, utilizing the low-level Windows FILETIME structure.

Set (Put): Updates the creation timestamp using a raw FILETIME struct.
Get: Retrieves the current creation timestamp.

Note: Scripting Compatibility: Languages such as VBScript, JavaScript, and PowerShell may not support raw structures. For these environments, use the CreateTimeAsDate property instead.

Parameters

[in]	newValue	The FILETIME structure containing the new creation time.
[out]	retval	Pointer to a FILETIME structure that receives the current creation time.

◆ CreateTimeAsDate

VARIANT IFTPItem::CreateTimeAsDate

getsetproperty

◆ CTime

FILETIME IFTPItem::CTime

getsetproperty

Sets or retrieves the item's metadata change time (Unix ctime).

This property stores the timestamp of when the item's attributes or metadata (e.g., permissions, owner, group) were last changed.

Distinction from other timestamps:

ModifyTime : Updates when the file's content is modified.
CreateTime : Updates when the file is created (born).
CTime: Updates when file properties change (common on Unix/Linux filesystems).
Set (Put): Updates the status change timestamp using a raw FILETIME struct.
Get: Retrieves the current status change timestamp.

Note: Scripting Compatibility: Languages such as VBScript, JavaScript, and PowerShell may not support raw structures. For these environments, use the CreateTimeAsDate property instead.

Parameters

[in]	newValue	The FILETIME structure containing the new metadata change time.
[out]	retval	Pointer to a FILETIME structure that receives the current metadata change time.

◆ CTimeAsDate

VARIANT IFTPItem::CTimeAsDate

getsetproperty

◆ Group

BSTR IFTPItem::Group

getsetproperty

Sets or retrieves the group of the item.

◆ LinkPoint

BSTR IFTPItem::LinkPoint

getsetproperty

Sets or retrieves the target path of a symbolic link.

This property contains the destination string that the symbolic link points to (i.e., the "real" file or directory).

Prerequisite: This property is valid only if the item's Type is set to ftpItemTypeSymbolicLink.

Value Content: The string typically contains:

An absolute path (e.g., /var/www/html).
A relative path (e.g., ../logs/access.log).

Parameters

[in]	newValue	The target path string (where the link should redirect).
[out]	retval	Pointer to a BSTR that receives the target path.

◆ MimeType

BSTR IFTPItem::MimeType

getsetproperty

◆ ModifyTime

FILETIME IFTPItem::ModifyTime

getsetproperty

Sets or retrieves the item's last modification time (FILETIME format).

This property stores the timestamp of when the item was last modified, utilizing the low-level Windows FILETIME structure.

Set (Put): Updates the modification timestamp using a raw FILETIME struct.
Get: Retrieves the current modification timestamp.

Note: Scripting Compatibility: Languages such as VBScript, JavaScript, and PowerShell may not support raw structures. For these environments, use the ModifyTimeAsDate property instead.

Parameters

[in]	newValue	The FILETIME structure containing the new modification time.
[out]	retval	Pointer to a FILETIME structure that receives the current modification time.

◆ ModifyTimeAsDate

VARIANT IFTPItem::ModifyTimeAsDate

getsetproperty

◆ Name

BSTR IFTPItem::Name

getsetproperty

Sets or retrieves the name of the item.

◆ Owner

BSTR IFTPItem::Owner

getsetproperty

Sets or retrieves the owner of the item.

◆ Size

ULONGLONG IFTPItem::Size

getsetproperty

Sets or retrieves the size of the item in bytes.

This property represents the file size as a 64-bit unsigned integer (ULONGLONG), allowing for the representation of files larger than 4GB.

Set (Put): Updates the file size (typically used when creating or mocking items).
Get: Retrieves the file size.

Note: Scripting & Legacy Compatibility: Environments such as VBScript, VB6, Classic ASP, and older JavaScript engines do not natively support the ULONGLONG (64-bit unsigned) data type.

Workaround: For these environments, use the split 32-bit properties:

SizeLo (Low 32 bits)
SizeHi (High 32 bits)

Parameters

[in]	newValue	The size of the item in bytes.
[out]	retval	Pointer to a ULONGLONG that receives the current size.

◆ SizeHi

long IFTPItem::SizeHi

getproperty

Retrieves the upper 32 bits of the file size.

This property provides the most significant 32 bits of the 64-bit file size.

For files smaller than 4GB, this value will be 0.
For files larger than 4GB, combine this with SizeLo to determine the total size.

See also: SizeLo for the reconstruction formula.

Parameters

[out] retval Pointer to a long that receives the upper 32 bits of the size.

◆ SizeLo

long IFTPItem::SizeLo

getproperty

Retrieves the lower 32 bits of the file size.

This property provides the least significant 32 bits of the 64-bit file size. It is intended for use in languages that do not support the Size property (ULONGLONG) directly.

Reconstructing the Full Size: To calculate the total file size in environments restricted to 32-bit integers:

TotalSize = (SizeHi * 4294967296) + SizeLo

IFTPItem::SizeHi

long SizeHi

Retrieves the upper 32 bits of the file size.

IFTPItem::SizeLo

long SizeLo

Retrieves the lower 32 bits of the file size.

Note

Important regarding Signed Integers: Since long is a signed type, large values (bit 31 set) may appear negative in languages like VB6 or VBScript. You must treat SizeLo as unsigned:

If SizeLo < 0, add 4294967296 (2^32) to correct the value.

Parameters

[out] retval Pointer to a long that receives the lower 32 bits of the size.

◆ TimePrecision

long IFTPItem::TimePrecision

getsetproperty

◆ Type

ItemType IFTPItem::Type

getsetproperty

Sets or retrieves the type of the item.

◆ Unique

BSTR IFTPItem::Unique

getsetproperty

◆ UnixFilePermissions

long IFTPItem::UnixFilePermissions

getsetproperty

Sets or retrieves the Unix file permissions.

This property controls the standard Unix/Linux access rights (Read, Write, Execute) for the file's Owner, Group, and Others.

Understanding the Value: The value is an integer typically represented in Octal (base-8) format (e.g., 0755 or 0644).

Set (Put): Updates the permission value stored in this object.
Get: Retrieves the current permission mask.

Common Values:

0777 (rwxrwxrwx): Full access for everyone.
0755 (rwxr-xr-x): Owner has full access; Group/Others can read and execute.
0644 (rw-r–r–): Owner can read/write; Group/Others can read only.

Note: Platform Support: This property is primarily effective on Unix/Linux-based servers (SFTP/FTP). Windows servers may ignore these values or map them imperfectly to ACLs.

Parameters

[in]	newValue	The integer representation of the permission mask (e.g., pass 493 for 0755).
[out]	retval	Pointer to a long that receives the current permission mask.

◆ UTC

VARIANT_BOOL IFTPItem::UTC

getsetproperty

Indicates whether the item's timestamps are in Coordinated Universal Time (UTC).

This property serves as a flag to determine the time zone context for the CreateTime, ModifyTime, and AccessTime properties.

TRUE: All time-related properties on this item are stored as UTC
FALSE: All time-related properties are stored in Local Time (relative to the server's time zone).

Parameters

[in]	newValue	The boolean flag to set.
[out]	retval	Pointer to a VARIANT_BOOL that receives the current state.

◆ ValidAttributeBits

long IFTPItem::ValidAttributeBits

getsetproperty

Sets or retrieves the mask of valid file attributes.

This property acts as a bitmask indicating which bits in the AttributeBits property (such as Read-Only, Hidden, System, Archive) are considered valid and accurate for this item.

This corresponds directly to the attrib-bits-valid field in the SSH File Transfer Protocol (SFTP).

Set (Put): Updates the mask of valid attributes (used when manually constructing file entries).
Get: Retrieves the current validity mask.

Usage: Before reading a flag from AttributeBits, check the corresponding bit in this property. If the bit in ValidAttributeBits is 0, the value in AttributeBits for that flag is undefined or unknown.

Protocol Reference: For detailed bit definitions, refer to Section 7.9 "attrib-bits and attrib-bits-valid" of the IETF SSH File Transfer Protocol (SFTP) draft.

Parameters

[in]	newValue	The bitmask representing the valid attributes.
[out]	retval	Pointer to a long that receives the current validity mask.

The documentation for this interface was generated from the following file:

sfFTPLib.idl

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ IsValidAttribute()

Property Documentation

◆ AccessTime

◆ AccessTimeAsDate

◆ AllocationSize

◆ AttributeBits

◆ CreateTime

◆ CreateTimeAsDate

◆ CTime

◆ CTimeAsDate

◆ Group

◆ LinkPoint

◆ MimeType

◆ ModifyTime

◆ ModifyTimeAsDate

◆ Name

◆ Owner

◆ Size

◆ SizeHi

◆ SizeLo

◆ TimePrecision

◆ Type

◆ Unique

◆ UnixFilePermissions

◆ UTC

◆ ValidAttributeBits