1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef _TEMPLATE_SCANNER_HXX
25 #define _TEMPLATE_SCANNER_HXX
26 
27 #include "tools/AsynchronousTask.hxx"
28 #include "sddllapi.h"
29 #include <ucbhelper/content.hxx>
30 #include <tools/string.hxx>
31 #include "com/sun/star/uno/Reference.hxx"
32 
33 #include <vector>
34 #include <boost/scoped_ptr.hpp>
35 
36 namespace com { namespace sun { namespace star { namespace ucb {
37 class XContent;
38 class XCommandEnvironment;
39 } } } }
40 
41 namespace com { namespace sun { namespace star { namespace sdbc {
42 class XResultSet;
43 } } } }
44 
45 namespace sd {
46 
47 /** Representation of a template or layout file.
48 */
49 class TemplateEntry
50 {
51 public:
TemplateEntry(const String & rsTitle,const String & rsPath)52     TemplateEntry   (const String& rsTitle, const String& rsPath)
53         :   msTitle(rsTitle), msPath(rsPath) {}
54 
55     String msTitle;
56     String msPath;
57 };
58 
59 
60 
61 
62 /** Representation of a template or layout folder.
63 */
64 class TemplateDir
65 {
66 public:
TemplateDir(const String & rsRegion,const String & rsUrl)67     TemplateDir (const String& rsRegion, const String& rsUrl )
68         :   msRegion(rsRegion), msUrl(rsUrl), maEntries() {}
69 
70     String msRegion;
71     String msUrl;
72     ::std::vector<TemplateEntry*> maEntries;
73 };
74 
75 
76 
77 
78 /** This class scans the template folders for impress templates.  There are
79     two ways to use this class.
80     1. The old and deprecated way is to call Scan() to scan all templates
81     and collect the supported ones in a tree structure.  This structure is
82     returned by GetFolderList().
83     2. The new way implements the AsynchronousTask interface.  Call
84     RunNextStep() as long HasNextStep() returns <TRUE/>.  After every step
85     GetLastAddedEntry() returns the template that was scanned (and has a
86     supported format) last.  When a step does not add a new template then
87     the value of the previous step is returned.
88 */
89 class SD_DLLPUBLIC TemplateScanner
90     : public ::sd::tools::AsynchronousTask
91 {
92 public:
93     /** Create a new template scanner and prepare but do not execute the scanning.
94     */
95     TemplateScanner (void);
96 
97     /** The destructor deletes any remaining entries of the local list of
98         templates.
99     */
100     virtual ~TemplateScanner (void);
101 
102     /** Execute the actual scanning of templates.  When this method
103         terminates the result can be obtained by calling the
104         <member>GetTemplateList</member> method.
105     */
106     void Scan (void);
107 
108     /** Return the list of template folders.  It lies in the responsibility
109         of the caller to take ownership of some or all entries and remove
110         them from the returned list.  All entries that remain until the
111         destructor is called will be destroyed.
112     */
113     std::vector<TemplateDir*>& GetFolderList (void);
114 
115     /** Implementation of the AsynchronousTask interface method.
116     */
117     virtual void RunNextStep (void);
118 
119     /** Implementation of the AsynchronousTask interface method.
120     */
121     virtual bool HasNextStep (void);
122 
123     /** Return the TemplateDir object that was last added to
124         mpTemplateDirectory.
125         @return
126             <NULL/> is returned either before the template scanning is
127             started or after it has ended.
128     */
129     const TemplateEntry* GetLastAddedEntry (void) const;
130 
131 private:
132     /** The current state determines which step will be executed next by
133         RunNextStep().
134     */
135     enum State {
136         INITIALIZE_SCANNING,
137         INITIALIZE_FOLDER_SCANNING,
138         GATHER_FOLDER_LIST,
139         SCAN_FOLDER,
140         INITIALIZE_ENTRY_SCAN,
141         SCAN_ENTRY,
142         DONE,
143         ERROR
144     };
145     State meState;
146 
147     ::ucbhelper::Content maFolderContent;
148     TemplateDir* mpTemplateDirectory;
149 
150     /** The data structure that is to be filled with information about the
151         template files.
152     */
153      std::vector<TemplateDir*> maFolderList;
154 
155     /** This member points into the maFolderList to the member that was most
156         recently added.
157     */
158     TemplateEntry* mpLastAddedEntry;
159 
160     /** The folders that are collected by GatherFolderList().
161     */
162     class FolderDescriptorList;
163     ::boost::scoped_ptr<FolderDescriptorList> mpFolderDescriptors;
164 
165     /** Set of state variables used by the methods
166         InitializeFolderScanning(), GatherFolderList(), ScanFolder(),
167         InitializeEntryScanning(), and ScanEntry().
168     */
169     com::sun::star::uno::Reference<com::sun::star::ucb::XContent> mxTemplateRoot;
170     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxFolderEnvironment;
171     com::sun::star::uno::Reference<com::sun::star::ucb::XCommandEnvironment> mxEntryEnvironment;
172     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxFolderResultSet;
173     com::sun::star::uno::Reference<com::sun::star::sdbc::XResultSet> mxEntryResultSet;
174 
175     /** Obtain the root folder of the template folder hierarchy.  The result
176         is stored in mxTemplateRoot for later use.
177     */
178     State GetTemplateRoot (void);
179 
180     /** Initialize the scanning of folders.  This is called exactly once.
181         @return
182             Returns one of the two states ERROR or GATHER_FOLDER_LIST.
183     */
184     State InitializeFolderScanning (void);
185 
186     /** Collect all available top-level folders in an ordered list which can
187         then be processed by ScanFolder().
188         @return
189             Returns one of the two states ERROR or SCAN_FOLDER.
190     */
191     State GatherFolderList (void);
192 
193     /** From the list of top-level folders collected by GatherFolderList()
194         the one with highest priority is processed.
195         @return
196             Returns one of the states ERROR, DONE, or INITILIZE_ENTRY_SCAN.
197     */
198     State ScanFolder (void);
199 
200     /** Initialize the scanning of entries of a top-level folder.
201         @return
202             Returns one of the states ERROR or SCAN_ENTRY.
203     */
204     State InitializeEntryScanning (void);
205 
206     /** Scan one entry.  When this entry matches the recognized template
207         types it is appended to the result set.
208         @return
209             Returns one of the states ERROR, SCAN_ENTRY, or SCAN_FOLDER.
210     */
211     State ScanEntry (void);
212 };
213 
214 } // end of namespace sd
215 
216 #endif
217