@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/file-info.d.ts

@@ -4,78 +4,562 @@ import { FileAttributeMatcher } from "./file-attribute-matcher.js";
 import { Icon } from "./icon.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Stores information about a file system object referenced by a [iface@Gio.File].
+ *
+ * Functionality for manipulating basic metadata for files. `GFileInfo`
+ * implements methods for getting information that all files should
+ * contain, and allows for manipulation of extended attributes.
+ *
+ * See the file attributes document for more
+ * information on how GIO handles file attributes.
+ *
+ * To obtain a `GFileInfo` for a [iface@Gio.File], use
+ * [method@Gio.File.query_info] (or its async variant). To obtain a `GFileInfo`
+ * for a file input or output stream, use [method@Gio.FileInputStream.query_info]
+ * or [method@Gio.FileOutputStream.query_info] (or their async variants).
+ *
+ * To change the actual attributes of a file, you should then set the
+ * attribute in the `GFileInfo` and call [method@Gio.File.set_attributes_from_info]
+ * or [method@Gio.File.set_attributes_async] on a `GFile`.
+ *
+ * However, not all attributes can be changed in the file. For instance,
+ * the actual size of a file cannot be changed via [method@Gio.FileInfo.set_size].
+ * You may call [method@Gio.File.query_settable_attributes] and
+ * [method@Gio.File.query_writable_namespaces] to discover the settable attributes
+ * of a particular file at runtime.
+ *
+ * The direct accessors, such as [method@Gio.FileInfo.get_name], are slightly more
+ * optimized than the generic attribute accessors, such as
+ * [method@Gio.FileInfo.get_attribute_byte_string].This optimization will matter
+ * only if calling the API in a tight loop.
+ *
+ * It is an error to call these accessors without specifying their required file
+ * attributes when creating the `GFileInfo`. Use
+ * [method@Gio.FileInfo.has_attribute] or [method@Gio.FileInfo.list_attributes]
+ * to check what attributes are specified for a `GFileInfo`.
+ *
+ * [struct@Gio.FileAttributeMatcher] allows for searching through a `GFileInfo`
+ * for attributes.
+ */
 export declare class FileInfo extends GObject.GObject {
+    /**
+     * Creates a new file info structure.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Clears the status information from @info.
+     */
     clearStatus(): void;
+    /**
+     * First clears all of the GFileAttribute of
+     * @dest_info, and then copies all of the file attributes from `src_info` to @dest_info.
+     * @param destInfo - destination to copy attributes to.
+     */
     copyInto(destInfo: FileInfo): void;
+    /**
+     * Duplicates a file info structure.
+     */
     dup(): FileInfo;
+    /**
+     * Gets the access time of the current `info` and returns it as a
+     * #GDateTime.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_TIME_ACCESS. If %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is
+     * provided, the resulting #GDateTime will additionally have microsecond
+     * precision.
+     *
+     * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must
+     * be queried separately using g_file_info_get_attribute_uint32().
+     */
     getAccessDateTime(): GLib.DateTime | null;
+    /**
+     * Gets the value of an attribute, formatted as a human readable string.
+     *
+     * This escapes things as needed to make the string valid UTF-8 and readable by
+     * humans. It’s not meant to be a machine readable or reversible escaping
+     * format.
+     *
+     * To format file name attributes of type
+     * [enum@Gio.FileAttributeType.BYTE_STRING] for output as UTF-8, use
+     * [func@GLib.filename_to_utf8] instead:
+     * ```c
+     * const char *trash_orig_path_byte_string;
+     * g_autofree char *trash_orig_path_utf8 = NULL;
+     *
+     * trash_orig_path_byte_string = g_file_info_get_attribute_byte_string (info, G_FILE_ATTRIBUTE_TRASH_ORIG_PATH);
+     * trash_orig_path_utf8 = g_filename_to_utf8 (trash_orig_path_byte_string, -1, NULL, NULL, NULL);
+     * if (trash_orig_path_utf8 != NULL)
+     * g_message ("Some larger UTF-8 string with filename embedded as %s", trash_orig_path_utf8);
+     * ```
+     * @param attribute - a file attribute key.
+     */
     getAttributeAsString(attribute: string): string | null;
+    /**
+     * Gets the value of a boolean attribute. If the attribute does not
+     * contain a boolean value, %FALSE will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeBoolean(attribute: string): boolean;
+    /**
+     * Gets the value of a byte string attribute. If the attribute does
+     * not contain a byte string, %NULL will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeByteString(attribute: string): string | null;
+    /**
+     * Gets the attribute type, value and status for an attribute key.
+     * @param attribute - a file attribute key
+     * @param type - return location for the attribute type, or %NULL
+     * @param valuePp - return location for the
+     * @param status - return location for the attribute status, or %NULL
+     */
     getAttributeData(attribute: string, type?: Ref<FileAttributeType> | null, valuePp?: Ref<number> | null, status?: Ref<FileAttributeStatus> | null): boolean;
+    /**
+     * Gets the value of a byte string attribute as a file path.
+     *
+     * If the attribute does not contain a byte string, `NULL` will be returned.
+     *
+     * This function is meant to be used by language bindings that have specific
+     * handling for Unix paths.
+     * @param attribute - a file attribute key.
+     */
     getAttributeFilePath(attribute: string): string | null;
+    /**
+     * Gets a signed 32-bit integer contained within the attribute. If the
+     * attribute does not contain a signed 32-bit integer, or is invalid,
+     * 0 will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeInt32(attribute: string): number;
+    /**
+     * Gets a signed 64-bit integer contained within the attribute. If the
+     * attribute does not contain a signed 64-bit integer, or is invalid,
+     * 0 will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeInt64(attribute: string): number;
+    /**
+     * Gets the value of a #GObject attribute. If the attribute does
+     * not contain a #GObject, %NULL will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeObject(attribute: string): GObject.GObject | null;
+    /**
+     * Gets the attribute status for an attribute key.
+     * @param attribute - a file attribute key
+     */
     getAttributeStatus(attribute: string): FileAttributeStatus;
+    /**
+     * Gets the value of a string attribute. If the attribute does
+     * not contain a string, %NULL will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeString(attribute: string): string | null;
+    /**
+     * Gets the value of a stringv attribute. If the attribute does
+     * not contain a stringv, %NULL will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeStringv(attribute: string): string[] | null;
+    /**
+     * Gets the attribute type for an attribute key.
+     * @param attribute - a file attribute key.
+     */
     getAttributeType(attribute: string): FileAttributeType;
+    /**
+     * Gets an unsigned 32-bit integer contained within the attribute. If the
+     * attribute does not contain an unsigned 32-bit integer, or is invalid,
+     * 0 will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeUint32(attribute: string): number;
+    /**
+     * Gets a unsigned 64-bit integer contained within the attribute. If the
+     * attribute does not contain an unsigned 64-bit integer, or is invalid,
+     * 0 will be returned.
+     * @param attribute - a file attribute key.
+     */
     getAttributeUint64(attribute: string): number;
+    /**
+     * Gets the file's content type.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
+     */
     getContentType(): string | null;
+    /**
+     * Gets the creation time of the current `info` and returns it as a
+     * #GDateTime.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_TIME_CREATED. If %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is
+     * provided, the resulting #GDateTime will additionally have microsecond
+     * precision.
+     *
+     * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must
+     * be queried separately using g_file_info_get_attribute_uint32().
+     */
     getCreationDateTime(): GLib.DateTime | null;
+    /**
+     * Returns the #GDateTime representing the deletion date of the file, as
+     * available in %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the
+     * %G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned.
+     */
     getDeletionDate(): GLib.DateTime | null;
+    /**
+     * Gets a display name for a file. This is guaranteed to always be set.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+     */
     getDisplayName(): string;
+    /**
+     * Gets the edit name for a file.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
+     */
     getEditName(): string;
+    /**
+     * Gets the [entity tag][iface@Gio.File#entity-tags] for a given
+     * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_ETAG_VALUE.
+     */
     getEtag(): string | null;
+    /**
+     * Gets a file's type (whether it is a regular file, symlink, etc).
+     * This is different from the file's content type, see g_file_info_get_content_type().
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_TYPE.
+     */
     getFileType(): FileType;
+    /**
+     * Gets the icon for a file.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_ICON.
+     */
     getIcon(): Icon | null;
+    /**
+     * Checks if a file is a backup file.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP.
+     */
     getIsBackup(): boolean;
+    /**
+     * Checks if a file is hidden.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
+     */
     getIsHidden(): boolean;
+    /**
+     * Checks if a file is a symlink.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
+     */
     getIsSymlink(): boolean;
+    /**
+     * Gets the modification time of the current `info` and returns it as a
+     * #GDateTime.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is
+     * provided, the resulting #GDateTime will additionally have microsecond
+     * precision.
+     *
+     * If nanosecond precision is needed, %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must
+     * be queried separately using g_file_info_get_attribute_uint32().
+     */
     getModificationDateTime(): GLib.DateTime | null;
+    /**
+     * Gets the modification time of the current `info` and sets it
+     * in @result.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED. If %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is
+     * provided it will be used too.
+     * @param result - a #GTimeVal.
+     */
     getModificationTime(result: Ref<number>): void;
+    /**
+     * Gets the name for a file. This is guaranteed to always be set.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_NAME.
+     */
     getName(): string;
+    /**
+     * Gets the file's size (in bytes). The size is retrieved through the value of
+     * the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted
+     * from #guint64 to #goffset before returning the result.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_SIZE.
+     */
     getSize(): number;
+    /**
+     * Gets the value of the sort_order attribute from the #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+     */
     getSortOrder(): number;
+    /**
+     * Gets the symbolic icon for a file.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
+     */
     getSymbolicIcon(): Icon | null;
+    /**
+     * Gets the symlink target for a given #GFileInfo.
+     *
+     * It is an error to call this if the #GFileInfo does not contain
+     * %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET.
+     */
     getSymlinkTarget(): string | null;
+    /**
+     * Checks if a file info structure has an attribute named @attribute.
+     * @param attribute - a file attribute key.
+     */
     hasAttribute(attribute: string): boolean;
+    /**
+     * Checks if a file info structure has an attribute in the
+     * specified @name_space.
+     * @param nameSpace - a file attribute namespace.
+     */
     hasNamespace(nameSpace: string): boolean;
+    /**
+     * Lists the file info structure's attributes.
+     * @param nameSpace - a file attribute key's namespace, or %NULL to list
+     */
     listAttributes(nameSpace?: string | null): string[] | null;
+    /**
+     * Removes all cases of `attribute` from `info` if it exists.
+     * @param attribute - a file attribute key.
+     */
     removeAttribute(attribute: string): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and
+     * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the
+     * given date/time value.
+     *
+     * %G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared.
+     * @param atime - a #GDateTime.
+     */
     setAccessDateTime(atime: GLib.DateTime): void;
+    /**
+     * Sets the `attribute` to contain the given value, if possible. To unset the
+     * attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type.
+     * @param attribute - a file attribute key.
+     * @param type - a #GFileAttributeType
+     * @param valueP - pointer to the value
+     */
     setAttribute(attribute: string, type: FileAttributeType, valueP: number): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a boolean value.
+     */
     setAttributeBoolean(attribute: string, attrValue: boolean): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a byte string.
+     */
     setAttributeByteString(attribute: string, attrValue: string): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     *
+     * This function is meant to be used by language bindings that have specific
+     * handling for Unix paths.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a file path.
+     */
     setAttributeFilePath(attribute: string, attrValue: string): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a signed 32-bit integer
+     */
     setAttributeInt32(attribute: string, attrValue: number): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - attribute name to set.
+     * @param attrValue - int64 value to set attribute to.
+     */
     setAttributeInt64(attribute: string, attrValue: number): void;
+    /**
+     * Sets `mask` on `info` to match specific attribute types.
+     * @param mask - a #GFileAttributeMatcher.
+     */
     setAttributeMask(mask: FileAttributeMatcher): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a #GObject.
+     */
     setAttributeObject(attribute: string, attrValue: GObject.GObject): void;
+    /**
+     * Sets the attribute status for an attribute key. This is only
+     * needed by external code that implement g_file_set_attributes_from_info()
+     * or similar functions.
+     *
+     * The attribute must exist in `info` for this to work. Otherwise %FALSE
+     * is returned and `info` is unchanged.
+     * @param attribute - a file attribute key
+     * @param status - a #GFileAttributeStatus
+     */
     setAttributeStatus(attribute: string, status: FileAttributeStatus): boolean;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - a UTF-8 string.
+     */
     setAttributeString(attribute: string, attrValue: string): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     *
+     * Sinze: 2.22
+     * @param attribute - a file attribute key
+     * @param attrValue - a %NULL
+     */
     setAttributeStringv(attribute: string, attrValue: string[]): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - an unsigned 32-bit integer.
+     */
     setAttributeUint32(attribute: string, attrValue: number): void;
+    /**
+     * Sets the `attribute` to contain the given @attr_value,
+     * if possible.
+     * @param attribute - a file attribute key.
+     * @param attrValue - an unsigned 64-bit integer.
+     */
     setAttributeUint64(attribute: string, attrValue: number): void;
+    /**
+     * Sets the content type attribute for a given #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
+     * @param contentType - a content type.
+     */
     setContentType(contentType: string): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and
+     * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the
+     * given date/time value.
+     *
+     * %G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared.
+     * @param creationTime - a #GDateTime.
+     */
     setCreationDateTime(creationTime: GLib.DateTime): void;
+    /**
+     * Sets the display name for the current #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.
+     * @param displayName - a string containing a display name.
+     */
     setDisplayName(displayName: string): void;
+    /**
+     * Sets the edit name for the current file.
+     * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.
+     * @param editName - a string containing an edit name.
+     */
     setEditName(editName: string): void;
+    /**
+     * Sets the file type in a #GFileInfo to @type.
+     * See %G_FILE_ATTRIBUTE_STANDARD_TYPE.
+     * @param type - a #GFileType.
+     */
     setFileType(type: FileType): void;
+    /**
+     * Sets the icon for a given #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_ICON.
+     * @param icon - a #GIcon.
+     */
     setIcon(icon: Icon): void;
+    /**
+     * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden.
+     * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.
+     * @param isHidden - a #gboolean.
+     */
     setIsHidden(isHidden: boolean): void;
+    /**
+     * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
+     * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.
+     * @param isSymlink - a #gboolean.
+     */
     setIsSymlink(isSymlink: boolean): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
+     * given date/time value.
+     *
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.
+     * @param mtime - a #GDateTime.
+     */
     setModificationDateTime(mtime: GLib.DateTime): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the
+     * given time value.
+     *
+     * %G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.
+     * @param mtime - a #GTimeVal.
+     */
     setModificationTime(mtime: number): void;
+    /**
+     * Sets the name attribute for the current #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_NAME.
+     * @param name - a string containing a name.
+     */
     setName(name: string): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info
+     * to the given size.
+     * @param size - a #goffset containing the file's size.
+     */
     setSize(size: number): void;
+    /**
+     * Sets the sort order attribute in the file info structure. See
+     * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.
+     * @param sortOrder - a sort order integer.
+     */
     setSortOrder(sortOrder: number): void;
+    /**
+     * Sets the symbolic icon for a given #GFileInfo.
+     * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.
+     * @param icon - a #GIcon.
+     */
     setSymbolicIcon(icon: Icon): void;
+    /**
+     * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info
+     * to the given symlink target.
+     * @param symlinkTarget - a static string containing a path to a symlink target.
+     */
     setSymlinkTarget(symlinkTarget: string): void;
+    /**
+     * Unsets a mask set by g_file_info_set_attribute_mask(), if one
+     * is set.
+     */
     unsetAttributeMask(): void;
     connect(signal: "notify", handler: (self: FileInfo, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;