staffilesystem.h

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

/*****************************************************************************/
/* Software Testing Automation Framework (STAF)                              */
/* (C) Copyright IBM Corp. 2001                                              */
/*                                                                           */
/* This software is licensed under the Common Public License (CPL) V1.0.     */
/*****************************************************************************/

#ifndef STAF_FileSystem
#define STAF_FileSystem

#include "STAF.h"
#include "STAFString.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*****************/
/* C Definitions */
/*****************/

/**********************************************/
/* Enumeration constants and type definitions */
/**********************************************/

typedef enum STAFFSCaseSensitive_e
{
    kSTAFFSCaseDefault = 0,
    kSTAFFSCaseSensitive = 1,
    kSTAFFSCaseInsensitive = 2
} STAFFSCaseSensitive_t;

typedef enum STAFFSSortBy_e
{
    kSTAFFSNoSort = 0,
    kSTAFFSSortByName = 1,
    kSTAFFSSortBySize = 2,
    kSTAFFSSortByModTime = 3
} STAFFSSortBy_t;

typedef enum STAFFSDirectoryCreateMode_e
{
    kSTAFFSCreateDirOnly = 0,
    kSTAFFSCreatePath = 1
} STAFFSDirectoryCreateMode_t;

typedef enum STAFFSInfoType_e
{
    kSTAFFSPathSep = 0,
    kSTAFFSFileSep = 1,
    kSTAFFSLineSep = 2,
    kSTAFFSCaseSensitivity = 3
} STAFFSInfoType_t;

typedef enum STAFFSEntryType_e
{
    kSTAFFSFile             = 0x00000001,
    kSTAFFSDirectory        = 0x00000002,
    kSTAFFSPipe             = 0x00000004,
    kSTAFFSSocket           = 0x00000008,
    kSTAFFSSymLink          = 0x00000010,
    kSTAFFSCharDev          = 0x00000020,
    kSTAFFSBlkDev           = 0x00000040,
    kSTAFFSSpecialDirectory = 0x00000080,
    kSTAFFSOther            = 0x80000000,
    kSTAFFSNone             = 0x00000000,
    kSTAFFSNormal           = 0x00000003,
    kSTAFFSAll              = 0xFFFFFFFF
} STAFFSEntryType_t;

typedef enum STAFFSComparePathResult_e
{
    kSTAFFSDoesNotIncludePath = 0,
    kSTAFFSDoesIncludePath = 1,
    kSTAFFSSamePath = 2
} STAFFSComparePathResult_t;

typedef struct STAFFSEnumHandleImpl *STAFFSEnumHandle_t;
typedef struct STAFFSEntryImpl *STAFFSEntry_t;
typedef struct STAFFSOSFileLockImpl *STAFFSOSFileLock_t;

/*****************************************************************************/
/*                         General File System APIs                          */
/*****************************************************************************/

/*****************************************************************************/
/* STAFFSInfo - Returns information about the OS's file system               */
/*                                                                           */
/* Accepts: (Out) Pointer to return data                                     */
/*          (In)  The type of information to retrieve                        */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) The types kSTAFFSPathSep, kSTAFFSFileSep, and kSTAFFSLineSep  */
/*             return data of type STAFString_t.  You are responsible for    */
/*             call STAFStringDestruct on these returned strings.            */
/*          2) The type kSTAFFSCaseSensitivity returns data of type          */
/*             STAFFSCaseSensitive_t.                                        */
/*****************************************************************************/
STAFRC_t STAFFSInfo(void *info, STAFFSInfoType_t infoType);


/*****************************************************************************/
/* STAFFSStringMatchesWildcards - Determines whether a given string matches  */
/*                                a given wildcard string                    */
/*                                                                           */
/* Accepts: (In)  String to check                                            */
/*          (In)  String containg wildcards                                  */
/*          (In)  Case sensitivity indicator                                 */
/*          (Out) Result of comparison (0 = no match, 1 = matches)           */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) Two wildcard characters are understood.  '*' matches zero or  */
/*             more characters.  '?' matches one single character.           */
/*****************************************************************************/
STAFRC_t STAFFSStringMatchesWildcards(STAFStringConst_t stringToCheck,
                                      STAFStringConst_t wildcardString,
                                      STAFFSCaseSensitive_t sensitive,
                                      unsigned int *matches);

/*****************************************************************************/
/* STAFFSComparePaths - Compares two path names after "normalizing" them.    */
/*                      Checks if path1 includes (starts with) path2 or if   */
/*                      path1 is the same as path2.                          */
/*                                                                           */
/* Accepts: (In)  Path name 1                                                */
/*          (In)  Path name 2                                                */
/*          (In)  Case sensitivity indicator                                 */
/*          (Out) Compare result:                                            */
/*                - kSTAFFSDoesNotIncludePath (path1 does not include path2) */
/*                - kSTAFFSDoesIncludePath (path1 includes path2)            */
/*                - kSTAFFSSamePath (path1 and path2 specify the same path)  */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Examples:                                                                 */
/*                                                                           */
/* 1) If called this API passing in the following arguments:                 */
/*      pathName1:  C:/temp/dir1/dir2                                        */
/*      pathName2:  C:/temp/dir2                                             */
/*    this API would set result to kSTAFFSDoesNotIncludePath                 */
/*                                                                           */
/* 2) If called this API passing in the following arguments:                 */
/*      pathName1:  C:/temp/dir1/dir2                                        */
/*      pathName2:  C:/temp  -OR-  C:/temp/dir1                              */
/*    this API would set result to kSTAFFSDoesIncludePath                    */
/*                                                                           */
/* 3) If called this API passing in the following arguments:                 */
/*      pathName1:  C:/temp/dir1/dir2                                        */
/*      pathName2:  C:/temp/dir1/dir2                                        */
/*    this API would set result to kSTAFFSSamePath                           */
/*****************************************************************************/
STAFRC_t STAFFSComparePaths(STAFStringConst_t pathName1,
                            STAFStringConst_t pathName2,
                            STAFFSCaseSensitive_t sensitive,
                            STAFFSComparePathResult_t *result);

/*****************************************************************************/
/*                                Path APIs                                  */
/*****************************************************************************/
/* In general, any STAFString_t returned from an API must be freed by the    */
/* caller.  No STAFStringConst_t passed into an API will be freed.           */
/*****************************************************************************/

/*****************************************************************************/
/* STAFFSAssemblePath - Generates a path string from component pieces        */
/*                                                                           */
/* Accepts: (Out) Pointer to the return string                               */
/*          (In)  A string representing the root of the path                 */
/*          (In)  The number of directory strings                            */
/*          (In)  An array of strings representing directories               */
/*          (In)  A string representing the name of the file system entry    */
/*          (In)  A string representing the extension of the file system     */
/*                entry                                                      */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*****************************************************************************/
STAFRC_t STAFFSAssemblePath(STAFString_t *path, STAFStringConst_t root,
                            unsigned int numDirs, STAFStringConst_t *dirs,
                            STAFStringConst_t name,
                            STAFStringConst_t extension);


/*****************************************************************************/
/* STAFFSDisassemblePath - Breaks a path string into its component pieces    */
/*                                                                           */
/* Accepts: (In)  The path string to disassemble                             */
/*          (Out) Pointer to the string representing the root of the path    */
/*          (Out) Pointer to the number of directory strings                 */
/*          (Out) Pointer to an array of strings representing the            */
/*                directories                                                */
/*          (Out) Pointer to the string representing the name of the file    */
/*                system entry                                               */
/*          (Out) Pointer to the string representing the extension of the    */
/*                file system entry                                          */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) Remember to free the directory array with                     */
/*             STAFFSFreePathDirs()                                          */
/*****************************************************************************/
STAFRC_t STAFFSDisassemblePath(STAFStringConst_t path, STAFString_t *root,
                               unsigned int *numDirs, STAFString_t **dirs,
                               STAFString_t *name, STAFString_t *extension);


/*****************************************************************************/
/* STAFFSFreePathDirs - Frees up the the memory associated with the array    */
/*                      of STAFString_t returned from STAFFSDissassemblePath */
/*                                                                           */
/* Accepts: (In) Pointer to the array of STAFString_t                        */
/*                                                                           */
/* Returns: Standard return codes                                            */
/*                                                                           */
/* Notes  : 1) You are still responsible for freeing the individual          */
/*             STAFString_t that are in the array.  This function simply     */
/*             frees the memory  associated with the array itself.           */
/*****************************************************************************/
STAFRC_t STAFFSFreePathDirs(STAFString_t *dirs);


/*****************************************************************************/
/*                          File System Entry APIs                           */
/*****************************************************************************/

/*****************************************************************************/
/* STAFFSExists - Determines whether a given file system entry exists        */
/*                                                                           */
/* Accepts: (In)  Path string                                                */
/*          (Out) Pointer to unsigned int indicating if the entry exists     */
/*                (0 = no, 1 = yes)                                          */