HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
FS_Reader.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: FS_Reader.h ( FS Library, C++)
7  *
8  * COMMENTS:
9  *
10  */
11 
12 #ifndef __FS_Reader__
13 #define __FS_Reader__
14 
15 #include "FS_API.h"
16 #include <time.h>
17 #include <SYS/SYS_Types.h>
18 #include <UT/UT_NonCopyable.h>
19 #include <UT/UT_String.h>
20 #include <UT/UT_ValArray.h>
21 #include "FS_ReaderStream.h"
22 
23 class UT_Options;
24 class UT_StringArray;
25 class FS_IndexFile;
26 class FS_ReaderHelper;
28 
29 /// Class for reading files
31 {
32 public:
33  FS_Reader();
34 
35  /// Use this constructor to create a new reader. The specified file is
36  /// opened immediately.
37  /// Common options:
38  /// - "string cache_mode" - Specify the "caching" pattern. This gives a
39  /// hint to the file system about how the stream will be accessed.
40  /// * "normal" - Normal caching
41  /// * "random" - Access pattern is random
42  /// * "sequential" - Access pattern is sequential
43  /// - "int buffer_size" - Specify the buffer size (see setvbuf)
44  /// - "bool ascii" - Specify whether the file should be opened in ASCII
45  /// read mode for automatically translating line-endings.
46  FS_Reader(const char *source, const UT_Options *options=0);
47 
48  /// NOTE: This new FS_Reader takes ownership of the FS_ReaderStream
49  FS_Reader(FS_ReaderStream *sourcestream);
50  virtual ~FS_Reader();
51 
52  /// Get the amount of memory owned by this FS_Reader
53  virtual int64 getMemoryUsage(bool inclusive) const;
54 
55  /// Closes the stream. After calling this function, the getStream()
56  /// function will always return @c NULL.
57  void close();
58 
59  /// This function is used to check if the file was successfully opened
60  bool isGood()
61  { return myStream && myStream->isGood(); }
62 
63  /// This function retrieves the C++ stream object which you can interact
64  /// with in the normal ways. If this function returns @c NULL, the file
65  /// specified in the constructor could not be found.
66  UT_IStream *getStream() const;
67 
68  // Obtains a stream reader that reads a portion of this reader's stream.
69  // Note, the underlying buffers are shared, invoking this method will
70  // advance the current read position to the subset's beginning, and any
71  // subsequent reading will further advance the read position.
72  FS_ReaderStream *shareDataAndGetSubstream(int64 stream_offset,
73  int64 sub_stream_size, int64 sub_data_size,
74  const FS_IStreamFilterFactory * f = NULL) const;
75 
76  time_t getModTime() const;
77  int64 getLength() const;
78  void getFilename( UT_String &filename ) const;
79 
80  // Obtains filter factories that are piggyacked from another FS_IndexFile.
81  FS_IStreamFilterFactory *getSubStreamReadFilterFactory() const;
82  FS_WriteFilterFactory *getSubStreamWriteFilterFactory() const;
83 
84  // Functions for adding and removing helpers.
85  static void addReaderHelper(FS_ReaderHelper *helper);
86  static void removeReaderHelper(FS_ReaderHelper *helper);
87 
88  /// @{
89  /// Utility fuction to split the original source path into the index file
90  /// path and the section name. It asks all registered reader helpers
91  /// whether they recognize the source path protocol and can provide the
92  /// section name. If none of the helpers do, then it tries FS_IndexFile to
93  /// split the source path on '?' by default.
94  /// @param[in] source_section_path The original source path to split.
95  /// @param[out] index_file_path If the original source path refers to
96  /// an index file section, this parameter is set to the
97  /// index file path. Otherwise, it is set to the
98  /// source_section_path parameter.
99  /// @param[out] section_name If the original source path refers to
100  /// and index file section, this parameter is set to the
101  /// name of that section. Otherwise, it is set to an empty
102  /// string. If there are many nested sections in the source
103  /// path, then this argument will contain the innermost
104  /// section name, and the index_file_path will point
105  /// to the containing section (itself an index file).
106  /// @param[out] section_names If the original source path refers to
107  /// a section that is nested within other
108  /// sections (that themselves are index files), then
109  /// this parameter is set to these section names, with
110  /// the outermost section at the beginning of the array
111  /// and the innermost section (contained within the outer
112  /// sections) at the end of the array. If there is just
113  /// a single section, the array will contain just one
114  /// entry (ie, the single section name),
115  /// and the call will be equivalent to the method
116  /// that takes just the single string.
117  /// @return True if the path refered to a section name and the outgoing
118  /// parameter 'section_name' contains a non-empty string;
119  /// otherwise, returns false.
120  static bool splitIndexFileSectionPath(
121  const char *source_section_path,
122  UT_String &index_file_path,
123  UT_String &section_name);
124  static bool splitIndexFileSectionPath(
125  const char *source_section_path,
126  UT_StringHolder &index_file_path,
127  UT_StringHolder &section_name);
128  static bool splitIndexFileSectionPath(
129  const char *source_section_path,
130  UT_String &index_file_path,
131  UT_StringArray &section_names );
132  /// @}
133 
134  /// @{
135  /// Utility function to combine index file name and section name into the
136  /// section path. It asks all registered reader helpers
137  /// whether they recognize the index_file_path path protocol and can
138  /// combine it with the section name into the section full path.
139  /// If none of the helpers do, then it asks FS_IndexFile to
140  /// combine the components, joining them with '?' by default.
141  /// @param[out] source_section_path The combined section full path.
142  /// @param[in] index_file_path The base path to the index file.
143  /// @param[in] section_name The name of the section inside the index file.
144  /// @param[in] section_names The names of the nested sections in
145  /// the index file, with the outermost section at the
146  /// beginning of the array and the innermost section
147  /// (contained within the outer sections) at the end
148  /// of the array. If the array contains only one entry,
149  /// it's equivalent to the method that takes just a single
150  /// string.
151  static void combineIndexFileSectionPath(
152  UT_String &source_section_path,
153  const char *index_file_path,
154  const char *section_name);
155  static void combineIndexFileSectionPath(
156  UT_String &source_section_path,
157  const char *index_file_path,
158  const UT_StringArray &section_names );
159  /// @}
160 
161 
162 private:
163  void createStreamFromSource(const char *source,
164  const UT_Options *options);
165 
166  static UT_ValArray<FS_ReaderHelper *> &getHelpers();
167 
168  FS_ReaderStream *myStream;
169 };
170 
171 /// This class provides a plug-in method for adding a custom "file-system"
172 /// @see FS_WriterHelper, FS_InfoHelper
174 {
175 public:
177  { FS_Reader::addReaderHelper(this); }
180 
181  /// Return an FS_ReaderStream if the helper is able to open the source
182  /// filename.
183  ///
184  /// The options are passed through directly from the FS_Reader
185  /// constructor. See FS_Reader for list of options.
186  virtual FS_ReaderStream *createStream(const char *source,
187  const UT_Options *options=NULL) = 0;
188 
189  /// Parse the source path into the index file path and the section name.
190  ///
191  /// The FS library recognizes a special source format for FS_IndexFile,
192  /// which is a file containing several sections indexed and accessible
193  /// by their name. That source format contains '?' as a separator between
194  /// the file path and the section name.
195  /// FS_Reader scans for '?' in the source path before asking helpers
196  /// to handle it. This way index files are supported for custom protoclos
197  /// automatically without them needing to implement it explicitly.
198  /// Eg, "myfiles:path/to/indexfile?section" will work automaticaly, since
199  /// FS_Reader will ask the helper for a read stream for
200  /// "myfiles:/path/to/indexfile" but will create and use the "section"
201  /// read stream itself.
202  /// The downside is that custom protocols can't use '?' in their path
203  /// format. To address this isse, this method has been added to let the
204  /// helpers decide how to handle the '?'.
205  ///
206  /// If the helper does not use '?' for any special purpose, it does not need
207  /// to override this virtual (or it can overloaded it and return false).
208  /// If the helper uses '?' for some special meaning (or if it supports some
209  /// custom syntax to refer to sections of an index file), then it should
210  /// override it and return true. Further, it can return a non-empty section
211  /// name if the protocol supports section naming and the source path indeed
212  /// refers to a section in an index file. Or, it can return an empty string
213  /// for the section name, if the source path does not refer to an index
214  /// file (or if helper does not want the automatic index file handling and
215  /// plans to handle index files explicitly by itself).
216  ///
217  /// @param[in] source_section_path Original source path to be opened for
218  /// reading.
219  /// @param[out] index_file_path If source_section_path refers to a section
220  /// in an index file, then this parameter is set to the index
221  /// file path (and method returns true).
222  /// If source_section_path does not refer to a section, then
223  /// this parameter is set to original path, ie, equal to
224  /// source_section_path (and method returns true).
225  /// If the helper does not recognize the source_section_path
226  /// (ie, it's another protocol), or if recognizes it but does
227  /// not need (nor want) custom handling for '?' separator,
228  /// then this parameter is not set (and method returns false).
229  /// @param[out] section_name This Similar to index_file_path, but this
230  /// outgoing parameter is set to the section name, if
231  /// source_section_path refers to a section and is set to
232  /// empty-string if it does not (and method returns true).
233  /// If the method returns false, it is not set.
234  ///
235  /// @return True if the source_section_path can be handled by the
236  /// helper, in which case index_file_path and section_name
237  /// are also set (though section can be an empty-string).
238  /// False if the source_code_path is not handled by helper,
239  /// or if helper wants default index file naming convention
240  /// (with '?' splitting the file and section name).
241  ///
242  virtual bool splitIndexFileSectionPath(const char *source_section_path,
243  UT_String &index_file_path,
244  UT_String &section_name)
245  {
246  return false;
247  }
248 
249  /// Utility function to combine index file name and section name into the
250  /// section path. Performs the reverse of splitIndexFileSectionPath().
251  /// If the helper does not use '?' for any special purpose in the source
252  /// path, then it does not need to override this virtual (see above).
253  /// @param[out] source_section_path The combined full section path.
254  /// @param[in] index_file_path The base path to the index file.
255  /// @param[in] section_name The name of the section inside the index file.
256  /// @return True if the helper recognizes the 'index_file_path' as its
257  /// own file protocol. False, if it does not recognize the
258  /// protocol or if it wants the default joining of file and
259  /// section names using the default convention of '?' to
260  /// join the components.
262  UT_String &source_section_path,
263  const char *index_file_path,
264  const char *section_name)
265  {
266  return false;
267  }
268 };
269 
270 #endif
271 
Class for reading files.
Definition: FS_Reader.h:30
static void addReaderHelper(FS_ReaderHelper *helper)
virtual ~FS_ReaderHelper()
Definition: FS_Reader.h:178
long long int64
Definition: SYS_Types.h:100
GLfloat f
Definition: glcorearb.h:1925
static void removeReaderHelper(FS_ReaderHelper *helper)
virtual bool splitIndexFileSectionPath(const char *source_section_path, UT_String &index_file_path, UT_String &section_name)
Definition: FS_Reader.h:242
GLsizei GLsizei GLchar * source
Definition: glcorearb.h:802
A map of string to various well defined value types.
Definition: UT_Options.h:42
virtual void close()
bool isGood()
This function is used to check if the file was successfully opened.
Definition: FS_Reader.h:60
#define FS_API
Definition: FS_API.h:10
virtual bool combineIndexFileSectionPath(UT_String &source_section_path, const char *index_file_path, const char *section_name)
Definition: FS_Reader.h:261