* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*
* Author: Alexander Larsson <alexl@redhat.com>
*/
#include "gioerror.h"
#include "glibintl.h"
+struct _GFileEnumeratorPrivate {
+ /* TODO: Should be public for subclasses? */
+ GFile *container;
+ guint closed : 1;
+ guint pending : 1;
+ GAsyncReadyCallback outstanding_callback;
+ GError *outstanding_error;
+};
/**
* SECTION:gfileenumerator
* @short_description: Enumerated Files Routines
* @include: gio/gio.h
*
- * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
+ * #GFileEnumerator allows you to operate on a set of #GFiles,
* returning a #GFileInfo structure for each file enumerated (e.g.
* g_file_enumerate_children() will return a #GFileEnumerator for each
* of the children within a directory).
* To get the next file's information from a #GFileEnumerator, use
* g_file_enumerator_next_file() or its asynchronous version,
* g_file_enumerator_next_files_async(). Note that the asynchronous
- * version will return a list of #GFileInfo<!---->s, whereas the
+ * version will return a list of #GFileInfos, 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 g_dir_read_name(). 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 g_file_enumerator_close(), or
* its asynchronous version, g_file_enumerator_close_async(). Once
* a #GFileEnumerator is closed, no further actions may be performed
*
**/
-G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
-
-struct _GFileEnumeratorPrivate {
- /* TODO: Should be public for subclasses? */
- GFile *container;
- guint closed : 1;
- guint pending : 1;
- GAsyncReadyCallback outstanding_callback;
- GError *outstanding_error;
-};
+G_DEFINE_TYPE_WITH_PRIVATE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT)
enum {
PROP_0,
g_file_enumerator_class_init (GFileEnumeratorClass *klass)
{
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
-
- g_type_class_add_private (klass, sizeof (GFileEnumeratorPrivate));
-
+
gobject_class->set_property = g_file_enumerator_set_property;
gobject_class->dispose = g_file_enumerator_dispose;
gobject_class->finalize = g_file_enumerator_finalize;
static void
g_file_enumerator_init (GFileEnumerator *enumerator)
{
- enumerator->priv = G_TYPE_INSTANCE_GET_PRIVATE (enumerator,
- G_TYPE_FILE_ENUMERATOR,
- GFileEnumeratorPrivate);
+ enumerator->priv = g_file_enumerator_get_instance_private (enumerator);
}
/**
* returned from this function will contain attributes that match the
* attribute string that was passed when the #GFileEnumerator was created.
*
+ * See the documentation of #GFileEnumerator 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.
*
- * Return value: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
- * Free the returned object with g_object_unref() when no longer needed.
+ * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error
+ * or end of enumerator. Free the returned object with
+ * g_object_unref() when no longer needed.
**/
GFileInfo *
g_file_enumerator_next_file (GFileEnumerator *enumerator,
* is dropped, but you might want to call this function to make
* sure resources are released as early as possible.
*
- * Return value: #TRUE on success or #FALSE on error.
+ * Returns: #TRUE on success or #FALSE on error.
**/
gboolean
g_file_enumerator_close (GFileEnumerator *enumerator,
* g_file_enumerator_next_files_async:
* @enumerator: a #GFileEnumerator.
* @num_files: the number of file info objects to request
- * @io_priority: the <link linkend="io-priority">io priority</link>
- * of the request.
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
* 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 #GFileEnumerator for information about the
+ * order of returned files.
*
* The callback can be called with less than @num_files files in case of error
* or at the end of the enumerator. In case of a partial error the callback will
*
* Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
*
- * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
+ * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with
* g_list_free() and unref the infos with g_object_unref() when you're
* done with them.
**/
/**
* g_file_enumerator_close_async:
* @enumerator: a #GFileEnumerator.
- * @io_priority: the <link linkend="io-priority">I/O priority</link>
- * of the request.
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: (closure): the data to pass to callback function
* inside loops with g_file_enumerator_next_file().
*
* This is a convenience method that's equivalent to:
- * |[
+ * |[<!-- language="C" -->
* gchar *name = g_file_info_get_name (info);
* GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
* name);