staffilesystem.h

Software Testing Automation Framework (STAF)的开发代码

                               unsigned int *osRC);


/*****************************************************************************/
/* STAFFSGetCurrentDirectory - Retrieves the current directory               */
/*                                                                           */
/* Accepts: (Out) Pointer to current directory string                        */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*****************************************************************************/
STAFRC_t STAFFSGetCurrentDirectory(STAFString_t *path, unsigned int *osRC);


/*****************************************************************************/
/* STAFFSSetCurrentDirectory - Sets the current directory                    */
/*                                                                           */
/* Accepts: (In)  Current directory string                                   */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) You should obtain the current directory lock before setting   */
/*             the current directory                                         */
/*****************************************************************************/
STAFRC_t STAFFSSetCurrentDirectory(STAFStringConst_t path, unsigned int *osRC);


/*****************************************************************************/
/* STAFFSRequestCurrentDirectoryLock - Obtains the lock on the current       */
/*                                     directory                             */
/*                                                                           */
/* Accepts: Nothing                                                          */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*****************************************************************************/
STAFRC_t STAFFSRequestCurrentDirectoryLock();


/*****************************************************************************/
/* STAFFSReleaseCurrentDirectoryLock - Releases the lock on the current      */
/*                                     directory                             */
/*                                                                           */
/* Accepts: Nothing                                                          */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*****************************************************************************/
STAFRC_t STAFFSReleaseCurrentDirectoryLock();


/*****************************************************************************/
/* STAFFSEnumOpen - Obtains an enumeration handle for an entry object        */
/*                                                                           */
/* Accepts: (Out) Pointer to enumeration handle                              */
/*          (In)  File system entry                                          */
/*          (In)  Pattern used to match names                                */
/*          (In)  Pattern used to match extension                            */
/*          (In)  Are name/extension patterns case sensitive                 */
/*          (In)  The types of entries to enumerate                          */
/*          (In)  How should the entries be sorted                           */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) The name and extension patterns may contain the '*' and '?'   */
/*             characters.  The '*' character matches zero or more           */
/*             characters.  The '?' character matches one character.         */
/*          2) It is legal to enumerate a non-directory entry.  You will     */
/*             simply receive an enumeration with no entries.                */
/*****************************************************************************/
STAFRC_t STAFFSEnumOpen(STAFFSEnumHandle_t *enumHandle, STAFFSEntry_t entry,
                        STAFStringConst_t namePattern,
                        STAFStringConst_t extPattern,
                        STAFFSCaseSensitive_t caseSensitivity,
                        STAFFSEntryType_t entryTypes,
                        STAFFSSortBy_t sortBy, unsigned int *osRC);


/*****************************************************************************/
/* STAFFSEnumNext - Retrieves the next entry in the enumeration              */
/*                                                                           */
/* Accepts: (In)  Enumeration handle                                         */
/*          (Out) Pointer to file system entry (this will zero if there are  */
/*                no more entries in the enumeration                         */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) You must free the entries obtained through this API           */
/*          2) No error will be returned when enumeration is complete.  You  */
/*             will simply receive a zero entry.                             */
/*****************************************************************************/
STAFRC_t STAFFSEnumNext(STAFFSEnumHandle_t enumHandle, STAFFSEntry_t *entry,
                        unsigned int *osRC);


/*****************************************************************************/
/* STAFFSEnumClose - Closes an enumeration handle                            */
/*                                                                           */
/* Accepts: (I/O) Pointer to enumeration handle                              */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*****************************************************************************/
STAFRC_t STAFFSEnumClose(STAFFSEnumHandle_t *enumHandle, unsigned int *osRC);


/*****************************************************************************/
/*                            Internal use only                              */
/*****************************************************************************/
/* Note: These APIs should not be used directly by the user                  */
/*****************************************************************************/

/*****************************************************************************/
/* STAFFSOSGetExclusiveFileLock - Gets an exclusive lock on a file           */
/*                                                                           */
/* Accepts: (In)  Path string                                                */
/*          (Out) Pointer to the lock                                        */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) This API is for internal STAF use only.  Users should use     */
/*             the STAFFSEntry<Read|Write>Lock APIs.                         */
/*          2) Porters - this need only provide an advisory lock.  A         */
/*             mandatory lock is not required.                               */
/*****************************************************************************/
STAFRC_t STAFFSOSGetExclusiveFileLock(STAFStringConst_t path,
                                      STAFFSOSFileLock_t *lock,
                                      unsigned int *osRC);


/*****************************************************************************/
/* STAFFSOSReleaseExclusiveFileLock - Releases an exclusive file lock        */
/*                                                                           */
/* Accepts: (I/O) Pointer to the lock                                        */
/*          (Out) Pointer to unsigned int indicating operating system error  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) This API is for internal STAF use only.  Users should use     */
/*             the STAFFSEntry<Read|Write>Unlock APIs.                       */
/*****************************************************************************/
STAFRC_t STAFFSOSReleaseExclusiveFileLock(STAFFSOSFileLock_t *lock,
                                          unsigned int *osRC);

/* The following definitions are for OS independent versions of the  */
/* File System APIs.  These should not be used by user applications. */

STAFRC_t STAFFSCopyEntryCommon(STAFFSEntry_t source, STAFStringConst_t target,
                               unsigned int *osRC);

#ifdef __cplusplus
}

#include "STAFString.h"
#include "STAFTimestamp.h"
#include "STAFRefPtr.h"
#include "STAFException.h"
#include <deque>

// C++ Definitions

// STAFFSPath - This class represents a path in the file system.  The path
//              can be represented as a string, or as its constituent pieces.
//              These pieces are the root of the path, the directories in the
//              path, the name of the item, and the extension of the item.
//
//              This class provides numerous methods to build up a path string
//              from its pieces and to determine a path's pieces from a path
//              string.
//
//              Given an instance of this class, you can retrieve the file
//              system entry object associated with it, as well as create the
//              directory represented by it.

class STAFFSEntry;
typedef STAFRefPtr<STAFFSEntry> STAFFSEntryPtr;
typedef std::pair<STAFRC_t, STAFFSEntryPtr> STAFFSEntryRC;

class STAFFSPath
{
public:

    // This constructor is designed for building a path piece by piece
    STAFFSPath();

    // This constructor is designed for breaking down a path string
    STAFFSPath(const STAFString &path);

    // These methods allow you to build up a path piece by piece
    STAFFSPath &setRoot(const STAFString &root = STAFString());
    STAFFSPath &addDir(const STAFString &dir);
    STAFFSPath &setName(const STAFString &name = STAFString());
    STAFFSPath &setExtension(const STAFString &extension = STAFString());

    // Allows you to reset the list of directories in the path
    STAFFSPath &clearDirList();

    // Get a path string based on pieces
    STAFString asString() const;

    // Get various pieces based on path string
    STAFString root() const;
    unsigned int numDirs() const;
    STAFString dir(unsigned int index = 0) const;
    STAFString name() const;
    STAFString extension() const;

    unsigned int exists() const;

    STAFFSEntryPtr getEntry() const;
    STAFFSEntryRC getEntry(unsigned int *osRC) const;

    STAFFSEntryPtr createDirectory(STAFFSDirectoryCreateMode_t mode =
                                   kSTAFFSCreateDirOnly) const;
    STAFFSEntryRC createDirectory(unsigned int *osRC,
                                  STAFFSDirectoryCreateMode_t mode =
                                  kSTAFFSCreateDirOnly) const;

private:

    void updatePath();
    void updatePieces();

    unsigned int fPathUpToDate;
    unsigned int fPiecesUpToDate;

    STAFString fPath;
    STAFString fRoot;
    std::deque<STAFString> fDirs;
    STAFString fName;
    STAFString fExtension;