gi-gio
CopyrightWill Thompson and Iñaki García Etxebarria
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Gio.Objects.FileEnumerator

Description

GFileEnumerator allows you to operate on a set of File objects, returning a FileInfo structure for each file enumerated (e.g. fileEnumerateChildren will return a GFileEnumerator for each of the children within a directory).

To get the next file's information from a GFileEnumerator, use fileEnumeratorNextFile or its asynchronous version, fileEnumeratorNextFilesAsync. Note that the asynchronous version will return a list of FileInfo objects, whereas the synchronous will only return the next file in the enumerator.

The ordering of returned files is unspecified for non-Unix platforms; for more information, see dirReadName. On Unix, when operating on local files, returned files will be sorted by inode number. Effectively you can assume that the ordering of returned files will be stable between successive calls (and applications) assuming the directory is unchanged.

If your application needs a specific ordering, such as by name or modification time, you will have to implement that in your application code.

To close a GFileEnumerator, use fileEnumeratorClose, or its asynchronous version, fileEnumeratorCloseAsync. Once a GFileEnumerator is closed, no further actions may be performed on it, and it should be freed with objectUnref.

Synopsis

Exported types

newtype FileEnumerator Source #

Memory-managed wrapper type.

Instances

Instances details
Eq FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

GObject FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

ManagedPtrNewtype FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

TypedObject FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

Methods

glibType :: IO GType #

HasParentTypes FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

HasAttributeList FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

(info ~ ResolveFileEnumeratorMethod t FileEnumerator, OverloadedMethod info FileEnumerator p, HasField t FileEnumerator p) => HasField (t :: Symbol) FileEnumerator (p :: Type) Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

Methods

getField :: FileEnumerator -> p #

(info ~ ResolveFileEnumeratorMethod t FileEnumerator, OverloadedMethodInfo info FileEnumerator) => IsLabel t (MethodProxy info FileEnumerator) Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

(info ~ ResolveFileEnumeratorMethod t FileEnumerator, OverloadedMethod info FileEnumerator p) => IsLabel t (FileEnumerator -> p) Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

Methods

fromLabel :: FileEnumerator -> p #

IsGValue (Maybe FileEnumerator) Source #

Convert FileEnumerator to and from GValue. See toGValue and fromGValue.

Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttributeList FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type ParentTypes FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type SignalList FileEnumerator Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

class (GObject o, IsDescendantOf FileEnumerator o) => IsFileEnumerator o Source #

Type class for types which can be safely cast to FileEnumerator, for instance with toFileEnumerator.

Instances

Instances details
(GObject o, IsDescendantOf FileEnumerator o) => IsFileEnumerator o Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

toFileEnumerator :: (MonadIO m, IsFileEnumerator o) => o -> m FileEnumerator Source #

Cast to FileEnumerator, for types for which this is known to be safe. For general casts, use castTo.

Methods

type family ResolveFileEnumeratorMethod (t :: Symbol) o where ... Source #

Equations

ResolveFileEnumeratorMethod "bindProperty" o = ObjectBindPropertyMethodInfo 
ResolveFileEnumeratorMethod "bindPropertyFull" o = ObjectBindPropertyFullMethodInfo 
ResolveFileEnumeratorMethod "close" o = FileEnumeratorCloseMethodInfo 
ResolveFileEnumeratorMethod "closeAsync" o = FileEnumeratorCloseAsyncMethodInfo 
ResolveFileEnumeratorMethod "closeFinish" o = FileEnumeratorCloseFinishMethodInfo 
ResolveFileEnumeratorMethod "forceFloating" o = ObjectForceFloatingMethodInfo 
ResolveFileEnumeratorMethod "freezeNotify" o = ObjectFreezeNotifyMethodInfo 
ResolveFileEnumeratorMethod "getv" o = ObjectGetvMethodInfo 
ResolveFileEnumeratorMethod "hasPending" o = FileEnumeratorHasPendingMethodInfo 
ResolveFileEnumeratorMethod "isClosed" o = FileEnumeratorIsClosedMethodInfo 
ResolveFileEnumeratorMethod "isFloating" o = ObjectIsFloatingMethodInfo 
ResolveFileEnumeratorMethod "iterate" o = FileEnumeratorIterateMethodInfo 
ResolveFileEnumeratorMethod "nextFile" o = FileEnumeratorNextFileMethodInfo 
ResolveFileEnumeratorMethod "nextFilesAsync" o = FileEnumeratorNextFilesAsyncMethodInfo 
ResolveFileEnumeratorMethod "nextFilesFinish" o = FileEnumeratorNextFilesFinishMethodInfo 
ResolveFileEnumeratorMethod "notify" o = ObjectNotifyMethodInfo 
ResolveFileEnumeratorMethod "notifyByPspec" o = ObjectNotifyByPspecMethodInfo 
ResolveFileEnumeratorMethod "ref" o = ObjectRefMethodInfo 
ResolveFileEnumeratorMethod "refSink" o = ObjectRefSinkMethodInfo 
ResolveFileEnumeratorMethod "runDispose" o = ObjectRunDisposeMethodInfo 
ResolveFileEnumeratorMethod "stealData" o = ObjectStealDataMethodInfo 
ResolveFileEnumeratorMethod "stealQdata" o = ObjectStealQdataMethodInfo 
ResolveFileEnumeratorMethod "thawNotify" o = ObjectThawNotifyMethodInfo 
ResolveFileEnumeratorMethod "unref" o = ObjectUnrefMethodInfo 
ResolveFileEnumeratorMethod "watchClosure" o = ObjectWatchClosureMethodInfo 
ResolveFileEnumeratorMethod "getChild" o = FileEnumeratorGetChildMethodInfo 
ResolveFileEnumeratorMethod "getContainer" o = FileEnumeratorGetContainerMethodInfo 
ResolveFileEnumeratorMethod "getData" o = ObjectGetDataMethodInfo 
ResolveFileEnumeratorMethod "getProperty" o = ObjectGetPropertyMethodInfo 
ResolveFileEnumeratorMethod "getQdata" o = ObjectGetQdataMethodInfo 
ResolveFileEnumeratorMethod "setData" o = ObjectSetDataMethodInfo 
ResolveFileEnumeratorMethod "setDataFull" o = ObjectSetDataFullMethodInfo 
ResolveFileEnumeratorMethod "setPending" o = FileEnumeratorSetPendingMethodInfo 
ResolveFileEnumeratorMethod "setProperty" o = ObjectSetPropertyMethodInfo 
ResolveFileEnumeratorMethod l o = MethodResolutionFailed l o :: Type 

close

fileEnumeratorClose Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsCancellable b) 
=> a

enumerator: a file enumerator

-> Maybe b

cancellable: optional cancellable object

-> m ()

(Can throw GError)

Releases all resources used by this enumerator.

The enumerator will return [errorgio.IOErrorEnum.CLOSED] on all subsequent calls.

This will be automatically called when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

closeAsync

fileEnumeratorCloseAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsCancellable b) 
=> a

enumerator: a file enumerator

-> Int32

ioPriority: the I/O priority of the request

-> Maybe b

cancellable: optional cancellable object

-> Maybe AsyncReadyCallback

callback: a callback to call when the request is satisfied

-> m () 

Asynchronously closes the file enumerator.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error [errorgio.IOErrorEnum.CANCELLED] will be returned by [methodgio.FileEnumerator.close_finish()].

closeFinish

fileEnumeratorCloseFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsAsyncResult b) 
=> a

enumerator: a file enumerator

-> b

result: an async result

-> m ()

(Can throw GError)

Finishes closing a file enumerator, started by fileEnumeratorCloseAsync.

If the file enumerator was already closed when fileEnumeratorCloseAsync was called, then this function will report [errorgio.IOErrorEnum.CLOSED] in error. If the file enumerator had a pending operation when the close operation was started, then [errorgio.IOErrorEnum.PENDING] will be reported. If the operation was cancelled from another thread using cancellable, [errorgio.IOErrorEnum.CANCELLED] will be reported.

getChild

fileEnumeratorGetChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsFileInfo b) 
=> a

enumerator: a file enumerator

-> b

info: a file info object received from fileEnumeratorNextFile or the async equivalent

-> m File

Returns: a file object for the file info object passed to it

Returns a new File which refers to the file named by info in the source directory of enumerator.

This function is primarily intended to be used inside loops with fileEnumeratorNextFile.

To use this, [constgio.FILE_ATTRIBUTE_STANDARD_NAME] must have been listed in the attributes list used when creating the FileEnumerator.

This is a convenience method that's equivalent to:

c code

char *name = g_file_info_get_name (info);
GFile *child = g_file_get_child (g_file_enumerator_get_container (enumerator), name);

Since: 2.36

getContainer

fileEnumeratorGetContainer Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a) 
=> a

enumerator: a file enumerator

-> m File

Returns: the file which is being enumerated

Get the File container which is being enumerated.

Since: 2.18

hasPending

fileEnumeratorHasPending Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a) 
=> a

enumerator: a file enumerator

-> m Bool

Returns: true if the enumerator has pending operations

Checks if the file enumerator has pending operations.

isClosed

fileEnumeratorIsClosed Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a) 
=> a

enumerator: a file enumerator

-> m Bool

Returns: true if the enumerator is closed

Checks if the file enumerator has been closed.

iterate

fileEnumeratorIterate Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsCancellable b) 
=> a

direnum: an open file enumerator

-> Maybe b

cancellable: optional cancellable object

-> m (FileInfo, File)

(Can throw GError)

A version of fileEnumeratorNextFile that’s easier to use correctly from C programs.

With fileEnumeratorNextFile, the boolean return value signifies “end of iteration or error”, which requires allocation of a temporary [typegLib.Error] to distinguish which one.

In contrast, with this function, a false return from fileEnumeratorIterate *always* means “error”. End of iteration is signaled by outInfo or outChild being NULL.

Another crucial difference is that the references for outInfo and outChild are owned by direnum (they are cached as hidden properties). You must not unref them in your own code. This makes memory management significantly easier for C code in combination with loops.

Finally, this function optionally allows retrieving a corresponding File as well as each FileInfo.

To use this, [constgio.FILE_ATTRIBUTE_STANDARD_NAME] must have been listed in the attributes list used when creating the FileEnumerator.

You must specify at least one of outInfo or outChild.

The code pattern for correctly using fileEnumeratorIterate from C is:

c code

direnum = g_file_enumerate_children (file, ...);
while (TRUE)
  {
    GFileInfo *info = NULL;

    if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
      goto out;

    if (info == NULL)
      break;

    // do stuff with "info"; do not unref it! ...
  }

out:
  g_object_unref (direnum); // Note: frees the last @info

Since: 2.44

nextFile

fileEnumeratorNextFile Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsCancellable b) 
=> a

enumerator: a file enumerator

-> Maybe b

cancellable: optional cancellable object

-> m (Maybe FileInfo)

Returns: A file info object, or NULL on error or end of enumerator (Can throw GError)

Returns information for the next file in the enumerated object.

Will block until the information is available. The FileInfo returned from this function will contain attributes that match the attribute string that was passed when the file enumerator was created.

See the documentation of FileEnumerator for information about the order of returned files.

On error, returns NULL and sets error to the error. If the enumerator is at the end, NULL will be returned and error will be unset.

nextFilesAsync

fileEnumeratorNextFilesAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsCancellable b) 
=> a

enumerator: a file enumerator

-> Int32

numFiles: the number of file info objects to request

-> Int32

ioPriority: the I/O priority of the request

-> Maybe b

cancellable: optional cancellable object

-> Maybe AsyncReadyCallback

callback: callback to call when the request is satisfied

-> m () 

Request information for a number of files from the enumerator asynchronously.

When all I/O for the operation is finished the callback will be called with the requested information.

See the documentation of FileEnumerator for information about the order of returned files.

Once the end of the enumerator is reached, or if an error occurs, the callback will be called with an empty list. In this case, the previous call to fileEnumeratorNextFilesAsync will typically have returned fewer than numFiles items.

If a request is cancelled the callback will be called with [errorgio.IOErrorEnum.CANCELLED].

This leads to the following pseudo-code usage:

c code

g_autoptr(GFile) dir = get_directory ();
g_autoptr(GFileEnumerator) enumerator = NULL;
g_autolist(GFileInfo) files = NULL;
g_autoptr(GError) local_error = NULL;

enumerator = yield g_file_enumerate_children_async (dir,
                                                    G_FILE_ATTRIBUTE_STANDARD_NAME ","
                                                    G_FILE_ATTRIBUTE_STANDARD_TYPE,
                                                    G_FILE_QUERY_INFO_NONE,
                                                    G_PRIORITY_DEFAULT,
                                                    cancellable,
                                                    …,
                                                    &local_error);
if (enumerator == NULL)
  g_error ("Error enumerating: %s", local_error->message);

// Loop until no files are returned, either because the end of the enumerator
// has been reached, or an error was returned.
do
  {
    files = yield g_file_enumerator_next_files_async (enumerator,
                                                      5,  // number of files to request
                                                      G_PRIORITY_DEFAULT,
                                                      cancellable,
                                                      …,
                                                      &local_error);

    // Process the returned files, but don’t assume that exactly 5 were returned.
    for (GList *l = files; l != NULL; l = l->next)
      {
        GFileInfo *info = l->data;
        handle_file_info (info);
      }
  }
while (files != NULL);

if (local_error != NULL &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
  g_error ("Error while enumerating: %s", local_error->message);

During an async request no other sync and async calls are allowed, and will result in [errorgio.IOErrorEnum.PENDING] errors.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is [constgLib.PRIORITY_DEFAULT].

nextFilesFinish

fileEnumeratorNextFilesFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a, IsAsyncResult b) 
=> a

enumerator: a file enumerator

-> b

result: an async result

-> m [FileInfo]

Returns: a list of file info objects (Can throw GError)

Finishes the asynchronous operation started with [methodgio.FileEnumerator.next_files_async()].

setPending

fileEnumeratorSetPending Source #

Arguments

:: (HasCallStack, MonadIO m, IsFileEnumerator a) 
=> a

enumerator: a file enumerator

-> Bool

pending: a boolean value

-> m () 

Sets the file enumerator as having pending operations.

Properties

container

The container that is being enumerated.

data FileEnumeratorContainerPropertyInfo Source #

Instances

Instances details
AttrInfo FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

Associated Types

type AttrAllowedOps FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrBaseTypeConstraint FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrGetType FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrSetTypeConstraint FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrTransferTypeConstraint FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrTransferType FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrLabel FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrOrigin FileEnumeratorContainerPropertyInfo 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrAllowedOps FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrBaseTypeConstraint FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrGetType FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrLabel FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrOrigin FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrSetTypeConstraint FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrTransferType FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

type AttrTransferTypeConstraint FileEnumeratorContainerPropertyInfo Source # 
Instance details

Defined in GI.Gio.Objects.FileEnumerator

constructFileEnumeratorContainer :: (IsFileEnumerator o, MonadIO m, IsFile a) => a -> m (GValueConstruct o) Source #

Construct a GValueConstruct with valid value for the “container” property. This is rarely needed directly, but it is used by new.