Next: A Directory Scan Example
Up: Scanning Directories in a Application
Previous: Introduction
An application scans a directory by creating a DirScan object. DirScan
objects are transient C++ objects, not persistent Shore objects. A DirScan
object can be in one of two states: open or closed. A scan
must be opened inside a transaction, and can only be used inside the
transaction in which it was opened. Once a scan is opened, it stays open
until it is explicitly closed, or until the scan object is destroyed, or
the transaction terminates. In particular, the scan object
remains open even after the end of the scan has been reached or an
error has occurred.
Directory scans request blocks of directory entries from the Shore server
and store them in a buffer. Applications can set the size of this buffer,
although the size must be at least DEF_DIRSCAN_BUFSIZE to ensure
that the buffer is large enough to hold at least one directory entry. If a
smaller buffer size is requested, it will be replaced by the default
size.
A scan of a directory returns some number of DirEntry structures.
The DirEntry type (defined in OCTypes.h) looks like this:
struct DirEntry {
LOID loid;
int namelen;
char name[MAXNAMLEN + 1];
};
The members of the structure are
- loid,
- the logical OID of the object named by the directory entry,
- namelen,
- the length of the name field, and
- name,
- the null-terminated name of the entry
(the last component of the pathname of the named object).
The public interface to the DirScan class is
class DirScan {
public:
DirScan();
DirScan(const char *path, int bufsize = DEF_DIRSCAN_BUFSIZE);
shrc open(const char *path, int bufsize = DEF_DIRSCAN_BUFSIZE);
shrc next(DirEntry *entry);
bool is_open();
shrc rc();
int operator==(shrc &rc);
int operator!=(shrc &rc);
shrc close();
~DirScan();
};
- DirScan()
- is the default constructor. The resulting DirScan object is in the
closed state.
It may be opened by the open member function.
- DirScan(const char *path, int bufsize).
- This constructor invokes the open member function.
The caller should whether the open operation was successful by calling
is_open() or by testing the return code with rc(),
operator==(), or operator!=().
- shrc open(const char *path, int bufsize).
- The path argument should be the pathname of a valid directory
in the Shore filesystem namespace, and the DirScan object should be in
the closed state.
The caller must have (at least) read permission for the named directory
and must have a transaction open.
The bufsize argument indicates the size of the scan's buffer. This
parameter defaults to DEF_DIRSCAN_BUFSIZE, which is large enough to
hold at least one directory entry.
Any smaller value for this argument is treated as
DEF_DIRSCAN_BUFSIZE.
Upon successful completion, RCOK is returned. Any
other return value indicates an error condition.
- shrc next(DirEntry *entry)
- copies the next director entry into the DirEntry structure
pointed to by the argument.
Returns RCOK on success.
Returns OC_EndOfScan if no more entries exist
(i.e., next is called after the last item in the scan has already
been returned).
Any other return code indicates an error condition.
- bool is_open()
- indicates whether the scan is open or closed.
Note that the scan remains open after retrieving the last entry.
- shrc rc()
- returns the return code generated by the last operation
(open or next).
- int operator==(shrc rc)
- int operator!=(shrc rc)
- These operators provide a convenient way to check the status of the scan.
For example, applications can say if (scan == RCOK) ....
- shrc DirScan::close()
- closes the scan object. Closing a scan object releases any resources
associated with the scan in both the server and client processes (such as
the scan buffer). It also allows the scan object to be reused.
The scan is closed implicitly when the DirScan object is
destroyed (either via operator delete or when the DirScan object goes out
of scope), or when the transaction in which the scan was opened terminates.
- ~DirScan().
- The DirScan destructor closes the scan object if it is open.
Next: A Directory Scan Example
Up: Scanning Directories in a Application
Previous: Introduction
This page was generated from LaTeX sources
10/27/1997