Class RDir

class RDir : public RSubSessionBase;

Description

Reads the entries contained in a directory.

You must first open the directory, specifying an attribute mask which is used by Read() calls to filter the entry types required. Then, use one of the Read() functions to read the filtered entries. When the operation is complete, the directory should be closed using Close()

There are two types of Read(): one works with a single entry at a time, requiring programs to iterate through the entries explicitly. The other works with an entire TEntryArray, allowing multiple entries to be read in one call. As well as making application program logic somewhat simpler, this type uses fewer calls to the server, and is more efficient.

Each type of Read() can be performed either synchronously or asynchronously.

It may be more convenient to use RFs::GetDir() than the Read() calls supported by this class. RFs::GetDir() has the advantage that it allows a directory’s entries to be sorted in various ways. However, it does not provide asynchronous as well as synchronous variants and does not allow entries to be read individually.

Derivation

• RSubSessionBase - Client-side handle to a sub-session

• RDir - Reads the entries contained in a directory

Members

Defined in RDir:

• Close()Closes the directory
• Open()Opens a directory using the specified UID type to filter the directory entry types that will subsequently be read
• Open()Opens a directory using an attribute bitmask to filter the directory entry types that will subsequently be read
• Read()Reads all filtered directory entries into the specified array
• Read()Reads all filtered directory entries into the specified array
• Read()Reads a single directory entry
• Read()Reads a single directory entry

Inherited from RSubSessionBase:

• CloseSubSession()Closes the sub-session
• CreateAutoCloseSubSession()Creates a new sub-session within an existing session
• CreateSubSession()Creates a new sub-session within an existing session
• Send()Sends a blind message to the server - no reply is expected
• SendReceive()Sends a message to the server and waits asynchronously for the reply
• Session()Returns a copy of the session associated with this sub-session
• SubSessionHandle()Gets the sub-session handle number

See also:

• RFsA handle to a file server session

Capability:

AllFiles

IMPORT_C TInt Open(RFs &aFs, const TDesC &aMatchName, const TUidType &aUidType);

Description

Opens a directory using the specified UID type to filter the directory entry types that will subsequently be read.

This function, or its overload, must be called before reading the entries in the directory.

Note: to close the directory, use Close()

Parameters

RFs &aFs The file server session. const TDesC &aMatchName Name of the directory to be opened. Any path components that are not specified here are taken from the session path. Note that the wildcard characters ? and * can be used. As with all directory paths aName must be terminated with '\', Please refer to "Structure of paths and filenames" section in the Symbian OS Library. const TUidType &aUidType UID type used by the Read() functions to filter the entry types required. Only those entries with the UID type specified here will be read.

Return value

TInt KErrNone, if successful, otherwise one of the other system-wide error codes.

Capability:

AllFiles

IMPORT_C TInt Open(RFs &aFs, const TDesC &aMatchName, TUint anAttMask);

Description

Opens a directory using an attribute bitmask to filter the directory entry types that will subsequently be read.

This function, or its overload, must be called before reading the entries in the directory.

Note: to close the directory, use Close()

Parameters

RFs &aFs The file server session. const TDesC &aMatchName Name of the directory to be opened. Any path components that are not specified here are taken from the session path. Note that the wildcard characters ? and * can be used. As with all directory paths aName must be terminated with '\', Please refer to "Structure of paths and filenames" section in the Symbian OS Library. TUint anAttMask An attribute mask used by the Read() functions to filter the entry types required. Only those entries with the attributes specified here will be read. See KEntryAttNormal, and the other file or directory attributes.

Return value

TInt KErrNone, if successful, otherwise one of the other system-wide error codes.

See also:

• KEntryAttNormalFile/directory attribute: any file without the hidden or system attribute

IMPORT_C void Close();

Description

Closes the directory.

Any open files are closed when the file server session is closed.

Close() is guaranteed to return, and provides no indication whether it completed successfully or not.

IMPORT_C TInt Read(TEntryArray &anArray) const;

Description

Reads all filtered directory entries into the specified array.

This is a synchronous function that returns when the operation is complete.

Parameters

TEntryArray &anArray On successful return, contains filtered entries from the directory.

Return value

TInt KErrNone, if the read operation is successful - the end of the directory has not yet been reached, and there may be more entries to be read; KErrEof, if the read operation is successful - all the entries in the directory have been read, and anArray contains the final set of entries; otherwise one of the other system-wide error codes (e.g. KErrCorrupt, KErrNoMemory etc).

IMPORT_C void Read(TEntryArray &anArray, TRequestStatus &aStatus) const;

Description

Reads all filtered directory entries into the specified array.

This is an asynchronous function.

Parameters

TEntryArray &anArray On request completion, contains filtered entries from the directory. TRequestStatus &aStatus The request status object. On completion, this will contain: KErrNone, if the read operation is successful - the end of the directory has not yet been reached, and there may be more entries to be read; KErrEof, if the read operation is successful - all the entries in the directory have been read, and anArray contains the final set of entries; otherwise one of the other system-wide error codes (e.g. KErrCorrupt, KErrNoMemory etc).

IMPORT_C TInt Read(TEntry &anEntry) const;

Description

Reads a single directory entry.

This is a synchronous function that returns when the operation is complete.

Parameters

TEntry &anEntry On successful return, contains a directory entry.

Return value

TInt KErrNone, if successful, otherwise one of the other system-wide error codes.

IMPORT_C void Read(TPckg< TEntry > &anEntry, TRequestStatus &aStatus) const;

Description

Reads a single directory entry.

This is an asynchronous function.

Parameters

TPckg< TEntry > &anEntry On request completion, contains a directory entry. TRequestStatus &aStatus The request status object. On request completion, contains: KErrNone, if successful; otherwise one of the other system-wide error codes.