aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/efreet/efreet_base.h
blob: ca011d95a355ed7467118b0bb93f6d2f2bb584b5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
#ifndef EFREET_BASE_H
#define EFREET_BASE_H
/**
 * @file efreet_base.h
 * @brief Contains the methods used to support the FDO base directory
 * specification.
 * @addtogroup Efreet_Base Efreet_Base: The XDG Base Directory Specification
 * functions
 * @ingroup Efreet
 *
 * @see http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
 * @see http://0pointer.de/blog/projects/tmp.html
 *
 * @{
 */


/**
 * @return Returns the XDG Data Home directory
 * @brief Retrieves the XDG Data Home directory
 *
 * This is where user-specific data files should be written
 * ($XDG_DATA_HOME or $HOME/.local/share).
 */
EAPI const char *efreet_data_home_get(void);

/**
 * @return Returns the Eina_List of preference ordered extra data directories
 * @brief Returns the Eina_List of preference ordered extra data directories
 *
 * Ordered base directories relative to which data files should be
 * searched ($XDG_DATA_DIRS or /usr/local/share/:/usr/share/)
 *
 * @note The returned list is static inside Efreet. If you add/remove from the
 * list then the next call to efreet_data_dirs_get() will return your
 * modified values. DO NOT free this list.
 */
EAPI Eina_List *efreet_data_dirs_get(void);


/**
 * @return Returns the XDG Config Home directory
 * @brief Retrieves the XDG Config Home directory
 *
 * This is where user-specific configuration files should be
 * written ($XDG_CONFIG_HOME or $HOME/.config).
 */
EAPI const char *efreet_config_home_get(void);

/**
 * @return Returns the XDG Desktop directory
 * @brief Retrieves the XDG Desktop directory
 *
 * This is where user-specific desktop files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @since 1.3
 */
EAPI const char *efreet_desktop_dir_get(void);

/**
 * @return Returns the XDG Download directory
 * @brief Retrieves the XDG Download directory
 *
 * This is where user-specific download files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * It's meant for large download or in-progress downloads, it's
 * private for the user but may be shared among different
 * machines. It's not automatically cleaned up.
 *
 * @see efreet_cache_home_get()
 * @see efreet_runtime_dir_get()
 * @see http://0pointer.de/blog/projects/tmp.html
 *
 * @since 1.8
 */
EAPI const char *efreet_download_dir_get(void);

/**
 * @return Returns the XDG Templates directory
 * @brief Retrieves the XDG Templates directory
 *
 * This is where user-specific template files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @see efreet_documents_dir_get()
 * @see efreet_music_dir_get()
 * @see efreet_pictures_dir_get()
 * @see efreet_videos_dir_get()
 *
 * @since 1.8
 */
EAPI const char *efreet_templates_dir_get(void);

/**
 * @return Returns the XDG Public Share directory
 * @brief Retrieves the XDG Public Share directory
 *
 * This is where user-specific public shareable files should be
 * located. It's localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * Usually local file servers should look here (Apache, Samba, FTP).
 *
 * @since 1.8
 */
EAPI const char *efreet_public_share_dir_get(void);

/**
 * @return Returns the XDG Documents directory
 * @brief Retrieves the XDG Documents directory
 *
 * This is where user-specific documents files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @see efreet_templates_dir_get()
 * @see efreet_music_dir_get()
 * @see efreet_pictures_dir_get()
 * @see efreet_videos_dir_get()
 *
 * @since 1.8
 */
EAPI const char *efreet_documents_dir_get(void);

/**
 * @return Returns the XDG Music directory
 * @brief Retrieves the XDG Music directory
 *
 * This is where user-specific music files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @see efreet_templates_dir_get()
 * @see efreet_download_dir_get()
 * @see efreet_pictures_dir_get()
 * @see efreet_videos_dir_get()
 *
 * @since 1.8
 */
EAPI const char *efreet_music_dir_get(void);

/**
 * @return Returns the XDG Pictures directory
 * @brief Retrieves the XDG Pictures directory
 *
 * This is where user-specific pictures files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @see efreet_templates_dir_get()
 * @see efreet_documents_dir_get()
 * @see efreet_music_dir_get()
 * @see efreet_videos_dir_get()
 *
 * @since 1.8
 */
EAPI const char *efreet_pictures_dir_get(void);

/**
 * @return Returns the XDG Videos directory
 * @brief Retrieves the XDG Videos directory
 *
 * This is where user-specific video files should be located. It's
 * localized (translated) to current user locale
 * (~/.config/user-dirs.locale and ~/.config/user-dirs.dirs).
 *
 * @see efreet_templates_dir_get()
 * @see efreet_documents_dir_get()
 * @see efreet_music_dir_get()
 * @see efreet_pictures_dir_get()
 *
 * @since 1.8
 */
EAPI const char *efreet_videos_dir_get(void);

/**
 * @return Returns the Eina_List of preference ordered extra config directories
 * @brief Returns the Eina_List of preference ordered extra config
 * directories
 *
 * Ordered base directories relative to which configuration files
 * should be searched ($XDG_CONFIG_DIRS or /etc/xdg)
 *
 * @note The returned list is static inside Efreet. If you add/remove from the
 * list then the next call to efreet_config_dirs_get() will return your
 * modified values. DO NOT free this list.
 */
EAPI Eina_List *efreet_config_dirs_get(void);


/**
 * @return Returns the XDG Cache Home directory
 * @brief Retrieves the XDG Cache Home directory
 *
 * This is the base directory relative to which user specific
 * non-essential data files should be stored ($XDG_CACHE_HOME or
 * $HOME/.cache).
 *
 * @see efreet_runtime_dir_get()
 * @see efreet_download_dir_get()
 * @see efreet_config_home_get()
 */
EAPI const char *efreet_cache_home_get(void);

/**
 * @return Returns the XDG User Runtime directory.
 * @brief Retrieves the XDG User Runtime directory.
 *
 * This is the base directory relative to which user-specific
 * non-essential runtime files and other file objects (such as
 * sockets, named pipes, ...) should be stored. The directory @b must
 * be owned by the user, and he @b must be the only one having read
 * and write access to it. Its Unix access mode @b must be 0700.
 *
 * The lifetime of this directory @b must be bound to the user being
 * logged in. It @b must be created when the user first logs in and if
 * the user fully logs out the directory @b must be removed. If the
 * user logs in more than once he should get pointed to the same
 * directory, and it is mandatory that the directory continues to
 * exist from his first login to his last logout on the system, and
 * not removed in between. Files in the directory @b must not survive
 * reboot or a full logout/login cycle.
 *
 * The directory @b must be on a local file system and not shared with
 * any other system. The directory @b must by fully-featured by the
 * standards of the operating system. More specifically, on Unix-like
 * operating systems AF_UNIX sockets, symbolic links, hard links,
 * proper permissions, file locking, sparse files, memory mapping,
 * file change notifications, a reliable hard link count must be
 * supported, and no restrictions on the file name character set
 * should be imposed. Files in this directory @b may be subjected to
 * periodic clean-up. To ensure that your files are not removed, they
 * should have their access time timestamp modified at least once
 * every 6 hours of monotonic time or the 'sticky' bit should be set
 * on the file.
 *
 * If @c NULL applications should fall back to a replacement directory
 * with similar capabilities and print a warning message. Applications
 * should use this directory for communication and synchronization
 * purposes and should not place larger files in it, since it might
 * reside in runtime memory and cannot necessarily be swapped out to
 * disk.
 *
 * @note this directory is similar to @c /run and is often created in
 * tmpfs (memory-only/RAM filesystem). It is created, managed and
 * cleaned automatically by systemd.
 *
 * @since 1.8
 */
EAPI const char *efreet_runtime_dir_get(void);

/**
 * @return Returns the current hostname
 * @brief Returns the current hostname or empty string if not found
 */
EAPI const char *efreet_hostname_get(void);

/**
 * Efreet_Event_Cache_Update
 */
typedef struct _Efreet_Event_Cache_Update Efreet_Event_Cache_Update;

/**
 * Efreet_Event_Cache_Update
 * @brief event struct sent with EFREET_EVENT_*_CACHE_UPDATE
 */
struct _Efreet_Event_Cache_Update
{
    int error;
};

/**
 * @}
 */

#endif