1 /***************************************************************************
2     This is the global namespace for Smb4K.
3                              -------------------
4     begin                : Sa Apr 2 2005
5     copyright            : (C) 2005-2020 by Alexander Reinholdt
6     email                : alexander.reinholdt@kdemail.net
7  ***************************************************************************/
8 
9 /***************************************************************************
10  *   This program is free software; you can redistribute it and/or modify  *
11  *   it under the terms of the GNU General Public License as published by  *
12  *   the Free Software Foundation; either version 2 of the License, or     *
13  *   (at your option) any later version.                                   *
14  *                                                                         *
15  *   This program is distributed in the hope that it will be useful, but   *
16  *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
17  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
18  *   General Public License for more details.                              *
19  *                                                                         *
20  *   You should have received a copy of the GNU General Public License     *
21  *   along with this program; if not, write to the                         *
22  *   Free Software Foundation, Inc., 51 Franklin Street, Suite 500, Boston,*
23  *   MA 02110-1335, USA                                                    *
24  ***************************************************************************/
25 
26 #ifndef SMB4KGLOBAL_H
27 #define SMB4KGLOBAL_H
28 
29 // Qt includes
30 #include <QMap>
31 #include <QString>
32 #include <QList>
33 #include <QEvent>
34 #include <QStringList>
35 #include <QSharedPointer>
36 
37 // forward declarations
38 class Smb4KBasicNetworkItem;
39 class Smb4KWorkgroup;
40 class Smb4KHost;
41 class Smb4KShare;
42 class Smb4KFile;
43 class Smb4KBookmark;
44 class Smb4KCustomOptions;
45 
46 // type definitions
47 typedef QSharedPointer<Smb4KBasicNetworkItem> NetworkItemPtr;
48 typedef QSharedPointer<Smb4KWorkgroup> WorkgroupPtr;
49 typedef QSharedPointer<Smb4KHost> HostPtr;
50 typedef QSharedPointer<Smb4KShare> SharePtr;
51 typedef QSharedPointer<Smb4KFile> FilePtr;
52 typedef QSharedPointer<Smb4KBookmark> BookmarkPtr;
53 typedef QSharedPointer<Smb4KCustomOptions> OptionsPtr;
54 
55 // Other definitions
56 #ifndef SMB4K_DEPRECATED
57 #define SMB4K_DEPRECATED __attribute__ ((__deprecated__))
58 #endif
59 
60 
61 /**
62  * This is the global namespace. It provides access to the global lists
63  * of workgroups, hosts and shares, to the global settings of the Samba
64  * configuration and much more.
65  *
66  * @author    Alexander Reinholdt <alexander.reinholdt@kdemail.net>
67  */
68 
69 namespace Smb4KGlobal
70 {
71   /**
72    * The Process enumeration.
73    *
74    * @enum LookupDomains          Look up domains
75    * @enum LookupDomainMembers    Look up those servers that belong to a domain/workgroup
76    * @enum LookupShares           Look up shares on a server
77    * @enum LookupFiles            Look up files and directories within a share
78    * @enum WakeUp                 Send magic Wake-On-LAN packages
79    * @enum PrintFile              Print a file
80    * @enum NetworkSearch          Network search
81    * @enum MountShare             Mount a share
82    * @enum UnmountShare           Unmount a share
83    * @enum NoProcess              No process
84    */
85   enum Process {
86     LookupDomains,
87     LookupDomainMembers,
88     LookupShares,
89     LookupFiles,
90     WakeUp,
91     PrintFile,
92     NetworkSearch,
93     MountShare,
94     UnmountShare,
95     NoProcess };
96 
97   /**
98    * The enumeration to determine the type of a network item.
99    *
100    * @enum Network                The network
101    * @enum Workgroup              A workgroup
102    * @enum Host                   A host
103    * @enum Share                  A share
104    * @enum Directory              A directory in a shared folder
105    * @enum File                   A file in a shared folder
106    * @enum UnknownNetworkItem     An unknown network item
107    */
108   enum NetworkItem {
109     Network,
110     Workgroup,
111     Host,
112     Share,
113     Directory,
114     File,
115     UnknownNetworkItem };
116 
117   /**
118    * The enumeration that determines the share type
119    *
120    * @enum FileShare              a file share
121    * @enum PrinterShare           a printer share
122    * @enum IpcShare               an IPC share
123    */
124   enum ShareType {
125     FileShare,
126     PrinterShare,
127     IpcShare,
128   };
129 
130   /**
131    * Use this function to initialize the core classes. Besides starting several
132    * core classes such as the scanner (for an initial browse list) and the mounter
133    * (for the import of all externally mounted shares), it also sets some default
134    * values for some of the settings used to browse the network.
135    *
136    * By setting the @p modifyCursor parameter to TRUE, you force the core classes
137    * to set a busy cursor when they do something. Default is FALSE.
138    *
139    * Setting @p initClasses to FALSE will avoid starting the core classes. This
140    * should only the used if you are starting the core classes in a different
141    * way (e. g. if you are starting them in the plasmoid via the Smb4KDeclarative
142    * class).
143    *
144    * You should execute this function before starting your main application.
145    */
146   Q_DECL_EXPORT void initCore(bool modifyCursor = false, bool initClasses = true);
147 
148   /**
149    * Aborts all actions that are run by the core classes and that can be aborted.
150    */
151   Q_DECL_EXPORT void abortCore();
152 
153   /**
154    * Check if at least one of the core classes that use KJobs (scanner, mounter, etc.)
155    * is running.
156    *
157    * @returns TRUE if at least one of the core classes is doing something.
158    */
159   Q_DECL_EXPORT bool coreIsRunning();
160 
161   /**
162    * Check if the core has been initialized through the initCore() function.
163    *
164    * @returns TRUE if the core has already been initialized.
165    */
166   Q_DECL_EXPORT bool coreIsInitialized();
167 
168   /**
169    * This function returns the global list of workgroups that were discovered by
170    * Smb4K. Use this if you want to access and modify the list with your code.
171    *
172    * @returns the global list of known workgroups.
173    */
174   Q_DECL_EXPORT const QList<WorkgroupPtr> &workgroupsList();
175 
176   /**
177    * This function returns the workgroup or domain that matches the name @p name or
178    * NULL if there is no such workgroup.
179    *
180    * @returns a pointer to the workgroup with name @p name.
181    */
182   Q_DECL_EXPORT WorkgroupPtr findWorkgroup(const QString &name);
183 
184   /**
185    * This function takes a workgroup @p workgroup, checks whether it is already
186    * in the list of domains and adds it to the list if necessary. It returns TRUE
187    * if the workgroup was added and FALSE otherwise.
188    *
189    * Please prefer this function over per class solutions.
190    *
191    * @param workgroup   The workgroup item
192    *
193    * @returns TRUE if the workgroup was added and FALSE otherwise.
194    */
195   Q_DECL_EXPORT bool addWorkgroup(WorkgroupPtr workgroup);
196 
197   /**
198    * This function takes a workgroup @p workgroup, and updates the respective workgroup
199    * in the global list, if it exists. It returns TRUE on success and FALSE otherwise.
200    * If you want to add a workgroup to the global list, use @see addWorkgroup().
201    *
202    * Please prefer this function over per class solutions.
203    *
204    * @returns TRUE if the workgroup was updated and FALSE otherwise
205    */
206   Q_DECL_EXPORT bool updateWorkgroup(WorkgroupPtr workgroup);
207 
208   /**
209    * This function removes a workgroup @p workgroup from the list of domains. The
210    * pointer that is passed to this function will be deleted. You won't be able
211    * to use it afterwards. This function returns TRUE if the workgroup was removed
212    * and FALSE otherwise.
213    *
214    * Please prefer this function over per class solutions.
215    *
216    * @param workgroup   The workgroup item
217    *
218    * @returns TRUE if the workgroup was removed and FALSE otherwise.
219    */
220   Q_DECL_EXPORT bool removeWorkgroup(WorkgroupPtr workgroup);
221 
222   /**
223    * This function clears the global list of workgroups.
224    */
225   Q_DECL_EXPORT void clearWorkgroupsList();
226 
227   /**
228    * This function returns the global list of hosts that were discovered by
229    * Smb4K. Use this if you want to access and modify the list with your code.
230    *
231    * @returns the global list of known hosts.
232    */
233   Q_DECL_EXPORT const QList<HostPtr> &hostsList();
234 
235   /**
236    * This function returns the host matching the name @p name or NULL if there is no
237    * such host. The name of the host is mandatory. The workgroup may be empty, but
238    * should be given, because this will speed up the search process.
239    *
240    * @param name          The name of the host
241    *
242    * @param workgroup     The workgroup where the host is located
243    *
244    * @returns an Smb4KHost item of NULL if none was found that matches @p name.
245    */
246   Q_DECL_EXPORT HostPtr findHost(const QString &name, const QString &workgroup = QString());
247 
248   /**
249    * This function takes a host @p host, checks whether it is already
250    * in the list of hosts and adds it to the list if necessary. It returns TRUE
251    * if the host was added and FALSE otherwise.
252    *
253    * Please prefer this function over per class solutions.
254    *
255    * @param host          The host item
256    *
257    * @returns TRUE if the host was added and FALSE otherwise.
258    */
259   Q_DECL_EXPORT bool addHost(HostPtr host);
260 
261   /**
262    * This function takes an host @p host, and updates the respective host
263    * in the global list, if it exists. It returns TRUE on success and FALSE otherwise.
264    * If you want to add an host to the global list, use @see addHost().
265    *
266    * Please prefer this function over per class solutions.
267    *
268    * @returns TRUE if the host was updated and FALSE otherwise
269    */
270   Q_DECL_EXPORT bool updateHost(HostPtr host);
271 
272   /**
273    * This function removes a host @p host from the list of hosts. The
274    * pointer that is passed to this function will be deleted. You won't
275    * be able to use it afterwards. This function returns TRUE if the host was removed
276    * and FALSE otherwise.
277    *
278    * Please prefer this function over per class solutions.
279    *
280    * @param host          The host item
281    *
282    * @returns TRUE if the host was removed and FALSE otherwise.
283    */
284   Q_DECL_EXPORT bool removeHost(HostPtr host);
285 
286   /**
287    * This function clears the global list of hosts.
288    */
289   Q_DECL_EXPORT void clearHostsList();
290 
291   /**
292    * This function returns all hosts that belong to the workgroup or domain
293    * @p workgroup.
294    *
295    * Please favor this function over per class solutions.
296    *
297    * @param workgroup   The workgroup for that the list should be returned.
298    *
299    * @returns the list of hosts belonging to the workgroup or domain @param workgroup.
300    */
301   Q_DECL_EXPORT QList<HostPtr> workgroupMembers(WorkgroupPtr workgroup);
302 
303   /**
304    * This function returns the list of shares that were discovered by Smb4K.
305    * Use this if you want to access and modify the list with your code.
306    *
307    * @returns the global list of known shares.
308    */
309   Q_DECL_EXPORT const QList<SharePtr> &sharesList();
310 
311   /**
312    * This function returns the share with URL @p url located in the workgroup or
313    * domain @p workgroup. If there is no such share, 0 is returned. The workgroup
314    * entry may be empty.
315    *
316    * @param url           The URL of the share
317    *
318    * @param workgroup     The workgroup
319    *
320    * @returns the share that matches @p url and optionally @p workgroup or 0.
321    */
322   Q_DECL_EXPORT SharePtr findShare(const QUrl &url, const QString &workgroup = QString());
323 
324   /**
325    * This function takes a share @p share, checks whether it is already
326    * in the list of shares and adds it to the list if necessary. It returns TRUE
327    * if the share was added and FALSE otherwise.
328    *
329    * Please prefer this function over per class solutions.
330    *
331    * @param share         The share item
332    *
333    * @returns TRUE if the share was added and FALSE otherwise.
334    */
335   Q_DECL_EXPORT bool addShare(SharePtr share);
336 
337   /**
338    * This function takes a share @p share, and updates the respective share
339    * in the global list, if it exists. It returns TRUE on success and FALSE otherwise.
340    * If you want to add a share to the global list, use @see addShare().
341    *
342    * Please prefer this function over per class solutions.
343    *
344    * @returns TRUE if the share was updated and FALSE otherwise
345    */
346   Q_DECL_EXPORT bool updateShare(SharePtr share);
347 
348   /**
349    * This function removes a share @p share from the list of shares. The
350    * pointer that is passed to this function will be deleted. You won't
351    * be able to use it afterwards. This function returns TRUE if the share was removed
352    * and FALSE otherwise.
353    *
354    * Please prefer this function over per class solutions.
355    *
356    * @param share         The share item
357    *
358    * @returns TRUE if the share was removed and FALSE otherwise.
359    */
360   Q_DECL_EXPORT bool removeShare(SharePtr share);
361 
362   /**
363    * This function clears the global list of shares.
364    */
365   Q_DECL_EXPORT void clearSharesList();
366 
367   /**
368    * This function returns the list of shares that is provided by one specific host
369    * @p host.
370    *
371    * Please favor this function over per class solutions.
372    *
373    * @param host          The host where the shares are located
374    *
375    * @returns the list of shares that are provided by the host @p host.
376    */
377   Q_DECL_EXPORT QList<SharePtr> sharedResources(HostPtr host);
378 
379   /**
380    * This function returns the global list of mounted shares that were discovered by
381    * Smb4K. Use this if you want to access and modify the list with your code.
382    *
383    * @returns the global list of known mounted shares.
384    */
385   Q_DECL_EXPORT const QList<SharePtr> &mountedSharesList();
386 
387   /**
388    * Find a mounted share by its path (i.e. mount point).
389    *
390    * @returns the share that is mounted to @p path.
391    */
392   Q_DECL_EXPORT SharePtr findShareByPath(const QString &path);
393 
394   /**
395    * Find all mounts of a particular share with URL @p url on the system.
396    *
397    * This function will compare the incoming URL with the URL of each
398    * mounted share to find all shares with the same URL. For the comparison
399    * the user info and the port will be stripped.
400    *
401    * @param url         The URL of the share
402    *
403    * @returns the complete list of mounts with the URL @p url.
404    */
405   Q_DECL_EXPORT QList<SharePtr> findShareByUrl(const QUrl &url);
406 
407   /**
408    * This function returns the list of inaccessible shares.
409    *
410    * @returns the list of inaccessible shares.
411    */
412   Q_DECL_EXPORT QList<SharePtr> findInaccessibleShares();
413 
414   /**
415    * This function takes a mounted share @p share, checks whether it is
416    * already in the list of mounted shares and adds it to the list if
417    * necessary. It returns TRUE if the share was added and FALSE otherwise.
418    *
419    * Please prefer this function over per class solutions.
420    *
421    * @param share       The share item
422    *
423    * @returns TRUE if the share was added and FALSE otherwise.
424    */
425   Q_DECL_EXPORT bool addMountedShare(SharePtr share);
426 
427   /**
428    * This function takes a mounted share @p share and updates the share that
429    * is already present in the internal list.
430    *
431    * @param share       The share item
432    * @returns TRUE if a share was found and updated. Returns FALSE otherwise.
433    */
434   Q_DECL_EXPORT bool updateMountedShare(SharePtr share);
435 
436   /**
437    * This function removes a mounted share @p share from the list of mounted
438    * shares. The pointer that is passed to this function will be deleted.
439    * You won't be able to use it afterwards. This function returns TRUE if
440    * the share was removed and FALSE otherwise.
441    *
442    * Please prefer this function over per class solutions.
443    *
444    * @param share       The share item
445    *
446    * @returns TRUE if the share was removed and FALSE otherwise.
447    */
448   Q_DECL_EXPORT bool removeMountedShare(SharePtr share);
449 
450   /**
451    * This function returns TRUE if only shares are present that are owned by
452    * other users and FALSE otherwise.
453    *
454    * @returns TRUE if there are only shares that are owned by other users.
455    */
456   Q_DECL_EXPORT bool onlyForeignMountedShares();
457 
458   /**
459    * This enumeration determines with which application the mount point
460    * of the current mounted share is to be opened.
461    */
462   enum OpenWith { FileManager,
463                   Konsole };
464 
465   /**
466    * Open the mount point of a share. Which application is used is determined by
467    * the value of @p openWith and - maybe - by settings that were defined by the
468    * user.
469    *
470    * @param share         The share that is to be opened.
471    *
472    * @param openWith      Integer of type Smb4KCore::OpenWith. Determines with which
473    *                      application the share should be opened.
474    */
475   Q_DECL_EXPORT void openShare(SharePtr share, OpenWith openWith = FileManager);
476 
477   /**
478    * Get the NetBIOS name of this computer.
479    *
480    * @returns the NetBIOS name
481    */
482   Q_DECL_EXPORT const QString machineNetbiosName();
483 
484   /**
485    * Get the name of the workgroup or domain this computer is in.
486    *
487    * @returns the workgroup or domain
488    */
489   Q_DECL_EXPORT const QString machineWorkgroupName();
490 
491   /**
492    * This function returns TRUE if the core classes should set a busy cursor when
493    * they are doing something.
494    *
495    * @returns TRUE in case a busy cursor should be set.
496    */
497   Q_DECL_EXPORT bool modifyCursor();
498 
499 #if defined(Q_OS_LINUX)
500   /**
501    * This list contains all allowed arguments for the mount.cifs binary and
502    * is only present under the Linux operating system.
503    */
504   Q_DECL_EXPORT QStringList allowedMountArguments();
505 #endif
506 
507   /**
508    * Find the mount executable on the system.
509    *
510    * @returns the path of the mount executable.
511    */
512   Q_DECL_EXPORT const QString findMountExecutable();
513 
514   /**
515    * Find the umount executable on the system.
516    *
517    * @returns the path of the umount executable.
518    */
519   Q_DECL_EXPORT const QString findUmountExecutable();
520 
521   /**
522    * This function returns the directory where data is to be placed.
523    * @returns the data location
524    */
525   Q_DECL_EXPORT const QString dataLocation();
526 };
527 
528 #endif
529