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
13class QString;
14class KSambaShare;
15class KSambaSharePrivate;
16class 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 */
27class KIOCORE_EXPORT KSambaShareData
28{
29public:
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
170private:
171 QExplicitlySharedDataPointer<KSambaShareDataPrivate> dd;
172
173 friend class KSambaSharePrivate;
174};
175
176#endif
177

source code of kio/src/core/ksambasharedata.h