1/*
2 * Copyright 2010 Rodrigo Belem <rclbelem@gmail.com>
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) version 3, or any
8 * later version accepted by the membership of KDE e.V. (or its
9 * successor approved by the membership of KDE e.V.), which shall
10 * act as a proxy defined in Section 6 of version 3 of the license.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library. If not, see <http://www.gnu.org/licenses/>
19 */
20
21#ifndef ksambasharedata_h
22#define ksambasharedata_h
23
24#include <QtCore/QExplicitlySharedDataPointer>
25#include <kio/kio_export.h>
26
27class QString;
28class KSambaShare;
29class KSambaSharePrivate;
30class KSambaShareDataPrivate;
31
32/**
33 * This class represents a Samba user share. It is possible to share a directory with one or more
34 * different names, update the share details or remove.
35 *
36 * @author Rodrigo Belem <rclbelem@gmail.com>
37 * @since 4.7
38 */
39class KIO_EXPORT KSambaShareData
40{
41
42public:
43 enum GuestPermission {
44 GuestsNotAllowed,
45 GuestsAllowed
46 };
47
48 enum UserShareError {
49 UserShareOk,
50 UserShareExceedMaxShares,
51 UserShareNameOk,
52 UserShareNameInvalid,
53 UserShareNameInUse,
54 UserSharePathOk,
55 UserSharePathInvalid,
56 UserSharePathNotExists,
57 UserSharePathNotDirectory,
58 UserSharePathNotAbsolute,
59 UserSharePathNotAllowed,
60 UserShareAclOk,
61 UserShareAclInvalid,
62 UserShareAclUserNotValid,
63 UserShareCommentOk,
64 UserShareGuestsOk,
65 UserShareGuestsInvalid,
66 UserShareGuestsNotAllowed,
67 UserShareSystemError
68 };
69
70 KSambaShareData();
71 KSambaShareData(const KSambaShareData &other);
72
73 ~KSambaShareData();
74
75 /**
76 * @return @c the share name.
77 */
78 QString name() const;
79
80 /**
81 * @return @c the share path.
82 */
83 QString path() const;
84
85 /**
86 * @return @c the share comment.
87 */
88 QString comment() const;
89
90 /**
91 * Returns a @c containing a string describing the permission added to the users, such as
92 * "[DOMAIN\]username1:X,[DOMAIN\]username2:X,...". X stands for "F" (full control), "R"
93 * (read-only) and "D" (deny). By dafault the acl is Everyone:R.
94 *
95 * @return @c the share acl.
96 */
97 QString acl() const;
98
99 /**
100 * @return @c whether guest access to the share is allowed or not.
101 */
102 KSambaShareData::GuestPermission guestPermission() const;
103
104 /**
105 * Sets the share name. If the share name is changed and valid it will remove the existing
106 * share and will create a new share.
107 * The share name cannot use a name of a system user or containing the forbidden characters
108 * '%, <, >, *, ?, |, /, \, +, =, ;, :, ",,. To check if the name is available or valid use
109 * the method KSambaShare::isShareNameAvailable().
110 *
111 * @param name the name that will be given to the share.
112 *
113 * @return @c UserShareNameOk if the name is valid.
114 * @return @c UserShareNameInvalid if the name contains invalid characters.
115 * @return @c UserShareNameInUse if the name is already in use by another shared folder or a
116 * by a system user.
117 */
118 KSambaShareData::UserShareError setName(const QString &name);
119
120 /**
121 * Set the path for the share.
122 *
123 * @param path the path that will be given to the share.
124 *
125 * @return @c UserSharePathOk if valid.
126 * @return @c UserSharePathInvalid if the path is in invalid format.
127 * @return @c UserSharePathNotExists if the path does not exists.
128 * @return @c UserSharePathNotDirectory if the path points to file instead of a directory.
129 * @return @c UserSharePathNotAbsolute if the path is not is absolute form.
130 * @return @c UserSharePathNotAllowed if the path is not owner by the user.
131 */
132 KSambaShareData::UserShareError setPath(const QString &path);
133
134 /**
135 * Sets the comment for the share.
136 *
137 * @param comment the comment that will be given to the share.
138 *
139 * @return @c UserShareCommentOk always.
140 */
141 KSambaShareData::UserShareError setComment(const QString &comment);
142
143 /**
144 * Sets the acl to the share.
145 *
146 * @param acl the acl that will be given to the share.
147 *
148 * @return @c UserShareAclOk if the acl is valid.
149 * @return @c UserShareAclInvalid if the acl has invalid format.
150 * @return @c UserShareAclUserNotValid if one of the users in the acl is invalid.
151 */
152 KSambaShareData::UserShareError setAcl(const QString &acl);
153
154 /**
155 * Flags if guest is allowed or not to access the share.
156 *
157 * @param permission the permission that will be given to the share.
158 *
159 * @return @c UserShareGuestsOk if the permission was set.
160 * @return @c UserShareGuestsNotAllowed if the system does not allow guest access to the
161 * shares.
162 */
163 KSambaShareData::UserShareError setGuestPermission(const GuestPermission &permission = KSambaShareData::GuestsNotAllowed);
164
165 /**
166 * Share the folder with the information that has been set.
167 *
168 * @return @c UserShareOk if the share was added.
169 */
170 KSambaShareData::UserShareError save();
171
172 /**
173 * Unshare the folder held by the object.
174 *
175 * @return @c UserShareOk if the share was removed.
176 */
177 KSambaShareData::UserShareError remove();
178
179 KSambaShareData &operator=(const KSambaShareData &other);
180 bool operator==(const KSambaShareData &other) const;
181 bool operator!=(const KSambaShareData &other) const;
182
183private:
184 QExplicitlySharedDataPointer<KSambaShareDataPrivate> dd;
185
186 friend class KSambaSharePrivate;
187};
188
189#endif
190