1 |
capela |
2174 |
/* |
2 |
|
|
Copyright 2010-2011 David Robillard <d@drobilla.net> |
3 |
|
|
|
4 |
|
|
Permission is hereby granted, free of charge, to any person obtaining a |
5 |
|
|
copy of this software and associated documentation files (the "Software"), |
6 |
|
|
to deal in the Software without restriction, including without limitation |
7 |
|
|
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
8 |
|
|
and/or sell copies of the Software, and to permit persons to whom the |
9 |
|
|
Software is furnished to do so, subject to the following conditions: |
10 |
|
|
|
11 |
|
|
The above copyright notice and this permission notice shall be included |
12 |
|
|
in all copies or substantial portions of the Software. |
13 |
|
|
|
14 |
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
15 |
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
16 |
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
17 |
|
|
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR |
18 |
|
|
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, |
19 |
|
|
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR |
20 |
|
|
OTHER DEALINGS IN THE SOFTWARE. |
21 |
|
|
*/ |
22 |
|
|
|
23 |
|
|
/** |
24 |
|
|
@file files.h |
25 |
|
|
C API for the LV2 Files extension <http://lv2plug.in/ns/ext/files>. |
26 |
|
|
*/ |
27 |
|
|
|
28 |
|
|
#ifndef LV2_FILES_H |
29 |
|
|
#define LV2_FILES_H |
30 |
|
|
|
31 |
|
|
#ifdef __cplusplus |
32 |
|
|
extern "C" { |
33 |
|
|
#endif |
34 |
|
|
|
35 |
|
|
#define LV2_FILES_URI "http://lv2plug.in/ns/ext/files" |
36 |
|
|
#define LV2_FILES_PATH_SUPPORT_URI LV2_FILES_URI "#pathSupport" |
37 |
|
|
#define LV2_FILES_NEW_FILE_SUPPORT_URI LV2_FILES_URI "#newFileSupport" |
38 |
|
|
|
39 |
|
|
typedef void* LV2_Files_Host_Data; |
40 |
|
|
|
41 |
|
|
/** |
42 |
|
|
files:pathSupport feature struct. |
43 |
|
|
|
44 |
|
|
To support this feature, the host MUST pass an LV2_Feature struct with @a |
45 |
|
|
URI @ref LV2_FILES_PATH_SUPPORT_URI and @a data pointed to an instance of |
46 |
|
|
this struct. |
47 |
|
|
*/ |
48 |
|
|
typedef struct { |
49 |
|
|
|
50 |
|
|
/** |
51 |
|
|
Opaque host data. |
52 |
|
|
*/ |
53 |
|
|
LV2_Files_Host_Data host_data; |
54 |
|
|
|
55 |
|
|
/** |
56 |
|
|
Map an absolute path to an abstract path for use in plugin state. |
57 |
|
|
@param host_data MUST be the @a host_data member of this struct. |
58 |
|
|
@param absolute_path The absolute path of a file. |
59 |
|
|
@return An abstract path suitable for use in plugin state. |
60 |
|
|
|
61 |
|
|
The plugin MUST use this function to map any paths that will be stored |
62 |
|
|
in plugin state. The returned value is an abstract path which MAY not |
63 |
|
|
be an actual file system path; @ref absolute_path MUST be used to map it |
64 |
|
|
to an actual path in order to use the file. |
65 |
|
|
|
66 |
|
|
Hosts MAY map paths in any way (e.g. by creating symbolic links within |
67 |
|
|
the plugin's state directory or storing a list of referenced files for |
68 |
|
|
later export). Plugins MUST NOT make any assumptions about abstract |
69 |
|
|
paths except that they can be mapped to an absolute path using @ref |
70 |
|
|
absolute_path. Particularly when restoring from state, this absolute |
71 |
|
|
path MAY not be the same as the original absolute path, but the host |
72 |
|
|
MUST guarantee it refers to a file with contents equivalent to the |
73 |
|
|
original. |
74 |
|
|
|
75 |
|
|
This function may only be called within the context of |
76 |
|
|
LV2_Persist.save() or LV2_Persist.restore(). The caller is responsible |
77 |
|
|
for freeing the returned value. |
78 |
|
|
*/ |
79 |
|
|
char* (*abstract_path)(LV2_Files_Host_Data host_data, |
80 |
|
|
const char* absolute_path); |
81 |
|
|
|
82 |
|
|
/** |
83 |
|
|
Map an abstract path from plugin state to an absolute path. |
84 |
|
|
@param host_data MUST be the @a host_data member of this struct. |
85 |
|
|
@param abstract_path An abstract path (e.g. a path from plugin state). |
86 |
|
|
@return An absolute file system path. |
87 |
|
|
|
88 |
|
|
Since abstract paths are not necessarily actual file paths (or at least |
89 |
|
|
not necessarily absolute paths), this function MUST be used in order to |
90 |
|
|
actually open or otherwise use the file referred to by an abstract path. |
91 |
|
|
|
92 |
|
|
This function may only be called within the context of |
93 |
|
|
LV2_Persist.save() or LV2_Persist.restore(). The caller is responsible |
94 |
|
|
for freeing the returned value. |
95 |
|
|
*/ |
96 |
|
|
char* (*absolute_path)(LV2_Files_Host_Data host_data, |
97 |
|
|
const char* abstract_path); |
98 |
|
|
|
99 |
|
|
} LV2_Files_Path_Support; |
100 |
|
|
|
101 |
|
|
/** |
102 |
|
|
files:newFileSupport feature struct. |
103 |
|
|
|
104 |
|
|
To support this feature, the host MUST pass an LV2_Feature struct with @a |
105 |
|
|
URI @ref LV2_FILES_NEW_FILE_SUPPORT_URI and @a data pointed to an instance |
106 |
|
|
of this struct. |
107 |
|
|
*/ |
108 |
|
|
typedef struct { |
109 |
|
|
|
110 |
|
|
/** |
111 |
|
|
Opaque host data. |
112 |
|
|
*/ |
113 |
|
|
LV2_Files_Host_Data host_data; |
114 |
|
|
|
115 |
|
|
/** |
116 |
|
|
Return an absolute path the plugin may use to create a new file. |
117 |
|
|
@param host_data MUST be the @a host_data member of this struct. |
118 |
|
|
@param relative_path The relative path of the file. |
119 |
|
|
@return The absolute path to use for the new file. |
120 |
|
|
|
121 |
|
|
The plugin can assume @a relative_path is relative to a namespace |
122 |
|
|
dedicated to that plugin instance; hosts MUST ensure this, e.g. by |
123 |
|
|
giving each plugin instance its own state directory. The returned path |
124 |
|
|
is absolute and thus suitable for creating and using a file, but NOT |
125 |
|
|
suitable for storing in plugin state (it MUST be mapped to an abstract |
126 |
|
|
path using @ref LV2_Files_Path_Support::abstract_path to do so). |
127 |
|
|
|
128 |
|
|
This function may be called from any non-realtime context. The caller |
129 |
|
|
is responsible for freeing the returned value. |
130 |
|
|
*/ |
131 |
|
|
char* (*new_file_path)(LV2_Files_Host_Data host_data, |
132 |
|
|
const char* relative_path); |
133 |
|
|
|
134 |
|
|
} LV2_Files_New_File_Support; |
135 |
|
|
|
136 |
|
|
#ifdef __cplusplus |
137 |
|
|
} /* extern "C" */ |
138 |
|
|
#endif |
139 |
|
|
|
140 |
|
|
#endif /* LV2_FILES_H */ |