1 /*
2     SPDX-FileCopyrightText: 2010 Rodrigo Belem <rclbelem@gmail.com>
3 
4     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 
7 #ifndef ksambasharedata_h
8 #define ksambasharedata_h
9 
10 #include "kiocore_export.h"
11 #include <QExplicitlySharedDataPointer>
12 
13 class QString;
14 class KSambaShare;
15 class KSambaSharePrivate;
16 class KSambaShareDataPrivate;
17 
18 /**
19  * @class KSambaShareData ksambasharedata.h <KSambaShareData>
20  *
21  * This class represents a Samba user share. It is possible to share a directory with one or more
22  * different names, update the share details or remove.
23  *
24  * @author Rodrigo Belem <rclbelem@gmail.com>
25  * @since  4.7
26  */
27 class KIOCORE_EXPORT KSambaShareData
28 {
29 public:
30     enum GuestPermission {
31         GuestsNotAllowed,
32         GuestsAllowed,
33     };
34 
35     enum UserShareError {
36         UserShareOk,
37         UserShareExceedMaxShares,
38         UserShareNameOk,
39         UserShareNameInvalid,
40         UserShareNameInUse,
41         UserSharePathOk,
42         UserSharePathInvalid,
43         UserSharePathNotExists,
44         UserSharePathNotDirectory,
45         UserSharePathNotAbsolute,
46         UserSharePathNotAllowed,
47         UserShareAclOk,
48         UserShareAclInvalid,
49         UserShareAclUserNotValid,
50         UserShareCommentOk,
51         UserShareGuestsOk,
52         UserShareGuestsInvalid,
53         UserShareGuestsNotAllowed,
54         UserShareSystemError, /* < A system error occurred; check KSambaShare::lastSystemErrorString */
55     };
56 
57     KSambaShareData();
58     KSambaShareData(const KSambaShareData &other);
59 
60     ~KSambaShareData();
61 
62     /**
63      * @return @c the share name.
64      */
65     QString name() const;
66 
67     /**
68      * @return @c the share path.
69      */
70     QString path() const;
71 
72     /**
73      * @return @c the share comment.
74      */
75     QString comment() const;
76 
77     /**
78      * Returns a @c containing a string describing the permission added to the users, such as
79      * "[DOMAIN\]username1:X,[DOMAIN\]username2:X,...". X stands for "F" (full control), "R"
80      * (read-only) and "D" (deny). By default the acl is Everyone:R.
81      *
82      * @return @c the share acl.
83      */
84     QString acl() const;
85 
86     /**
87      * @return @c whether guest access to the share is allowed or not.
88      */
89     KSambaShareData::GuestPermission guestPermission() const;
90 
91     /**
92      * Sets the share name. If the share name is changed and valid it will remove the existing
93      * share and will create a new share.
94      * The share name cannot use a name of a system user or containing the forbidden characters
95      * '%, <, >, *, ?, |, /, \, +, =, ;, :, ",,. To check if the name is available or valid use
96      * the method KSambaShare::isShareNameAvailable().
97      *
98      * @param name the name that will be given to the share.
99      *
100      * @return @c UserShareNameOk if the name is valid.
101      * @return @c UserShareNameInvalid if the name contains invalid characters.
102      * @return @c UserShareNameInUse if the name is already in use by another shared folder or a
103      *            by a system user.
104      */
105     KSambaShareData::UserShareError setName(const QString &name);
106 
107     /**
108      * Set the path for the share.
109      *
110      * @param path the path that will be given to the share.
111      *
112      * @return @c UserSharePathOk if valid.
113      * @return @c UserSharePathInvalid if the path is in invalid format.
114      * @return @c UserSharePathNotExists if the path does not exists.
115      * @return @c UserSharePathNotDirectory if the path points to file instead of a directory.
116      * @return @c UserSharePathNotAbsolute if the path is not is absolute form.
117      * @return @c UserSharePathNotAllowed if the path is not owner by the user.
118      */
119     KSambaShareData::UserShareError setPath(const QString &path);
120 
121     /**
122      * Sets the comment for the share.
123      *
124      * @param comment the comment that will be given to the share.
125      *
126      * @return @c UserShareCommentOk always.
127      */
128     KSambaShareData::UserShareError setComment(const QString &comment);
129 
130     /**
131      * Sets the acl to the share.
132      *
133      * @param acl the acl that will be given to the share.
134      *
135      * @return @c UserShareAclOk if the acl is valid.
136      * @return @c UserShareAclInvalid if the acl has invalid format.
137      * @return @c UserShareAclUserNotValid if one of the users in the acl is invalid.
138      */
139     KSambaShareData::UserShareError setAcl(const QString &acl);
140 
141     /**
142      * Flags if guest is allowed or not to access the share.
143      *
144      * @param permission the permission that will be given to the share.
145      *
146      * @return @c UserShareGuestsOk if the permission was set.
147      * @return @c UserShareGuestsNotAllowed if the system does not allow guest access to the
148      *            shares.
149      */
150     KSambaShareData::UserShareError setGuestPermission(const GuestPermission &permission = KSambaShareData::GuestsNotAllowed);
151 
152     /**
153      * Share the folder with the information that has been set.
154      *
155      * @return @c UserShareOk if the share was added or other errors as applicable. Also see UserShareSystemError.
156      */
157     KSambaShareData::UserShareError save();
158 
159     /**
160      * Unshare the folder held by the object.
161      *
162      * @return @c UserShareOk if the share was removed or other errors as applicable. Also see UserShareSystemError.
163      */
164     KSambaShareData::UserShareError remove();
165 
166     KSambaShareData &operator=(const KSambaShareData &other);
167     bool operator==(const KSambaShareData &other) const;
168     bool operator!=(const KSambaShareData &other) const;
169 
170 private:
171     QExplicitlySharedDataPointer<KSambaShareDataPrivate> dd;
172 
173     friend class KSambaSharePrivate;
174 };
175 
176 #endif
177