File indexing completed on 2024-04-21 15:42:50
0001 /*************************************************************************** 0002 Smb4K's container class for information about a share. 0003 ------------------- 0004 begin : Mo Jan 28 2008 0005 copyright : (C) 2008-2019 by Alexander Reinholdt 0006 email : alexander.reinholdt@kdemail.net 0007 ***************************************************************************/ 0008 0009 /*************************************************************************** 0010 * This program is free software; you can redistribute it and/or modify * 0011 * it under the terms of the GNU General Public License as published by * 0012 * the Free Software Foundation; either version 2 of the License, or * 0013 * (at your option) any later version. * 0014 * * 0015 * This program is distributed in the hope that it will be useful, but * 0016 * WITHOUT ANY WARRANTY; without even the implied warranty of * 0017 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 0018 * General Public License for more details. * 0019 * * 0020 * You should have received a copy of the GNU General Public License * 0021 * along with this program; if not, write to the * 0022 * Free Software Foundation, Inc., 51 Franklin Street, Suite 500, Boston,* 0023 * MA 02110-1335, USA * 0024 ***************************************************************************/ 0025 0026 #ifndef SMB4KSHARE_H 0027 #define SMB4KSHARE_H 0028 0029 // application specific includes 0030 #include "smb4kbasicnetworkitem.h" 0031 0032 // Qt includes 0033 #include <QString> 0034 #include <QStringList> 0035 #include <QtGlobal> 0036 #include <QScopedPointer> 0037 #include <QHostAddress> 0038 0039 // KDE includes 0040 #include <KCoreAddons/KUser> 0041 0042 // forward declarations 0043 class Smb4KAuthInfo; 0044 class Smb4KSharePrivate; 0045 0046 class Q_DECL_EXPORT Smb4KShare : public Smb4KBasicNetworkItem 0047 { 0048 friend class Smb4KSharePrivate; 0049 0050 public: 0051 /** 0052 * This constructor takes the host name @p hostName and the name of the 0053 * shared resource @p shareName. All other information has to be set by the 0054 * other functions this class provides. 0055 * 0056 * This constructor will also assemble the UNC from the provided arguments. 0057 * 0058 * @param hostName The name of the host where the share is 0059 * located. 0060 * 0061 * @param shareName The name of the share. 0062 */ 0063 Smb4KShare(const QString &hostName, const QString &shareName); 0064 0065 /** 0066 * This constructor takes the URL @p url as only argument. All other 0067 * information has to be set by the other functions this class provides. 0068 * 0069 * @param url The URL 0070 */ 0071 explicit Smb4KShare(const QUrl &url); 0072 0073 /** 0074 * This is the copy constructor. It takes another Smb4KShare item and copies all 0075 * its values. 0076 * 0077 * @param share The Smb4KShare item that is to be copied 0078 */ 0079 Smb4KShare(const Smb4KShare &share); 0080 0081 /** 0082 * The empty constructor. You need to set all information by the functions that 0083 * are provided with this class. 0084 */ 0085 Smb4KShare(); 0086 0087 /** 0088 * The destructor. 0089 */ 0090 ~Smb4KShare(); 0091 0092 /** 0093 * Sets the name of the share (*not* the UNC). 0094 * 0095 * @param name The share name 0096 */ 0097 void setShareName(const QString &name); 0098 0099 /** 0100 * Returns the name of the share, e.g. "Music", "Data", etc. 0101 * 0102 * @returns the name of the share. 0103 */ 0104 QString shareName() const; 0105 0106 /** 0107 * Sets the name of the host where the share is located. 0108 * 0109 * @param hostName The host name 0110 */ 0111 void setHostName(const QString &hostName); 0112 0113 /** 0114 * Returns the name of the host where the share is located. 0115 * 0116 * @returns the host name 0117 */ 0118 QString hostName() const; 0119 0120 /** 0121 * In case of a 'homes' share, this function returns the URL of the user's 0122 * home repository. 0123 * 0124 * If the share is not a 'homes' share or no user name for the homes share 0125 * has been defined, this function returns an empty string. 0126 * 0127 * @returns the user's home repository's URL. 0128 */ 0129 QUrl homeUrl() const; 0130 0131 /** 0132 * Returns the display string. Prefer this over all other alternatives in your 0133 * GUI. 0134 * 0135 * @param showHomesShare Show the name of the users home share instead of 'homes' 0136 * in case this is a homes share. Setting this argument on a 0137 * non-homes share does nothing. 0138 * 0139 * @returns the display string. 0140 */ 0141 QString displayString(bool showHomeShare = false) const; 0142 0143 /** 0144 * Set the workgroup where the host is located that offers this share. 0145 * 0146 * @param workgroup The name of the workgroup 0147 */ 0148 void setWorkgroupName(const QString &workgroup); 0149 0150 /** 0151 * Returns the name of the workgroup where the host is located that 0152 * offers this share. 0153 * 0154 * @returns the workgroup name 0155 */ 0156 QString workgroupName() const; 0157 0158 /** 0159 * Set the type of the share as reported by the server. 0160 * 0161 * @param type The type of the string 0162 */ 0163 void setShareType(Smb4KGlobal::ShareType type); 0164 0165 /** 0166 * Returns the type of the share as reported by the server. If you are 0167 * looking for a translated type string, then use the shareTypeString() 0168 * function. 0169 * 0170 * @returns the type of the share. 0171 */ 0172 Smb4KGlobal::ShareType shareType() const; 0173 0174 /** 0175 * Returns the translated type string of the share. You can use this 0176 * in the GUI. 0177 * 0178 * @returns a translated type string. 0179 */ 0180 QString shareTypeString() const; 0181 0182 /** 0183 * Sets the comment that was defined for the share. 0184 * 0185 * @param comment The comment for the share 0186 */ 0187 void setComment(const QString &comment); 0188 0189 /** 0190 * Returns the comment that was defined for this share. 0191 * 0192 * @returns the comment. 0193 */ 0194 QString comment() const; 0195 0196 /** 0197 * Set the IP address of the host where the share is located. @p ip will 0198 * only be accepted if it is compatible with either IPv4 or IPv6. 0199 * 0200 * @param ip The host's IP address 0201 */ 0202 void setHostIpAddress(const QString &ip); 0203 0204 /** 0205 * Set the IP address of the host where the share is located. @p ip will only be accepted 0206 * if it is compatible with either IPv4 or IPv6. 0207 * 0208 * @param ip The host's IP address 0209 */ 0210 void setHostIpAddress(const QHostAddress &address); 0211 0212 /** 0213 * Returns the IP address of the host. If the IP address was not compatible 0214 * with IPv4 and IPv6 or if no IP address was supplied, an empty string is 0215 * returned. 0216 * 0217 * @returns the IP address of the host or an empty string. 0218 */ 0219 QString hostIpAddress() const; 0220 0221 /** 0222 * Returns TRUE if the host's IP address is set and FALSE otherwise. 0223 * 0224 * @returns TRUE if the host's IP address is set and FALSE otherwise. 0225 */ 0226 bool hasHostIpAddress() const; 0227 0228 /** 0229 * If the share is a hidden one, i.e. it ends with a '$', this function returns 0230 * TRUE and FALSE otherwise. 0231 * 0232 * @returns TRUE if this is a hidden share. 0233 */ 0234 bool isHidden() const; 0235 0236 /** 0237 * If the share is a printer this function returns TRUE and otherwise FALSE. 0238 * 0239 * @returns TRUE if the share is a printer. 0240 */ 0241 bool isPrinter() const; 0242 0243 /** 0244 * Sets the path aka mount point of the share as gathered by the mounter. 0245 * 0246 * @param mountpoint The mount point of the share. 0247 */ 0248 void setPath(const QString &mountpoint); 0249 0250 /** 0251 * Returns the path to the mounted share (aka the mount point) as it was gathered 0252 * by the mounter. It is a C-type string. 0253 * 0254 * @returns the path to the mounted share. 0255 */ 0256 QString path() const; 0257 0258 /** 0259 * Returns the canonical path to the mounted share. In contrast to the path() 0260 * function it will return the absolute path without symlinks. However, should 0261 * the share be inaccessible (i.e. the isInaccessible() returns TRUE), only 0262 * the "normal" path is returned. 0263 * 0264 * @returns the canonical path to the mounted share. 0265 */ 0266 QString canonicalPath() const; 0267 0268 /** 0269 * Set @p in to TRUE if the share cannot be accessed by the user. This may be 0270 * because if strict permissions or because the remote server went offline. By 0271 * default it is assumed that the share is accessible. 0272 * 0273 * @param in Tells if the share is inaccessible or not. 0274 */ 0275 void setInaccessible(bool in); 0276 0277 /** 0278 * Returns TRUE if the share is mounted and not accessible by the user. 0279 * 0280 * @returns TRUE if the share is mounted and inaccessible. 0281 */ 0282 bool isInaccessible() const; 0283 0284 /** 0285 * If the share was mounted by another user, @p foreign should be set to TRUE. 0286 * By default it is assumed that the share is not foreign but owned by the 0287 * user. 0288 * 0289 * @param foreign TRUE if the share is foreign and FALSE otherwise. 0290 */ 0291 void setForeign(bool foreign); 0292 0293 /** 0294 * Returns TRUE if the share is mounted and is owned by another user. 0295 * 0296 * @returns TRUE if this is a foreign share. 0297 */ 0298 bool isForeign() const; 0299 0300 /** 0301 * Returns the file system as string in capital letters. If no file system 0302 * was specified, an empty string is returned. 0303 * 0304 * @returns the file system string or an empty string. 0305 */ 0306 QString fileSystemString() const; 0307 0308 /** 0309 * Sets the owner of this share. 0310 * @param user The UID of the owner 0311 */ 0312 void setUser(const KUser &user); 0313 0314 /** 0315 * Returns the owner of this share or the current user, if 0316 * the owner was not set using @see setUser(). 0317 * @returns the owner. 0318 */ 0319 KUser user() const; 0320 0321 /** 0322 * Set the group that owns this share. 0323 * @param group The owning GID 0324 */ 0325 void setGroup(const KUserGroup &group); 0326 0327 /** 0328 * Returns the group that owns this share or the current group, if 0329 * the group was not set using @see setGroup(). 0330 * @returns the group. 0331 */ 0332 KUserGroup group() const; 0333 0334 /** 0335 * Sets the value of the total disk space that is available on the share. If 0336 * the disk usage could not be determined, @p size has to be set to 0. 0337 * 0338 * @param total The total disk space that is available on the share 0339 */ 0340 void setTotalDiskSpace(qulonglong size); 0341 0342 /** 0343 * Returns the total disk space that is available on the share or 0 if the 0344 * total disk space was not set or could not be determined. 0345 * 0346 * @returns the total disk space or 0. 0347 */ 0348 qulonglong totalDiskSpace() const; 0349 0350 /** 0351 * Returns the total disk space in a human readable form with value and unit 0352 * (e.g. 10 KiB, 25 MiB, etc.) even if the total disk space was not set or could 0353 * not be determined. If the value is a valid one, you have to check by evaluating 0354 * the return value of the isInaccessible() function. 0355 * 0356 * @returns the total disk space in a human readable form. 0357 */ 0358 QString totalDiskSpaceString() const; 0359 0360 /** 0361 * Sets the value of the free disk space that is available on the share. If 0362 * the free disk space could not be determined, @p size has to be set to 0. 0363 * 0364 * @param free The free disk space that is available on the share 0365 */ 0366 void setFreeDiskSpace(qulonglong size); 0367 0368 /** 0369 * Returns the free disk space that is available on the share or 0 if the 0370 * free disk space was not set or could not be determined. 0371 * 0372 * @returns the free disk space or 0. 0373 */ 0374 qulonglong freeDiskSpace() const; 0375 0376 /** 0377 * Returns the free disk space in a human readable form with value and unit 0378 * (e.g. 10 KiB, 25 MiB, etc.) even if the free disk space was not set or could 0379 * not be determined. If the value is a valid one, you have to check by evaluating 0380 * the return value of the isInaccessible() function. 0381 * 0382 * @returns the free disk space in a human readable form. 0383 */ 0384 QString freeDiskSpaceString() const; 0385 0386 /** 0387 * Sets the value of the disk space that is used on the share. If the used 0388 * disk space could not be determined, @p size has to be set to 0. 0389 * 0390 * @param free The free disk space that is available on the share 0391 */ 0392 void setUsedDiskSpace(qulonglong size); 0393 0394 /** 0395 * Returns the used disk space that is used on the share or 0 if the 0396 * used disk space was not set or could not be determined. 0397 * 0398 * @returns the used disk space or 0. 0399 */ 0400 qulonglong usedDiskSpace() const; 0401 0402 /** 0403 * Returns the used disk space in a human readable form with value and unit 0404 * (e.g. 10 KiB, 25 MiB, etc.) even if the used disk space was not set or could 0405 * not be determined. If the value is a valid one, you have to check by evaluating 0406 * the return value of the isInaccessible() function. 0407 * 0408 * @returns the used disk space in a human readable form. 0409 */ 0410 QString usedDiskSpaceString() const; 0411 0412 /** 0413 * Returns the disk usage in percent. 0414 0415 * @returns the disk usage in percent. 0416 */ 0417 qreal diskUsage() const; 0418 0419 /** 0420 * Returns the disk usage in a human readable form with value and unit, 0421 * for example 3.5 %, 67.0 % etc. If the usage was not set or could not 0422 * be determined, this function returns an empty string. 0423 * 0424 * @returns the disk usage in a human readable form or an empty string. 0425 */ 0426 QString diskUsageString() const; 0427 0428 /** 0429 * If this share was mounted, set @p mounted to TRUE. This function will not 0430 * work with printer shares. 0431 * 0432 * @param mounted Should be set to TRUE if the share was mounted. 0433 */ 0434 void setMounted(bool mounted); 0435 0436 /** 0437 * This function returns TRUE if the share has been mounted and FALSE 0438 * otherwise. 0439 * 0440 * @returns TRUE if this share was mounted. 0441 */ 0442 bool isMounted() const; 0443 0444 /** 0445 * This convenience function sets the mount related data that is copied 0446 * from @p share. 0447 * 0448 * @param share The share object from where the mount related 0449 * data should be copied. 0450 */ 0451 void setMountData(Smb4KShare *share); 0452 0453 /** 0454 * This convenience function resets the mount related data. 0455 */ 0456 void resetMountData(); 0457 0458 /** 0459 * Returns TRUE if the share is or *was* a 'homes' share. That means that 0460 * this value is not changed when the share name is changed. 0461 * 0462 * @returns TRUE if this is or *was* a 'homes' share and FALSE otherwise. 0463 */ 0464 bool isHomesShare() const; 0465 0466 /** 0467 * Set the port for the use in the UNC. 0468 * 0469 * @param port The port 0470 */ 0471 void setPort(int port); 0472 0473 /** 0474 * Returns the port that is used in the UNC. 0475 * 0476 * @returns the port. 0477 */ 0478 int port() const; 0479 0480 /** 0481 * Set the authentication information for the share. This function will add 0482 * the authentication information to the URL of the share. Any previous 0483 * user information including the login will be overwritten. 0484 * 0485 * @param authInfo The authentication information 0486 */ 0487 void setAuthInfo(Smb4KAuthInfo *authInfo); 0488 0489 /** 0490 * Set the login for the share. This function will add the login name 0491 * to the URL of the share. 0492 * 0493 * @param login The login name 0494 */ 0495 void setLogin(const QString &login); 0496 0497 /** 0498 * Returns the login. 0499 * 0500 * @returns the login. 0501 */ 0502 QString login() const; 0503 0504 /** 0505 * Set the password used for authentication. 0506 * 0507 * @param passwd The password 0508 */ 0509 void setPassword(const QString &passwd); 0510 0511 /** 0512 * Returns the password. 0513 * 0514 * @returns the password. 0515 */ 0516 QString password() const; 0517 0518 /** 0519 * Updates the share item if the workgroup name and the UNC of @p share and 0520 * of this item is equal. Otherwise it does nothing. 0521 * @param share The share object that is used to update 0522 * this object 0523 */ 0524 void update(Smb4KShare *share); 0525 0526 private: 0527 const QScopedPointer<Smb4KSharePrivate> d; 0528 0529 /** 0530 * Set up the shares icon. 0531 */ 0532 void setShareIcon(); 0533 }; 0534 0535 #endif