1 /*
2  * Copyright (C) by Christian Kamm <mail@ckamm.de>
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12  * for more details.
13  */
14 
15 #ifndef PINSTATE_H
16 #define PINSTATE_H
17 
18 #include "ocsynclib.h"
19 
20 #include <QObject>
21 
22 namespace OCC {
23 
24 namespace PinStateEnums {
25 OCSYNC_EXPORT Q_NAMESPACE
26 
27 /** Determines whether items should be available locally permanently or not
28  *
29  * The idea is that files and folders can be marked with the user intent
30  * on availability.
31  *
32  * The Inherited state is used for resetting a pin state to what its
33  * parent path would do.
34  *
35  * The pin state of a directory usually only matters for the initial pin and
36  * hydration state of new remote files. It's perfectly possible for a
37  * AlwaysLocal directory to have only OnlineOnly items. (though setting pin
38  * states is usually done recursively, so one'd need to set the folder to
39  * pinned and then each contained item to unpinned)
40  *
41  * Note: This enum intentionally mimics CF_PIN_STATE of Windows cfapi.
42  */
43 enum class PinState {
44     /** The pin state is derived from the state of the parent folder.
45      *
46      * For example new remote files start out in this state, following
47      * the state of their parent folder.
48      *
49      * This state is used purely for resetting pin states to their derived
50      * value. The effective state for an item will never be "Inherited".
51      */
52     Inherited = 0,
53 
54     /** The file shall be available and up to date locally.
55      *
56      * Also known as "pinned". Pinned dehydrated files shall be hydrated
57      * as soon as possible.
58      */
59     AlwaysLocal = 1,
60 
61     /** File shall be a dehydrated placeholder, filled on demand.
62      *
63      * Also known as "unpinned". Unpinned hydrated files shall be dehydrated
64      * as soon as possible.
65      *
66      * If a unpinned file becomes hydrated (such as due to an implicit hydration
67      * where the user requested access to the file's data) its pin state changes
68      * to Unspecified.
69      */
70     OnlineOnly = 2,
71 
72     /** The user hasn't made a decision. The client or platform may hydrate or
73      * dehydrate as they see fit.
74      *
75      * New remote files in unspecified directories start unspecified, and
76      * dehydrated (which is an arbitrary decision).
77      */
78     Unspecified = 3,
79 };
80 Q_ENUM_NS(PinState)
81 
82 /** A user-facing version of PinState.
83  *
84  * PinStates communicate availability intent for an item, but particular
85  * situations can get complex: An AlwaysLocal folder can have OnlineOnly
86  * files or directories.
87  *
88  * For users this is condensed to a few useful cases.
89  *
90  * Note that this is only about *intent*. The file could still be out of date,
91  * or not have been synced for other reasons, like errors.
92  *
93  * NOTE: The numerical values and ordering of this enum are relevant.
94  */
95 enum class VfsItemAvailability {
96     /** The item and all its subitems are hydrated and pinned AlwaysLocal.
97      *
98      * This guarantees that all contents will be kept in sync.
99      */
100     AlwaysLocal = 0,
101 
102     /** The item and all its subitems are hydrated.
103      *
104      * This may change if the platform or client decide to dehydrate items
105      * that have Unspecified pin state.
106      *
107      * A folder with no file contents will have this availability.
108      */
109     AllHydrated = 1,
110 
111     /** There are dehydrated and hydrated items.
112      *
113      * This would happen if a dehydration happens to a Unspecified item that
114      * used to be hydrated.
115      */
116     Mixed = 2,
117 
118     /** There are only dehydrated items but the pin state isn't all OnlineOnly.
119      */
120     AllDehydrated = 3,
121 
122     /** The item and all its subitems are dehydrated and OnlineOnly.
123      *
124      * This guarantees that contents will not take up space.
125      */
126     OnlineOnly = 4,
127 };
128 Q_ENUM_NS(VfsItemAvailability)
129 }
130 using namespace PinStateEnums;
131 
132 }
133 
134 #endif
135