/*================================================================================================== Copyright (c) 2013 Siemens PLM Unpublished - All rights reserved ====================================================================================================*/ /** @file Contains the definition of the directory class. This class is useful to complete all sort of operation on OS-related directories. */ /** */ #ifndef FCLASSES_OSDIRECTORY_INCLUDE_HXX #define FCLASSES_OSDIRECTORY_INCLUDE_HXX /** @file Provides various methods to manipulate directories. */ #include #include #include #include namespace Teamcenter { /** @brief Manipulates a directory. It provides a wide range of methods to create, delete, rename, etc. a directory. */ class FCLASSES_API OSDirectory { public: /** Defines the different OS types to consider for operations */ enum OSType { TCSERVER_OS = 0, /**< The operating system to consider for the operation will be the one of the Teamcenter server. */ UNIX_OS, /**< The operation will run using the UNIX operating system and its folder separator character '/'. */ WINDOWS_OS /**< The operation will run using the Windows operating system and its folder separator character '\'. */ }; /** Constructs an instance of OSDir based on the path to the specified directory.
The value for the @p iOSType parameter will be used for getLeafName(), copyDirectory() and wipeOut() methods. It is recommended to use the default value #TCSERVER_OS. @param[in] iDirectoryPath The path to the directory to be managed by this class. @param[in] iOSType Possible overloading of the OS directory separator. */ OSDirectory(const char *iDirectoryPath, OSType iOSType=TCSERVER_OS); /** Copy constructor */ OSDirectory(const OSDirectory&); /** Default constructor
The current work directory will be used. */ OSDirectory(OSType iOSType=TCSERVER_OS); /** Destructor */ virtual ~OSDirectory(); /** Operator equal definition */ OSDirectory& operator = (const OSDirectory&); /** Returns the name of the directory or the file at the end of a path.

Use the @p iOSType parameter to specify the separator to consider, if needed. @param[in] iDirectoryPath The path to the directory for which to extract the directory name. @param[in] iOSType Possible overloading of the OS directory separator. @returns The name of the leaf directory If the path is empty, it'll return a 0 pointer. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ static char* getLeafName( const char* iDirectoryPath, OSType iOSType=TCSERVER_OS ); /** Returns the name of the directory or the file at the end of a path. @returns The name of the leaf directory If the path is empty, it'll return a 0 pointer. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ char* getLeafName() const; /** Appends either a sub-directory path or a sub-file path to a directory path.

Use the @p iOSType parameter to specify the separator to consider, if needed. @param[in] iDirectoryPath The initial directory path. @param[in] iSubPath The path to append. @param[in] iOSType Possible overloading of the OS directory separator. @returns The merged path. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ static char *mergePaths(const char *iDirectoryPath, const char *iSubPath, OSType iOSType=TCSERVER_OS); /** Generates a pseudo-random, unique string suitable for temporary directory and file names.
The name is generated by concatenation of the current time, process id and a pseudo-random number. @param[in] iPrefix A prefix to the auto-generated name. @returns The generated unique name. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ static char* generateUniqueName(const char* iPrefix = 0); /** Retrieves the current work directory. @returns The name of the current work directory.
If it cannot be found the returned pointer will be 0. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ static char* getCurrentWorkDirectory(); /** Retrieves the full path as it was passed in the constructor. @returns The full path name. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ char *getDirectoryPath() const; /** Checks if the directory exists. @param[out] oDirectoryExists Bears the existence status @returns
  • ITK_ok if the status can be determined without errors.
  • Possibly other errors, in which case the out value for the parameter @p oDirectoryExists is false.
*/ int exists(bool& oDirectoryExists) const; /** Creates the directory with the permission as specified in the @p iMode arguments

The value for the mode is a numeric mode is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2 and 1. Any omitted digits are assumed to be leading zeros:
  • The first digit selects the set user ID (4) and set group ID (2) and sticky (1) attributes. Leave it as 0 if unsure.
  • The second digit selects permissions for the user who owns the file: read(4), write(2) and execute (1).
  • The third selects permissions for other users in the file's group, with the same values.
  • The fourth for other users not in the file's group, with the same values.
The following modes can be used as defined in the ITK documentation group SS_CONST: SS_ALL_PERMISSIONS_DMODE, SS_DEF_FMODE, SS_DEF_DMODE, SS_NO_WORLD_ACCESS_FMODE, SS_NO_WORLD_ACCESS_DMODE @param[in] iMode The needed mode as explained above. By default, the directories are created with the mode SS_DEF_DMODE (user can read/write, all others can only read). @returns
  • ITK_ok if the directory is created with the specified permission.
  • SS_ALREADYOPEN if the directory has been opened and not closed.
  • SS_DIREXISTS if the directory already exists.
  • Possibly other errors.
*/ int create (int iMode = SS_DEF_DMODE); /** Changes the access permission of a directory.

Refer to the create() method for explanation on the values for the @p iMode parameter. @param[in] iMode The requested mode as explained above. @returns
  • ITK_ok if the permission has correctly been modified.
  • Possibly other errors.
*/ int chmod(int iMode); /** Changes the current work directory, as well as the directory of the OSDirectory instance.

The directory needs to be closed before calling this method. @param[in] iDirectoryPath The path to the new current work directory. If the pointer is 0, the directory of the OSDirectory instance will become the new current work directory. @returns
  • ITK_ok if the directory has correctly been changed.
  • SS_ALREADYOPEN if the directory was not closed prior to the call.
  • Possibly other errors.
*/ int setCurrentWorkDirectory(const char *iDirectoryPath); /** Deletes the directory.
It needs to be closed prior to this call. @returns
  • ITK_ok if the directory has been deleted.
  • SS_FILEBUSY if the directory is opened. This might be an indication that the directory does not exist.
  • Possibly other errors.
*/ int deleteDirectory(); /** Opens the directory. @returns
  • ITK_ok if the directory is correctly being opened.
  • SS_ALREADYOPEN if the directory is already opened.
  • Possibly other errors.
*/ int open(); /** Closes the directory. @returns
  • ITK_ok if the directory is correctly being closed.
  • SS_FILENOTOPEN if the directory is already closed.
  • Possibly other errors.
*/ int close(); /** Reads the content of the directory located at the directory pointer position, and then increments this pointer.
The directory needs to be opened prior to calling this method.

Calls have to be made in a recursive manner in order to parse the whole directory content. @code OSDirectory directory( pathToDirectory ); //Open the directory if( directory.open() != ITK_ok ) { return; } //Loop reading the directory entries std::vector directoryVector; std::vector fileVector; SS_file_status fileStatus; while(directory.readDirectory(&fileStatus) == ITK_ok) { if( fileStatus.ftype == SS_DIRECTORY ) { directoryVector.append( Teamcenter::OSDirectory(fileStatus.path) ); } else if( fileStatus.ftype == SS_FILE ) { fileVector.append( Teamcenter::OSFile(fileStatus.path, fileStatus.fmt); } } @endcode @param[in,out] ioStatus The status for the read element. @returns
  • ITK_ok on success (an element has been read)
  • SS_EOF if there is no more element to read
  • SS_FILENOTOPEN if the directory is not opened
  • SS_NOREADDIR if the user does not have directory access
  • Possibly other errors
*/ int readDirectory(SS_file_status *ioStatus); /** Reads the content of the directory located at the directory pointer position, and then increments this pointer.
The difference with the readDirectory() method is that the output structure data member "fmt" is not populated. This improves performances.
The directory needs to be opened prior to calling this method.

Calls have to be made in a recursive manner in order to parse the whole directory content. @param[in,out] ioStatus The status for the read element. @returns
  • ITK_ok on success (an element has been read)
  • SS_EOF if there is no more element to read
  • SS_FILENOTOPEN if the directory is not opened
  • SS_NOREADDIR if the user does not have directory access
  • Possibly other errors
*/ int readDirectoryWithoutFormatData(SS_file_status *ioStatus); /** Copies the directory and its contents to another directory. If the destination directory does not exist, the method will create it. @param[in] iDestinationPath Path to the destination directory @returns
  • ITK_ok if the directory has correctly been copied.
  • Possibly other errors. Note that the directory copy might have then been partially completed.
*/ int copyDirectory (const char *iDestinationPath); /** Wipes out the whole content of a directory (files and sub-directories included), and possibly the directory itself. @param[in] iDeleteOnlyIfEmpty If set to true, the directory will only be deleted if there is no file in the directory and any of its sub-directories. @returns
  • ITK_ok on success
  • -1 if the directory has been wiped out, but not deleted because of files existing in the directory. This return code is to be expected if the parameter @p iDeleteOnlyIfEmpty is set to true.
  • VM_NO_DELETE_DIR if the directory or any of its content could not be deleted. This can happen if the directory does not exist.
  • VM_PATH_TOO_BIG if the path of one of the directory component is too long.
  • VM_UNRECOGNIZED_FORMAT if the directory contains an object that can be recognized neither as a directory nor as a file.
*/ int wipeOut(bool iDeleteOnlyIfEmpty=false); /** Returns the list of directories directly contained under the current directory.
The method will open the directory if it's not already opened, and it will also close it if it had to open it.

The method does not return directories that are not directly under the current directory. @param[out] oListDirectories The list of found directories. @returns
  • ITK_ok on success
  • Possibly other errors
*/ int listSubDirectories( std::vector& oListDirectories ); /** Returns the list of files directly located under the current directory.
The method will open the directory if it's not already opened, and it will also close it if it had to open it.

The method does not return files that are located in sub-directories. @param[out] oListFiles The list of found files. @returns
  • ITK_ok on success
  • Possibly other errors
*/ int listFiles( std::vector& oListFiles ); /** Returns the list of directories and files directly contained under the current directory.
The method will open the directory if it's not already opened, and it will also close it if it had to open it.

The structure of any sub-directory is not retrieved. @param[out] oListDirectories The list of found directories. @param[out] oListFiles The list of found files. @returns
  • ITK_ok on success
  • Possibly other errors
*/ int listContent( std::vector& oListDirectories, std::vector& oListFiles ); /** Dumps the content of a OSDirectory object, printing all of its attributes.
All references to other objects will only be dumped as hexadecimal addresses. @note The returned pointer needs to be free through a call to MEM_free or Teamcenter::scoped_smptr. */ virtual char *asString() const; private: /** Lists the content of a directory */ int listContent(std::vector& oListDirectories, std::vector& oListFiles, int file_format); /** Defines the type of directory (Windows or UNIX) */ OSType m_osType; /** The path to the directory */ char* m_directoryPath; /** Directory descriptor */ SS_dir m_directoryDescriptor; /** Status of the directory */ struct { int error_status; const char* operation; } m_directoryStatus; /** Constants defining the different types of operations done on the OSDirectory instance */ static const char* OPERATION_CONSTRUCTOR; static const char* OPERATION_COPYCONST; static const char* OPERATION_OPERATOREQUALS; static const char* OPERATION_CREATE; static const char* OPERATION_OPEN; static const char* OPERATION_CLOSE; static const char* OPERATION_DELETEDIR; static const char* OPERATION_EXISTS; static const char* OPERATION_CHMOD; static const char* OPERATION_SETDIRPATH; static const char* OPERATION_READ; }; } #include #endif